Magento Connector Bundle Laravel Package

Getting Started

First thing to internalize: this is not a Laravel package. It is a Symfony bundle that must be installed inside an Akeneo PIM application and registered in that app's kernel. There is no service provider, no config file you publish with php artisan vendor:publish, no facade. Attempting composer require akeneo/magento-connector-bundle inside a Laravel composer.json will either fail dependency resolution (it pulls Akeneo pim-* components, BatchBundle, ConnectorBundle, Doctrine ORM, Symfony 2.x) or produce a package you can never load. Treat it as reference material and an integration endpoint, not a library your Laravel app consumes.

Where to look first, in order:

1. DependencyInjection/ and Resources/config/ — this is the wiring. Job definitions, step services, and parameters live here. Read the job YAML files first; they tell you what the connector actually does (reader → processor chain → writer) faster than any doc.
2. Writer/ — the Magento API client surface. This is where payloads are assembled and where you would subclass if you needed custom behavior.
3. Processor/ and Normalizer/ — attribute mapping, family handling, and configurable/variant logic. This is where 90% of real-world mapping problems surface.
4. The Akeneo UI under Exports → Create export profile — the day-to-day touchpoint. A "Magento" connector type appears once the bundle boots.

Minimal first use case (do this, not a full catalog):

• Stand up an isolated staging Akeneo at the exact target version and a staging Magento 1.x with a scratch store view.
• Install the bundle, register in AppKernel, clear cache, confirm the export profile type appears in the UI.
• Configure one profile: single channel, single locale, one small attribute set, one simple product with one image.
• Run it via akeneo:batch:job <job_code> and verify the product, its attributes, its category assignment, and its image land correctly in Magento.
• Only after that round-trips cleanly do you touch configurable products, options, or multi-store profiles.

If you are a Laravel developer whose job is to orchestrate these exports from a Laravel app (which is the realistic scenario), your "getting started" is different: you do not install this bundle at all. You drive Akeneo from the outside — via akeneo:batch:job triggered through SSH, Akeneo's REST API, or scheduled exports that drop files for a Magento-side importer — and you study this repo's job/profile structure to understand the contract you are triggering.

Implementation Patterns

Profile-as-configuration. The bundle's primary day-to-day surface is the export profile, not code. In practice you create or duplicate a profile per Magento store view, each with its own channel, locale, attribute mapping, and Magento credentials. Do not multiplex store views inside one profile — the mapping assumes a single target. Treat profiles as versioned configuration artifacts and keep their exported YAML in source control so a Laravel deployment pipeline can diff them.

The batch job is the unit of work. Everything runs as a standard Akeneo batch job (reader → processor(s) → writer), invoked with akeneo:batch:job. From a Laravel orchestration perspective, the useful pattern is to wrap invocation in a queued job that: runs the export via SSH or the Akeneo API, tails the batch status, captures the job execution log, and records a reconciliation row (source count vs. target count per family). Never fire-and-forget — the connector's failure modes are partial writes, so you need a follow-up verification step.

Fork-and-extend for custom mapping. When the default mapping does not fit, the correct pattern is to subclass the existing writer or implement Akeneo's WriterInterface/ProcessorInterface, register the new service in Resources/config/, and override the job's step definition via a compiler pass or job YAML override. This is standard Symfony DI — no Laravel service provider. If you must extend, keep the fork in a separate bundle so you can rebase against the upstream tag you pinned.

Attribute normalization belongs in the normalizer, not post-processing. Simple products flow through attribute-set normalizers reasonably well; configurable products need explicit handling of variant groups, axes, and option linkage. If you find yourself patching the Magento payload after the fact, you have chosen the wrong extension point — extend the normalizer that maps Akeneo attribute codes to Magento attribute codes instead. The mapping YAML is the seam; use it.

One profile per concern when catalogs grow. For large catalogs, partition exports by family or website view rather than scaling a single giant job. This is engineering work, not configuration toggling — but it is the pattern that keeps runtimes inside their window and makes partial failures recoverable per-partition.

Idempotent re-run is the workflow, not an edge case. Design every orchestration around the assumption that a job will be re-run: dedupe by SKU on the Magento side, treat "already exists" as a no-op where possible, and always run a post-export reconciliation report before marking the pipeline green.

Where this fits in a Laravel architecture. Realistic patterns, in preference order:

1. Middleware/decoupled — Akeneo export profile emits structured files; a Laravel queue worker (or a small Magento-side importer) consumes them and owns version-tolerant mapping. You control the contract and survive PIM upgrades.
2. Orchestration only — Laravel schedules and monitors akeneo:batch:job runs, stores execution history, alerts on failure, and computes reconciliation metrics. Your app never imports the bundle.
3. Fork-and-pin — only if a legacy estate must be maintained short-term. Vendor the bundle into the PIM image, pin exact Akeneo/PHP/Symfony versions, freeze the dependency graph, and plan the exit before you start.

Gotchas and Tips

• It is not a Laravel package and never will be. Do not try to require it into a Laravel app, do not look for a service provider, do not expect Laravel's config publishing. Any assessment that assumes "Laravel package" is misreading the artifact.
• Version lock matrix is mandatory. Pin Akeneo minor ↔ bundle commit ↔ PHP ↔ Symfony ↔ Magento API version ↔ Magento extension set. A mismatch here is the single most common install failure on legacy installs, and the failure surfaces as an opaque DI error, not a clear message.
• Everything targets EOL software. Magento 1 (EOL 2020), PHP 5.6/7.0, Symfony 2.x. Zero stars and zero dependents on the package means a thin knowledge base — most issues will be diagnosed from source, not from Stack Overflow. Budget for that.
• Partial-batch failures leave Magento inconsistent. Mid-run API timeouts can leave half-written products, orphaned or duplicated SKUs, and broken configurable/variant associations. Assume you need a reconciliation query per family (source count vs. target count, plus a missing/extra SKU list) as a hard gate in every pipeline.
• Delta logic is the weak spot. Removals, disabled products, and deleted attribute options are historically fragile — stale products can persist forever because the incremental path does not handle deletions cleanly. Prefer explicit full-refresh for families where drift matters, or write your own reconciliation-based removal step.
• Silent skips are real. Missing attribute options in Magento can cause products to be skipped without failing the job. If a product count is short, check option mapping before anything else.
• Media failures often do not fail the job. Image transfer can partially succeed and still report success. Verify image presence separately from product presence.
• Configurable assembly is order-sensitive. Changing option order in Akeneo can break variant associations on the Magento side. Treat axis/option ordering as part of your frozen config, and re-test after any option reorder in the PIM.
• Debugging the batch engine. akeneo:batch:job gives you a job execution ID; the Akeneo batch status and execution log are your primary forensic tools. Tailing those logs from the Laravel orchestrator (rather than parsing Magento errors) is the fastest path to root-causing partial failures.
• Extension points to know cold: WriterInterface/ProcessorInterface implementations, Resources/config/ job and service YAML, and the attribute-mapping YAML. If you extend anywhere else, you are probably fighting the framework.
• Support reality check. No vendor escalation path on either side, no upstream fixes, no CVE response. If you run this, you own the security patching for a PHP/Symfony stack that the rest of the industry left behind, and you need a named owner plus a runbook (job schedules, failure triage, re-run procedure, reconciliation queries) from day one.
• For anything greenfield: do not adopt. Akeneo 3+/SaaS with Magento 2/Adobe Commerce needs the official Akeneo Connector for Magento 2 (a Magento-side module) or a middleware integration — not this bundle. Use this repo to understand the export-profile/job/reconciliation pattern, then specify your replacement against Akeneo's API and Magento 2's import/API surface.