lucciano / proxymanager

OOP Proxy wrappers utilities - generates and manages proxies of your objects

Proxy Manager

This library aims at providing abstraction for generating various kinds of proxy classes.

Currently, this project supports generation of Virtual Proxies and Smart References. Additionally, it can generate a small high-performance Hydrator class to optimize transition of data from and into your objects.

Installation

The suggested installation method is via composer:

php composer.phar require ocramius/proxy-manager:0.4.*

Lazy Loading Value Holders (Virtual Proxy)

ProxyManager can generate lazy loading value holders, which are virtual proxies capable of saving performance and memory for objects that require a lot of dependencies or CPU cycles to be loaded: particularly useful when you may not always need the object, but are constructing it anyways.

$config  = new \ProxyManager\Configuration(); // customize this if needed for production
$factory = new \ProxyManager\Factory\LazyLoadingValueHolderFactory($config);

$proxy = $factory->createProxy(
    'MyApp\HeavyComplexObject',
    function (& $wrappedObject, $proxy, $method, $parameters, & $initializer) {
        $wrappedObject = new HeavyComplexObject(); // instantiation logic here
        $initializer   = null; // turning off further lazy initialization
    
        return true;
    }
);

$proxy->doFoo();

See the complete documentation about lazy loading value holders in the docs/ directory.

Access Interceptors

An access interceptor is a smart reference that allows you to execute logic before and after a particular method is executed or a particular property is accessed, and it allows to manipulate parameters and return values depending on your needs.

$config  = new \ProxyManager\Configuration(); // customize this if needed for production
$factory = new \ProxyManager\Factory\AccessInterceptorValueHolderFactory($config);

$proxy = $factory->createProxy(
    new \My\Db\Connection(),
    array('query' => function () { echo "Query being executed!\n"; }),
    array('query' => function () { echo "Query completed!\n"; })
);

$proxy->query(); // produces "Query being executed!\nQuery completed!\n"

See the complete documentation about access interceptor value holders in the docs/ directory.

Fallback Value Holders

A fallback value holder is a particular value holder that implements the null object pattern.

This kind of value holder allows you to have fallback logic in case loading of the wrapped value failed.

This feature is planned.

Ghost Objects

Similar to value holder, a ghost object is usually created to handle lazy loading.

The difference between a value holder and a ghost object is that the ghost object does not contain a real instance of the required object, but handles lazy loading by initializing its own inherited properties.

ProxyManager can generate lazy loading ghost objects, which are proxies used to save performance and memory for large datasets and graphs representing relational data. Ghost objects are particularly useful when building data-mappers.

Additionally, the overhead introduced by ghost objects is very low when compared to the memory and performance overhead caused by virtual proxies.

$config  = new \ProxyManager\Configuration(); // customize this if needed for production
$factory = new \ProxyManager\Factory\LazyLoadingGhostFactory($config);

$proxy = $factory->createProxy(
    'MyApp\HeavyComplexObject',
    function ($proxy, $method, $parameters, & $initializer) {
        $initializer   = null; // turning off further lazy initialization

        // modify the proxy instance
        $proxy->setFoo('foo');
        $proxy->setBar('bar');

        return true;
    }
);

$proxy->doFoo();

See the complete documentation about lazy loading ghost objects in the docs/ directory.

This feature is planned.

Lazy References

A lazy reference proxy is actually a proxy backed by some kind of reference holder (usually a registry) that can fetch existing instances of a particular object.

A lazy reference is usually necessary when multiple instances of the same object can be avoided, or when the instances are not hard links (like with Weakref), and could be garbage-collected to save memory in long time running processes.

This feature yet to be planned.

Remote Object

A remote object proxy is an object that is located on a different system, but is used as if it was available locally. There's various possible remote proxy implementations, which could be based on xmlrpc/jsonrpc/soap/dnode/etc.

This feature yet to be planned.

Contributing

Please read the CONTRIBUTING.md contents if you wish to help out!

Credits

The idea was originated by a talk about Proxies in PHP OOP that I gave at the @phpugffm in January 2013.