[Routing] Document the PSR-4 route loader #17373
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
derrabus
force-pushed
the
feature/psr4-attribute-routing
branch
from
46e6876 to
c356c5f
Compare
derrabus
force-pushed
the
feature/psr4-attribute-routing
branch
from
c356c5f to
ac2f793
Compare
welcoMattic
approved these changes
Oct 19, 2022
maxbeckers
reviewed
Oct 20, 2022
| 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.
missing colon directory, which follows?
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
Here as well act as a controller as well, which?
fabpot
added a commit
to symfony/symfony
that referenced
this pull request
Oct 20, 2022
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#17373 This 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: ```YAML controllers: 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. ```YAML controllers: 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
symfony-splitter
pushed a commit
to symfony/framework-bundle
that referenced
this pull request
Oct 20, 2022
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#17373 This 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: ```YAML controllers: 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. ```YAML controllers: 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
maxbeckers
approved these changes
Oct 20, 2022
javiereguiluz
added
the
Waiting Code Merge
|
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. |
fabpot
added a commit
to symfony/symfony
that referenced
this pull request
Oct 22, 2022
…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. ```YAML controllers: 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
symfony-splitter
pushed a commit
to symfony/framework-bundle
that referenced
this pull request
Oct 22, 2022
…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. ```YAML controllers: 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
OskarStark
added
Waiting Code Merge
javiereguiluz
removed
the
Waiting Code Merge
carsonbot
changed the title
|
Thanks Alexander! Note: while merging I updated the config to match the changes in symfony/symfony#47943 |
symfony-splitter
pushed a commit
to symfony/framework-bundle
that referenced
this pull request
Jul 28, 2023
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#17373 This 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: ```YAML controllers: 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. ```YAML controllers: 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
symfony-splitter
pushed a commit
to symfony/framework-bundle
that referenced
this pull request
Jul 28, 2023
…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. ```YAML controllers: 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR documents symfony/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.