nelmio/alice: YAML Fixtures That Reference Each Other

The problem Alice solves: fixture files that reference each other

Hand-written fixtures break down when objects point at each other. A user needs a group, the group needs an owner, and the owner needs a favourite number that is sometimes null. Writing that by hand in PHP means either a fixed dataset that drifts from the schema or a loop that nobody wants to read. Alice takes a different route: you describe the objects in a fixture file, and the library builds them, filling in fake values through FakerPHP and resolving references between objects for you. The README states the goal plainly: it lets you "generate complex data with constraints in a readable and easy to edit way, so that everyone on your team can tweak the fixtures if needed." That last clause is the real selling point. The audience is PHP teams, typically on Symfony, who seed a development database or a test suite and want the seed files to be reviewable by people who are not the person who wrote them.

How Alice builds an object graph from a fixture file

A fixture file is a map of class names to named fixture sets. Each entry under a class name is an object, and each key under that object is a property, constructor argument or method call depending on the flags used. Values written as strings in angle brackets are expressions, evaluated by the expression language rather than stored literally. The README's own example shows the shape: a User class with a range user{1..10}, a username of '<username()>', and a Group whose owner is '@user1' and whose members is '<numberBetween(1, 10)>x @user*'. The '@' prefix is a reference to another fixture, and the trailing '*' is a wildcard over the range, so the group's members are picked from the ten users. That is the core mechanism: ranges produce many objects, references wire them together, and the expression language computes values that depend on other values. The README points to a separate document, doc/relations-handling.md, for references, multiple references, self references and passing references to providers, which suggests relations are the part the maintainers expect people to get wrong first.

Installing nelmio/alice and writing a first fixture

Alice is a Composer package published as nelmio/alice. The README gives a single install command and marks it as a development dependency, which is the right default: fixture generation belongs in dev and test environments, not in production.

composer require --dev nelmio/alice

There is no framework-specific install step in the README itself. Framework integration lives in doc/getting-started.md, which covers Symfony under its own heading, and the README also lists third-party libraries for Symfony, Nette, Zend Framework 2 and a framework-agnostic option. So the loader you use depends on your framework, and the README does not spell out a bare-PHP bootstrap.

The README's complete example is the best starting point because it exercises ranges, Faker calls and references in one file. Written as YAML, it looks like this:

Nelmio\Entity\User:
    user{1..10}:
        username: '<username()>'
        fullname: '<firstName()> <lastName()>'
        birthDate: '<date_create()>'
        email: '<email()>'
        favoriteNumber: '50%? <numberBetween(1, 200)>'

Nelmio\Entity\Group:
    group1:
        name: Admins
        owner: '@user1'
        members: '<numberBetween(1, 10)>x @user*'
        created: '<dateTimeBetween("-200 days", "now")>'
        updated: '<dateTimeBetween(

The expression '<username()>' calls Faker. The '50%?' prefix is the optional-data syntax documented in doc/complete-reference.md under Optional Data, meaning the value is present half the time. The '@user1' and '@user*' entries are the references described in doc/relations-handling.md. The README also shows the same fixtures expressible as PHP or JSON, so YAML is a convenience, not a requirement. What you should see after loading the file is ten user objects and one group whose members are drawn from those users, with a birth date and timestamps generated at load time.

Where Alice stops being the right tool

Alice generates fake data. That is the whole point, and it is also the limit. If you need fixtures that reproduce a specific production state to debug a specific bug, randomised values work against you: the username changes between runs, so the record you were chasing is not the record you get. The same applies to tests that assert on exact values rather than on structure. A second limit is the dependency itself. Alice is installed as a dev dependency and pulls in FakerPHP, so it belongs to the Composer graph of the project under test. A library that ships its own fixtures to consumers cannot put Alice in require-dev without pushing it onto everyone downstream. Third, the README is explicit that the 2.x line is in maintenance mode: PRs are accepted, but no active development is done on it by the maintainers. Anyone still on 2.x is on a branch the maintainers have stopped developing, and UPGRADE.md documents the breaking changes between 2.x and 3.0 for teams that want to move. Finally, the documentation set is large but split across files, and the README itself does not document rollback, cleanup or how to remove fixtures once loaded.

Alice compared with Doctrine's own data fixtures

The obvious alternative in a Symfony project is doctrine/data-fixtures, which provides the interface and the loading order for fixture classes that you write in PHP. The difference is where the data lives. With Doctrine's fixtures, each fixture is a PHP class implementing FixtureInterface, and you populate objects with explicit setter calls; the relationships between objects are expressed in code, and generating many rows means writing a loop. Alice moves the description out of PHP and into a file format, adds FakerPHP as the value source, and resolves references through the '@' syntax instead of object variables. The trade-off is real: Doctrine's approach gives you full PHP for conditional logic and no extra file format to learn, while Alice gives you a file a non-programmer can edit and a range syntax that collapses ten objects into one line. They are not mutually exclusive, since Alice can be driven from a fixture class, but the mental model is different enough that mixing them in one project tends to confuse the team about which file to edit.

Maintenance, upgrades and the MIT licence

The repository is not archived, and the last push was on 2026-06-15. The most recent release listed is 3.17.0, dated 2026-02-24, following 3.16.1 in December 2025 and 3.16.0 earlier that month, so the 3.x line has seen releases across the past year. The README includes a section titled Backward Compatibility Promise (BCP), which is the document to read before planning an upgrade, and UPGRADE.md carries the breaking changes between Alice 2.x and 3.0. The Makefile shows the quality tooling the maintainers run: PHP-CS-Fixer, Rector in dry-run mode, PHPStan with a 1G memory limit, PHPUnit, infection for mutation testing, and a separate Symfony test suite. That is a maintenance cost you inherit only if you contribute; as a consumer your cost is the upgrade path between minor versions, which the BCP section governs. The licence is MIT, which permits commercial and closed-source use with the usual requirement to keep the copyright notice and permission notice. That is a summary of the licence text, not legal advice; read LICENSE and your own organisation's policy before relying on it.

Editorial conclusion

Adopt nelmio/alice when your seed data is a graph of related objects and you want it expressed in files your whole team can edit, and when you can accept that the generated data is fake by design. Do not adopt it if you need fixtures that mirror production rows or if your project cannot add a dev dependency. Before committing, run composer require --dev nelmio/alice on a branch, write one fixture file with a range and a reference, and confirm the loader you plan to use is the one documented for your framework.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nelmio/alice on GitHub
4. README
5. Releases