Skip to content

Commit b990b26

Browse files
nicolas-grekasnicolas-grekas
committed
minor #51971 [DependencyInjection][HttpKernel] Add PHPDoc to attribute classes and properties (alexandre-daubois)
This PR was merged into the 7.1 branch. Discussion ---------- [DependencyInjection][HttpKernel] Add PHPDoc to attribute classes and properties | Q | A | ------------- | --- | Branch? | 7.1 | Bug fix? | no | New feature? | yes | Deprecations? | no | Tickets | Part of #51920 | License | MIT Friendly ping `@GromNaN`, is that what you had in mind? 🙂 Commits ------- a9030f1 [DependencyInjection][HttpKernel] Add PHPDoc to attribute classes and properties
2 parents d0887a3 + a9030f1 commit b990b26

22 files changed

+130
-17
lines changed

‎src/Symfony/Component/DependencyInjection/Attribute/AsAlias.php

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,10 @@
1919
#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
2020
final class AsAlias
2121
{
22+
/**
23+
* @param string|null $id The id of the alias
24+
* @param bool $public Whether to declare the alias public
25+
*/
2226
public function __construct(
2327
public ?string $id = null,
2428
public bool $public = false,

‎src/Symfony/Component/DependencyInjection/Attribute/AsDecorator.php

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,17 @@
1313

1414
use Symfony\Component\DependencyInjection\ContainerInterface;
1515

16+
/**
17+
* Declares a decorating service.
18+
*/
1619
#[\Attribute(\Attribute::TARGET_CLASS)]
1720
class AsDecorator
1821
{
22+
/**
23+
* @param string $decorates The service id to decorate
24+
* @param int $priority The priority of this decoration when multiple decorators are declared for the same service
25+
* @param int $onInvalid The behavior to adopt when the decoration is invalid; must be one of the {@see ContainerInterface} constants
26+
*/
1927
public function __construct(
2028
public string $decorates,
2129
public int $priority = 0,

‎src/Symfony/Component/DependencyInjection/Attribute/AsTaggedItem.php

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,10 @@
1919
#[\Attribute(\Attribute::TARGET_CLASS)]
2020
class AsTaggedItem
2121
{
22+
/**
23+
* @param string|null $index The property or method to use to index the item in the locator
24+
* @param int|null $priority The priority of the item; the higher the number, the earlier the tagged service will be located in the locator
25+
*/
2226
public function __construct(
2327
public ?string $index = null,
2428
public ?int $priority = null,

‎src/Symfony/Component/DependencyInjection/Attribute/Autoconfigure.php

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,18 @@
1919
#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
2020
class Autoconfigure
2121
{
22+
/**
23+
* @param array<array-key, array<array-key, mixed>>|null $tags The tags to add to the service
24+
* @param array<string, array<array-key, mixed>>|null $calls The calls to be made when instantiating the service
25+
* @param array<string, mixed>|null $bind The bindings to declare for the service
26+
* @param bool|string|null $lazy Whether the service is lazy-loaded
27+
* @param bool|null $public Whether to declare the service as public
28+
* @param bool|null $shared Whether to declare the service as shared
29+
* @param bool|null $autowire Whether to declare the service as autowired
30+
* @param array<string, mixed>|null $properties The properties to define when creating the service
31+
* @param array<class-string, string>|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
32+
* @param string|null $constructor The public static method to use to instantiate the service
33+
*/
2234
public function __construct(
2335
public ?array $tags = null,
2436
public ?array $calls = null,

‎src/Symfony/Component/DependencyInjection/Attribute/AutoconfigureTag.php

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,10 @@
1919
#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::IS_REPEATABLE)]
2020
class AutoconfigureTag extends Autoconfigure
2121
{
22+
/**
23+
* @param string|null $name The tag name to add
24+
* @param array<array-key, mixed> $attributes The tag attributes to attach to the tag
25+
*/
2226
public function __construct(string $name = null, array $attributes = [])
2327
{
2428
parent::__construct(

‎src/Symfony/Component/DependencyInjection/Attribute/AutowireCallable.php

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,10 @@
2222
class AutowireCallable extends Autowire
2323
{
2424
/**
25-
* @param bool|class-string $lazy Whether to use lazy-loading for this argument
25+
* @param string|array|null $callable The callable to autowire
26+
* @param string|null $service The service containing the callable to autowire
27+
* @param string|null $method The method name that will be autowired
28+
* @param bool|class-string $lazy Whether to use lazy-loading for this argument
2629
*/
2730
public function __construct(
2831
string|array $callable = null,

‎src/Symfony/Component/DependencyInjection/Attribute/AutowireDecorated.php

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@
1111

1212
namespace Symfony\Component\DependencyInjection\Attribute;
1313

14+
/**
15+
* Autowires the inner object of decorating services.
16+
*/
1417
#[\Attribute(\Attribute::TARGET_PARAMETER)]
1518
class AutowireDecorated
1619
{

‎src/Symfony/Component/DependencyInjection/Attribute/AutowireIterator.php

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,14 @@
2020
class AutowireIterator extends Autowire
2121
{
2222
/**
23-
* @param string|string[] $exclude A service or a list of services to exclude
23+
* @see ServiceSubscriberInterface::getSubscribedServices()
24+
*
25+
* @param string $tag A tag name to search for to populate the iterator
26+
* @param string|null $indexAttribute The name of the attribute that defines the key referencing each service in the tagged collection
27+
* @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
28+
* @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
29+
* @param string|array<string> $exclude A service id or a list of service ids to exclude
30+
* @param bool $excludeSelf Whether to automatically exclude the referencing service from the iterator
2431
*/
2532
public function __construct(
2633
string $tag,

‎src/Symfony/Component/DependencyInjection/Attribute/AutowireLocator.php

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,12 @@ class AutowireLocator extends Autowire
2828
/**
2929
* @see ServiceSubscriberInterface::getSubscribedServices()
3030
*
31-
* @param string|array<string|SubscribedService> $services An explicit list of services or a tag name
32-
* @param string|string[] $exclude A service or a list of services to exclude
31+
* @param string|array<string|SubscribedService> $services A tag name or an explicit list of service ids
32+
* @param string|null $indexAttribute The name of the attribute that defines the key referencing each service in the locator
33+
* @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
34+
* @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
35+
* @param string|array $exclude A service id or a list of service ids to exclude
36+
* @param bool $excludeSelf Whether to automatically exclude the referencing service from the locator
3337
*/
3438
public function __construct(
3539
string|array $services,

‎src/Symfony/Component/DependencyInjection/Attribute/AutowireServiceClosure.php

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@
2020
#[\Attribute(\Attribute::TARGET_PARAMETER)]
2121
class AutowireServiceClosure extends Autowire
2222
{
23+
/**
24+
* @param string $service The service id to wrap in the closure
25+
*/
2326
public function __construct(string $service)
2427
{
2528
parent::__construct(new ServiceClosureArgument(new Reference($service)));

‎src/Symfony/Component/DependencyInjection/Attribute/TaggedIterator.php

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,20 @@
1111

1212
namespace Symfony\Component\DependencyInjection\Attribute;
1313

14+
/**
15+
* Autowires an iterator of services based on a tag name.
16+
*/
1417
#[\Attribute(\Attribute::TARGET_PARAMETER)]
1518
class TaggedIterator extends AutowireIterator
1619
{
20+
/**
21+
* @param string $tag The tag to look for to populate the iterator
22+
* @param string|null $indexAttribute The name of the attribute that defines the key referencing each service in the tagged collection
23+
* @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
24+
* @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
25+
* @param string|string[] $exclude A service id or a list of service ids to exclude
26+
* @param bool $excludeSelf Whether to automatically exclude the referencing service from the iterator
27+
*/
1728
public function __construct(
1829
public string $tag,
1930
public ?string $indexAttribute = null,

‎src/Symfony/Component/DependencyInjection/Attribute/TaggedLocator.php

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,20 @@
1111

1212
namespace Symfony\Component\DependencyInjection\Attribute;
1313

14+
/**
15+
* Autowires a locator of services based on a tag name.
16+
*/
1417
#[\Attribute(\Attribute::TARGET_PARAMETER)]
1518
class TaggedLocator extends AutowireLocator
1619
{
20+
/**
21+
* @param string $tag The tag to look for to populate the locator
22+
* @param string|null $indexAttribute The name of the attribute that defines the key referencing each service in the tagged collection
23+
* @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
24+
* @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
25+
* @param string|string[] $exclude A service id or a list of service ids to exclude
26+
* @param bool $excludeSelf Whether to automatically exclude the referencing service from the locator
27+
*/
1728
public function __construct(
1829
public string $tag,
1930
public ?string $indexAttribute = null,

‎src/Symfony/Component/DependencyInjection/Attribute/Target.php

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,9 +22,11 @@
2222
#[\Attribute(\Attribute::TARGET_PARAMETER)]
2323
final class Target
2424
{
25-
public function __construct(
26-
public ?string $name = null,
27-
) {
25+
/**
26+
* @param string|null $name The name of the target autowiring alias
27+
*/
28+
public function __construct(public ?string $name = null)
29+
{
2830
}
2931

3032
public function getParsedName(): string

‎src/Symfony/Component/DependencyInjection/Attribute/When.php

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,10 @@
1919
#[\Attribute(\Attribute::TARGET_CLASS | \Attribute::TARGET_METHOD | \Attribute::TARGET_FUNCTION | \Attribute::IS_REPEATABLE)]
2020
class When
2121
{
22-
public function __construct(
23-
public string $env,
24-
) {
22+
/**
23+
* @param string $env The environment under which the class will be registered as a service (i.e. "dev", "test", "prod")
24+
*/
25+
public function __construct(public string $env)
26+
{
2527
}
2628
}

‎src/Symfony/Component/HttpKernel/Attribute/AsTargetedValueResolver.php

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,10 @@
1717
#[\Attribute(\Attribute::TARGET_CLASS)]
1818
class AsTargetedValueResolver
1919
{
20-
public function __construct(
21-
public readonly ?string $name = null,
22-
) {
20+
/**
21+
* @param string|null $name The name with which the resolver can be targeted
22+
*/
23+
public function __construct(public readonly ?string $name = null)
24+
{
2325
}
2426
}

‎src/Symfony/Component/HttpKernel/Attribute/MapDateTime.php

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,19 @@
1212
namespace Symfony\Component\HttpKernel\Attribute;
1313

1414
use Symfony\Component\HttpKernel\Controller\ArgumentResolver\DateTimeValueResolver;
15+
use Symfony\Component\HttpKernel\Controller\ValueResolverInterface;
1516

1617
/**
1718
* Controller parameter tag to configure DateTime arguments.
1819
*/
1920
#[\Attribute(\Attribute::TARGET_PARAMETER)]
2021
class MapDateTime extends ValueResolver
2122
{
23+
/**
24+
* @param string|null $format The DateTime format to use, @see https://php.net/datetime.format
25+
* @param bool $disabled Whether this value resolver is disabled; this allows to enable a value resolver globally while disabling it in specific cases
26+
* @param class-string<ValueResolverInterface>|string $resolver The name of the resolver to use
27+
*/
2228
public function __construct(
2329
public readonly ?string $format = null,
2430
bool $disabled = false,

‎src/Symfony/Component/HttpKernel/Attribute/MapQueryParameter.php

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313

1414
use Symfony\Component\HttpFoundation\Response;
1515
use Symfony\Component\HttpKernel\Controller\ArgumentResolver\QueryParameterValueResolver;
16+
use Symfony\Component\HttpKernel\Controller\ValueResolverInterface;
1617

1718
/**
1819
* Can be used to pass a query parameter to a controller argument.
@@ -26,7 +27,11 @@ final class MapQueryParameter extends ValueResolver
2627
/**
2728
* @see https://php.net/filter.filters.validate for filter, flags and options
2829
*
29-
* @param string|null $name The name of the query parameter. If null, the name of the argument in the controller will be used.
30+
* @param string|null $name The name of the query parameter; if null, the name of the argument in the controller will be used
31+
* @param (FILTER_VALIDATE_*)|(FILTER_SANITIZE_*)|null $filter The filter to pass to "filter_var()"
32+
* @param int-mask-of<(FILTER_FLAG_*)|FILTER_NULL_ON_FAILURE> $flags The flags to pass to "filter_var()"
33+
* @param array $options The options to pass to "filter_var()"
34+
* @param class-string<ValueResolverInterface>|string $resolver The name of the resolver to use
3035
*/
3136
public function __construct(
3237
public ?string $name = null,

‎src/Symfony/Component/HttpKernel/Attribute/MapQueryString.php

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,12 @@ class MapQueryString extends ValueResolver
2626
{
2727
public ArgumentMetadata $metadata;
2828

29+
/**
30+
* @param array<string, mixed> $serializationContext The serialization context to use when deserializing the query string
31+
* @param string|GroupSequence|array<string>|null $validationGroups The validation groups to use when validating the query string mapping
32+
* @param class-string $resolver The class name of the resolver to use
33+
* @param int $validationFailedStatusCode The HTTP code to return if the validation fails
34+
*/
2935
public function __construct(
3036
public readonly array $serializationContext = [],
3137
public readonly string|GroupSequence|array|null $validationGroups = null,

‎src/Symfony/Component/HttpKernel/Attribute/MapRequestPayload.php

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,13 @@ class MapRequestPayload extends ValueResolver
2626
{
2727
public ArgumentMetadata $metadata;
2828

29+
/**
30+
* @param array<string>|string|null $acceptFormat The payload formats to accept (i.e. "json", "xml")
31+
* @param array<string, mixed> $serializationContext The serialization context to use when deserializing the payload
32+
* @param string|GroupSequence|array<string>|null $validationGroups The validation groups to use when validating the query string mapping
33+
* @param class-string $resolver The class name of the resolver to use
34+
* @param int $validationFailedStatusCode The HTTP code to return if the validation fails
35+
*/
2936
public function __construct(
3037
public readonly array|string|null $acceptFormat = null,
3138
public readonly array $serializationContext = [],

‎src/Symfony/Component/HttpKernel/Attribute/ValueResolver.php

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,15 @@
1313

1414
use Symfony\Component\HttpKernel\Controller\ValueResolverInterface;
1515

16+
/**
17+
* Defines which value resolver should be used for a given parameter.
18+
*/
1619
#[\Attribute(\Attribute::TARGET_PARAMETER | \Attribute::IS_REPEATABLE)]
1720
class ValueResolver
1821
{
1922
/**
20-
* @param class-string<ValueResolverInterface>|string $resolver
23+
* @param class-string<ValueResolverInterface>|string $resolver The class name of the resolver to use
24+
* @param bool $disabled Whether this value resolver is disabled; this allows to enable a value resolver globally while disabling it in specific cases
2125
*/
2226
public function __construct(
2327
public string $resolver,

‎src/Symfony/Component/HttpKernel/Attribute/WithHttpStatus.php

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,16 @@
1212
namespace Symfony\Component\HttpKernel\Attribute;
1313

1414
/**
15+
* Defines the HTTP status code applied to an exception.
16+
*
1517
* @author Dejan Angelov <angelovdejan@protonmail.com>
1618
*/
1719
#[\Attribute(\Attribute::TARGET_CLASS)]
1820
class WithHttpStatus
1921
{
2022
/**
21-
* @param array<string, string> $headers
23+
* @param int $statusCode The HTTP status code to use
24+
* @param array<string, string> $headers The HTTP headers to add to the response
2225
*/
2326
public function __construct(
2427
public readonly int $statusCode,

‎src/Symfony/Component/HttpKernel/Attribute/WithLogLevel.php

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,15 @@
1414
use Psr\Log\LogLevel;
1515

1616
/**
17+
* Defines the log level applied to an exception.
18+
*
1719
* @author Dejan Angelov <angelovdejan@protonmail.com>
1820
*/
1921
#[\Attribute(\Attribute::TARGET_CLASS)]
2022
final class WithLogLevel
2123
{
2224
/**
23-
* @param LogLevel::* $level
25+
* @param LogLevel::* $level The level to use to log the exception
2426
*/
2527
public function __construct(public readonly string $level)
2628
{

0 commit comments

Comments
 (0)