Object Enumerator Laravel Package

Getting Started

Start by installing the package via Composer (typically as a dev dependency, since this is primarily used in testing and debugging tooling):

composer require --dev sebastian/object-enumerator

The core use case is integrating it into test assertions or debugging tools where you need to inspect all objects referenced by a variable (including nested objects and circular references). For example, when writing PHPUnit tests that validate deep object graph state—like in Doctrine ORM or Symfony services—it’s essential to ensure no unexpected side objects are retained.

First usage example:

use SebastianBergmann\ObjectEnumerator\Enumerator;

$enumerator = new Enumerator();
$objects = $enumerator->enumerate($someComplexObject);

foreach ($objects as $object) {
    echo get_class($object) . "\n";
}

Check src/Enumerator.php for the class definition and tests/ for real-world usage (the package is heavily used by PHPUnit internally).

Implementation Patterns

• Testing & Debugging: Use enumerate() to verify that a fixture isn’t leaking references (e.g., to avoid memory bloat or accidental mutation).
• Object Graph Analysis: Useful in custom inspectors for services, DTOs, or value objects where you want to recursively inspect internal state without manual recursion.
• Deep Comparison Helpers: Combine with spl_object_hash() to deduplicate or track object identity across complex structures.
• Integration with CLI Tools: Often used inside artisan commands or Monolog processors that inspect object structures during logging (e.g., dumping service state for troubleshooting).

Common pattern:

$enumerator = new Enumerator();
foreach ($enumerator->enumerate($payload) as $object) {
    if (is_object($object) && method_exists($object, 'getId')) {
        $ids[] = $object->getId();
    }
}

It’s especially valuable in test suites where assertions like assertObjectNotCloneable() or assertGraphContainsOnly() are implemented.

Gotchas and Tips

• Circular Reference Safety: The enumerator explicitly handles circular references (avoids infinite loops), but be aware the traversal is depth-first. If you’re inspecting large graphs (e.g., Laravel service containers), consider limiting scope manually.
• PHP Version Guardrails: As of v8.0.0+, it drops support for PHP 8.3—check compatibility with your stack before upgrading. Always check release notes when updating.
• Performance: While optimized, deep enumeration can be slow on huge graphs (e.g., Symfony DIC with 1000+ services). Use it in tests only or filter early (e.g., array_filter($objects, fn($o) => in_array(...))).
• Not for Production Debugging: Prefer dd()/dump() (Symfony VarDumper) for interactive debugging—this package is for programmatic enumeration, not human-readable output.
• Extending: It’s a final class—no inheritance. To customize behavior (e.g., skip traits), you’d wrap it in your own iterator.
• Alias Conflicts: If you have custom Enumerator classes, alias carefully:

  use SebastianBergmann\ObjectEnumerator\Enumerator as ObjectEnumerator;