yiisoft/proxy

1.0.5 2023-01-17 13:21 UTC

README

68747470733a2f2f796969736f66742e6769746875622e696f2f646f63732f696d616765732f7969695f6c6f676f2e737667

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.

Latest Stable Version Total Downloads Build status Scrutinizer Code Quality Code Coverage Mutation testing badge static analysis type-coverage

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

Open Collective

Follow updates

Official website Twitter Telegram Facebook Slack

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.