Фиолетовый свет обволакивает ряд прозрачных стеклянных предметов и даёт каждому новую грань.
Возможность · Расширения классов

Расширяйте возможности классам, которые вам не принадлежат.

Добавляйте интерфейсы и трейты существующим классам, не изменяя их исходный код и не выстраивая иерархии наследования.

Два способа расширить класс

Оба объявляются в классе поведений (в API — aspect, аспект), и оба не трогают ваши исходные файлы.

Перехват

Меняет то, что происходит при выполнении существующего кода.

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

Метод сохраняет сигнатуру. Вокруг каждого вызова выполняется поведение: кеширование, логирование, транзакции.

Перехват чего угодно
Внедрение

Меняет то, какие возможности дают существующие классы.

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

Класс получает интерфейс и методы трейта. Вокруг существующих вызовов ничего не выполняется: ваш код вызывает новые методы.

Посмотреть пример
Сторонние классы

Расширяйте vendor-классы без форка.

Ваш конвейер экспорта принимает всё, что реализует Exportable. DTO платёжного SDK его не реализуют, к тому же они final. Вместо того чтобы форкать пакет или оборачивать каждый DTO в адаптер, один класс поведений добавляет им всем ваш интерфейс и переиспользуемый трейт.

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, чтобы он компилировался как ваш собственный код. Компиляция vendor-кода удлиняет прогрев, поэтому перечисляйте только те пакеты, которые расширяете.

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.phpvendor, без изменений

        
        
        <?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;
        ваш трейт
        
        
      
        
        
        }
        
        
        
      

Поведение без наследования

Подробнее — в docs/advices.md и docs/configuration.md.

  • Не нужно поддерживать форк

    Пакет остаётся таким, каким его установил Composer. Обновления по-прежнему приходят через composer update, а следующий прогрев кеша снова их компилирует.

  • И final-, и readonly-классы

    Класс сохраняет имя, модификаторы и родителей. Интерфейс и трейт добавляются ему самому, а не подклассу.

  • Настоящий интерфейс

    instanceof и объявления типов работают, потому что класс, который загружает PHP, действительно его реализует.