Search by

klass8s / proximity

tequila

Create PHP proxy objects with ease

Package info

github.com/klass8s/proximity

Type:symfony-bundle

pkg:composer/klass8s/proximity

Statistics

Installs: 47

Dependents: 1

Suggesters: 0

Stars: 0

Open Issues: 0

v0.2.0 2026-11-17 14:52 UTC

This package is auto-updated.

Last update: 2026-11-17 14:58:18 UTC


README

Create PHP proxy objects with ease. Proximity wraps an object you already constructed in a generated subclass that intercepts its method calls: before the body, to observe the call or replace it, and after it, to observe or replace the result. It is a small library for PHP 8.4 and later, with a Symfony bundle, and it handles what modern PHP objects carry: readonly classes, property hooks and typed properties.

This README is the documentation: the API is small, and every part of it is shown below.

Motivation

This library is inspired by the brilliant Ocramius/ProxyManager library. The mentioned library is lacking some features for now, such as the ability to create proxies from class instances with non-nullable typed properties. Unfortunately, this great library is not actively supported, therefore klass8s/proximity tries to implement some of ProxyManager's functionality.

Installation

Proximity requires PHP 8.4 or later.

composer require klass8s/proximity

The core classes need no framework. In a Symfony application, register the bundle in config/bundles.php:

return [
    // ...
    Proximity\Bundle\ProximityBundle::class => ['all' => true],
];

Usage

A ProxyFactory takes a generator and a proxy strategy — the strategy decides how generated proxy classes are loaded. EvaluatingStrategy loads them with eval() (nothing touches disk — the default choice, a once-per-worker cost under FrankenPHP worker mode); SaveToFileStrategy writes them to a directory for inspection and debugging:

use Proximity\ProxyFactory;
use Proximity\ProxyGenerator;
use Proximity\ProxyStrategy\EvaluatingStrategy;
use Proximity\ProxyStrategy\SaveToFileStrategy;

$factory = new ProxyFactory(new ProxyGenerator(), new EvaluatingStrategy());
// or:
$factory = new ProxyFactory(new ProxyGenerator(), new SaveToFileStrategy('/path/for/proxy/classes'));

$proxy = $factory->proxy(new Foo());

The proxied class must not be final — the proxy is a generated subclass. Each proxy class is generated once per factory and reused for subsequent instances.

Intercepting method calls

Body interceptors run before the method body and may veto it; result interceptors run after it and may rewrite the return value. Both are wired per-method (or as defaults for every method) via ProxyOptions:

use Proximity\MethodsInterception\BodyInterceptionResult;
use Proximity\MethodsInterception\BodyInterceptorInterface;
use Proximity\MethodsInterception\InterceptionContext;
use Proximity\MethodsInterception\ResultInterceptorInterface;
use Proximity\ProxyInterface;
use Proximity\ProxyOptions;

class Foo
{
    public function bar(string $who = 'world'): string
    {
        return "Bar for {$who}!";
    }
}

$logger = new class implements BodyInterceptorInterface, ResultInterceptorInterface {
    public function beforeMethodBody(ProxyInterface $proxy, object $object, string $methodName, array $methodArgs): BodyInterceptionResult|null
    {
        // $methodArgs is a named map: parameter name => value, declared defaults applied
        echo "→ {$methodName}(" . json_encode($methodArgs) . ")\n";

        return null; // null: proceed normally
    }

    public function afterMethodBody(ProxyInterface $proxy, object $object, string $methodName, array $methodArgs, InterceptionContext $context): void
    {
        echo "← {$methodName} returned " . var_export($context->returnValue, true) . "\n";
    }
};

$proxy = $factory->proxy(new Foo(), new ProxyOptions(
    bodyInterceptors: ['bar' => [$logger]],       // per-method…
    defaultResultInterceptors: [$logger],         // …or for every method
));

$proxy->bar();
→ bar({"who":"world"})
← bar returned 'Bar for world!'

To veto a method body, return a BodyInterceptionResult from a body interceptor:

return new BodyInterceptionResult(preventMethodBody: true, returnValue: 'replaced');

To rewrite the result, assign to the writable context from a result interceptor:

$context->returnValue = 'New value';

Whatever is in $context->returnValue after the last result interceptor is what the caller receives.

Symfony

The bundle (Proximity\Bundle\ProximityBundle) wires ProxyFactory, ProxyGenerator and both strategies (aliasing ProxyStrategyInterface to EvaluatingStrategy by default), and autoconfigures any service implementing an interceptor interface. SaveToFileStrategy writes into %kernel.project_dir%/var/proxy and the generated classes live in the namespace Proximity\Proxy; the environment variables PROXIMITY_PROXY_CLASSES_DIR and PROXIMITY_PROXY_NAMESPACE change either.

Known limits

  • By-reference parameters lose their reference semantics through a proxy (arguments are forwarded by value).
  • Objects with uninitialized readonly properties cannot be proxied.

Origins

Proximity continues dealroadshow/proximity and dealroadshow/proximity-bundle, MIT-licensed packages merged here into one library with its Symfony bundle. Their notice is in NOTICE.

Contributing

Bug reports and pull requests are welcome: CONTRIBUTING.md says what a pull request needs. Report a security vulnerability privately, as SECURITY.md describes.

License

Proximity is released under the MIT License. The portions that come from the packages named under Origins remain under their own MIT notice, in NOTICE.