Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork5.3k
[Routing] Document the PSR-4 route loader#17373
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
[Routing] Document the PSR-4 route loader#17373
Uh oh!
There was an error while loading.Please reload this page.
Conversation
46e6876 toc356c5fComparec356c5f toac2f793Compare| directory. | ||
| This configuration tells Symfony to look for routes defined as attributes on | ||
| classes declared in the ``App\Controller`` namespace which are stored in the | ||
| ``src/Controller/`` directory which follows the PSR-4 standard. In addition, |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
missing colondirectory, which follows?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Not sure, it feels very German to set that comma. Let's see what the docs team says.
| This configuration tells Symfony to look for routes defined as attributes on | ||
| classes declared in the ``App\Controller`` namespace which are stored in the | ||
| ``src/Controller/`` directory which follows the PSR-4 standard. In addition, | ||
| our kernel can act as a controller as well which is especially useful for small |
maxbeckersOct 20, 2022 • edited
Loading Uh oh!
There was an error while loading.Please reload this page.
edited
Uh oh!
There was an error while loading.Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Here as wellact as a controller as well, which?
This PR was merged into the 6.2 branch.Discussion----------[Routing] PSR-4 directory loader| Q | A| ------------- | ---| Branch? | 6.2| Bug fix? | no| New feature? | yes| Deprecations? | no (but we could…)| Tickets |Fix#47881| License | MIT| Doc PR |symfony/symfony-docs#17373This PR adds a PSR-4 directory loader to the Routing component.When we currently want to load routes from a directory with controllers, we configure it like this:```YAMLcontrollers: resource: ../src/Controller/ type: attribute```What happens now is that `AnnotationDirectoryLoader` searches that directory recursively for `*.php` files and uses PHP's tokenizer extension to discover all controller classes that are defined within that directory. This step feels unnecessarily expensive given that modern projects follow the PSR-4 standard to structure their code. And if we use the DI component's autodiscovery feature to register our controllers as services, our controller directory already has to follow PSR-4.A client I'm working with adds the additional challange that they deliver their code to their customers in encrypted form (using SourceGuardian). This means that the PHP files contain encrypted bytecode instead of plain PHP and thus cannot be parsed. We currently overcome this limitation by extending `AnnotationDirectoryLoader` and overriding the protected `findClass()` method.This PR proposes to extend the resource type `attribute` and allow to suffix it with a PSR-4 namespace root.```YAMLcontrollers: resource: ../src/Controller/ type: attribute@App\Controller```In order to use PSR-4 to discover controller classes, the directory path is not enough. We always need an additional piece of information which is the namespace root for the given directory. Without changing large parts of the Config component, I did not find a nice way to pass down that information to the PSR-4 route loader. Encoding that information into the `type` parameter seemed like the pragmatic approach, but I'm open to discussing alternatives.This approach should play nicely with projects that already use attributes for routing and PSR-4 autodiscovery to register controllers as services. In fact, most project should be able to swap the `type: annotation` or `type: attribute` config with `type: attribute@Your\Namespace\Here` and the only difference they notice is that router compilation becomes a bit faster.Commits-------158e30d [Routing] PSR-4 directory loader
This PR was merged into the 6.2 branch.Discussion----------[Routing] PSR-4 directory loader| Q | A| ------------- | ---| Branch? | 6.2| Bug fix? | no| New feature? | yes| Deprecations? | no (but we could…)| Tickets | Fix #47881| License | MIT| Doc PR |symfony/symfony-docs#17373This PR adds a PSR-4 directory loader to the Routing component.When we currently want to load routes from a directory with controllers, we configure it like this:```YAMLcontrollers: resource: ../src/Controller/ type: attribute```What happens now is that `AnnotationDirectoryLoader` searches that directory recursively for `*.php` files and uses PHP's tokenizer extension to discover all controller classes that are defined within that directory. This step feels unnecessarily expensive given that modern projects follow the PSR-4 standard to structure their code. And if we use the DI component's autodiscovery feature to register our controllers as services, our controller directory already has to follow PSR-4.A client I'm working with adds the additional challange that they deliver their code to their customers in encrypted form (using SourceGuardian). This means that the PHP files contain encrypted bytecode instead of plain PHP and thus cannot be parsed. We currently overcome this limitation by extending `AnnotationDirectoryLoader` and overriding the protected `findClass()` method.This PR proposes to extend the resource type `attribute` and allow to suffix it with a PSR-4 namespace root.```YAMLcontrollers: resource: ../src/Controller/ type: attribute@App\Controller```In order to use PSR-4 to discover controller classes, the directory path is not enough. We always need an additional piece of information which is the namespace root for the given directory. Without changing large parts of the Config component, I did not find a nice way to pass down that information to the PSR-4 route loader. Encoding that information into the `type` parameter seemed like the pragmatic approach, but I'm open to discussing alternatives.This approach should play nicely with projects that already use attributes for routing and PSR-4 autodiscovery to register controllers as services. In fact, most project should be able to swap the `type: annotation` or `type: attribute` config with `type: attribute@Your\Namespace\Here` and the only difference they notice is that router compilation becomes a bit faster.Commits-------158e30df9a [Routing] PSR-4 directory loader
javiereguiluz commentedOct 20, 2022
I've tagged this with "Waiting code merge" because we're discussing internally about some potential tweaks to the syntax of this new feature. Let's wait for a decision before merging. Thanks. |
…loading (derrabus)This PR was merged into the 6.2 branch.Discussion----------[Config][Routing] Nicer config syntax for PSR-4 route loading| Q | A| ------------- | ---| Branch? | 6.2| Bug fix? | no| New feature? | yes| Deprecations? | no| Tickets | Follow-up to#47916| License | MIT| Doc PR |symfony/symfony-docs#17373 (WIP)This PR implements an alternative syntax for the PSR-4 route loader introduced in#47916.```YAMLcontrollers: resource: path: ./Controllers namespace: App\Controllers type: attribute``````XML<routes> <import type="attribute"> <resource path="./Controllers" namespace="App\Psr4Controllers" /> </import></routes>```Commits-------d7df3be Nicer config syntax for PSR-4 route loading
…loading (derrabus)This PR was merged into the 6.2 branch.Discussion----------[Config][Routing] Nicer config syntax for PSR-4 route loading| Q | A| ------------- | ---| Branch? | 6.2| Bug fix? | no| New feature? | yes| Deprecations? | no| Tickets | Follow-up to #47916| License | MIT| Doc PR |symfony/symfony-docs#17373 (WIP)This PR implements an alternative syntax for the PSR-4 route loader introduced in #47916.```YAMLcontrollers: resource: path: ./Controllers namespace: App\Controllers type: attribute``````XML<routes> <import type="attribute"> <resource path="./Controllers" namespace="App\Psr4Controllers" /> </import></routes>```Commits-------d7df3be956 Nicer config syntax for PSR-4 route loading
javiereguiluz commentedOct 26, 2022
Thanks Alexander! Note: while merging I updated the config to match the changes insymfony/symfony#47943 |
This PR was merged into the 6.2 branch.Discussion----------[Routing] PSR-4 directory loader| Q | A| ------------- | ---| Branch? | 6.2| Bug fix? | no| New feature? | yes| Deprecations? | no (but we could…)| Tickets | Fix #47881| License | MIT| Doc PR |symfony/symfony-docs#17373This PR adds a PSR-4 directory loader to the Routing component.When we currently want to load routes from a directory with controllers, we configure it like this:```YAMLcontrollers: resource: ../src/Controller/ type: attribute```What happens now is that `AnnotationDirectoryLoader` searches that directory recursively for `*.php` files and uses PHP's tokenizer extension to discover all controller classes that are defined within that directory. This step feels unnecessarily expensive given that modern projects follow the PSR-4 standard to structure their code. And if we use the DI component's autodiscovery feature to register our controllers as services, our controller directory already has to follow PSR-4.A client I'm working with adds the additional challange that they deliver their code to their customers in encrypted form (using SourceGuardian). This means that the PHP files contain encrypted bytecode instead of plain PHP and thus cannot be parsed. We currently overcome this limitation by extending `AnnotationDirectoryLoader` and overriding the protected `findClass()` method.This PR proposes to extend the resource type `attribute` and allow to suffix it with a PSR-4 namespace root.```YAMLcontrollers: resource: ../src/Controller/ type: attribute@App\Controller```In order to use PSR-4 to discover controller classes, the directory path is not enough. We always need an additional piece of information which is the namespace root for the given directory. Without changing large parts of the Config component, I did not find a nice way to pass down that information to the PSR-4 route loader. Encoding that information into the `type` parameter seemed like the pragmatic approach, but I'm open to discussing alternatives.This approach should play nicely with projects that already use attributes for routing and PSR-4 autodiscovery to register controllers as services. In fact, most project should be able to swap the `type: annotation` or `type: attribute` config with `type: attribute@Your\Namespace\Here` and the only difference they notice is that router compilation becomes a bit faster.Commits-------158e30df9a [Routing] PSR-4 directory loader
…loading (derrabus)This PR was merged into the 6.2 branch.Discussion----------[Config][Routing] Nicer config syntax for PSR-4 route loading| Q | A| ------------- | ---| Branch? | 6.2| Bug fix? | no| New feature? | yes| Deprecations? | no| Tickets | Follow-up to #47916| License | MIT| Doc PR |symfony/symfony-docs#17373 (WIP)This PR implements an alternative syntax for the PSR-4 route loader introduced in #47916.```YAMLcontrollers: resource: path: ./Controllers namespace: App\Controllers type: attribute``````XML<routes> <import type="attribute"> <resource path="./Controllers" namespace="App\Psr4Controllers" /> </import></routes>```Commits-------d7df3be956 Nicer config syntax for PSR-4 route loading
This PR documentssymfony/symfony#47916
Although the PR does not deprecate
AnnotationDirectoryLoaderandAnnotationFileLoader, I chose to recommend only the newPsr4DirectoryLoaderandAnnotationDirectoryLoaderinrouting.rst. Inrouting/custom_route_loader.rst, all four loaders are listed for completeness.Using a class name as resource instead of a file path has always worked, but wasn't documented for some reason. I have added examples for that as well.