[RFC]: Deprecate ApplicationConfigInjectionDelegator and Application#post, etc.

[boesing]

RFC

Q	A
Proposed Version(s)	4.0.0
BC Break?	Yes

Goal

Provide dedicated delegators for both Router and MiddlewarePipe instead of having ApplicationConfigInjectionDelegator only.
That way, we move configuration of those "services" to the container rather than to the Application. This will benefit laminas-cli commands which should not be aware that they have to $container->get(Application::class) before using $container->get(Router::class) (because the application delegator might register routes).

Allowing the Application#* methods to configure routes should be dropped at all.

Background

There are several issues in laminas-cli which are around the fact, that something is being executed in either laminas-mvc or mezzio Application (or index.php) which is not available in the CLI Commands afterwards.

Regarding mezzio, thats "okayish" as it never provided such details from the beginning.
In laminas-mvc that is problematic, as we suggest projects migrating away from laminas-console to use laminas-cli. laminas-console actually used index.php of laminas-mvc which inherited exactly the same method as a HTTP request does. Therefore, everything was bootstrapped, etc. the same way as for an HTTP request. That is not the case for laminas-cli and thus, there are plenty of complaints about this (and I understand these complaints somehow).

Considerations

Migration from ApplicationConfigInjectionDelegator

Users will have to modify their config:

1. remove ApplicationConfigInjectionDelegator as a delegator for Mezzio\Application
2. add new RouterConfigInjectionDelegator as a delegator for Mezzio\RouteCollectorInterface but maybe that should be dropped as well as we so that routes are directly passed to the Mezzio\RouterInterface itself while having deduplication happening in the delegator? Dunno, just sharing ideas here
3. add new MiddlewarePipelineConfigInjectionDelegator as a delegator for MiddlewarePipeInterface

Removal of the Application#pipe, Application#get, etc. methods

When it comes to the removal of the handy methods Application#pipe, etc., we should encourage users to properly move this to configuration rather than having dedicated php files which are returning callables so that these can be called in index.php.
Having stuff configured this way won't be available to laminas-cli commands, so we are unable to e.g. provide a CLI command in mezzio-router to list all registered routes as the routes are injected at HTTP request runtime (in index.php calling routes.php callable) and not at configuration time. Therefore, there is no way of accessing these methods which makes the CLI command kinda useless.

Proposal(s)

Instead of having a dedicated delegator which still configures the application and not the Router/Middlewarepipeline, I'd suggest having a dedicated delegator for both Router and Middlewarepipeline.

Regarding the Application#pipe, etc. sugar, we should encourage projects to move this into the configuration - we could provide some static factories to provide autocompletion, i.e. something like:

final class RouteConfigurator
{
     /**
      * @param non-empty-string $path
      * @param class-string<MiddlewareInterface|RequestHandlerInterface>|non-empty-list<class-string<MiddlewareInterface|RequestHandlerInterface>> $middleware
      * @param non-empty-string|null $name
      * @return array{
      *  name:non-empty-string,
      *  path:non-empty-string,
      *  middleware:non-empty-list<class-string<MiddlewareInterface>|class-string<RequestHandlerInterface>>,
      *  options?:non-empty-array<non-empty-string,mixed>,
      *  allowed_methods:non-empty-list<RequestMethodInterface::*>
      * }
      */
     public function get(string $path, array|string $middleware, ?string $name = null): array
     {}
}

This will allow upstream to have the same methods available but using these to create a proper route configuration rather than directly injecting the route.

Appendix

Ref: laminas/laminas-cli#106 (comment)