紫色的光包裹着一排透明玻璃物体,为每一个添上新的棱面。
特性 · 类扩展

为不属于你的类添加能力。

为已有的类引入接口和 trait,无需修改它们的源码,也无需构建继承层次。

扩展类的两种方式

两者都在行为类(在 API 里叫 aspect(切面))中声明,也都不会改动你的源文件。

拦截

改变已有代码执行时发生的事。

#[Around('@execution(App\Attribute\Cacheable)')]

方法保持原有签名。行为在每次调用周围运行:缓存、日志、事务。

拦截一切
Introduction

改变已有类对外提供的能力。

#[DeclareParents('within(Acme\Payments\Dto\*)', …)]

类获得一个接口以及一个 trait 的方法。已有的调用周围不会多运行任何东西;由你的代码去调用这些新方法。

查看示例
第三方类

扩展第三方类,无需 fork。

你的导出流水线接受任何 Exportable。支付 SDK 的 DTO 并没有实现它,而且它们是 final 的。与其 fork 这个包,或为每个 DTO 包一层适配器,不如用一个行为类为它们全部加上你的接口和一个可复用的 trait。

src/Contract/Exportable.php你的代码
interface Exportable{    /** @return array<string, scalar|null> */    public function toExportRow(): array;} // src/Export/ExportsPublicProperties.phptrait ExportsPublicProperties{    public function toExportRow(): array    {        return get_object_vars($this);    }}

在 includePaths 中写上这个包,它就会像你自己的代码一样被织入。织入第三方代码会增加预热时间,所以只列出你要扩展的包。

public/index.php内核
AppKernel::getInstance()->init([    // …    'includePaths' => [        __DIR__ . '/src',        __DIR__ . '/vendor/acme/payments-sdk/src',    ],]);
在应用的任何地方用法
$charge = new Charge('ch_1', 4200, 'EUR');  // a vendor DTO $charge instanceof Exportable;  // true$exporter->write($charge);       // accepts any Exportable$charge->toExportRow();          // ['id' => 'ch_1', 'amount' => 4200, 'currency' => 'EUR']
Charge.php第三方代码,原封不动

        
        
        <?php
        
        
        
      
        
        
         
        
        
        
      
        
        
        declare(strict_types=1);
        
        
        
      
        
        
         
        
        
        
      
        
        
        namespace Acme\Payments\Dto;
        
        
        
      
        
        
         
        
        
        
      
        
        
        final readonly class Charge
        final 且 readonly
        
        
      
        
        
        {
        
        
        
      
        
        
            public function __construct(
        
        
        
      
        
        
                public string $id,
        
        
        
      
        
        
                public int $amount,
        
        
        
      
        
        
                public string $currency,
        
        
        
      
        
        
            ) {}
        
        
        
      
        
        
        }
        
        
        
      
ExportAspect.php你的行为类

        
        
        <?php
        
        
        
      
        
        
         
        
        
        
      
        
        
        declare(strict_types=1);
        
        
        
      
        
        
         
        
        
        
      
        
        
        namespace App\Aspect;
        
        
        
      
        
        
         
        
        
        
      
        
        
        use App\Contract\Exportable;
        
        
        
      
        
        
        use App\Export\ExportsPublicProperties;
        
        
        
      
        
        
        use Go\Aop\Aspect;
        
        
        
      
        
        
        use Go\Lang\Attribute\DeclareParents;
        
        
        
      
        
        
         
        
        
        
      
        
        
        final class ExportAspect implements Aspect
        
        
        
      
        
        
        {
        
        
        
      
        
        
            #[DeclareParents('within(Acme\Payments\Dto\*)', interfaceName: Exportable::class, traitName: ExportsPublicProperties::class)]
        这个包的每个 DTO
        
        
      
        
        
            protected null $exportable;
        
        
        
      
        
        
        }
        
        
        
      
Charge.php生成

        
        
        <?php
        
        
        
      
        
        
        declare(strict_types=1);
        
        
        
      
        
        
        namespace Acme\Payments\Dto;
        
        
        
      
        
        
         
        
        
        
      
        
        
        use Go\Aop\Framework\InterceptorInjector;
        
        
        
      
        
        
        use Go\Aop\Framework\Interceptor;
        
        
        
      
        
        
        use Go\Aop\Framework\The;
        
        
        
      
        
        
        final readonly class Charge implements \App\Contract\Exportable, \Go\Aop\Proxy
        你的接口
        
        
      
        
        
        {
        
        
        
      
        
        
            use ChargeOriginalTrait, \App\Export\ExportsPublicProperties;
        你的 trait
        
        
      
        
        
        }
        
        
        
      

不靠继承的扩展

更多内容见 docs/advices.md 和 docs/configuration.md。

  • 无需维护 fork

    包保持 Composer 安装时的原样。更新照常通过 composer update 到来,下一次缓存预热会再次织入它们。

  • final 和 readonly 类也可以

    类保留它的名称、修饰符和父类。接口和 trait 加在这个类本身上,而不是加在子类上。

  • 真正的接口

    instanceof 和类型声明都能正常工作,因为 PHP 加载的类确实实现了这个接口。