Yaml Fixtures Bundle Laravel Package

Getting Started

1. Install as a dev dependency — this is fixture tooling, not runtime code:

   composer require --dev limetecbiotechnologies/yaml-fixtures-bundle
   

   The package is a fork of the original khepin/yaml-fixtures-bundle (hence the repo name), so most existing Khepin documentation/examples apply, modulo namespace changes.

2. Register the bundle manually in config/bundles.php — there is no Flex recipe, and with 0 stars you should assume nothing is auto-wired:

   LimetecBiotechnologies\YamlFixturesBundle\KhepinYamlFixturesBundle::class => ['dev' => true, 'test' => true],
   

3. Where to look first — before writing any fixture, read these three files in vendor/limetecbiotechnologies/yaml-fixtures-bundle/:

   • DependencyInjection/Configuration.php — the only source of truth for config keys (directory, load_command, manager/namespace options). The fork may have renamed or dropped Khepin's keys.
   • Command/*.php — to confirm the actual command name (khepin:yamlfixtures:load in the original).
   • The loader/parser class — to confirm the reference syntax the fork supports. Run php bin/console list | grep -i fixture to confirm registration worked.

4. First use case — create fixtures/User.yaml, define a couple of users, then:

   php bin/console khepin:yamlfixtures:load --env=dev
   

   Point the bundle at your directory first (path and key names verbatim from Configuration.php):

   # config/packages/dev/khepin_yaml_fixtures.yaml
   khepin_yaml_fixtures:
       directory: '%kernel.project_dir%/fixtures'
   

Implementation Patterns

• File-per-entity convention. Name each file after the entity short name (Article.yaml, Author.yaml); the bundle resolves the class from the filename. The YAML body is a list of records, not a map — the list index becomes the fixture's identity for references.
• Cross-entity references. The Khepin pattern is @EntityShortName#index, e.g. a Post referencing the first user:

  # Post.yaml
  - title: 'Hello'
    author: '@User#0'
    createdAt: '2023-01-01 10:00:00'
  

  Many-to-one/many-to-many are just arrays of reference strings.
• Load order = file order. Because references resolve against already-created records, keep alphabetically-dependent entities ordered (Author before Post) or rely on the bundle's dependency resolution if present. For nontrivial graphs, name files with numeric prefixes (01_User.yaml, 02_Article.yaml) so order is explicit.
• Pair with doctrine:fixtures:load for purge + load semantics (--purge-with-truncate on Postgres/SQLite where FK-truncate is cheaper). Use the bundle's own command when you only want to append YAML fixtures.
• Test-suite integration. Load fixtures once per test class in setUpBeforeClass() or a kernel-boot helper, and wrap each test in a transaction (dama/doctrine-test-bundle or a manual beginTransaction/rollBack) so YAML fixtures are the stable baseline and the DB is never rebuilt per test.
• Environment-specific directories. Keep a small shared fixtures/ for entity shapes and a fixtures/test/ for auth-related records (roles, permissions); override the directory config in config/packages/test/.
• Seed data as code review artifacts. Because the fixtures are readable YAML, they double as documentation of the domain model — keep them under version control and treat changes as schema-adjacent PRs.

Gotchas and Tips

• Maintenance risk is the headline. Last release 2022-06-13, 0 stars, 0 dependents, no published compatibility matrix. Verify it boots on your Symfony version before adopting it; if it fails, either pin Symfony, vendor the bundle with a composer.json path repository and patch the services.yaml/type hints yourself, or fall back to doctrine/data-fixtures + PHP fixture classes. Budget for the fork being the last commit.
• Dates and enums get mangled. Symfony's YAML parser will turn unquoted dates into timestamps unless PARSE_DATETIME is used — the bundle may call plain Yaml::parse(). Quote date strings and confirm what the loader does; for enums/backed enums, test one record early since the loader likely bypasses setters or uses reflection.
• References are index-fragile. Reordering or inserting a record in User.yaml silently rewires every @User#n in other files. Never insert in the middle; append, or switch to a key: value naming scheme if the fork supports one.
• No implicit purge. Running the load command twice duplicates rows (unique constraints, if any, are your only guard). Always run against a purged/truncated DB in CI.
• Short-name class resolution. If an entity lives outside App\Entity or you use multiple managers, you'll need the namespace/manager config key — check Configuration.php; failures here surface as "class not found", not as a helpful config error.
• Setters vs. reflection. The loader probably writes properties directly, so validation, updatedAt listeners, password hashing, and cascade: persist assumptions in your entities do not run. Pre-seed hashed passwords (e.g. password: '$2y$...' from bin/console security:hash-password) rather than relying on a prePersist listener.
• Debugging: run -vvv and, if a record fails, isolate the file (--fixtures-dir/--file if supported) — a bad record aborts the run, and Doctrine's exception often names the column, not the YAML line. Dump the parsed array from the loader with a temporary dump() if the error is opaque.
• Extension points: the bundle's loader class is a service — override it in services.yaml with a higher-priority definition (or decorate it) to add custom value transforms (e.g. [~, 'value'] for service references, or relative date parsing like '-3 days'). This is the cleanest way to extend without forking.