northwoods/entity-proxy

A hydrating proxy for objects with private properties

2.1.0 2018-09-10 22:36 UTC

This package is auto-updated.

Last update: 2024-10-13 11:12:17 UTC


README

Become a Supporter Latest Stable Version License Build Status Code Coverage Scrutinizer Code Quality

A reflection based proxy for hydrating objects with private properties.

Attempts to be PSR-1, PSR-2, and PSR-4 compliant.

Install

composer require northwoods/entity-proxy

Usage

Proxies are created with the singleton ProxyFactory:

use Northwoods\EntityProxy\ProxyFactory;

Proxies can be created as wrappers around existing objects:

$proxy = ProxyFactory::modify($user);

$proxy->set('email', 'user@example.com');

Or new instances when hydrating from other data sources:

$proxy = ProxyFactory::create(User::class);

$proxy->setArray([
    'id' => 1234,
    'username' => 'jane.doe',
    'email' => null,
]);

/** @var User */
$user = $proxy->reveal();

Proxies can also read existing values on the object:

$username = $proxy->get('username');

Reasoning

In Domain Driven Design it is often recommended that entities use private properties with getters to access state and setters to change state based on business requirements. Since an entity is considered to be a persistent object, its constructor should only be called once for the lifetime of the entity. This allows for domain events to be triggered by the constructor to notify the application that, for example, a new user has registered.

With this limitation in mind, the requirements for the hydrator are:

  1. It must not call the entity constructor.
  2. It must be able to set private/protected properties.
  3. It must be as efficient as possible.

The easiest way to achieve these goals is to use reflection, which allows us to create objects without constuctor, make properties accessible, and write property values. The reflection of every class should be internally cached for the lifetime of the factory to maximize performance.

If performance is of concern there are other viable approaches that are faster but more complicated to setup and use.

License

MIT