PHP: rfc:reflectionattribute-getcurrent

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== PHP RFC: Add ReflectionAttribute::getCurrent() ======
  * Version: 0.1
  * Date: 2026-04-19
  * Author: Daniel Scherzer, daniel.e.scherzer@gmail.com
  * Status: Draft
  * Implementation: https://github.com/php/php-src/pull/21440

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 a new static method, <php>ReflectionAttribute::getCurrent()</php>, that, //when called from an attribute constructor//, returns a reflection object corresponding to what the attribute was 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 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 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 a PHP-provided replacement, <php>ReflectionAttribute::getCurrent()</php>. This 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();
	}
}

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

}

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

?>
</PHP>

===== Proposal =====

When called from the constructor of an attribute, the method will return one of the following, depending on what item the attribute was applied to. Attributes can be applied to different types of items depending on the <php>Attribute::TARGET_*</php> flags, and even among the same type of item the reflection extension sometimes has more specific classes to use

^ 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 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, the return type will be declared with a new interface, <php>ReflectionAttributeTarget</php>, that 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 static function getCurrent(): ReflectionAttributeTarget {}
}

?>
</PHP>

==== Examples ====

Simple example:
<PHP>
<?php

#[Attribute(Attribute::TARGET_CLASS)]
class StableInterface {
	public function __construct() {
		$target = ReflectionAttribute::getCurrent();
		// Only targets classes
		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.

===== 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 =====
Make sure there are no open issues when the vote starts!

==== Behavior on failure ===

When <php>ReflectionAttribute::getCurrent()</php> is //not// called from the constructor of an attribute being instantiated via <php>ReflectionAttribute::newInstance()</php>, should it throw an exception, or return null?

===== Future Scope =====

Now that <php>ReflectionAttribute</php> knows what it is being applied to, maybe there would be a way to retrieve that information directly from an instance of <php>ReflectionAttribute</php>

===== Voting Choices =====
Add <php>ReflectionAttribute::getCurrent()</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
Page Tools
