README

PHP 对象装饰器

一个简单的工具，用于动态地为您的PHP对象添加/修改行为

动机

有时候我们不得不打破规则，特别是在打造流畅且“神奇”的开发者体验时。这个工具可以帮助您在运行时动态添加任何新的行为，并修改PHP对象的任何 public 和 protected 方法。有了这个工具，您可以将一个愚蠢的数据持有对象变为拥有超能力的对象，在它需要的时候立即赋予它力量。

警告：元编程不是为胆小者准备的。在跳入这个特定的兔子洞之前，您真的应该探索您的所有选项。

您已经被警告了。

要求

这个库没有外部依赖。然而，它需要至少PHP 8.1.2版本。让我们使用现代技术。让我们不要使用过时的技术。此外，PHP 8.1有交集类型，它与这个库的主题搭配得非常好。

安装

composer require exsio/php-object-decorator

用法

简而言之，以下是您可以使用此工具对对象执行的操作

/**
* PHP 8.1 offers Intersection Types. 
* They prove that the Decorated Object indeed contains all the new Behaviors.
* Additionally, they allow for your IDE to properly assist you with intellisense and code completion.
* PhpDecoratedObjectInterface is always added as an additional, default Behavior to every decorated Object Instance.
*/
public function decorate(ObjectToDecorate $obj): ObjectToDecorate & PhpDecoratedObjectInterface & BehaviorInterface
{
    /**
    * Point the Decorator to the Object Instance that you want to modify.
    */
    $decorated = PhpObjectDecorator::decorate($obj)
        /**
        * Optionally, you can define a custom Class Name for the Decorated Object;
        * Otherwise it will be an original Fully Qualified Class Name with \ replaced with _ and a _PhpObjectDecorated suffix.
        */
        ->withClassName("DecoratedObject")
        /**
        * Optionally, add the Namespace to the generated Class.
        * Otherwise, the Decorated Object's Class will have no Namespace.
        */
        ->withNamespace("Exsio\PhpObjectDecorator\Examples")
        /**
        * Class Generation is expensive, you can cache the generated Class Definitions.
        * 
        * @see PhpObjectDecoratorCacheInterface
        */
        ->withCache(new DecorationCache())
        /**
        * You can add your Custom Behavior to your Object. Behavior is a pair of a PHP Interface, 
        * and a corresponding PHP Trait that implements all the methods from that Interface.
        *
        * The Tool validates whether the Trait implments all the Interface's methods and if the method declarations match.
        */
        ->withBehavior(new PhpObjectDecoratorBehavior(BehaviorInterface::class, BehaviorTrait::class))
        /**
        * You can override and customize single, named PHP Method.
        * The %CALL_PARENT% placeholder will be replaced automatically with the parent:: call to the original Method.
        *
        * The Tool validates whether the Method you want to override exists in the original Class.
        * You can't override Methods from your Behaviors. Only from the original Class (and its parents).
        */
        ->withMethodOverride(new PhpObjectDecoratorMethodOverride("methodNameToOverride",
            "
                return 'OVERRIDDEN METHOD ' . %CALL_PARENT%;
        "))
        /**
         * You can use a Method Processor to go over every public and protected Method, and modify them how you like.
         * Method Processor will skip Methods affected by Method Overrides.
         *
         * You can skip the Method by returing self::SKIP from the Processor.
         * 
         * @see PhpObjectDecoratorMethodProcessorInterface
         */
        ->withMethodProcessor(new DecorationMethodProcessor())
        /**
        * When you're ready, go ahead and build your Decorated Object.
        * 
        * @see PhpDecoratedObject
        */
        ->get();

    /**
    * Now you can get a string representation of your Decorated Class.
    * YOu can save it to a File for later usage. 
    * You can use PhpDecoratedObject::newInstanceOf() to instantiate it, 
    * or you can simply load it using an autoloader and call its Constructor.
    * 
    * @see PhpDecoratedObject::newInstanceOf()
    */
    $body = $decorated->getBody();
    
    /**
    * Or you can immediately instantiate the Decorated Class and get a handle to the Instance,
    * that has your new Behaviors.
    */
    return $decorated->newInstance();
}

有关可执行示例，请随时浏览自动化的单元测试。