Annotation syntax
#[Route]
#[Route()]
#[Route("/path", ["get"])]
#[Route(path: "/path", methods: ["get"])]
In fact, the syntax is very similar to the instantiated class, except that the new keyword is missing.
It should be noted that the annotation name cannot be a variable, but can only be a constant or constant expression
//实例化类 $route = new Route(path: "/path", methods: ["get"]);
(path: "/path", methods : ["get"]) is the new syntax of php8. When passing parameters, you can specify the parameter name and do not pass the parameters in the order of the formal parameters.
Annotation class scope
When defining an annotation class, you can use the built-in annotation class#[Attribute] to define the scope of the annotation class, or you can omit it,The scope is automatically defined by PHP dynamically based on usage scenarios.
Annotation scope list:
- Attribute::TARGET_CLASS
- Attribute::TARGET_FUNCTION
- Attribute::TARGET_METHOD
- Attribute::TARGET_PROPERTY
- Attribute::TARGET_CLASS_CONSTANT
- Attribute::TARGET_PARAMETER
- Attribute::TARGET_ALL
- Attribute::IS_REPEATABLE
When used,#[Attribute]is equivalent to#[Attribute(Attribute::TARGET_ALL)]. For convenience, the former is generally used.
1~7 are all easy to understand and correspond to classes, functions, class methods, class attributes, class constants, parameters, and everything respectively. The first 6 items can be combined at will using | or operators , such as Attribute::TARGET_CLASS | Attribute::TARGET_FUNCTION. (Attribute::TARGET_ALLcontains the first 6 items, but does not contain Attribute::IS_REPEATABLE).
Attribute::IS_REPEATABLE Set whether the annotation can be repeated, for example:
class IndexController
{
#[Route('/index')]
#[Route('/index_alias')]
public function index()
{
echo "hello!world" . PHP_EOL;
}
}
If Attribute::IS_REPEATABLE is not set, Route Two uses are not allowed.
As mentioned above, if the scope is not specified, PHP will dynamically determine the scope. How to understand? Example:
<?php
class Deprecated
{
}
class NewLogger
{
public function newLogAction(): void
{
//do something
}
#[Deprecated('oldLogAction已废弃，请使用newLogAction代替')]
public function oldLogAction(): void
{
}
}
#[Deprecated('OldLogger已废弃，请使用NewLogger代替')]
class OldLogger
{
}The above-mentioned custom annotation classDeprecated does not use the built-in annotation class#[Attribute] to define the scope, so when it modifies the class OldLogger, its scope is dynamically defined as TARGET_CLASS. When it modifies method oldLogAction, its scope is dynamically defined as TARGET_METHOD. In one sentence, where it is modified, its scope will be
It should be noted that after setting the scope, during the compilation phase, in addition to the built-in annotation class #[Attribute], custom annotation classes will not automatically check the scope. Unless you use the newInstance method of the reflection class ReflectionAttribute.
Example:
<?php
#[Attribute]
function foo()
{
}An error will be reported hereFatal error: Attribute "Attribute" cannot target function (allowed targets: class), because of the role of the built-in annotation class The scope is TARGET_CLASS, which can only be used to modify classes and not functions. Because the scope of the built-in annotation class is only TARGET_CLASS, so cannot be modified repeatedly.
The scope of custom annotation classes will not be checked at compile time.
<?php
#[Attribute(Attribute::TARGET_CLASS)]
class A1
{
}
#[A1]
function foo() {}This way no error will be reported. So what’s the point of defining scope? Let’s look at a comprehensive example.
<?php
#[Attribute(Attribute::TARGET_METHOD | Attribute::TARGET_FUNCTION | Attribute::IS_REPEATABLE)]
class Route
{
protected $handler;
public function __construct(
public string $path = '',
public array $methods = []
) {}
public function setHandler($handler): self
{
$this->handler = $handler;
return $this;
}
public function run()
{
call_user_func([new $this->handler->class, $this->handler->name]);
}
}
class IndexController
{
#[Route(path: "/index_alias", methods: ["get"])]
#[Route(path: "/index", methods: ["get"])]
public function index(): void
{
echo "hello!world" . PHP_EOL;
}
#[Route("/test")]
public function test(): void
{
echo "test" . PHP_EOL;
}
}
class CLIRouter
{
protected static array $routes = [];
public static function setRoutes(array $routes): void
{
self::$routes = $routes;
}
public static function match($path)
{
foreach (self::$routes as $route) {
if ($route->path == $path) {
return $route;
}
}
die('404' . PHP_EOL);
}
}
$controller = new ReflectionClass(IndexController::class);
$methods = $controller->getMethods(ReflectionMethod::IS_PUBLIC);
$routes = [];
foreach ($methods as $method) {
$attributes = $method->getAttributes(Route::class);
foreach ($attributes as $attribute) {
$routes[] = $attribute->newInstance()->setHandler($method);
}
}
CLIRouter::setRoutes($routes);
CLIRouter::match($argv[1])->run();
php test.php /index php test.php /index_alias php test.php /test
The defined scope will only take effect when using newInstance. It is checked whether the scope defined by the annotation class is consistent with the actual modified scope. Other scenarios are not tested.
Annotation namespace
<?php
namespace {
function dump_attributes($attributes) {
$arr = [];
foreach ($attributes as $attribute) {
$arr[] = ['name' => $attribute->getName(), 'args' => $attribute->getArguments()];
}
var_dump($arr);
}
}
namespace Doctrine\ORM\Mapping {
class Entity {
}
}
namespace Doctrine\ORM\Attributes {
class Table {
}
}
namespace Foo {
use Doctrine\ORM\Mapping\Entity;
use Doctrine\ORM\Mapping as ORM;
use Doctrine\ORM\Attributes;
#[Entity("imported class")]
#[ORM\Entity("imported namespace")]
#[\Doctrine\ORM\Mapping\Entity("absolute from namespace")]
#[\Entity("import absolute from global")]
#[Attributes\Table()]
function foo() {
}
}
namespace {
class Entity {}
dump_attributes((new ReflectionFunction('Foo\foo'))->getAttributes());
}
//输出：
array(5) {
[0]=>
array(2) {
["name"]=>
string(27) "Doctrine\ORM\Mapping\Entity"
["args"]=>
array(1) {
[0]=>
string(14) "imported class"
}
}
[1]=>
array(2) {
["name"]=>
string(27) "Doctrine\ORM\Mapping\Entity"
["args"]=>
array(1) {
[0]=>
string(18) "imported namespace"
}
}
[2]=>
array(2) {
["name"]=>
string(27) "Doctrine\ORM\Mapping\Entity"
["args"]=>
array(1) {
[0]=>
string(23) "absolute from namespace"
}
}
[3]=>
array(2) {
["name"]=>
string(6) "Entity"
["args"]=>
array(1) {
[0]=>
string(27) "import absolute from global"
}
}
[4]=>
array(2) {
["name"]=>
string(29) "Doctrine\ORM\Attributes\Table"
["args"]=>
array(0) {
}
}
}
is consistent with the namespace of ordinary classes.
Some other issues to pay attention to
-
You cannot use the
unpacksyntax in the annotation class parameter list.
<?php
class IndexController
{
#[Route(...["/index", ["get"]])]
public function index()
{
}
}Although the lexical parsing stage is passed, an error will be thrown during the compilation stage.
- You can wrap lines when using annotations
<?php
class IndexController
{
#[Route(
"/index",
["get"]
)]
public function index()
{
}
}- Annotations can be used in groups
<?php
class IndexController
{
#[Route(
"/index",
["get"]
), Other, Another]
public function index()
{
}
}- Inheritance of annotations
Annotations can be inherited or overridden.
<?php
class C1
{
#[A1]
public function foo() { }
}
class C2 extends C1
{
public function foo() { }
}
class C3 extends C1
{
#[A1]
public function bar() { }
}
$ref = new \ReflectionClass(C1::class);
print_r(array_map(fn ($a) => $a->getName(), $ref->getMethod('foo')->getAttributes()));
$ref = new \ReflectionClass(C2::class);
print_r(array_map(fn ($a) => $a->getName(), $ref->getMethod('foo')->getAttributes()));
$ref = new \ReflectionClass(C3::class);
print_r(array_map(fn ($a) => $a->getName(), $ref->getMethod('foo')->getAttributes()));
C3 inherits the foo method of C1 and also inherits the annotations of foo. And C2 covers the foo method of C1, so the annotation does not exist.