Export Connector Bundle Laravel Package

Getting Started

This release (4.0.0) is primarily a compatibility bump: the package now targets Akeneo PIM 4.0 and 5.0. That single line is the entire changelog, so treat the upgrade as a breaking-change event until proven otherwise — a major version bump combined with an Akeneo platform realignment almost always means dropped support for older Akeneo versions (3.x and below) and, quite possibly, changes to the underlying API client, endpoint paths, or authentication flow.

Minimal first steps:

1. Confirm your Akeneo version first. Run php artisan --version-style checks on the PIM side (or check the Akeneo admin UI footer / composer show akeneo/pim-community-dev in the PIM itself). If you are still on Akeneo 3.x, do not upgrade this package — pin the previous major.
2. Read the package's own README and UPGRADE/CHANGELOG files in vendor/, not just the release notes. The composer.json of the new tag will tell you the truth about PHP and Laravel version constraints and about which akeneo/api-php-client (or equivalent) major it pulls in. That constraint is the real compatibility contract.
3. Install into a scratch branch with composer require <vendor>/<package>:^4.0 -W and inspect the diff of any published config: php artisan vendor:publish --provider="...\ServiceProvider" --tag=config --force into a temp path and diff it against your existing config/*.php.
4. First use case: the lowest-risk smoke test is a read-only call — fetch a single product or a page of products by identifier — through the package's facade/client, with credentials in .env. If that works after the upgrade, writes are next.

Where to look first in the codebase: the service provider (bindings and config keys), any Contracts/ or Client/ directory (interface stability), and the exception classes (error taxonomy usually shifts across API client majors).

Implementation Patterns

Wrap the client behind your own interface. This package's major-version churn is driven by Akeneo's platform, not by your domain. Bind the package client to an application-level interface (ProductRepository, AkeneoGateway) in a service provider so the next Akeneo bump touches one adapter class instead of forty call sites. This is the single highest-leverage pattern with packages of this type, and 4.0.0 is exactly the kind of release that validates it.

Configuration and credentials. Keep host, client ID, secret, username and password in config/services.php backed by .env. Never let the package read credentials directly from env() in its own config file — publish the config and reference your own keys, because published configs are cached with config:cache and env() calls inside them return null in production.

Sync jobs belong on the queue, always. Akeneo API calls are network-bound and rate-limited. Wrap every write in a queued job with $tries, $backoff and $timeout set explicitly. Use ShouldBeUnique keyed on the product identifier to avoid duplicate upserts racing each other — Akeneo will happily accept them and you will get confusing last-write-wins behaviour.

Batching and pagination. For reads, page through results with the package's paginator rather than loading collections; product payloads are large and memory blows up quickly on catalog-wide scans. For writes, chunk your upserts and inspect the returned per-item error array — Akeneo's batch endpoints return HTTP 200 with embedded per-item failures, so a "successful" response is not proof of success.

Integration tip — treat Akeneo as the source of truth for catalogue data, Laravel as the source of truth for everything else. Store an akeneo_identifier (and a updated_at mirror) on your local models. This gives you idempotent upserts, lets you reconcile drift with a scheduled command, and makes the migration to the next Akeneo version a re-sync rather than a data-archaeology project.

Testing. Do not hit a real PIM in your test suite. If the package ships a fake or a transport abstraction, use it; otherwise bind a mock of your own gateway interface in the container. For integration confidence, run a single contract test against a dockerised Akeneo (there are community images for 5.0) in CI, nightly rather than per-commit.

Gotchas and Tips

• The changelog is one sentence. There is no upgrade guide, no list of breaking changes, and no deprecation notices. Assume breaking. Diff the composer.json between the 3.x tag and 4.0.0 — the PHP, Laravel and Akeneo client constraints there are the only reliable record of what actually changed.
• "Works with Akeneo 4.0 and 5.0" implies dropped 3.x support. If any production system still talks to an Akeneo 3.x instance, this is a hard stop. Version-gate your deployment: package major and PIM major must move together.
• Akeneo 4.0 → 5.0 has its own API differences. Supporting both does not mean both behave identically — response envelopes, endpoint availability and required fields differ between the two. Test against the version you actually run, and don't assume a green suite on 5.0 means green on 4.0.
• Pagination semantics and page-size caps are a classic source of silent data loss after a client upgrade: the client's default page size changes, your scan processes half the catalogue, nothing errors. Assert the expected item count in at least one scheduled sync.
• Rate limiting and 429s. Akeneo throttles. If your package version changed the retry/backoff behaviour, your queue workers may start failing en masse. Set explicit retry policy at the job level rather than relying on the package default.
• Timeouts on large product models. Media and variant payloads are heavy; the default HTTP timeout is usually too short. Publish the config and set an explicit timeout, and prefer queue over synchronous calls in request/response cycles.
• Config cache after upgrade. Always run php artisan config:clear && php artisan cache:clear after a major bump; stale serialised config from the old version references keys that no longer exist and produces null-pointer style failures inside the client.
• Extension points worth checking: the service provider's container bindings (override them to swap in decorators — e.g. a caching or logging wrapper), the event hooks if the package dispatches any, and the exception hierarchy (catch the package's base exception, not raw Guzzle exceptions, so a future HTTP-client swap doesn't break your handlers).
• Debugging: log the full HTTP method, URL, status and response body at debug level on a dedicated channel, with credentials redacted. With terse changelogs, request/response logs are the fastest way to discover that 4.0.0 changed a path or a payload shape.
• Pin tightly and upgrade deliberately. "vendor/package": "4.0.*" rather than ^4.0, paired with a CI job that runs the contract test against a real PIM on your exact Akeneo version.