README

Stop rebuilding test content by hand. Put your Pimcore content in Git and recreate it anywhere with one command.

Every Pimcore team has lost a day to it: a new developer needs a working dataset, a CI run needs known content, a customer bug only reproduces against their data. The usual answer is a stale, oversized database dump full of someone else's test garbage. This bundle replaces that with plain YAML you can commit, diff, and review.

Point it at a folder in your Pimcore tree and it writes everything it finds to YAML — data objects, documents, assets, plus the system config they depend on. Commit those files, and any teammate or environment recreates the exact same Pimcore state with bin/console basilicom:pimcore:fixtures:load.

What sets it apart: it follows cross-domain references automatically. Export /products and the categories, hero images, and landing pages those products point to come along too — including parent folders, so every path resolves on the other side. Most fixture tools dump objects and stop. This one brings the whole graph.

Because fixtures are readable YAML with @key references, a content change shows up as a reviewable Git diff — and --diff previews exactly what a load would change before you run it.

Typical use cases:

• Onboard developers in minutes — clone, load, done. No begging a colleague for a DB dump.
• Deterministic CI — reset --force && load gives every test run identical, known content.
• Reproducible bug reports — snapshot the affected subtree (refs followed) and debug locally against the real data.
• Ship demo data with your product — bundle a curated dataset; the installer loads it and the demo looks great instantly.
• Config as code — keep sites, roles, glossary, units, and classification stores in version control and promote them env-to-env.

Works with Pimcore 12 / PHP 8.3 / Symfony 7.

Installation

composer require --dev basilicom/pimcore-fixtures

Register the bundle in config/bundles.php:

return [
    // ...
    Basilicom\PimcoreFixtures\PimcoreFixturesBundle::class => ['dev' => true],
    // ...
];

Optional config in config/packages/basilicom_pimcore_fixtures.yaml:

basilicom_pimcore_fixtures:
  path: '%kernel.project_dir%/fixtures'   # where fixture files live
  format: yaml                             # fixture file format: yaml (default) or json
  ignored_fields: []                       # DataObject field names to skip
  ignored_classes: []                      # DataObject classes to skip
  ignored_paths: []                        # Pimcore paths to skip
  ignored_properties: []                   # Pimcore property names to skip on documents/assets/dataObjects
  ignored_website_settings: []             # Website setting names to skip

Defaults are sensible — path falls back to var/bundles/PimcoreFixtures. Empty values (null, '', []) and inherited values are skipped during generation to keep files clean.

