Instantiator Laravel Package

Getting Started

Install via Composer: composer require doctrine/instantiator. The core usage is straightforward—Instantiator::instantiate(). Start by testing it on a class with a private constructor or one that requires complex dependencies you don’t want to instantiate in tests. For example:

use Doctrine\Instantiator\Instantiator;

$instantiator = new Instantiator();

// Works even if the class has a private constructor
$instance = $instantiator->instantiate(MyClass::class);

First real-world use case: bootstrapping a mock object for unit testing without invoking side effects (e.g., database connections, file I/O) from the constructor. Check the src/Instantiator.php source for minimal internal logic—it’s only ~250 lines and heavily commented.

Implementation Patterns

• Testing & Mocking: Create unconstructed stubs for dependency injection scenarios (e.g., mocking Doctrine entities or objects with strict constructor contracts). Especially useful in PHPUnit or Mockery where you need real object instances but can’t/won’t run constructors.

• ORM / Hydration: After fetching raw data from the DB, populate hydrated objects via reflection without triggering lazy-loading traps or validation logic in constructors. Popular in Doctrine DBAL/ORM internals.

• Proxy Generation: Tools like Proxy Manager or your own AOP setup use Instantiator to create proxy objects that delegate to a wrapped subject without constructing the proxy subject prematurely.

• Custom Serialization/Deserialization: When implementing custom __unserialize() or deserializing from non-standard formats (e.g., Redis hashes), instantiate first, hydrate later.

Typical workflow:

$object = $instantiator->instantiate(MyEntity::class);
// Now use reflection or manual property assignment to hydrate
foreach ($data as $field => $value) {
    $refl = new ReflectionClass($object);
    $prop = $refl->getProperty($field);
    $prop->setValue($object, $value);
}

Gotchas and Tips

• Visibility matters: While it handles private/protected constructors, properties still respect PHP visibility—you’ll need ReflectionProperty to set them.
• No PHP 8.2+ named arguments: Constructor bypass means all named/typed constructor logic is skipped—ensure your hydration logic doesn’t assume it.
• Internal classes: Some internal classes (e.g., Closure, Generator) may fail or behave unexpectedly—always wrap calls in try/catch (Throwable).
• Performance: It’s extremely fast (uses low-level reflection + ReflectionClass::newInstanceWithoutConstructor() under the hood), but for hot paths with thousands of objects, batch instantiation or caching the Instantiator instance.
• Extensibility: While the API is tiny (instantiate(), instantiateMultiple()), it’s not designed for extension. Prefer composition: write your own hydrator wrapper that uses Instantiator internally.
• Debug tip: Use var_dump(get_class($instance)) to confirm the class is actually instantiated correctly—sometimes autoloading errors cause surprises.