====== PHP RFC: Add ReflectionAttribute::getCurrent() ======
  * Version: 0.3
  * Date: 2026-04-19
  * Author: Daniel Scherzer, daniel.e.scherzer@gmail.com
  * Status: Under discussion
  * Implementation: https://github.com/php/php-src/pull/21440
  * Discussion thread: https://news-web.php.net/php.internals/130766

Userland attributes (i.e. attributes not provided by PHP itself or an extension) are created with <php>ReflectionAttribute::newInstance()</php> and have their constructors called with the arguments provided to the attribute. However, they lack addition context as to what they are being applied to. While it is possible to hack around with <php>debug_backtrace</php> to identify the original <php>ReflectionAttribute</php> instance, and thus the type of construct the attribute is applied to (class, class constant, etc.) there is no way to identify //which// class (or class constant, etc.) the attribute is being applied to.

This RFC proposes the addition of two new methods:

  * <php>ReflectionAttribute::getReflectionTarget()</php> allows identifying the target of an attribute represented by a <php>ReflectionAttribute</php> instance
  * the static method <php>ReflectionAttribute::getCurrent()</php>, //when called from an attribute constructor//, returns the <php>ReflectionAttribute</php> corresponding to the attribute usage

Together, these methods allow an attribute constructor to identify the target it is applied to.

For the purposes of this RFC, an "item" is something that can have attributes applied to it, including classes, functions, parameters, constants, etc.

===== Introduction =====

Attributes were first introduced in [[rfc:attributes_v2]] in PHP 8.0, with the current syntax adopted [[rfc:shorter_attribute_syntax_change]]. Userland attributes provide a way to add metadata to items in a structured way that can be read by external tools using reflection.

However, userland attributes, when created via <php>ReflectionAttribute::newInstance()</php>, only know about the arguments passed to the attribute when it was applied. Backtracing hacking can be used to identify the <php>ReflectionAttribute</php> object that was used, and from there <php>ReflectionAttribute::getTarget()</php> could be used to identify what type of item the attribute was applied to, but not which specific item.

