Akeneo Enrich Bundle Laravel Package

Getting Started

• Verify compatibility before anything else. A new v1.0.0 tag now exists (the previous one was 2017-10-10), but the release notes only mention translation and translated media — they say nothing about bumping PHP/Symfony/Akeneo constraints. Diff composer.json between the old tag and v1.0.0 before assuming the bundle has been modernized; if the constraints are unchanged, you are still in the Akeneo 1.7/2.x era (Symfony 2.8/3.x, PHP 5.6/7.0/7.1) and must match your akeneo/pim-community-dev and Symfony minors or the kernel will fail to boot.
• Install with composer require kiboko/akeneo-enrich-bundle:^1.0. Now that a real tag exists you can pin to ^1.0 instead of floating on dev-master, but still pin exactly if the constraints are loose.
• Register the bundle in app/AppKernel.php (new Kiboko\Bundle\EnrichBundle\KibokoEnrichBundle()) and, if it ships routes, import them in app/config/routing.yml. Then bin/console cache:clear and confirm it loaded with bin/console debug:container | grep -i kiboko.
• Where to look first: DependencyInjection/Configuration.php for the config tree, DependencyInjection/*Extension.php for hardcoded service wiring, Resources/config/services.yml for service IDs (your extension points), Resources/translations for UI strings, and — new in this release — the translation service/loader and the media-handling code paths, since those are what v1.0.0 changed.
• First use case: verify the bundle enriches reference-data records with extra attributes/relations. Create a reference data set in Akeneo, open the enrichment UI the bundle adds, add a translatable label and attach a media file per locale, and confirm both render and persist in every locale before wiring any product import.

Implementation Patterns

• Never fork the bundle. Akeneo bundles are DI-heavy; override behavior by registering your own service that decorates: the bundle's service ID in your app bundle. Keep all customization in a dedicated AppBundle/AcmeBundle so upgrades (or abandonment) are isolated.
• Extend the record form, not the entity. Reference-data enrichment is surfaced through form extensions and attribute types. Add a form extension for the enrichment form rather than editing the bundle's form classes.
• Translation workflow (new focus in v1.0.0). Supply per-locale strings through the bundle's translation mechanism / Resources/translations/messages.<locale>.yml in your app bundle rather than editing vendor files. Keep translation keys in sync with the record form fields so the enriched labels render localized instead of falling back to the key.
• Translated media workflow (new in v1.0.0). Attach media per locale/channel and make sure the target attribute is a media attribute backed by a configured catalog storage/filesystem. On import, reference files by absolute path (or your configured storage root) and confirm Akeneo copies them into its own media directory rather than leaving dangling references.
• Wire into import/export via processors and normalizers. Register a custom processor/normalizer (or an event subscriber on Akeneo's import events — akeneo.storage.pre_save, step events) and let the bundle's job handle orchestration. For translated media, ensure the media normalizer runs after the translation step so locale-specific files map to the right record.
• Grid/list customization: if the bundle decorates the reference-data datagrid, use a datagrid extension in your own bundle to add columns/actions; do not modify the YAML in vendor/.
• Data model: Akeneo stores reference data under pim_catalog_reference_data_* tables; the bundle may add joins or extra columns, and translated media adds file rows. Inspect migrations (bin/console doctrine:migrations:status) before touching schema, and put your own migrations in your app bundle, never in the vendor tree.
• Typical workflow: import reference-data records via the bundle's import job → translate labels and attach translated media → enrich extra attributes/relations → read the enriched values on products through Akeneo's product value normalizers/API. Keep the whole chain idempotent so re-imports update rather than duplicate rows and don't orphan media files.

Gotchas and Tips

• Age is still the dominant risk — the release notes don't prove otherwise. The changelog describes translation and translated media only; treat the compatibility matrix as unverified until you read composer.json. If constraints weren't bumped, the old PHP 7.4+/Symfony 4+/Akeneo 3+ incompatibility warnings still apply.
• Zero dependents means zero community support. You are effectively the maintainer. Vendor the source or fork it under your org and pin the fork; do not rely on upstream for fixes.
• Translated media pitfalls are the new failure mode. Watch for: media files written per locale but only one surviving (locale fallback overwriting), orphaned files on re-import/update, wrong filesystem adapter config, and CSV imports pointing at paths outside the configured storage root. Test a re-import that replaces an existing translation file, not just a clean first import.
• Translation caching. Akeneo caches translations aggressively; a new locale string won't appear until you cache:clear --env=prod. Verify with debug:translation <locale> (or the web profiler in dev) before assuming the bundle's translation code is broken.
• Config tree quirks: check Configuration.php for required nodes without defaults — Akeneo's config validation throws at container compile time, not runtime, with a generic InvalidConfigurationException. Read the tree carefully.
• Heavy caching. Akeneo caches config, DI, and translations; after any config or service change, run cache:clear --env=prod and rebuild the container. Stale cache is the most common cause of "my decorator isn't applied" and "my translation/media update didn't take."
• Debugging: use debug:container --tag= and debug:router to find the bundle's services and routes, then set Xdebug breakpoints in its normalizers/processors and the new translation/media handlers. bin/console --env=dev with the web profiler is your fastest feedback loop for form/grid/media changes.
• Extension points to prefer: event subscribers, service decoration, form extensions, and datagrid extensions. Avoid class rewrites and avoid touching vendor/; both make upgrades and debugging miserable.
• Evaluate native reference entities first. Akeneo 3.0 introduced reference entities, which overlap heavily with "advanced reference data." If you are on a modern Akeneo, compare the bundle's feature set — including this release's translated medias — against native reference entities and their media handling before investing in porting this bundle.
• Smoke test the kernel. Add a test that boots the kernel with the bundle enabled and runs lint:yaml/lint:container; it catches most install-time incompatibilities in seconds and is cheap insurance for a package this old. Add a translation/media round-trip test too, since that is where v1.0.0 changed behavior.