Better documentation of factory pattern with Symfony

I think the documentation about the factory pattern should be better.

This is the current documentation:
http://symfony.com/doc/master/components/dependency_injection/factories.html

Example A:
I have a Product entity. It has a field type. The type could be table, chair or something else.

Example B:
I have a File entity with types xml, php or yaml.

I think the current documentation does not easily explain that a factory pattern allows something like this:

class FileFactory
{
    public static function get($type)
    {
        switch ($type)
        {
            case 'xml':
                return new XmlFile($type);
                break;
            case 'php':
                return new PhpFile($type);
                break;
            case 'yml':
                return new YamlFile($type);
                break;
        }

        throw new \InvalidArgumentException();
    }
}

Instead currently it just contains this code:

class NewsletterManagerFactory
{
    public static function createNewsletterManager()
    {
        $newsletterManager = new NewsletterManager();

        // ...

        return $newsletterManager;
    }
}

Where are the different types? I understand that it is easily possible but I think the documentation should be updated for a better explaination about the factory pattern. Everybody should easily understand why they should use a factory pattern.

[numediaweb]

Would be great to submit a PR.

[aminvoly]

@JHGitty And I have a question, in the documentation, we have to specify the class and configurator, like below:

App\Email\NewsletterManager: # call the static method factory: ['App\Email\NewsletterManagerStaticFactory', 'createNewsletterManager']
So based on what you have written, the response of your get function could be three different classes, so what is the purpose of the NewsletterManager class ?! if we want to return an instance of another class, why there should be NewsletterManager? I'm confused. FileFcatory is your factory, but what is your service you have to specify in services.yaml file?

[aminvoly]

@JHGitty Actually I think the factory is for another purpose, it is useful when you wanna construct your object(service), and Symfony's default container is not good enough to satisfy your needs(maybe your service construct is too complex).

[xabbuh]

Rereading the issue I'd vote to close here. The Symfony documentation is not meant to teach the reader all about design patterns. There are better resources for that. What we need to achieve is show people how to make use of the DI component when they use factories to show them that they do not have to change their code when they start using the service container.

@symfony/team-symfony-docs What do you think?

[fabpot]

I agree with @xabbuh

[BooleanType]

Rereading the issue I'd vote to close here. The Symfony documentation is not meant to teach the reader all about design patterns. There are better resources for that. What we need to achieve is show people how to make use of the DI component when they use factories to show them that they do not have to change their code when they start using the service container.

@symfony/team-symfony-docs What do you think?

And I think, that documentation is for Symfony beginners, who know about factory pattern, but want to use it right according to framework. For example, I didn't understand too, why NewsletterManagerStaticFactory "knows" about NewsletterManager (createNewsletterManager() method naming, new NewsletterManager() to get an object...).
I would like that article to be reworded with correct example, showing the real working factory to create services, and how to use it.
Thanks.

[wouterj]

Please note that this article has been rewritten, based on this issue in #12885

Furthermore: We don't have to resources to document the whole world. That's why we try to focus. Good thing here is that Symfony and its documentation is open source. So feel free to add a real world factory (that doesn't make the example more complex than the feature) and submit it as a pull request.

[BooleanType]

Please note that this article has been rewritten, based on this issue in #12885

Furthermore: We don't have to resources to document the whole world. That's why we try to focus. Good thing here is that Symfony and its documentation is open source. So feel free to add a real world factory (that doesn't make the example more complex than the feature) and submit it as a pull request.

Thanks for reply!
I read Symfony 5.0 docs and I've noticed that note, but rewritten material was still not clear for me.
I've created a pull request, as you advised me.