Mapping Connector Bundle Laravel Package

Getting Started

First, a reality check: this is not a Laravel package. It's a Symfony bundle built for Akeneo PIM (2.x/3.x era), so "leverage day-to-day" means running it inside an Akeneo instance, not composer require-ing it into a Laravel app. If your stack is Laravel-only, the correct integration is a sidecar: run Akeneo + this bundle as a service, and talk to it over HTTP or bin/console.

Minimal steps (Akeneo host required):

1. Add the repo via VCS since Packagist/abandonment status is unclear from 0 dependents:

   composer config repositories.mapping-connector vcs https://github.com/nicolasfl/MappingConnector
   composer require nicolas-souffleur/mapping-connector-bundle:dev-master
   

2. Register the bundle — app/AppKernel.php (Akeneo 2.x) or config/bundles.php (Akeneo 3.x).
3. Clear cache (bin/console cache:clear), then open Products → Import/Export profiles in the Akeneo UI. The connector appears as a new job type with a mapping configuration UI.
4. Where to look first: the bundle's Connector/ directory (Reader/Processor/Writer steps) and its Resources/config/ — that's where the mapping schema lives.
5. First use case: an export job that renames Akeneo attribute codes to vendor-friendly column headers (e.g. description-en_US → Description EN) for a feed you hand to marketing/ERP. Or the reverse: ingest a supplier CSV with arbitrary headers into Akeneo attributes.

Implementation Patterns

Export pattern (the common one). Create an export profile in the UI, attach a mapping (source attribute code → target column header, plus locale/channel scope per attribute), then schedule the job:

bin/console akeneo:batch:job <job_code> --env=prod

Wrap that in a Laravel scheduled command (Process::run(...) or exec) if your orchestrator is a Laravel app — that's the pragmatic bridge. Poll job status via the Akeneo REST API /api/rest/v1/jobs/execution/{code} if you need the result back in Laravel.

Import pattern. Supplier feed → mapping file → connector reads the CSV, translates columns to attribute codes, applies type coercion (metric with unit, simpleselect with option code). Use the connector's processor step to reject unknown columns rather than silently drop them.

Per-attribute scoping. Each mapping row carries attribute_code, optional locale, optional channel, and a type. Multi-locale attributes need one mapping row per locale — this is the pattern that trips most people up.

Extending it. Follow Akeneo connector conventions: implement a Step and register it with the appropriate tag (akeneo.step.reader, akeneo.step.processor, akeneo.step.writer). If you need custom transformation (e.g. splitting a name field into firstname/lastname), a custom Processor is the cleanest extension point — don't fork the writer.

Laravel-side orchestration. Treat it as an external process: queue an Artisan job, shell out to the Akeneo console command, store job codes in a table, poll, then consume the produced CSV with League\Csv (Laravel ecosystem) to do anything further.

Gotchas and Tips

• Dead as of 2019. Last release Feb 2019, Akeneo 2.x/3.x era. It will not install cleanly on Akeneo 4+ (PHP 8, new UI, removed legacy Symfony). Pin to a commit hash — dev-master will drift.
• Zero dependents = no safety net. Expect to read the source and patch it. Budget time for that; don't assume docs exist.
• Locale/channel mismatch is the #1 failure. "Attribute not found" almost always means a missing or wrong locale/channel on a mapping row, not a bad attribute code.
• Option codes vs. labels. Akeneo stores simpleselect values as option codes. If your supplier CSV uses human labels, you need an explicit code mapping — the connector won't guess.
• Encoding/delimiter quirks. UTF-8 BOM, ; delimiters, and Windows line endings all bite import readers. Normalize upstream.
• Debugging: bin/console akeneo:batch:job <code> -vvv and check var/logs/. The connector's step messages are terse; add logging in the processor if a row silently disappears.
• No Laravel affordances. No service provider, no facade, no config/ publish, no queue integration. Do not try to treat it as a Laravel package — the abstraction mismatch will cost more than the sidecar approach.
• Fork-ready. Given the maintenance state, cloning and vendoring into your Akeneo build is often safer than depending on the remote.
• Not a replacement for Akeneo's native CSV connector. If your column names already match attribute codes, you don't need this bundle at all — use native import/export. Reach for this only when column names genuinely diverge.