This PR was squashed before being merged into the 3.3-dev branch (closes#21763).
Discussion
----------
[DI] Replace wildcard-based methods autowiring by `@required` annotation
| Q | A
| ------------- | ---
| Branch? | master
| Bug fix? | no
| New feature? | yes
| BC breaks? | no (affects things that are only on master)
| Deprecations? | no
| Tests pass? | yes
| Fixed tickets | -
| License | MIT
| Doc PR | -
While playing a bit with new features in master around DI configuration, several people around me got bitten by wildcard-based autowiring. The typical example is adding `autowire: [set*]` in `_defaults`: use that on `resource: ../src/Command/` PSR4-based loading and boom, `setApplication` and `setHelperSet` will now be wrongly called. You could tell me "of course, don't to that" - but being bitten so early on a master-only feature makes me really unconfident that this will be easy enough for people after the release.
If wildcard-based autowiring is removed, then I don't see anymore the need for allowing arrays as in `autowire: [setFoo,getBar]`. Moreover, this array syntax has a core DX issue: it's a dead end as far as the learning curve is concerned. You learn it, then when becoming a more advanced dev, someone teaches you that you'd better use another syntax: explicit wiring.
And in fact, we don't need it at all, because something else already exists: just declare a method call, but don't define its arguments. If `autowire: true` is set, then the AutowiringPass already fills in the holes. There is only one tweak required to make this work: don't autowire optional arguments for method calls - or that'd be a BC break. To my PoV that's even better: this makes autowiring fit a "do the minimum to make it work" strategy. A really good one to me.
But there is still an issue: wildcard-based autowiring fits a need. Namely, it allows one to define a convention (eg. `'set*'`), and have all such methods that follow the convention be autowired. To me, this looks like doing it reverse (the DI config should adapt to the code, not reverse). So, to fill this need, let the declaration be in the source: just use an annotation!
This PR adds support for the `@required` annotation, borrowed from the Spring framework:
https://www.tutorialspoint.com/spring/spring_required_annotation.htm
Using the annotation is totally optional of course. If you do, *and if autowiring is on*, then it'll be autowired. If you don't, nothing changes: do manual wiring.
Even when not using autowiring, the annotation is still a nice hint for the consumer of your classes: it tells the reader that this method needs to be called for correct instantiation - thus lowering one drawback of setter injection (discoverability).
The implementation of the annotation parsing is done using a few regexp (no dep on any complex parser) - and works with inheritance, by leveraging the `@inheritdoc` tag (the default behavior being to *not* inherit anything from parent methods).
All in all, looking at the diff stats, it makes everything simpler. Good sign, isn't it?
Commits
-------
f286fcc25f [DI] Replace wildcard-based methods autowiring by `@required` annotation
9081699980 Revert "minor #21315 [DI][FrameworkBundle] Show autowired methods in descriptors (ogizanagi)"
This PR was merged into the 3.3-dev branch.
Discussion
----------
[DI][FrameworkBundle] Show autowired methods in descriptors
| Q | A
| ------------- | ---
| Branch? | master
| Bug fix? | no
| New feature? | yes
| BC breaks? | no
| Deprecations? | no
| Tests pass? | yes
| Fixed tickets | N/A
| License | MIT
| Doc PR | N/A
so we can see the autowired methods using `debug:container`.
Commits
-------
482435c501 [DI][FrameworkBundle] Show autowired methods in descriptors
* 3.2: (40 commits)
fixed CS
fixed CS
fixed CS fixer config
fixed typo
Revert "fixed typo"
fixed typo
fixed CS
Avoid setting request attributes from signature arguments in AnnotationClassLoader
[DependencyInjection] Add some missing typehints in YamlFileLoader
[DependencyInjection] minor: Fix a DocBlock
[HttpKernel] Give higher priority to adding request formats
[Cache] Fix tags expiration
[PhpUnit] Blacklist DeprecationErrorHandler in stack traces
[PropertyInfo] Don't try to access a property thru a static method
[PropertyInfo] Exclude static methods form properties guessing
[Workflow] Added new validator to make sure each place has unique translation names
[Cache] [PdoAdapter] Fix MySQL 1170 error (blob as primary key)
[FrameworkBundle] Fix third level headers for MarkdownDescriptor
[Ldap] Using Ldap stored username instead of form submitted one
[Ldap] load users with the good username case
...
* 3.1: (31 commits)
fixed CS
fixed CS
fixed CS fixer config
fixed typo
Revert "fixed typo"
fixed typo
fixed CS
Avoid setting request attributes from signature arguments in AnnotationClassLoader
[DependencyInjection] Add some missing typehints in YamlFileLoader
[DependencyInjection] minor: Fix a DocBlock
[HttpKernel] Give higher priority to adding request formats
[PropertyInfo] Don't try to access a property thru a static method
[PropertyInfo] Exclude static methods form properties guessing
[FrameworkBundle] Fix third level headers for MarkdownDescriptor
[Ldap] Using Ldap stored username instead of form submitted one
[Ldap] load users with the good username case
[DoctrineBridge] Fixed invalid unique value as composite key
[Doctrine Bridge] fix UniqueEntityValidator for composite object primary keys
[TwigBundle] do not lose already set method calls
#20411 fix Yaml parsing for very long quoted strings
...
* 2.8: (26 commits)
fixed CS
fixed CS
fixed CS fixer config
fixed typo
Revert "fixed typo"
fixed typo
fixed CS
Avoid setting request attributes from signature arguments in AnnotationClassLoader
[DependencyInjection] Add some missing typehints in YamlFileLoader
[DependencyInjection] minor: Fix a DocBlock
[HttpKernel] Give higher priority to adding request formats
[PropertyInfo] Don't try to access a property thru a static method
[PropertyInfo] Exclude static methods form properties guessing
[FrameworkBundle] Fix third level headers for MarkdownDescriptor
[TwigBundle] do not lose already set method calls
#20411 fix Yaml parsing for very long quoted strings
CS: apply is_null
DX: remove invalid inheritdoc
bumped Symfony version to 2.8.17
updated VERSION for 2.8.16
...
* 2.7:
fixed typo
Revert "fixed typo"
fixed typo
fixed CS
Avoid setting request attributes from signature arguments in AnnotationClassLoader
[DependencyInjection] Add some missing typehints in YamlFileLoader
[DependencyInjection] minor: Fix a DocBlock
[HttpKernel] Give higher priority to adding request formats
[FrameworkBundle] Fix third level headers for MarkdownDescriptor
[TwigBundle] do not lose already set method calls
#20411 fix Yaml parsing for very long quoted strings
CS: apply is_null
DX: remove invalid inheritdoc
bumped Symfony version to 2.7.24
updated VERSION for 2.7.23
update CONTRIBUTORS for 2.7.23
updated CHANGELOG for 2.7.23
[FrameworkBundle] Skip test if xdebug.file_link_format is defined.
* 3.2: (51 commits)
[FrameworkBundle] [Workflow] Fix service marking store configuration
Fix merge
[Validator] add class name to the cache key
[Serializer] Remove AbstractObjectNormalizer::isAttributeToNormalize
Throw less misleading exception when property access not found
[Twig] Fix deprecations with Twig 1.29
[FrameworkBundle] Fix validation cache warmer with failing or missing classes
Fixed typo
[FrameworkBundle] Removed the kernel.debug parameter from the cache pool namespace seed
Fix email address
fix the docblock in regard to the role argument
[Bridge\Twig] Trigger deprecation when using FormExtension::$renderer
Don't use the "app" global variable in the profiler
[VarDumper] fix tests when xdebug is enabled
Fix merge
FIXED NON EXISTING TYPE DECLARATION
[Form] Add failing test for data collector bug
[Cache] Fix dumping SplDoublyLinkedList iter mode
[Form] Fix FormDataCollector
Ignore missing 'debug.file_link_formatter' service in Debug and Twig bundles
...
* 3.0:
[Console] SymfonyStyle: Fix alignment/prefixing of multi-line comments
[Routing] Finish annotation loader taking a class constant as a beginning of a class name
[Routing] Fix the annotation loader taking a class constant as a beginning of a class name
* 2.8:
[Console] SymfonyStyle: Fix alignment/prefixing of multi-line comments
[Routing] Finish annotation loader taking a class constant as a beginning of a class name
[Routing] Fix the annotation loader taking a class constant as a beginning of a class name
* 3.0: (31 commits)
Drop hirak/prestissimo
[MonologBridge] Uninstallable together with symfony/http-kernel in 3.0.6
bumped Symfony version to 3.0.7
updated VERSION for 3.0.6
updated CHANGELOG for 3.0.6
bumped Symfony version to 2.8.7
updated VERSION for 2.8.6
updated CHANGELOG for 2.8.6
bumped Symfony version to 2.7.14
updated VERSION for 2.7.13
updated CHANGELOG for 2.7.13
bumped Symfony version to 2.3.42
[Debug] Fix fatal error handlers on PHP 7
updated VERSION for 2.3.41
update CONTRIBUTORS for 2.3.41
updated CHANGELOG for 2.3.41
fixed bad merge
Fixed issue with blank password with Ldap
limited the maximum length of a submitted username
[2.3][Component/Security] Fixed phpdoc in AnonymousToken constructor for user param
...
Conflicts:
src/Symfony/Component/DependencyInjection/Compiler/AutowirePass.php
src/Symfony/Component/DependencyInjection/Tests/Compiler/AutowirePassTest.php
src/Symfony/Component/HttpKernel/Kernel.php
* 2.8:
[2.3][Component/Security] Fixed phpdoc in AnonymousToken constructor for user param
prevent calling get() for service_container service
call get() after the container was compiled
Fixed readme of OptionsResolver
top-level anonymous services must be public
[DependencyInjection] Suggest ExpressionLanguage in composer.json
added a conflict between Monolog bridge 2.8 and HTTP Kernel 3.0+
* 2.7:
[2.3][Component/Security] Fixed phpdoc in AnonymousToken constructor for user param
prevent calling get() for service_container service
call get() after the container was compiled
Fixed readme of OptionsResolver
[DependencyInjection] Suggest ExpressionLanguage in composer.json
* 3.0: (24 commits)
add @Event annotation for AuthenticationEvents
bumped Symfony version to 3.0.6
updated VERSION for 3.0.5
updated CHANGELOG for 3.0.5
bumped Symfony version to 2.8.6
[PropertyInfo] PHPDoc correction
add @Event annotation for KernelEvents
Fixed typo
updated VERSION for 2.8.5
updated CHANGELOG for 2.8.5
bumped Symfony version to 2.7.13
updated VERSION for 2.7.12
update CONTRIBUTORS for 2.7.12
updated CHANGELOG for 2.7.12
bumped Symfony version to 2.3.41
updated VERSION for 2.3.40
update CONTRIBUTORS for 2.3.40
updated CHANGELOG for 2.3.40
Revert "minor #18257 [Routing] Don't needlessly execute strtr's as they are fairly expensive (arjenm)"
Revert "fixed CS"
...
* 2.8:
add @Event annotation for AuthenticationEvents
bumped Symfony version to 2.8.6
[PropertyInfo] PHPDoc correction
add @Event annotation for KernelEvents
updated VERSION for 2.8.5
updated CHANGELOG for 2.8.5
bumped Symfony version to 2.7.13
updated VERSION for 2.7.12
update CONTRIBUTORS for 2.7.12
updated CHANGELOG for 2.7.12
bumped Symfony version to 2.3.41
updated VERSION for 2.3.40
update CONTRIBUTORS for 2.3.40
updated CHANGELOG for 2.3.40
Revert "minor #18257 [Routing] Don't needlessly execute strtr's as they are fairly expensive (arjenm)"
Revert "fixed CS"
fixed deprecation notices in tests
[Security] Normalize "symfony/security-acl" dependency versions across all composer.json files
[FrameworkBundle] Remove misleading comment
bug #17460 [DI] fix ambiguous services schema
* 2.7:
add @Event annotation for AuthenticationEvents
add @Event annotation for KernelEvents
bumped Symfony version to 2.7.13
updated VERSION for 2.7.12
update CONTRIBUTORS for 2.7.12
updated CHANGELOG for 2.7.12
bumped Symfony version to 2.3.41
updated VERSION for 2.3.40
update CONTRIBUTORS for 2.3.40
updated CHANGELOG for 2.3.40
Revert "minor #18257 [Routing] Don't needlessly execute strtr's as they are fairly expensive (arjenm)"
Revert "fixed CS"
[FrameworkBundle] Remove misleading comment
bug #17460 [DI] fix ambiguous services schema
* 2.8:
[DependencyInjection] fix dumped YAML snytax
Remove InputOption::VALUE_REQUIRED mode from $default parameter description as InputOption::setDefault() throws an exception only when called in InputOption::VALUE_NONE mode. In practice the $default value could still be accessed in InputOption::VALUE_REQUIRED mode in case InputOption was never set but accessed from InputDefinition::getOption() method
[Form] Fixed violation mapping if multiple forms are using the same (or part of the same) property path
fix FQCN in tests added by #17694
Fix locale and written standard inconsistencies for Norwegian translations
[Form] [Validator] Fix locale inconsistencies in Norwegian translations
[TwigBridge] Symfony 3.1 forward compatibility
fixed CS
[DependencyInjection] fixed exceptions thrown by get method of ContainerBuilder
[Yaml] properly parse lists in object maps
[FrameworkBundle] Remove unused private method.
[Form] remove useless code in ResizeFormListener
[Config] Fix EnumNodeDefinition to allow building enum nodes with one element
fix choice_value option in EntityType and add some tests
* 2.8:
[Process] Enhance compatiblity with --enable-sigchild
[Validator] removes unused variable in LengthValidator class.
[FrameworkBundle] [Bug] Fixes new InputStyle bug #16920
fix short array syntax for php 5.3
[Serializer] Fixed on array of objects in .
[Process] Always call proc_close
[Form] Add missing tests for StringUtil::fqcnToBlockPrefix()
[Security] Fix a Polyfill import statement in StringUtils
[Validator] Updated Luxembourgish translations for 2.8
Improved the code of the commands that use the new SymfonyStyle class
disable server commands without Process component
list all server command names in suggestion
Suggested Process dependency
disable server:run cmd without Process component
Suggested Process dependency
[FrameworkBundle] prevent cache:clear creating too long paths
[FrameworkBundle] [Translation] Fixed translations not written when no translations directory in update command
Conflicts:
.travis.yml
src/Symfony/Bridge/Twig/Command/LintCommand.php
src/Symfony/Bundle/FrameworkBundle/Command/ConfigDebugCommand.php
src/Symfony/Bundle/FrameworkBundle/Command/ContainerDebugCommand.php
src/Symfony/Bundle/FrameworkBundle/Command/RouterApacheDumperCommand.php
src/Symfony/Bundle/FrameworkBundle/Command/RouterDebugCommand.php
src/Symfony/Bundle/FrameworkBundle/Command/ServerRunCommand.php
src/Symfony/Bundle/FrameworkBundle/Command/TranslationDebugCommand.php
src/Symfony/Bundle/FrameworkBundle/Command/YamlLintCommand.php
src/Symfony/Bundle/TwigBundle/Command/DebugCommand.php
src/Symfony/Component/Security/Core/Util/StringUtils.php
* 2.8:
[ci] Phpunit tests wont run if composer is installed in a wrapper
[ci] Add version tag in phpunit wrapper to trigger cache-reset on demand
fix race condition at mkdir (#16258)
[VarDumper] Fix PHP7 type-hints compat
[Bridge] [PhpUnit] fixes documentation markup.
[PropertyAccess] Port of the performance optimization from 2.3
trigger deprecation warning when using empty_value
[PropertyAccess] Test access to dynamic properties
[PropertyAccess] Fix dynamic property accessing.
[Serializer] GetSetNormalizer shouldn't set/get static methods
[Serializer] PropertyNormalizer shouldn't set static properties
JsonDescriptor - encode container params only once
Conflicts:
src/Symfony/Component/Form/Extension/Core/Type/ChoiceType.php
src/Symfony/Component/Form/Extension/Core/Type/DateType.php
src/Symfony/Component/Form/Extension/Core/Type/TimeType.php
src/Symfony/Component/VarDumper/Tests/Caster/ReflectionCasterTest.php
* 2.7:
[ci] Phpunit tests wont run if composer is installed in a wrapper
[ci] Add version tag in phpunit wrapper to trigger cache-reset on demand
fix race condition at mkdir (#16258)
[VarDumper] Fix PHP7 type-hints compat
[Bridge] [PhpUnit] fixes documentation markup.
[PropertyAccess] Port of the performance optimization from 2.3
trigger deprecation warning when using empty_value
[PropertyAccess] Test access to dynamic properties
[PropertyAccess] Fix dynamic property accessing.
[Serializer] GetSetNormalizer shouldn't set/get static methods
[Serializer] PropertyNormalizer shouldn't set static properties
JsonDescriptor - encode container params only once
Conflicts:
src/Symfony/Component/VarDumper/Tests/Caster/ReflectionCasterTest.php
* 2.8:
[Bridge\PhpUnit] Add extra clock-mocked namespaces in phpunit.xml.dist
[DependencyInjection] Autowing: exclude abstract definitons
[DependencyInjection] Autowiring: support parent/decorators
[FrameworkBundle] Autowiring support for debug:container
Fixing bad type-hint auto-wiring bug
[Yaml] deprecate unquoted indicator characters
added a micro kernel
Re-adding the ability to add a resource to the RouteCollectionBuilder
[DependencyInjection] Add autowiring support to dumpers
ldap_set_option should be called with a valid link identifier
[FrameworkBundle][Form] Better exception message for private form tagged services
Conflicts:
src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Compiler/FormPass.php
src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/builder_1_public.xml
src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/builder_1_services.xml
src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/builder_1_tag1.xml
src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/builder_1_tags.xml
src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/definition_1.txt
src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/definition_1.xml
src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/definition_2.txt
src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/definition_2.xml
src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/legacy_synchronized_service_definition_1.json
src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/legacy_synchronized_service_definition_1.md
src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/legacy_synchronized_service_definition_1.txt
src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/legacy_synchronized_service_definition_1.xml
src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/legacy_synchronized_service_definition_2.json
src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/legacy_synchronized_service_definition_2.md
src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/legacy_synchronized_service_definition_2.txt
src/Symfony/Bundle/FrameworkBundle/Tests/Fixtures/Descriptor/legacy_synchronized_service_definition_2.xml
src/Symfony/Component/DependencyInjection/Compiler/ResolveDefinitionTemplatesPass.php
src/Symfony/Component/DependencyInjection/Dumper/YamlDumper.php
