Clarify documentation for MVC users.

brian-n-millar commented 1 year ago

Feature Request

Q	A
New Feature	yes
RFC	no
BC Break	no

Summary

I was migrating a Zend Framework 3 application to Laminas and hence from zend-console to laminas-cli. I read the following page: https://docs.laminas.dev/laminas-cli/intro/

I find step 3 is confusing:


// config/autoload/dependencies.global.php:
return [
    'dependencies' => [
        'factories' => [
            MyNamespace\Command\MyCommand::class => MyNamespace\Command\MyCommandFactory::class,
        ],
    ],
];

I spent a good while trying to get this to work and could not, it was only by reading the other stuff further down about ConfigProvider:

namespace MyNamespace;

class Module
{
    public function getConfig() : array
    {
        $configProvider = new ConfigProvider();

        return [
            'laminas-cli' => $configProvider->getCliConfig(),
            'service_manager' => $configProvider->getDependencyConfig(),
        ];
    }
}

That I then realized that dependencies should be service_manager for MVC applications and I got the first code working by making it be like:


return [
    'service_manager' => [
        'factories' => [
            MyNamespace\Command\MyCommand::class => MyNamespace\Command\MyCommandFactory::class,
        ],
    ],
];

Maybe this is obvious to some but I think it would help MVC users to point this out clearly in step 3 as it took me some time to realize why it wasn't working.

boesing commented 1 year ago

Good finding, this is indeed too specific for mezzio projects.

Could be something like:

return [
    '<container config identifier>' => [
        'factories' => [
            MyNamespace\Command\MyCommand::class => MyNamespace\Command\MyCommandFactory::class,
        ],
    ],
];

Plus an addition below like:

> ### Container Config Identifier
>
> - for **Laminas MVC** projects, this has to be `service_manager`
> - for **Mezzio** projects, this has to be `dependencies`

Would you mind creating a PR for this? I'd be happy to merge that.

brian-n-millar commented 1 year ago

Thank you, I've made a PR using your suggested wording. PR #112

brian-n-millar commented 1 year ago

Looks like I caused linting errors, sorry about that.

Update: fixed.

froschdesign commented 1 year ago

@brian-n-millar This is an important hint, so thanks for opening this issue report! 👍🏻

Unfortunately, the entire page is a horror for me, so I will completely rework it. There needs to be a clear separation of explanations and the confusion needs to be resolved.

laminas / laminas-cli

Clarify documentation for MVC users. #111

Feature Request

Summary