feat(metadata): allow extending the Link attribute

[soyuka]

Q	A
Branch?	4.4
Tickets	Closes #8449
License	MIT
Doc PR	n/a

Link was the only final subclass of the abstract Parameter — QueryParameter and HeaderParameter are both extendable. That prevents users from giving a recurring link shape a domain name:

#[\Attribute(\Attribute::TARGET_PROPERTY | \Attribute::TARGET_METHOD | \Attribute::TARGET_PARAMETER)]
final class ProjectLink extends Link
{
    public function __construct(string $permission)
    {
        parent::__construct(
            fromClass: Project::class,
            toProperty: 'project',
            security: \sprintf('is_granted("%s", project)', $permission),
            securityObjectName: 'project',
        );
    }
}

// call site
uriVariables: ['projectId' => new ProjectLink('RULE_VIEW')]

A static factory is not a workaround: attribute arguments must be constant expressions, and while new has been allowed there since PHP 8.1, static calls are not.

Dropping final is safe — every wither on Link uses clone $this, so a subclass survives them, and consumers (LinksHandlerTrait, IdentifiersExtractor, UriVariablesConverter) only read it through its getters.

LinkFactory::createLinksFromAttributes() needed the matching half of the change: it looked up property attributes with getAttributes(Link::class), which filters on the exact class name, so a subclassed attribute placed on a property would have been silently ignored. It now passes \ReflectionAttribute::IS_INSTANCEOF. No class in the tree extends Link, so this is a no-op for existing code.

Covered by LinkFactoryTest::testCreateLinksFromAttributesWithExtendedLink, which asserts the subclass instance survives the factory and keeps the values its constructor preset.

[lyrixx]

Thanks