Entity Factory Bundle Laravel Package

Getting Started

Scoping note before you start. Despite the Laravel framing of this assessment, lkovace18/entity-factory-bundle is a Symfony bundle built around Doctrine entities. The -bundle suffix is Symfony convention, "entity" is Doctrine vocabulary, and there is no service provider, no auto-discovery entry, and no integration with Illuminate\Database\Eloquent\Factories\Factory. It will not boot in a Laravel app as-shipped. So there are exactly two ways a Laravel developer "gets started" here:

• Study-and-port (recommended). Read the source for the factory pattern and reimplement it with native Eloquent factories. Takes an hour and adds no dependency.
• Use it in a Symfony/Doctrine context, or in an internal packages/ namespace you vendor and own.

Minimal steps, in order:

1. Read composer.json first. Look for symfony/* and doctrine/* in require vs. require-dev, plus the PHP constraint. Any hard Symfony or Doctrine ORM constraint is a blocker for Laravel and a likely platform-pin risk even in Symfony. This one file usually ends the evaluation.
2. If Symfony: install as require-dev only, pinned to an exact tag or commit hash. Zero stars and zero dependents means nothing is holding the API stable. Register the bundle in config/bundles.php under env: ['test'] so it never loads in prod.
3. Find the factory base class in src/. That is the contract: what method builds the entity, what method persists it, and how it acquires the EntityManager. Everything else in the package hangs off those three answers.
4. Read tests/ before the README. At this maturity level the test suite is the documentation. If there is no test suite, stop — you are the QA department.
5. First use case: replace a setUp() that hand-constructs an entity, assigns a dozen properties, and calls persist()/flush() with a single factory call. Start with the non-persisted path — build an object, assert on defaults, no database — then graduate to persisted creation once you trust the builder.

Implementation Patterns

One factory per entity, with complete defaults. The whole value of a factory is that every default is valid. Define the factory once with a fully-populated "happy path" entity and let tests deviate only where they care. A factory with one required field missing just moves the boilerplate.

Overrides at the call site, not in the factory. The description's headline feature is per-case overrides. Use it as the primary variation mechanism: build the default entity, pass an override map for the two or three attributes the test actually asserts on. This keeps the factory from growing a branching if forest.

Compose named variants on top of the base factory (admin user, expired order, unpaid invoice) as small wrapper methods that pass a fixed override map — never as separate factories and never as flags threaded through the base. In Laravel terms this is the equivalent of ->state([...]); you're building it by hand.

Persisted vs. non-persisted is a deliberate split, not a default. Use non-persisted creation for unit tests and for building object graphs you'll assert on in memory. Use persisted creation for functional tests, fixtures, and seed data. Don't let the factory quietly persist when the test didn't ask for a database — that's the most common source of slow, flaky suites.

Relationships: build parents first, inject via overrides. Factories here have no relationship graph or for()/has() magic, so the caller owns the topology: create the parent, pass it into the child's override map. This is fine for two models and gets ugly fast at ten — which is exactly why mature solutions (foundry, alice) exist.

Bulk generation via a loop with index-aware overrides. For fixtures, iterate N times and vary attributes by index (unique emails, staggered dates) rather than hoping randomness produces valid distinct data.

Determinism where it matters. Any randomized defaults should be seedable, or explicitly disabled in tests that assert on exact values. Random data in a test is a future flake.

If you port to Laravel, the mapping is nearly 1:1: factory definition → Model::factory()->state([...]), non-persisted → make(), persisted → create(), override map → ->state([...]), named variant → a dedicated state method. Eloquent gives you sequences, recycling, and relationship factories for free, so the port shrinks rather than grows.

Gotchas and Tips

• The naming is the trap. -bundle + Entity means Symfony + Doctrine. Confirm compatibility in composer.json before spending an hour; there is no Laravel service provider to register and no illuminate/* constraint to satisfy.
• Never put it in require. Dev/test tooling only. If a symfony/* or doctrine/* entry lands in your production dependency tree, you've inherited an upgrade blocker that will outlive the package's usefulness.
• You are the maintainer. A single maintainer, zero dependents, and no issue corpus means no upstream bug fixes and no Stack Overflow answers. Budget for fork-and-own: internal namespace, your own tests, removal as a one-file delete rather than a dependency untangle.
• Override merge depth is the classic surprise. Verify whether an array-valued override replaces or merges into the factory default. Shallow replacement silently drops sibling values and produces half-built entities.
• Doctrine identity-map leakage between tests. Persisted entities stay in the EntityManager; without clearing it you get stale objects and phantom rows across test methods. Check that your test base class clears or recreates the EM.
• Flush semantics. Find out whether the factory flushes or only persists. Unflushed entities look correct in memory and vanish from assertions that query the database.
• Fixture drift after migrations. With no upstream maintenance, every schema change is your patch. Add a test that builds each factory and asserts it persists cleanly, and run it in CI.
• Name collisions when porting. Factory and Entity are generic; alias imports or namespace your internal copies under something app-specific so they don't shadow or confuse Eloquent's Factory in IDE resolution and static analysis.
• Debugging tip: dump the final attribute array immediately before construction/persist. Nearly every failure here is "the override didn't apply" or "a default was null."
• Extension points are just subclassing. Add named variant methods to a subclass rather than editing the base factory, so an upstream rebase (or a fork sync) stays possible.
• Revisit criteria: only re-open the evaluation if you fork it into an internally owned, internally tested package — or if the source audit reveals genuinely novel entity-graph functionality that native factories can't express. Neither is likely.