README

Yii Proxy

The package is able to build generic proxy for a class i.e. it allows intercepting all class method calls. It's used in yii-debug package to collect service's method calls information.

For license information check the LICENSE-file.

Installation

The preferred way to install this extension is through Сomposer.

composer require --prefer-dist yiisoft/proxy

Usage

Custom base proxy class

Custom base proxy class is useful to perform certain actions during each method call.

use Yiisoft\Proxy\ObjectProxy;

class MyProxy extends ObjectProxy
{
    protected function afterCall(string $methodName, array $arguments, mixed $result, float $timeStart) : mixed {
        $result = parent::afterCall($methodName, $arguments, $result, $timeStart);
        
        $error = $this->getCurrentError(); // Use to track and handle errors. 
        $time = microtime(true) - $timeStart; // Use to measure / log execution time.
        
        return $result;
    }
}

Additionally, you can customize new instance creation, etc. See examples in yii-debug extension.

Class with interface

Having an interface and class implementing it, the proxy can be created like this:

use Yiisoft\Proxy\ProxyManager;

interface CarInterface
{
    public function horsepower(): int;
}

class Car implements CarInterface
{
    public function horsepower(): int
    {
        return 1;
    }
}

$path = sys_get_temp_dir();
$manager = new ProxyManager(
    // This is optional. The proxy can be created "on the fly" instead. But it's recommended to specify path to enable
    // caching.
    $path
);
/** @var Car|MyProxy $object */
$object = $manager->createObjectProxy(
    CarInterface::class,
    MyProxy::class, // Custom base proxy class defined earlier.
    [new Car()]
);
// Now you can call `Car` object methods through proxy the same as you would call it in original `Car` object.
$object->horsepower(); // Outputs "1".

Class without interface

An interface is not required though, the proxy still can be created almost the same way:

use Yiisoft\Proxy\ProxyManager;

class Car implements CarInterface
{
    public function horsepower(): int
    {
        return 1;
    }
}

$path = sys_get_temp_dir();
$manager = new ProxyManager($path);
/** @var Car|MyProxy $object */
$object = $manager->createObjectProxy(
    Car::class, // Pass class instead of interface here. 
    MyProxy::class, 
    [new Car()]
);

Proxy class contents

Here is an example how proxy class looks internally:

class CarProxy extends MyProxy implements CarInterface
{
    public function horsepower(): int
    {
        return $this->call('horsepower', []);
    }
}

Unit testing

The package is tested with PHPUnit. To run tests:

./vendor/bin/phpunit

Mutation testing

The package tests are checked with Infection mutation framework. To run it:

./vendor/bin/infection

Static analysis

The code is statically analyzed with Psalm. To run static analysis:

./vendor/bin/psalm

Support the project

Follow updates

License

The Yiisoft Proxy is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

yiisoft / proxy

Maintainers

Details