format controls the serialization of every fixture file the bundle writes and reads — data objects, documents, asset metadata, and all pimcore/* config fixtures. With yaml (the default), loading accepts both .yaml and .yml; with json, only .json files are read.

Switching formats does not convert existing fixtures. After changing format, files in the old format become invisible to both export-merge and fixtures:load. Convert them manually (the data structures are identical) or regenerate from a seeded system, and remove the old files.

ignored_properties matches on Property::getName() and applies wherever Pimcore properties are exported (document YAML, asset _metadata.yaml, and dataObject property holders). ignored_website_settings matches on WebsiteSetting::getName() and filters entries before they are written to pimcore/website_settings.yaml.

How it works

The bundle has two sides:

• Generate — read live Pimcore content and write YAML fixture files.
• Load — read those YAML files and recreate the content in another Pimcore instance.

Loading is idempotent: re-running won't duplicate content, it updates existing entries by fixture key.

Below is a tour of the main commands. Run any of them with --help to see all options.

What gets exported

Everything at once

bin/console basilicom:pimcore:fixtures:generate

The umbrella command: exports the complete content set in one run — all data objects, documents, and asset binaries from their tree roots, plus every system-config fixture (sites, units, glossary, website settings, roles, classification store, translations). Use --levels to cap tree depth, --skip-translations to leave translations out, and --force to overwrite instead of merge.

For scoped or interactive exports, use the dedicated per-domain commands below.

Data objects

bin/console basilicom:pimcore:fixtures:generate-objects

Without arguments it opens an interactive picker (filter, ↑/↓, space, enter) to choose one or more folders from your data object tree. Pass --folder=/products to skip the picker, or --all to export everything.

By default it also follows cross-domain references: if a Product points to a Category, a hero image, and a landing page, all four are pulled into the same export — including parent folders so paths resolve cleanly on load. Disable with --no-follow-refs.

Re-running merges new entries into existing fixture files. Pass --force to overwrite from scratch.

Documents

bin/console basilicom:pimcore:fixtures:generate-documents

Same flags as generate-objects. Exports pages, snippets, links, emails, folders, and hardlinks to {path}/documents/. Includes title, description, pretty URL, controller, template, editables, link targets, properties, and the original sibling index so loaded documents keep their Pimcore tree order. Reference following pulls in any data objects and assets the documents link to.

Hardlinks are exported with their source (as an @key reference to the source document) and the childrenFromSource / propertiesFromSource flags. The source document is pulled into the export via reference following, so the link resolves on load.

Assets

bin/console basilicom:pimcore:fixtures:generate-assets

Copies asset binaries into {path}/assets/, mirroring the Pimcore asset tree. On load, files are restored to their original Pimcore paths. Same flag set as the other generators (interactive picker, --folder, --all, --levels, --force, …).

You can also drop replacement files into fixtures/assets/ manually — merge mode leaves existing binaries untouched.

Per-asset state that can't be expressed by the binary itself is written to {path}/assets/_metadata.yaml: own (non-inherited) Pimcore properties and Pimcore asset metadata items (the "Metadata" tab — name/type/data/language, with element-typed values stored as paths). The asset seeder reads this sidecar after creating the binaries and applies both.

System configuration

A few Pimcore-wide settings travel with your fixtures, written as single files under {path}/pimcore/:

All of them are emitted when you run generate. Classification stores, roles, and translations also have their own dedicated commands if you want to regenerate just one:

bin/console basilicom:pimcore:fixtures:generate-classification-store
bin/console basilicom:pimcore:fixtures:generate-roles
bin/console basilicom:pimcore:fixtures:generate-translations

Translation file format — each top-level key is a translation key, each value is a locale → text map:

my.label.headline:
  de: 'Überschrift'
  en: 'Headline'
my.label.subtitle:
  de: 'Untertitel'
  en: 'Subtitle'

On load, missing keys are created and existing keys updated; locales not configured in Pimcore are skipped with a warning. Pass --skip-translations to generate or load to opt out entirely.

File-based config that already lives in var/config/ — static routes, predefined properties, document types — isn't fixturized. Commit those files directly.

Loading fixtures

bin/console basilicom:pimcore:fixtures:load

Loads everything in the fixtures folder back into Pimcore in the right order: units and classification config first, then assets, document shells, data objects (in two passes so circular relations work), document content, sites, glossary, translations, website settings, and finally roles.

Useful options:

--diff loads nothing — it compares each fixture data object against the live object at the same path and prints the differences:

~ /products/example-shoe  (Product)
    name: 'Old Shoe' → 'New Shoe'
    price: 49.9 → 39.9
+ /products/brand-new      (Product) [new]

Diff: 1 new, 1 changed.

Use it to sanity-check a load against a populated environment before committing to it. Field-level detail covers data objects; documents, assets, and system config run as a dry run under --diff.

Schema drift: if a fixture references a data object field that no longer exists on the current class definition (renamed or removed since the fixture was generated), the load no longer aborts. The field is skipped and surfaced as a warning in the end-of-run summary, so a stale fixture degrades gracefully instead of crashing the whole import.

Resetting

bin/console basilicom:pimcore:fixtures:reset --force

Truncates Pimcore content tables before a fresh load. The --force flag is mandatory to avoid accidents. In the prod environment the command additionally refuses to run unless --allow-prod is passed — two deliberate flags between you and an empty production database.

Scope it with --types (objects, documents, assets), --classes, --exclude, or --drop-folder. Some shared tables (notes, edit_lock, search_backend_data, recyclebin) are always truncated.

Fixture file format

Fixtures are plain YAML (or JSON, see the format config option) keyed by class and fixture id, with @key references between entries. The structure is identical in both formats — JSON merely escapes the backslashes in class-name keys ("\\App\\Model\\DataObject\\Product").

Data object example:

\App\Model\DataObject\Product:
  001_product_example_abc123:
    key: example-product
    parentId: 1
    published: true
    name: 'Example product'
    category: '@002_category_shoes_def456'   # cross-fixture reference

Document example:

\Pimcore\Model\Document\Page:
  003_page_about_xyz789:
    key: about-us
    parent: '@001_folder_content_abc123'
    title: 'About Us'
    template: '@AppBundle/Default/default.html.twig'
    properties:
      - { name: nav_title, type: text, data: About, inheritable: false }

Classification store field values on a data object are nested by groupName → keyName → language:

classificationAttributes:
  technicalSpecs:
    weight:
      default: '2.5 kg'
  marketingData:
    headline:
      de: Produktüberschrift
      en: Product headline

Extending

You can teach the bundle about new Pimcore field types or custom load behaviour without forking it.

• Custom field type — add a transformer in src/Generation/DataTransformer/ for export, and a hydrator implementing ChainedPropertyHydratorInterface for load. Tag the hydrator service with basilicom_pimcore_fixtures.property_hydrator and a priority.
• Custom property hydrator — same tag, used as a fallback when none of the built-in hydrators match.
• Pre/post processors — extend AbstractProcessor and tag with basilicom_pimcore_fixtures.pre_processor or basilicom_pimcore_fixtures.post_processor to run code around each object save.
• Custom fixture format — implement FixtureFormatInterface and tag the service with basilicom_pimcore_fixtures.fixture_format. Note that the format config option validates against the built-in names (yaml, json), so a custom format also needs that enum extended via a PR.

See AGENTS.md for architectural details.

Contributing

You don't need a local PHP or Composer install — everything runs in Docker via make.

git clone git@github.com:basilicom/pimcore-fixtures.git
cd pimcore-fixtures
make setup

Common tasks:

Run make lint && make test-unit before opening a PR. Architecture and conventions are documented in AGENTS.md.