Akeneo Extension Laravel Package

Getting Started

First, calibrate what this is. Despite living in a composer-shaped world, textmaster/akeneo-extension is an Akeneo PIM bundle (Symfony kernel, DependencyInjection/, Resources/config/), not a Laravel package. There is no TextMasterServiceProvider, no facade, no publishable config. You install it into an Akeneo project, not into a Laravel app. If your day-to-day is Laravel, the realistic value is either (a) you also operate an Akeneo instance for product data, or (b) you read this bundle as a reference implementation and rebuild the workflow against TextMaster's REST API in your own Laravel service.

Minimal steps (Akeneo route):

1. Get TextMaster API credentials (API key + secret) from your TextMaster account; note the sandbox vs. production base URL and use sandbox keys first.
2. composer require textmaster/akeneo-extension in the Akeneo project, pinning a version compatible with your Akeneo major (the 4.0.x line is Akeneo 4-era, last released 2021-09-01).
3. Register the bundle in config/bundles.php and confirm it appears in the PIM's connector/import-export screens after bin/console cache:clear.
4. Configure credentials via environment/parameters (not committed YAML), plus default source locale, target locales, and the attribute whitelist.
5. Run one real order against sandbox with two products and a single attribute.

Where to look first: the TextMaster API client/service, the connector's form-type/config classes (that's where the attribute/locale selection lives), and the persistence layer for translation projects — that model is what your sync job keys off.

First use case: take name and description on ~10 products, order translation from your source locale into one target locale, then watch the sync command move the project pending → in_progress → completed and write the values back. Do that once end-to-end before scaling to a full catalog; it exercises credentials, locale mapping, value write-back, and the polling command in one pass.

Implementation Patterns

Ordering is an async, multi-step state machine — model it that way. The natural Laravel-side shape (or the shape to look for in the bundle) is: translation_project (TextMaster project id, source locale, target locale, status, timestamps) → translation_item (product sku, attribute code, locale, scope, status). Ordering is slow and billed; polling is cheap. Never call TextMaster inline in a web request.

Scheduled sync, not webhooks. The 2021-era extension is built around a console/batch command that polls project state and imports completed translations. Wire it into cron (or a Laravel Schedule::command(...)->everyFifteenMinutes() if you're mirroring the pattern) and make the sync idempotent: key on textmaster_project_id + sku + attribute + locale, and treat "already written" as success rather than re-PATCHing.

Keep Akeneo as the system of record. The write-back step is a product-value PATCH with locale and scope — in Akeneo's API shape, {"values": {"description": [{"locale": "fr_FR", "scope": "ecommerce", "data": "..."}]}}. Only localizable attributes accept localized values, and only scopable ones accept a scope; get that wrong and values silently vanish or 422.

If you're rebuilding this in Laravel (the likely case): treat TextMaster as a third-party HTTP dependency.

• Http::withBasicAuth($key, $secret)->baseUrl($sandbox ? ... : ...)->timeout(30) behind a TextMasterClient class.
• Queue jobs: CreateTranslationProject, PollProjectStatus, ImportCompletedTranslations — each retryable and idempotent.
• Persist the raw request/response payload alongside each project row; you will need it for support and for cost reconciliation.
• Put a feature flag in front of the "send to translation" action so you can disable it without a deploy when billing surprises appear.

Scope tightly and lock during translation. Translation is billed per word, and re-ordering already-translated text is the classic waste. Choose the attribute whitelist deliberately (marketing copy yes, SKUs and dimensions no), and decide a conflict policy up front: either lock the attribute for editing while a project is open, or accept last-write-wins and document it. Silent overwrites of a merchandiser's manual edit are the most common complaint.

Sandbox for everything but the final check. Sandbox projects simulate the lifecycle without real translators or charges; use them in CI-adjacent smoke tests and keep one production run in the release checklist.

Gotchas and Tips

• It is not a Laravel package. Don't try to composer require it into an Eloquent app and expect a service provider. Any integration advice that frames it as a Laravel package is mistranslated from a generic template.
• Maintenance risk is the headline. Last release 2021-09-01, 2 stars, and a NOASSERTION license. Treat the license as "all rights reserved" until you've read the LICENSE file — if you intend to ship this commercially, get that cleared or plan to fork.
• Version matrix, not semver, is the constraint. The 4.0.x line targets Akeneo 4.x / Symfony 4–5 / PHP 7.4–8.0. On Akeneo 5+ or PHP 8.1+ you will be patching composer.json and probably a handful of deprecated Symfony calls. Budget for a fork.
• The only release note is a schema-mapping detail. v4.0.2 makes created_at / updated_at nullable in the Doctrine mapping. That's a config-level change: it only matters for schema-diff tooling, and only if your live tables disagree with the mapping. Run a schema diff in a staging clone before deploying — a diff proposing ALTER TABLE ... MODIFY created_at NULL is the expected (and reviewable) outcome, not a surprise to ignore.
• Locales must pre-exist in Akeneo. Ordering a translation into de_DE that isn't enabled in the PIM produces a project whose results have nowhere to land. Validate target locales against bin/console akeneo:locale:list-style output before creating the order.
• Locale vs. channel confusion is the #1 bug. locale selects language, scope selects channel. Attributes that are neither localizable nor scopable (identifiers, numbers, booleans) should never enter the whitelist — but nothing stops you from adding them, and the failure is silent.
• Opaque 422s from the API. TextMaster validation errors come back with thin messages. Log the full request body (redact the auth header) for any non-2xx; the offending field is usually a missing target locale or a project template mismatch.
• Idempotency and duplicate orders. A retried job or a double-clicked button can open two projects for the same product+locale and bill twice. Enforce a unique constraint on (sku, attribute, locale) for open projects at the database level, not in application code.
• Debugging the sync: the extension's value-write step is where everything fails last and loudest. Add a dry-run flag to the import command so you can see what would be written before it lands.
• Extension points worth adding in a fork: a real webhook listener (TextMaster can push status changes) to replace polling, per-channel attribute filters, and a cost estimate shown at order time so merchandisers see the bill before they click.
• Rate limits and timeouts. Project creation can take seconds; bulk-order in batches of tens, not thousands, and use queued retries with backoff. A single synchronous loop over 5,000 products will hit both HTTP timeouts and API throttles.