Laravel Productive Laravel Package

Technical Evaluation

Verdict: worth a timeboxed spike, not an unconditional adoption. This is an unusually complete first release — full endpoint coverage, live-API corrections, contract tests, fake-based test doubles — but it is v0.1.0 with an unverified write path and no webhook receiver. Treat it as a strong accelerator for read-heavy integrations and a supervised bet for anything that mutates customer data.

Architecture fit

• Fits the standard Laravel integration seam: publishable config, a connector with typed exceptions, a facade entry point, an artisan health check. Low coupling — it sits at the edge of the app, not in the domain.
• Readonly, typed models are DTOs, not Eloquent models. The team must map them into our own domain/persistence layer. That's the right boundary, but it needs to be an explicit design decision up front or someone will try to treat them as records and get burned by the absence of dirty tracking and save semantics.
• Strictness is deliberate: relationship accessors throw on type mismatch. Good for surfacing drift loudly, bad for resilience — every accessor call is a potential runtime exception and needs an owning policy (fail the job vs. log and skip).
• Inputs distinguishing omitted from explicit null is the correct PATCH semantic and materially reduces the classic "accidentally cleared a field" class of bug.

Integration feasibility

• The headline is coverage: 668 operations across 139 resources plus the 3 bulk-hidden creates. That removes the usual "SDK does 60%, we hand-roll HTTP for the rest" tax, which is where most of the estimate for this kind of work normally goes.
• Self-corrected against the live API — 31 corrected types, 73 undocumented attributes, 10 undocumented relationships, JSON-text list decoding, required create fields the spec omits. This is the difference between a spec wrapper and a usable client, and it is the strongest signal in the notes.
• Unknown: is there a raw-request escape hatch? Any integration eventually needs to hit something the generator missed or that changed after release. Without it, the package becomes a blocker rather than an accelerator.
• Testing story is production-grade for a 0.1: Productive::fake() records real wire traffic, seeding by operation or path, plus assertions and example-derived factories. This is the single biggest lever on delivery speed and should be weighted heavily.

Technical risk

Key questions for engineering / the maintainer

1. What are the supported PHP and Laravel version floors, and what is the transitive dependency footprint?
2. Is the throttle cache store required to be shared across nodes? What happens under the array driver in a multi-pod deployment?
3. Is there a raw/ungenerated request path for endpoints the generator misses?
4. Does Productive support idempotency keys on writes? If not, how are retried or partially-failed creates reconciled?
5. How are write operations expected to be validated before we trust them — is there a sandbox org for staged verification?
6. What is the intended upgrade cadence for the generated surface, and is the spec-drift PR reviewed by the maintainer or purely automated?
7. Is there any commitment to a 1.0 / stability milestone?

Integration Approach

Stack fit

• Composer-installed Laravel package; matches a conventional Laravel service. No runtime infrastructure beyond a cache store (required — see operational impact) and outbound HTTPS.
• Multi-organization and per-call token support, plus Octane safety, is a genuine fit signal for multi-tenant products where each tenant holds their own Productive credentials. Verify residency: tokens per call must not leak across coroutines/requests under Octane, and this needs a targeted test in our own suite, not just trust in the release note.

Migration path

• Greenfield integrations: adopt directly as the transport layer; do not wrap it further.
• Existing hand-rolled or third-party integrations: strangler pattern. Introduce the SDK behind our existing repository/gateway interface, migrate one resource at a time, and delete the old path only after the new one has run in production. Do not do a big-bang swap on writes.

Compatibility

• JSON:API semantics (included, identity index, ext=bulk) mean callers must understand compound documents; that's a knowledge dependency, not a code dependency.
• Cursor pagination with a page-number fallback, plus the repeated-next-link guard, covers the known Productive pagination quirks. Validate explicitly against the reporting endpoints, which are the most likely to diverge.
• Client-side throttling is advisory, not authoritative. Server 429 handling must remain in place regardless.

Sequencing

1. Spike (3–5 days): ping command, auth, one read resource end to end, fake-based test in CI, shared-cache throttle behaviour under two workers. Gate: does it survive our CI and staging?
2. Reads in production: migrate reporting and list screens first. Low blast radius, exercises pagination, includes, filters and the reports limit.
3. Non-destructive writes: creates only, in a sandbox org, cross-checked against the UI. Extend the live-verification beyond the 14 upstream creates.
4. Destructive writes and actions: behind a feature flag, with reconciliation and an audit trail, and only after step 3 has run clean for a defined period.
5. Polling/changefeed layer: build our own since webhooks are absent; design it to be replaced by a receiver when one ships.

Operational Impact

Maintenance

• The weekly spec-drift workflow that opens a PR is the right pattern and materially lowers long-term cost — but it produces a PR, not an upgrade. Someone must own triage: run contract tests, scan docs/reference.md and docs/api-differences.md diffs, and decide on the generated-code churn. Budget a recurring, non-trivial slice of an engineer's time; generated diffs are noisy and effectively unreviewable line by line.
• Local maintenance tooling (composer record, seed, record:types, record:fixtures with a leak check) is a meaningful operational asset: it lets us re-verify against the live API ourselves instead of waiting upstream. The leak check is a good sign of production hygiene, but re-recording touches real customer data — gate it to a dedicated org and treat the guard as defence in depth, not a licence.
• Assume we may need to vendor/fork if the maintainer stalls. Before committing, confirm the code is legible enough to patch — generated code often is not.

Support

• Single-maintainer package at 0.1.0 with no stated SLA. Our mitigation is a documented fallback to direct HTTP for any endpoint that blocks us, plus the escape-hatch question above.
• Internal support burden lands on whoever owns the integration: typed exceptions are a help (they make failure classes enumerable), but the mapping from exception type to user-facing behaviour is our job.

Scaling

• The per-token, cache-backed throttle is the primary scaling constraint. If several services or pods share one Productive token, the throttle must sit on a shared cache or each node will independently believe it is under the limit and collectively blow through it. This is the single most likely production surprise.
• Use lazy() for large result sets rather than all(); memory blowups on wide resources are the usual second surprise.
• ext=bulk and report grouping reduce round trips; prefer them over client-side fan-out.
• Retry policy is correctly scoped — 429 for every method, 5xx and dropped connections for reads only. That protects writes from accidental duplication but means a dropped connection mid-write surfaces as an error to the caller, who must own reconciliation.

Failure modes to design for

• 429 storms when multiple consumers share a token without a shared throttle cache.
• Write succeeds server-side but the response is lost → duplicate or orphaned records. Needs an application-level dedupe/reconcile strategy; idempotency-key support is unconfirmed.
• Relationship accessor throws on a type mismatch after an upstream API change — surfaces as a hard failure in whatever code path dereferences it. Decide per call site: fail loudly in ETL, degrade gracefully in UI.
• Polling gaps: without webhooks, missed or delayed changes are inherent. Bound staleness explicitly and communicate it to users rather than implying real-time.
• Spec drift PRs that land and are merged without live re-verification — the corrections layer can regress while tests stay green.
• Pagination edge cases on reporting endpoints; the loop guard prevents infinite hangs but not silently truncated data.

Ramp-up

• JSON:API fluency (included resources, identity index, sparse fieldsets, bulk extension) is the real learning curve, not Laravel. Estimate roughly half a day for a competent Laravel developer to be productive on reads, and two to three days to be confident on write flows, error taxonomy and reconciliation.
• Productive::fake() plus factories should cut test-writing effort significantly and is the main reason to expect a fast ramp — insist the team writes its first feature test against the fake in the spike so this claim is validated early rather than assumed.