Optilog Laravel Package

Getting Started

1. Require the bundle: composer require splash/optilog. It is an embedded Splash connector, so it assumes splash/connector (or splash/core) is already installed in your Splash API host project. Confirm the version constraint in composer.json matches your Splash major (2.x vs 3.x — these are not compatible).
2. Register the bundle in config/bundles.php if not auto-registered by Flex:

   Splash\Optilog\OptilogBundle::class => ['all' => true],
   

3. Configure credentials under the bundle's config key (usually splash_optilog in config/packages/splash_optilog.yaml), sourced from env vars: OPTILOG_API_URL, OPTILOG_USERNAME, OPTILOG_PASSWORD/OPTILOG_API_KEY, and often a company/site identifier because Optilog is a WMS/TMS style system scoped per warehouse.
4. Enable the connector in your splash.yaml entity list. First use case: pull reference data (Products, ThirdParties) from Optilog into Splash, then push transactional data (Orders, Shipments, Stock) back. Most teams start with products because it exercises auth, pagination, and the mapping layer with the least business risk.
5. Verify connectivity via the Splash console — bin/console splash:connector:test optilog or splash:connector:walk products depending on your Splash version. A walk prints the normalized Splash payload for one entity, which is the fastest way to sanity-check field mapping.
6. Where to look first:
   • src/Connectors/ — the class implementing ConnectorInterface; this is your entry point for entity-level sync logic.
   • src/Services/ — the HTTP client wrapper around Optilog's REST endpoints (auth, pagination, error decoding).
   • src/Resources/config/ — DI wiring, service aliases, and the default config tree.
   • src/Mapping/ (or src/Fields/) — the field translation between Splash's canonical model and Optilog's payload shape.

Implementation Patterns

One connector per entity, one client for everything. Keep ProductsConnector, OrdersConnector, etc. thin — they should only orchestrate "fetch page → map → yield entity." All HTTP, retry, and auth logic belongs in the Services/ layer so it can be reused and unit-tested in isolation.

Pull with a cursor, not offsets. Optilog endpoints in this family are typically {id}, ?updatedSince=…, or paginated via a link. Drive incremental syncs off a Splash-stored lastSync timestamp, and store the highest updatedAt you actually saw — not now() — so midnight boundary and clock skew issues do not silently skip records.

Push in bounded chunks. Optilog usually accepts 100–500 lines per call but rejects the entire batch on a single bad row. Pattern:

foreach (array_chunk($orders, 100) as $chunk) {
    $result = $this->client->postOrders($chunk);
    // Optilog returns per-line acceptance; map failures back to Splash entities
    $this->handlePartialFailures($chunk, $result);
}

Emit per-entity success/failure back to Splash rather than throwing on the first error, otherwise Splash retries the whole batch and you duplicate orders.

Mapping belongs in config, not code. Expose status codes (OrderStatus, ShipmentStatus) and warehouse IDs via the bundle config so a deployment to a new Optilog tenant does not require a code change. Default mappings in code, override in splash.yaml.

Use Symfony's HttpClientInterface decorator chain (the bundle typically wires one). This lets you inject a mock MockHttpClient in tests and add a Logger/RetryableHttpClient middleware without touching connector code. If the bundle hardcodes file_get_contents or a raw curl handle, that's a red flag — wrap it yourself before doing anything else.

Event subscriber for pre-push enrichment. Register an Events\OrderPushEvent (or the Splash equivalent) subscriber in src/EventListener/ to inject fields Optilog requires but Splash does not carry — e.g. warehouseCode, carrierCode, or a customerRef derived from the third-party. Keeping this out of the connector class means you can vary behavior per host without forking.

Test fixtures beat live calls. Build a Fixtures/ set of representative Optilog responses (a full page, an empty page, a 429, a 401, a 200-with-error-body) and write integration tests against MockHttpClient. For a zero-star package this is the single highest-value investment you can make.

Gotchas and Tips

• Version compatibility is the #1 risk. Zero stars, zero dependents, and no visible README mean the bundle is almost certainly a private connector published for a single deployment. Pin it exactly ("splash/optilog": "1.2.3") and diff the repo against your Splash core version before upgrading either side. Splash's connector interfaces change between majors.
• HTTP 200 with an error body. Optilog-family REST APIs often return 200 OK with {"status":"error","messages":[…]}. If you only check $response->getStatusCode(), failed orders will be marked as synced in Splash and you will never retry them. Decode the body and assert on an explicit success field before returning.
• Token/session lifetime. Auth is typically a login call returning a short-lived token. Do not put credentials straight into per-request Authorization headers and hope; implement a memoized token fetch with refresh-on-401 in the API client. Caching the token in Symfony's cache pool across workers avoids re-authenticating per entity.
• Pagination drift. If you page while records are being inserted, offset pagination will duplicate or skip rows. Prefer updatedAt-based cursors, and de-duplicate by Optilog's id when yielding to Splash.
• Rate limiting is real. WMS endpoints are often throttled per tenant, sometimes as low as 5 req/s. Add a RateLimiter middleware or a simple usleep backoff with exponentiation; Splash's own retry will hammer the endpoint and can get your IP/account blocked.
• Config key typos fail silently. The bundle's Configuration tree usually does not strict-type everything. If a value appears ignored, dump the resolved config (bin/console debug:config splash_optilog) rather than guessing.
• Logging leaks secrets. Splash logs full request/response at debug level. Ensure the Optilog Authorization header and any password field are redacted in your Services/ client before they get logged — this bites during incident triage.
• Extension points to prefer: override the connector service via services.yaml alias (not by editing vendor), extend the abstract connector if one exists, and add custom EventListener subscribers. Avoid forking the bundle — with no upstream activity, your fork will never receive fixes.
• Multi-warehouse semantics. Optilog is frequently scoped per site/warehouse. Splash's canonical order/stock model is single-context. Build an explicit warehouseCode dimension into your mapping or you will sum stock across sites and produce nonsense.
• Deployment footprint. The connector runs inside the Splash API worker. Long walk loops and full re-syncs need memory_limit and max_execution_time raised, and should be chunked with generator-based iteration so a 200k-SKU catalog does not OOM.
• Assume no upstream support. Treat the bundle as vendored code: add your own tests, pin the version, and keep a short PATCHES.md describing any local edits, so you can reapply them after an eventual update.