README

此包提供了一种轻松使用和应用 PHP 8 属性的方法，并允许快速实现与元数据或注释相关的功能，如路由、事件、数据库关系。

功能

将 PHP 8 属性应用于类及其组件
自动将属性应用于自动加载的类
限制属性以过滤类名、命名空间或类反射的条件

查看下一版本的即将推出的功能。

概念

php-attributes 使用装饰过的 composer 自动加载器，并通过加载的类名通知处理程序。使用反射解析类组件的属性。

此包支持以下属性的属性

类
类常量
类方法
类方法参数
类属性。

安装

通过 Composer

$ composer require mbunge/php-attributes

用法

通过工厂 PhpAttributes\PhpAttributesFactory::createResolver() 或直接实例化属性处理程序 Mbunge\PhpAttributes\AttributeResolver。

通过将类名作为字符串传递给 Mbunge\PhpAttributes\Resolver\AttributeResolver::resolve(string $class) 来解析目标类组件的属性。

所有解析的属性都作为数据传输对象 (dto) Mbunge\PhpAttributes\Resolver\ResolvedAttributesDto 的数组返回。

<?php

use Mbunge\PhpAttributes\PhpAttributesFactory;

// instantiate via factory
$handler = (new PhpAttributesFactory())->createResolver();

// instantiate direct
$handler = new Mbunge\PhpAttributes\AttributeResolver();

/** @var \Mbunge\PhpAttributes\Resolver\ResolvedAttributeDto[] $result */
// via string
$result = $handler->resolve('\MyProject\MyClassWithAttributes');

// or via class name
$result = $handler->resolve(\MyProject\MyClassWithAttributes::class);

运行多个解析器

\Mbunge\PhpAttributes\Resolver\ChainedAttributeResolver 接收一个解析器列表，执行每个解析器并合并解析结果。

当需要同时执行具有不同上下文的解析器时，这很有用。

<?php

use Mbunge\PhpAttributes\Resolver\ChainedAttributeResolver;

$resolvers = [
    new CustomAttributeResolver(),
    new AnotherAttributeResolver(),
    // ...
];

$resolver = new ChainedAttributeResolver($resolvers);

// receive results from CustomerAttributeResolver and AnotherAttributeResolver
$results = $resolver->resolve('MyProject\AnyClass');

限制属性以过滤类名、命名空间或类反射的条件

Mbunge\PhpAttributes\Resolver\FilterClassAttributeResolverDecorator 使用任何可调用的过滤器装饰属性处理程序实例。

<?php

use Mbunge\PhpAttributes\Resolver\FilterClassAttributeResolverDecorator;

// instantiate base handler
$handler = new Mbunge\PhpAttributes\AttributeResolver();

// instantiate filter decorator with filter given as callable
$decoratedResolver = new FilterClassAttributeResolverDecorator(
    $handler,
    fn(string $className) => str_starts_with($className, 'MyProject')
);

// Attribute resolves only if filter condition matches
$result = $decoratedResolver
    ->resolve(\MyProject\MyClassWithAttributes::class);

有关过滤器的示例，请参阅 FilterClassAttributeResolverDecoratorTest。

呈现解析的属性

解析的属性提供声明的元数据。

将解析的属性传递给呈现器并执行特定于上下文的操作。

示例

所有示例都使用一个小型应用程序实现。

使用事件分派器感知的自动订阅事件监听器和呈现器。

链式呈现器

\Mbunge\PhpAttributes\Presenter\ChainedAttributePresenter 接收一个呈现器列表，执行每个呈现器并合并结果。

当需要将属性呈现给不同的上下文时，这很有用，例如应用程序路由、事件分派器等。

请参阅 ChainedAttributePresenterTest 以获取详细实现。

属性处理程序

避免蓝图代码并使用处理程序来解析属性并在之后呈现它们。

<?php

use Mbunge\PhpAttributes\AttributeHandler;
use Mbunge\PhpAttributes\PhpAttributesFactory;

/** @var ClassLoader $loader */
$loader = require __DIR__ . '/vendor/autoload.php';

// optionally pass a handler to handler
// You may add custom handler behaviour or a custom handler at this point
$handler = new AttributeHandler(
    (new PhpAttributesFactory())->createResolver(),
    new NullAttributePresenter()
);

$handler->handle('MyProject\MyClass');

自动将属性应用于自动加载的类

该库提供了一个 composer 类加载器装饰器，该装饰器扩展了 composer 自动加载器，可以在类被自动加载时执行属性处理程序。

有关打包的自动加载的更多信息，请参阅 autoload。

<?php

use Composer\Autoload\ClassLoader;
use Mbunge\PhpAttributes\AttributeHandler;
use Mbunge\PhpAttributes\LoaderHandler;
use Mbunge\PhpAttributes\PhpAttributesFactory;

/** @var ClassLoader $loader */
$loader = require __DIR__ . '/vendor/autoload.php';

// optionally pass a handler to handler
// You may add custom handler behaviour or a custom handler at this point
$attributeHandler = new AttributeHandler(
    (new PhpAttributesFactory())->createResolver(),
    new NullAttributePresenter()
);

$handler = new LoaderHandler($attributeHandler);

return $handler->handle($loader);

// optionally avoid unregister of previous autoloader
// it is recommanded to keep only one autoloader, since previous autoloader will be unreachable
return $handler->handle($loader, false);

使用打包的自动加载

将 composer 默认自动加载 /vendor/autoload 替换为打包的自动加载 /vendor/mbunge/php-attributes/autoload.php。

打包的自动加载将所有属性应用于自动加载的类。

<?php

require_once __DIR__ . '/vendor/mbunge/php-attributes/autoload.php';

注意事项

PHP 8 属性并不能解决所有问题。

通过元数据声明自动应用逻辑听起来很酷，但需要很多约定，这可能导致复杂性，并且可能难以调试！

由于属性某种程度上是一种依赖，SOLID原则可能会被违反。仅在使用属性进行有用任务且不违反代码整洁原则的情况下使用属性！

此外，提供属性分析和调试的命令行工具很有帮助。

变更日志

有关最近更改的更多信息，请参阅变更日志。

测试

$ composer test

贡献

有关详细信息，请参阅贡献指南和行为准则。

部署

只有维护者才能部署新版本！

运行composer run release，这将运行测试，并在成功后更新变更日志、包版本并创建发布标签
切换到master分支并合并develop分支
运行composer run deploy，这将运行测试，并在成功后推送标签、master分支和develop分支

安全

如果您发现任何与安全相关的问题，请通过电子邮件marco_bunge@web.de联系，而不是使用问题跟踪器。

鸣谢

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。

进一步阅读

由stitcher.io深入探讨的PHP属性：https://www.stitcher.io/blog/attributes-in-php-8

mbunge / php-attributes

维护者

详细信息