Optilog Laravel Package

Technical Evaluation

What this is. splash/optilog is an embedded REST API connector that wraps the Optilog logistics/transport management API and exposes it inside a PHP application. The repository name (Optilog-Bundle), the package namespace (splash/*), and the “Embedded” descriptor place it in the Splash e-commerce/ERP connector family, where each WMS/TMS/ERP integration ships as a thin adapter over a shared connector abstraction. It is not a Laravel package in the conventional sense — there is no evidence of a Laravel service provider, facade, publishable config, or Laravel-version constraint. Treat it as a PHP integration library that happens to run inside a Laravel app.

Architecture fit. The fit depends entirely on how much of the Splash connector contract is baked into the classes. If the connector is a self-contained client (HTTP transport + DTOs + endpoint methods), it drops cleanly behind an interface in our domain layer. If it inherits from Splash base classes and expects Splash’s container, config tree, logging interface, and entity/mapping conventions, we inherit the Splash framework as a transitive dependency — an unacceptable coupling for a Laravel product. The presence of splash/connectors-style abstractions would be the single largest architectural risk, and it is the first thing to verify by reading composer.json and the top-level src/ tree.

Integration feasibility. Mechanically simple: composer require, instantiate, inject credentials, call methods. Practically uncertain: no published API documentation, no README signal, no example usage in the metadata we have. Feasibility therefore hinges on there being a Splash-authored sandbox account and credentials for Optilog. Without a sandbox, integration is blind — we would be writing against an undocumented French logistics API with only this package’s method signatures as a spec. The Embedded label also implies synchronous request/response calls into Optilog at the point of use, which has consequences for order flow latency and failure handling.

Technical risk. High, and mostly non-technical in origin:

• Adoption signal is zero. 0 stars, 0 dependents, 0 score, blank star count. There is no observable install base — no third party has validated this against a real Optilog instance in public. We would be the first, in effect.
• GitLab-hosted, not Packagist-visible. Composer installation likely requires a VCS repository entry and possibly auth tokens. That is an ongoing CI/CD and secret-management burden, and it means no Packagist metadata (download stats, version history, dependency graph) to reason about.
• Bus factor and provenance. Single-vendor, single-team ownership with no public issue tracker activity to read. If Splash deprioritizes this connector, we fork and maintain it ourselves — including keeping pace with Optilog API changes we cannot see.
• Versioning and stability. No release tags or semantic-versioning guarantees are visible. We would need to pin to a commit SHA in composer.lock and treat every upstream merge as a review gate.
• Credential and data surface. The connector handles Optilog auth and transmits order, shipment, and likely customer data. Audit of token handling, logging of payloads, and TLS verification is mandatory before production use.
• Unspecified error semantics. REST connectors in this family typically throw on non-2xx and return arrays; nothing indicates retry policy, rate-limit handling, idempotency keys, or partial-failure reporting. For a logistics API where duplicate order submissions create real-world duplicate shipments, this is the highest-severity unknown.

Key questions for the vendor/repo owner.

1. Does splash/optilog require any splash/* framework packages at runtime, or is it standalone with PSR-7/PSR-18 or Guzzle?
2. What is the supported PHP and Laravel version matrix, and is there an integration test suite?
3. Is there an Optilog sandbox, and who holds the credentials?
4. Which Optilog API version is targeted, and what is the vendor’s deprecation notice period?
5. Does the connector expose idempotency keys, retry/backoff, and rate-limit awareness?
6. Is there a tagged release we can pin, and is the package published to a private Packagist/Satis registry?
7. What is the support commitment — SLA, issue triage, security disclosure path?

Integration Approach

Stack fit. Assume Laravel 10/11 with PHP 8.2+. The connector should be treated as an external SDK, not an application dependency to be used directly in controllers or jobs. The correct shape is: a thin OptilogGateway interface in our domain layer, an adapter implementing it that delegates to splash/optilog, and DTO mapping at the boundary so vendor classes never leak into our models, events, or API responses. If the package turns out to require Splash framework internals, we abandon it and write a ~300-line HTTP client against the Optilog API directly — at this adoption level, the package saves less engineering time than the coupling costs.

Migration path. Because there is no incumbent integration, this is greenfield rather than migration. Phase it:

1. Spike (1–2 days). Clone the repo, read composer.json and src/, attempt composer require from VCS in a scratch Laravel app, and confirm whether it boots without Splash packages. This single step decides build-vs-adopt.
2. Contract capture. With sandbox credentials, exercise each endpoint the connector exposes and record request/response fixtures. These become our test suite regardless of which implementation we ship.
3. Adapter. Implement OptilogGateway over the package; write contract tests against the fixtures using Laravel’s HTTP fake layer.
4. Feature-flag rollout. Ship behind a flag, run in shadow mode against real traffic, compare outcomes before enabling writes (order submission, shipment creation).

Compatibility. Pin to a commit SHA, not a branch. Add a composer.json VCS repository entry with a read-only deploy token, stored in CI secrets and in the build environment — not in developer dotfiles. Verify PHP constraint compatibility with our runtime and check for Guzzle major-version conflicts with existing HTTP clients.

Sequencing. Authentication and read-only endpoints first (carrier lookup, shipment status, reference data) — these validate connectivity, credentials, and payload shapes without business risk. Writes (order creation, label generation, cancellation) come only after idempotency and rollback behavior are proven in the sandbox. Do not couple the connector to synchronous user-facing requests; wrap all writes in queued jobs with retry and dead-letter handling.

Operational Impact

Maintenance. Assume we own this code eventually. Budget for a fork: mirror the repository internally, apply security patches ourselves, and track Optilog API changes through the vendor relationship rather than the package. The connector’s thinness is a mitigating factor — a small surface is cheap to reimplement if upstream goes quiet. Add a quarterly review of upstream commits and a documented exit cost.

Support. No public issue volume, no release notes, no community to consult. Support is a direct relationship with the Splash/Optilog account team, which must be established contractually before this lands in a revenue path. If Optilog changes an endpoint, our recourse is a support ticket with a logistics vendor, not a GitHub issue.

Scaling. Every connector call is a synchronous network hop to a third-party TMS. Under load, that translates to latency in our request path and thread/worker occupancy. Mitigations: route all calls through the queue, enforce timeouts at the HTTP client (aggressively — 5–10s), apply circuit-breaking so an Optilog outage degrades our order flow gracefully instead of exhausting PHP-FPM workers, and cache reference data (carriers, service levels, zones) with a TTL rather than fetching per request. Confirm Optilog’s rate limits and per-account concurrency caps during the spike; logistics APIs frequently throttle hard.

Failure modes to design for explicitly.

• Duplicate submissions. A timeout after Optilog accepted an order produces a duplicate on retry. Mitigate with client-generated idempotency keys and a reconciliation query before retry.
• Partial state. Order created but label not generated — model this as a multi-step saga with compensating cancellation, not a single transaction.
• Silent data loss. Connectors that swallow non-2xx responses into null or empty arrays are common in this family; assert on response codes explicitly and log full request IDs.
• Credential expiry. Token refresh failures surface as 401s mid-batch; alert on auth errors separately from business errors.
• Schema drift. Optilog adds a required field, our writes start 400ing. Contract tests run nightly against the sandbox to catch this before customers do.
• Observability gap. Without instrumentation, failures inside a vendor library are invisible. Wrap the adapter with structured logging (correlation ID, endpoint, status, latency) and emit metrics per endpoint.

Ramp-up. Expect roughly one to two weeks for an engineer to become productive here: most of it is Optilog domain vocabulary (shipment vs. consignment, service levels, label formats, EDI-adjacent concepts), not PHP. That knowledge currently lives only in the vendor’s documentation and our sandbox experiments — capture it in an ADR and a runbook. Plan for at least two engineers to hold it so the integration is not a single-person dependency on top of a single-vendor dependency.

Overall recommendation. Proceed only through a time-boxed spike with sandbox access, and only if the package proves to be free of Splash framework couplings. Given zero adoption, zero dependents, no release signal, and GitLab-only distribution, the default posture is treat as reference implementation: use it to learn the Optilog API surface, then decide whether to depend on it or own a small internal client. Do not put it on a critical order path without idempotency, circuit-breaking, reconciliation, and a named vendor contact.