Various workarounds exist in userland, such as:

  * the [[https://github.com/Crell/AttributeUtils|Crell/AttributeUtils]] composer library, which provides interfaces (e.g. <php>FromReflectionClass</php>) that indicate an attribute wants to be told what item (e.g. for <php>FromReflectionClass</php>, what class) the attribute was applied to. This information is provided after the attribute is constructed, and only when the attribute is loaded through the library.
  * adding manual <php>::tryFrom</php> static constructors to use (e.g. Symfony/console's attributes like [[https://github.com/symfony/console/blob/ad665e88b844414e81707b0a33dfe757c65393f7/Attribute/Option.php#L60|Option]])

However, these rely on using an external library or creating attributes separately from <php>ReflectionAttribute::newInstance()</php>. This RFC proposes two new methods; the first, <php>ReflectionAttribute::getReflectionTarget()</php>, allows associating a <php>ReflectionAttribute</php> with the specific target it was applied to, rather than just the type of target. The second, <php>ReflectionAttribute::getCurrent()</php>, abstracts away the backtrace hacking. These would allow attributes to add custom validation or otherwise make use of the information about what item they were applied to:

<PHP>
<?php
#[Attribute]
class Demo {
    public function __construct($args) {
        // will echo the same ReflectionClass that `echo $case;` does below
        // this is a contrived example, real world code would do something useful
        echo ReflectionAttribute::getCurrent()->getReflectionTarget();
    }
}

#[Demo("class")]
class WithDemo {

}

$case = new ReflectionClass(WithDemo::class);
echo $case;
echo "\n";
$case->getAttributes()[0]->newInstance();

?>
</PHP>

===== Proposal =====

When called within the constructor of an attribute object, <php>ReflectionAttribute::getCurrent()</php> will return a <php>ReflectionAttribute</php> that corresponds to the attribute application.

Anywhere that a <php>ReflectionAttribute</php> object is available (now including attribute constructors), <php>ReflectionAttribute::getReflectionTarget()</php> returns the reflection object of the item to which the attribute was attached.  The type of that reflection object is highly variable, as there are many types of item to which an attribute may be attached, and there is not a 1:1 correspondence between the <php>Attribute::TARGET_*</php> constant used and the resulting reflection object type.

For example, a <php>Attribute::TARGET_CLASS_CONSTANT</php> attribute could be applied to a class constant, unit enum case, or backed enum case, which would result in <php>ReflectionClassConstant</php>, <php>ReflectionEnumUnitCase</php>, or <php>ReflectionEnumBackedCase</php>, respectively.

To avoid a huge union return type, and to account for potential future expansions of attribute targets (e.g. [[rfc:attributes-on-constants]]) or new reflection subclasses, this RFC introduces a new interface, <php>ReflectionAttributeTarget</php>, which represents "things that can have attributes" or "things that an attribute can be applied to".

Thus, the additions in this RFC look like the following (classes that implement <php>Reflector</php> did so previously, and are just updated to also implement <php>ReflectionAttributeTarget</php>)

<PHP>
<?php

interface ReflectionAttributeTarget extends Reflector
{
    public function getAttributes(?string $name = null, int $flags = 0): array {}
}

// ...

abstract class ReflectionFunctionAbstract implements Reflector, ReflectionAttributeTarget { /* ... */ }
class ReflectionClass implements Reflector, ReflectionAttributeTarget { /* ... */ }
class ReflectionProperty implements Reflector, ReflectionAttributeTarget { /* ... */ }
class ReflectionClassConstant implements Reflector, ReflectionAttributeTarget { /* ... */ }
class ReflectionParameter implements Reflector, ReflectionAttributeTarget { /* ... */ }
class ReflectionConstant implements Reflector, ReflectionAttributeTarget { /* ... */ }

class ReflectionAttribute implements Reflector
{
    // ...
    public function getReflectionTarget(): ReflectionAttributeTarget {}

    public static function getCurrent(): ReflectionAttribute {}
}

?>
</PHP>

When using the result of <php>ReflectionAttribute::getReflectionTarget()</php>, the developer may either <php>assert()</php> the type of the reflection object and/or use an <php>instanceof</php> check, as appropriate, if the logic depends on the type, or to provide information to static analysis tools and IDEs.  For example, if an attribute may be placed on a class or method, it could check that like so:

<code php>
#[Attribute(Attribute::TARGET_CLASS)]
class SingleTargetAttribute {
    public function __construct() {
        // SA tools won't know what type $target is,
        // beyond ReflectionAttributeTarget
        $target = ReflectionAttribute::getCurrent()->getReflectionTarget();
        
        assert($target instanceof ReflectionClass);
        // Now SA tools know that $target is ReflectionClass, and can
        // offer appropriate code completion and validation.
        
        // More stuff here.
    }
}


#[Attribute(Attribute::TARGET_CLASS|Attribute::TARGET_METHOD)]
class MultiUseAttribute {
    public function __construct() {
        $target = ReflectionAttribute::getCurrent()->getReflectionTarget();
        if ($target instanceof ReflectionClass) {
            // Do class-specific logic here.
        } else if ($target instanceof ReflectionMethod) {
            // Do method-specific logic here.
        }
        // Do logic common to all attributes here.
    }
}
</code>

==== Examples ====

Simple example:
<PHP>
<?php

#[Attribute(Attribute::TARGET_CLASS)]
class StableInterface {
    public function __construct() {
        $target = ReflectionAttribute::getCurrent()->getReflectionTarget();
        // For SA tools:
        assert($target instanceof ReflectionClass);
        
        // Should only be applied to interfaces
        if (!$target->isInterface()) {
            throw new Exception("#[StableInterface] is only for interfaces!");
        }
        
        // Some global function that exists elsewhere
        record_stable_interface($target->getName());
    }
}

?>
</PHP>

The above attribute, when instantiated, will confirm that it is being applied to an interface (rather than a class, trait, or enum) and then record the name of the targeted interface. This could then be used by tools to automatically generate a list of interfaces in a library that are considered stable, perhaps with the help of the [[https://github.com/olvlvl/composer-attribute-collector|olvlvl/composer-attribute-collector library]].

<php>ReflectionAttribute::getCurrent()</php> must be called directly from the constructor of an attribute that is being instantiated with <php>ReflectionAttribute::newInstance()</php>, otherwise it fails.

==== Returned classes ====

<php>ReflectionAttribute::getReflectionTarget()</php> is documented on a type level to return <php>ReflectionAttributeTarget</php>, but the actual underlying class will be:

^ Flag                                        ^ Applied to         ^ Return type                          ^
| <php>Attribute::TARGET_CLASS</php>          | Class              | <php>ReflectionClass</php>           |
| <php>Attribute::TARGET_CLASS</php>          | Trait              | <php>ReflectionClass</php>           |
| <php>Attribute::TARGET_CLASS</php>          | Interface          | <php>ReflectionClass</php>           |
| <php>Attribute::TARGET_CLASS</php>          | Enum               | <php>ReflectionEnum</php>            |
| <php>Attribute::TARGET_METHOD</php>         | Class method       | <php>ReflectionMethod</php>          |
| <php>Attribute::TARGET_CLASS_CONSTANT</php> | Class constant     | <php>ReflectionClassConstant</php>   |
| <php>Attribute::TARGET_CLASS_CONSTANT</php> | Enum case (unit)   | <php>ReflectionEnumUnitCase</php>    |
| <php>Attribute::TARGET_CLASS_CONSTANT</php> | Enum case (backed) | <php>ReflectionEnumBackedCase</php>  |
| <php>Attribute::TARGET_PROPERTY</php>       | Class property     | <php>ReflectionProperty</php>        |
| <php>Attribute::TARGET_FUNCTION</php>       | Global function    | <php>ReflectionFunction</php>        |
| <php>Attribute::TARGET_PARAMETER</php>      | Function parameter | <php>ReflectionParameter</php>       |
| <php>Attribute::TARGET_PARAMETER</php>      | Method parameter   | <php>ReflectionParameter</php>       |
| <php>Attribute::TARGET_CONSTANT</php>       | Global constant    | <php>ReflectionConstant</php>        |

Note that

  * <php>ReflectionEnum</php> is a subclass of <php>ReflectionClass</php>
  * <php>ReflectionEnumBackedCase</php> is a subclass of <php>ReflectionEnumUnitCase</php> which is a subclass of <php>ReflectionClassConstant</php>

To be clear, even when the <php>ReflectionAttribute</php> was retrieved from a different type, the return type will be the type listed in the table above. For example, using <php>ReflectionClassConstant</php> with an enum case works fine, but <php>ReflectionAttribute::getReflectionTarget()</php> will return the enum-specific subclass. Similarly, <php>ReflectionObject</php> can be used for classes and enums, but <php>ReflectionClass</php> or <php>ReflectionEnum</php> will be returned from <php>ReflectionAttribute::getReflectionTarget()</php>

===== Backward Incompatible Changes =====
None

===== Proposed PHP Version(s) =====
Next minor version (PHP 8.6).

===== RFC Impact =====
==== To the Ecosystem ====
Attribute-related libraries may want to make use of the new feature.

==== To Existing Extensions ====
Only ext/reflection is affected - all of this is implemented in reflection.

==== To SAPIs ====
None

===== Open Issues =====
None

===== Voting Choices =====
Add <php>ReflectionAttribute::getCurrent()</php>, <php>ReflectionAttribute::getReflectionTarget()</php> and the associated <php>ReflectionAttributeTarget</php> interface?

----

Primary Vote requiring a 2/3 majority to accept the RFC:

<doodle title="Add ReflectionAttribute::getCurrent() as outlined in the RFC?" voteType="single" closed="true" closeon="2026-01-01T15:30:00Z">
   * Yes
   * No
   * Abstain
</doodle>

===== Patches and Tests =====

https://github.com/php/php-src/pull/21440

===== Implementation =====
After the RFC is implemented, this section should contain:
  - the version(s) it was merged into
  - a link to the git commit(s)
  - a link to the PHP manual entry for the feature

===== References =====

  * [[rfc:attributes_v2]]
  * [[rfc:shorter_attribute_syntax_change]]
  * [[rfc:attributes-on-constants]]
  * https://github.com/Crell/AttributeUtils
  * https://github.com/olvlvl/composer-attribute-collector
  * Symfony/console (https://github.com/symfony/console/tree/ad665e88b844414e81707b0a33dfe757c65393f7)
  * Previous mailing list discussion: https://externals.io/message/120443

===== Rejected Features =====
Keep this updated with features that were discussed on the mail lists.

===== Changelog =====
If there are major changes to the initial proposal, please include a short summary with a date or a link to the mailing list announcement here, as not everyone has access to the wikis' version history.

  * v0.1: created
  * v0.2: updates with improvements from Crell
  * v0.3: switch from having just a static method, <php>ReflectionAttribute::getCurrent(): ReflectionAttributeTarget</php>, to a static method, <php>ReflectionAttribute::getCurrent(): ReflectionAttribute</php> and an instance method <php>ReflectionAttribute::getReflectionTarget(): ReflectionAttributeTarget</php>