From a9030f1aea2f3ecaf2bffd770934522ac46f46e1 Mon Sep 17 00:00:00 2001 From: Alexandre Daubois Date: Tue, 10 Oct 2023 13:13:40 +0200 Subject: [PATCH] [DependencyInjection][HttpKernel] Add PHPDoc to attribute classes and properties --- .../DependencyInjection/Attribute/AsAlias.php | 4 ++++ .../DependencyInjection/Attribute/AsDecorator.php | 8 ++++++++ .../DependencyInjection/Attribute/AsTaggedItem.php | 4 ++++ .../DependencyInjection/Attribute/Autoconfigure.php | 12 ++++++++++++ .../Attribute/AutoconfigureTag.php | 4 ++++ .../Attribute/AutowireCallable.php | 5 ++++- .../Attribute/AutowireDecorated.php | 3 +++ .../Attribute/AutowireIterator.php | 9 ++++++++- .../Attribute/AutowireLocator.php | 8 ++++++-- .../Attribute/AutowireServiceClosure.php | 3 +++ .../DependencyInjection/Attribute/TaggedIterator.php | 11 +++++++++++ .../DependencyInjection/Attribute/TaggedLocator.php | 11 +++++++++++ .../DependencyInjection/Attribute/Target.php | 8 +++++--- .../Component/DependencyInjection/Attribute/When.php | 8 +++++--- .../HttpKernel/Attribute/AsTargetedValueResolver.php | 8 +++++--- .../Component/HttpKernel/Attribute/MapDateTime.php | 6 ++++++ .../HttpKernel/Attribute/MapQueryParameter.php | 7 ++++++- .../HttpKernel/Attribute/MapQueryString.php | 6 ++++++ .../HttpKernel/Attribute/MapRequestPayload.php | 7 +++++++ .../Component/HttpKernel/Attribute/ValueResolver.php | 6 +++++- .../HttpKernel/Attribute/WithHttpStatus.php | 5 ++++- .../Component/HttpKernel/Attribute/WithLogLevel.php | 4 +++- 22 files changed, 130 insertions(+), 17 deletions(-) diff --git a/src/Symfony/Component/DependencyInjection/Attribute/AsAlias.php b/src/Symfony/Component/DependencyInjection/Attribute/AsAlias.php index 8068959899733..2f03e5fcdf4e2 100644 --- a/src/Symfony/Component/DependencyInjection/Attribute/AsAlias.php +++ b/src/Symfony/Component/DependencyInjection/Attribute/AsAlias.php @@ -19,6 +19,10 @@ #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)] final class AsAlias { + /** + * @param string|null $id The id of the alias + * @param bool $public Whether to declare the alias public + */ public function __construct( public ?string $id = null, public bool $public = false, diff --git a/src/Symfony/Component/DependencyInjection/Attribute/AsDecorator.php b/src/Symfony/Component/DependencyInjection/Attribute/AsDecorator.php index 0f80c16e974dc..b5125c8b0f24e 100644 --- a/src/Symfony/Component/DependencyInjection/Attribute/AsDecorator.php +++ b/src/Symfony/Component/DependencyInjection/Attribute/AsDecorator.php @@ -13,9 +13,17 @@ use Symfony\Component\DependencyInjection\ContainerInterface; +/** + * Declares a decorating service. + */ #[\Attribute(\Attribute::TARGET_CLASS)] class AsDecorator { + /** + * @param string $decorates The service id to decorate + * @param int $priority The priority of this decoration when multiple decorators are declared for the same service + * @param int $onInvalid The behavior to adopt when the decoration is invalid; must be one of the {@see ContainerInterface} constants + */ public function __construct( public string $decorates, public int $priority = 0, diff --git a/src/Symfony/Component/DependencyInjection/Attribute/AsTaggedItem.php b/src/Symfony/Component/DependencyInjection/Attribute/AsTaggedItem.php index 2320336338b4c..2e649bdeaaadd 100644 --- a/src/Symfony/Component/DependencyInjection/Attribute/AsTaggedItem.php +++ b/src/Symfony/Component/DependencyInjection/Attribute/AsTaggedItem.php @@ -19,6 +19,10 @@ #[\Attribute(\Attribute::TARGET_CLASS)] class AsTaggedItem { + /** + * @param string|null $index The property or method to use to index the item in the locator + * @param int|null $priority The priority of the item; the higher the number, the earlier the tagged service will be located in the locator + */ public function __construct( public ?string $index = null, public ?int $priority = null, diff --git a/src/Symfony/Component/DependencyInjection/Attribute/Autoconfigure.php b/src/Symfony/Component/DependencyInjection/Attribute/Autoconfigure.php index 4560ed696183e..be492e4fda8f1 100644 --- a/src/Symfony/Component/DependencyInjection/Attribute/Autoconfigure.php +++ b/src/Symfony/Component/DependencyInjection/Attribute/Autoconfigure.php @@ -19,6 +19,18 @@ #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)] class Autoconfigure { + /** + * @param array>|null $tags The tags to add to the service + * @param array>|null $calls The calls to be made when instantiating the service + * @param array|null $bind The bindings to declare for the service + * @param bool|string|null $lazy Whether the service is lazy-loaded + * @param bool|null $public Whether to declare the service as public + * @param bool|null $shared Whether to declare the service as shared + * @param bool|null $autowire Whether to declare the service as autowired + * @param array|null $properties The properties to define when creating the service + * @param array|string|null $configurator A PHP function, reference or an array containing a class/Reference and a method to call after the service is fully initialized + * @param string|null $constructor The public static method to use to instantiate the service + */ public function __construct( public ?array $tags = null, public ?array $calls = null, diff --git a/src/Symfony/Component/DependencyInjection/Attribute/AutoconfigureTag.php b/src/Symfony/Component/DependencyInjection/Attribute/AutoconfigureTag.php index ed5807ca02670..ea738342c5bd3 100644 --- a/src/Symfony/Component/DependencyInjection/Attribute/AutoconfigureTag.php +++ b/src/Symfony/Component/DependencyInjection/Attribute/AutoconfigureTag.php @@ -19,6 +19,10 @@ #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)] class AutoconfigureTag extends Autoconfigure { + /** + * @param string|null $name The tag name to add + * @param array $attributes The tag attributes to attach to the tag + */ public function __construct(string $name = null, array $attributes = []) { parent::__construct( diff --git a/src/Symfony/Component/DependencyInjection/Attribute/AutowireCallable.php b/src/Symfony/Component/DependencyInjection/Attribute/AutowireCallable.php index 87e119746d84d..1fdc160e724c5 100644 --- a/src/Symfony/Component/DependencyInjection/Attribute/AutowireCallable.php +++ b/src/Symfony/Component/DependencyInjection/Attribute/AutowireCallable.php @@ -22,7 +22,10 @@ class AutowireCallable extends Autowire { /** - * @param bool|class-string $lazy Whether to use lazy-loading for this argument + * @param string|array|null $callable The callable to autowire + * @param string|null $service The service containing the callable to autowire + * @param string|null $method The method name that will be autowired + * @param bool|class-string $lazy Whether to use lazy-loading for this argument */ public function __construct( string|array $callable = null, diff --git a/src/Symfony/Component/DependencyInjection/Attribute/AutowireDecorated.php b/src/Symfony/Component/DependencyInjection/Attribute/AutowireDecorated.php index ed8f33e0080b2..58f77b8e51bde 100644 --- a/src/Symfony/Component/DependencyInjection/Attribute/AutowireDecorated.php +++ b/src/Symfony/Component/DependencyInjection/Attribute/AutowireDecorated.php @@ -11,6 +11,9 @@ namespace Symfony\Component\DependencyInjection\Attribute; +/** + * Autowires the inner object of decorating services. + */ #[\Attribute(\Attribute::TARGET_PARAMETER)] class AutowireDecorated { diff --git a/src/Symfony/Component/DependencyInjection/Attribute/AutowireIterator.php b/src/Symfony/Component/DependencyInjection/Attribute/AutowireIterator.php index b81bd8f92a57e..92e5f02d7ecb4 100644 --- a/src/Symfony/Component/DependencyInjection/Attribute/AutowireIterator.php +++ b/src/Symfony/Component/DependencyInjection/Attribute/AutowireIterator.php @@ -20,7 +20,14 @@ class AutowireIterator extends Autowire { /** - * @param string|string[] $exclude A service or a list of services to exclude + * @see ServiceSubscriberInterface::getSubscribedServices() + * + * @param string $tag A tag name to search for to populate the iterator + * @param string|null $indexAttribute The name of the attribute that defines the key referencing each service in the tagged collection + * @param string|null $defaultIndexMethod The static method that should be called to get each service's key when their tag doesn't define the previous attribute + * @param string|null $defaultPriorityMethod The static method that should be called to get each service's priority when their tag doesn't define the "priority" attribute + * @param string|array $exclude A service id or a list of service ids to exclude + * @param bool $excludeSelf Whether to automatically exclude the referencing service from the iterator */ public function __construct( string $tag, diff --git a/src/Symfony/Component/DependencyInjection/Attribute/AutowireLocator.php b/src/Symfony/Component/DependencyInjection/Attribute/AutowireLocator.php index a60a76960138d..bd5c912697f17 100644 --- a/src/Symfony/Component/DependencyInjection/Attribute/AutowireLocator.php +++ b/src/Symfony/Component/DependencyInjection/Attribute/AutowireLocator.php @@ -28,8 +28,12 @@ class AutowireLocator extends Autowire /** * @see ServiceSubscriberInterface::getSubscribedServices() * - * @param string|array $services An explicit list of services or a tag name - * @param string|string[] $exclude A service or a list of services to exclude + * @param string|array $services A tag name or an explicit list of service ids + * @param string|null $indexAttribute The name of the attribute that defines the key referencing each service in the locator + * @param string|null $defaultIndexMethod The static method that should be called to get each service's key when their tag doesn't define the previous attribute + * @param string|null $defaultPriorityMethod The static method that should be called to get each service's priority when their tag doesn't define the "priority" attribute + * @param string|array $exclude A service id or a list of service ids to exclude + * @param bool $excludeSelf Whether to automatically exclude the referencing service from the locator */ public function __construct( string|array $services, diff --git a/src/Symfony/Component/DependencyInjection/Attribute/AutowireServiceClosure.php b/src/Symfony/Component/DependencyInjection/Attribute/AutowireServiceClosure.php index a468414a4e8c6..a640a7fccc597 100644 --- a/src/Symfony/Component/DependencyInjection/Attribute/AutowireServiceClosure.php +++ b/src/Symfony/Component/DependencyInjection/Attribute/AutowireServiceClosure.php @@ -20,6 +20,9 @@ #[\Attribute(\Attribute::TARGET_PARAMETER)] class AutowireServiceClosure extends Autowire { + /** + * @param string $service The service id to wrap in the closure + */ public function __construct(string $service) { parent::__construct(new ServiceClosureArgument(new Reference($service))); diff --git a/src/Symfony/Component/DependencyInjection/Attribute/TaggedIterator.php b/src/Symfony/Component/DependencyInjection/Attribute/TaggedIterator.php index dce969bd2b9f5..60a67f69c1f26 100644 --- a/src/Symfony/Component/DependencyInjection/Attribute/TaggedIterator.php +++ b/src/Symfony/Component/DependencyInjection/Attribute/TaggedIterator.php @@ -11,9 +11,20 @@ namespace Symfony\Component\DependencyInjection\Attribute; +/** + * Autowires an iterator of services based on a tag name. + */ #[\Attribute(\Attribute::TARGET_PARAMETER)] class TaggedIterator extends AutowireIterator { + /** + * @param string $tag The tag to look for to populate the iterator + * @param string|null $indexAttribute The name of the attribute that defines the key referencing each service in the tagged collection + * @param string|null $defaultIndexMethod The static method that should be called to get each service's key when their tag doesn't define the previous attribute + * @param string|null $defaultPriorityMethod The static method that should be called to get each service's priority when their tag doesn't define the "priority" attribute + * @param string|string[] $exclude A service id or a list of service ids to exclude + * @param bool $excludeSelf Whether to automatically exclude the referencing service from the iterator + */ public function __construct( public string $tag, public ?string $indexAttribute = null, diff --git a/src/Symfony/Component/DependencyInjection/Attribute/TaggedLocator.php b/src/Symfony/Component/DependencyInjection/Attribute/TaggedLocator.php index 15fb62d1c0f85..606394861587f 100644 --- a/src/Symfony/Component/DependencyInjection/Attribute/TaggedLocator.php +++ b/src/Symfony/Component/DependencyInjection/Attribute/TaggedLocator.php @@ -11,9 +11,20 @@ namespace Symfony\Component\DependencyInjection\Attribute; +/** + * Autowires a locator of services based on a tag name. + */ #[\Attribute(\Attribute::TARGET_PARAMETER)] class TaggedLocator extends AutowireLocator { + /** + * @param string $tag The tag to look for to populate the locator + * @param string|null $indexAttribute The name of the attribute that defines the key referencing each service in the tagged collection + * @param string|null $defaultIndexMethod The static method that should be called to get each service's key when their tag doesn't define the previous attribute + * @param string|null $defaultPriorityMethod The static method that should be called to get each service's priority when their tag doesn't define the "priority" attribute + * @param string|string[] $exclude A service id or a list of service ids to exclude + * @param bool $excludeSelf Whether to automatically exclude the referencing service from the locator + */ public function __construct( public string $tag, public ?string $indexAttribute = null, diff --git a/src/Symfony/Component/DependencyInjection/Attribute/Target.php b/src/Symfony/Component/DependencyInjection/Attribute/Target.php index 6fbb3ad42b6a4..57c0a7dbd5667 100644 --- a/src/Symfony/Component/DependencyInjection/Attribute/Target.php +++ b/src/Symfony/Component/DependencyInjection/Attribute/Target.php @@ -22,9 +22,11 @@ #[\Attribute(\Attribute::TARGET_PARAMETER)] final class Target { - public function __construct( - public ?string $name = null, - ) { + /** + * @param string|null $name The name of the target autowiring alias + */ + public function __construct(public ?string $name = null) + { } public function getParsedName(): string diff --git a/src/Symfony/Component/DependencyInjection/Attribute/When.php b/src/Symfony/Component/DependencyInjection/Attribute/When.php index 302b7b0507737..af36e0596bcfa 100644 --- a/src/Symfony/Component/DependencyInjection/Attribute/When.php +++ b/src/Symfony/Component/DependencyInjection/Attribute/When.php @@ -19,8 +19,10 @@ #[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::TARGET_FUNCTION | \Attribute::IS_REPEATABLE)] class When { - public function __construct( - public string $env, - ) { + /** + * @param string $env The environment under which the class will be registered as a service (i.e. "dev", "test", "prod") + */ + public function __construct(public string $env) + { } } diff --git a/src/Symfony/Component/HttpKernel/Attribute/AsTargetedValueResolver.php b/src/Symfony/Component/HttpKernel/Attribute/AsTargetedValueResolver.php index c58f0e6dd596c..0635566174a45 100644 --- a/src/Symfony/Component/HttpKernel/Attribute/AsTargetedValueResolver.php +++ b/src/Symfony/Component/HttpKernel/Attribute/AsTargetedValueResolver.php @@ -17,8 +17,10 @@ #[\Attribute(\Attribute::TARGET_CLASS)] class AsTargetedValueResolver { - public function __construct( - public readonly ?string $name = null, - ) { + /** + * @param string|null $name The name with which the resolver can be targeted + */ + public function __construct(public readonly ?string $name = null) + { } } diff --git a/src/Symfony/Component/HttpKernel/Attribute/MapDateTime.php b/src/Symfony/Component/HttpKernel/Attribute/MapDateTime.php index bfe48a809095d..db6b4d613e4f8 100644 --- a/src/Symfony/Component/HttpKernel/Attribute/MapDateTime.php +++ b/src/Symfony/Component/HttpKernel/Attribute/MapDateTime.php @@ -12,6 +12,7 @@ namespace Symfony\Component\HttpKernel\Attribute; use Symfony\Component\HttpKernel\Controller\ArgumentResolver\DateTimeValueResolver; +use Symfony\Component\HttpKernel\Controller\ValueResolverInterface; /** * Controller parameter tag to configure DateTime arguments. @@ -19,6 +20,11 @@ #[\Attribute(\Attribute::TARGET_PARAMETER)] class MapDateTime extends ValueResolver { + /** + * @param string|null $format The DateTime format to use, @see https://php.net/datetime.format + * @param bool $disabled Whether this value resolver is disabled; this allows to enable a value resolver globally while disabling it in specific cases + * @param class-string|string $resolver The name of the resolver to use + */ public function __construct( public readonly ?string $format = null, bool $disabled = false, diff --git a/src/Symfony/Component/HttpKernel/Attribute/MapQueryParameter.php b/src/Symfony/Component/HttpKernel/Attribute/MapQueryParameter.php index f83e331e4118f..20c1da7222153 100644 --- a/src/Symfony/Component/HttpKernel/Attribute/MapQueryParameter.php +++ b/src/Symfony/Component/HttpKernel/Attribute/MapQueryParameter.php @@ -12,6 +12,7 @@ namespace Symfony\Component\HttpKernel\Attribute; use Symfony\Component\HttpKernel\Controller\ArgumentResolver\QueryParameterValueResolver; +use Symfony\Component\HttpKernel\Controller\ValueResolverInterface; /** * Can be used to pass a query parameter to a controller argument. @@ -24,7 +25,11 @@ final class MapQueryParameter extends ValueResolver /** * @see https://php.net/filter.filters.validate for filter, flags and options * - * @param string|null $name The name of the query parameter. If null, the name of the argument in the controller will be used. + * @param string|null $name The name of the query parameter; if null, the name of the argument in the controller will be used + * @param (FILTER_VALIDATE_*)|(FILTER_SANITIZE_*)|null $filter The filter to pass to "filter_var()" + * @param int-mask-of<(FILTER_FLAG_*)|FILTER_NULL_ON_FAILURE> $flags The flags to pass to "filter_var()" + * @param array $options The options to pass to "filter_var()" + * @param class-string|string $resolver The name of the resolver to use */ public function __construct( public ?string $name = null, diff --git a/src/Symfony/Component/HttpKernel/Attribute/MapQueryString.php b/src/Symfony/Component/HttpKernel/Attribute/MapQueryString.php index 83722266ee4e3..dfff4ddcc91e8 100644 --- a/src/Symfony/Component/HttpKernel/Attribute/MapQueryString.php +++ b/src/Symfony/Component/HttpKernel/Attribute/MapQueryString.php @@ -26,6 +26,12 @@ class MapQueryString extends ValueResolver { public ArgumentMetadata $metadata; + /** + * @param array $serializationContext The serialization context to use when deserializing the query string + * @param string|GroupSequence|array|null $validationGroups The validation groups to use when validating the query string mapping + * @param class-string $resolver The class name of the resolver to use + * @param int $validationFailedStatusCode The HTTP code to return if the validation fails + */ public function __construct( public readonly array $serializationContext = [], public readonly string|GroupSequence|array|null $validationGroups = null, diff --git a/src/Symfony/Component/HttpKernel/Attribute/MapRequestPayload.php b/src/Symfony/Component/HttpKernel/Attribute/MapRequestPayload.php index cbac606e83fe1..5ee2ffeb64e5c 100644 --- a/src/Symfony/Component/HttpKernel/Attribute/MapRequestPayload.php +++ b/src/Symfony/Component/HttpKernel/Attribute/MapRequestPayload.php @@ -26,6 +26,13 @@ class MapRequestPayload extends ValueResolver { public ArgumentMetadata $metadata; + /** + * @param array|string|null $acceptFormat The payload formats to accept (i.e. "json", "xml") + * @param array $serializationContext The serialization context to use when deserializing the payload + * @param string|GroupSequence|array|null $validationGroups The validation groups to use when validating the query string mapping + * @param class-string $resolver The class name of the resolver to use + * @param int $validationFailedStatusCode The HTTP code to return if the validation fails + */ public function __construct( public readonly array|string|null $acceptFormat = null, public readonly array $serializationContext = [], diff --git a/src/Symfony/Component/HttpKernel/Attribute/ValueResolver.php b/src/Symfony/Component/HttpKernel/Attribute/ValueResolver.php index 5875a27484ba7..e295965fca73b 100644 --- a/src/Symfony/Component/HttpKernel/Attribute/ValueResolver.php +++ b/src/Symfony/Component/HttpKernel/Attribute/ValueResolver.php @@ -13,11 +13,15 @@ use Symfony\Component\HttpKernel\Controller\ValueResolverInterface; +/** + * Defines which value resolver should be used for a given parameter. + */ #[\Attribute(\Attribute::TARGET_PARAMETER | \Attribute::IS_REPEATABLE)] class ValueResolver { /** - * @param class-string|string $resolver + * @param class-string|string $resolver The class name of the resolver to use + * @param bool $disabled Whether this value resolver is disabled; this allows to enable a value resolver globally while disabling it in specific cases */ public function __construct( public string $resolver, diff --git a/src/Symfony/Component/HttpKernel/Attribute/WithHttpStatus.php b/src/Symfony/Component/HttpKernel/Attribute/WithHttpStatus.php index 718427aacc761..18aa6246ddeb7 100644 --- a/src/Symfony/Component/HttpKernel/Attribute/WithHttpStatus.php +++ b/src/Symfony/Component/HttpKernel/Attribute/WithHttpStatus.php @@ -12,13 +12,16 @@ namespace Symfony\Component\HttpKernel\Attribute; /** + * Defines the HTTP status code applied to an exception. + * * @author Dejan Angelov */ #[\Attribute(\Attribute::TARGET_CLASS)] class WithHttpStatus { /** - * @param array $headers + * @param int $statusCode The HTTP status code to use + * @param array $headers The HTTP headers to add to the response */ public function __construct( public readonly int $statusCode, diff --git a/src/Symfony/Component/HttpKernel/Attribute/WithLogLevel.php b/src/Symfony/Component/HttpKernel/Attribute/WithLogLevel.php index 762b077043ae2..534c80248fad2 100644 --- a/src/Symfony/Component/HttpKernel/Attribute/WithLogLevel.php +++ b/src/Symfony/Component/HttpKernel/Attribute/WithLogLevel.php @@ -14,13 +14,15 @@ use Psr\Log\LogLevel; /** + * Defines the log level applied to an exception. + * * @author Dejan Angelov */ #[\Attribute(\Attribute::TARGET_CLASS)] final class WithLogLevel { /** - * @param LogLevel::* $level + * @param LogLevel::* $level The level to use to log the exception */ public function __construct(public readonly string $level) {