Record Laravel Package

Technical Evaluation

Architecture fit. psx/record is a small value-object / data-bag library extracted from the PSX API framework: a schema-less key/value record with consistent get/set and array-access semantics. In a Laravel application that role is already filled three times over — associative arrays, Illuminate\Support\Collection, Eloquent models, readonly DTOs, or spatie/laravel-data. Architecturally it fits only if we are already inside the PSX lineage (consuming psx/api, psx/schema, or SDKs generated by sdkgen, where Record is the wire-level data type). Outside that context it is a parallel abstraction competing with the framework's own primitives.

Integration feasibility. High. composer require psx/record is the whole install: PSR-4 autoload, no service provider, no config, no published assets, negligible dependency surface. It can be confined to a single namespace without forcing architectural change anywhere else. Integration cost is measured in minutes; the question is whether the minutes buy anything.

Technical risk. Low absolute risk, poor risk-to-value ratio. The library is small and stable, which caps the blast radius. But 2 stars and 0 dependents means no ecosystem: no tutorials, no StackOverflow corpus, no third-party integrations, no signals of production use. Single maintainer (apioo), bus factor 1, release cadence driven by PSX framework needs rather than by a broad user base. The main semantic hazard is implicit type coercion on get/set that will surprise developers trained on Laravel's stricter casting and data_get behavior. Apache-2.0 with patent grant is unambiguously fine for commercial use.

Key questions.

• What does Record give us that a readonly DTO or a plain array does not? If we cannot answer this in one sentence, we should not take the dependency.
• What PHP versions are exercised in upstream CI (8.2 / 8.3 / 8.4)? Support ceiling is whatever the last release targeted.
• Is Record an artifact of a PSX-generated SDK we must consume, or an optional choice? Only the former justifies adoption.
• Who owns the fork if upstream goes quiet? At a few hundred lines the answer is "we do, cheaply" — but it should be an explicit decision, not a surprise.
• Does it overlap with a pattern we already standardized on internally?

Integration Approach

Stack fit. Poor-to-neutral for a standard Laravel app; genuinely strong only at the PSX boundary. If our application code already speaks Eloquent models, DTOs, and Collections, introducing Record adds a fourth dialect for the same concept. If we are consuming PSX-generated clients or building against psx/api, Record is unavoidable and the correct move is containment rather than avoidance.

Migration path. Do not introduce it greenfield. If a generated SDK hands back Record objects, wrap them at the boundary: one adapter class that maps Record into Eloquent models, arrays, or our own DTOs, so the rest of the codebase never imports PSX\Record. That single seam is the exit ramp — swapping or forking later touches one file. Do not let Record leak into domain services, controllers, or jobs.

Compatibility. No Laravel provider required, but two practical gotchas: (1) Record is not a Collection and must not be passed into Arr::, data_get, or collection pipelines expecting arrays — convert at the edge; (2) serialization behavior matters. Confirm what json_encode, queue payloads, and log formatters do with a Record so we do not accidentally ship internal fields to a client or a log sink. Also verify it does not conflict with any ArrayAccess conventions we rely on.

Sequencing.

1. Half-day spike: install, implement the adapter, prove round-trip against the real consumer (SDK or PSX payload).
2. Verify the PHP version matrix against our CI target and pin an exact version in composer.json.
3. Define our own interface in front of it; Record becomes an implementation detail.
4. Only then allow a single production call site; expand from there. If the spike cannot articulate a concrete capability gap, stop at step 1.

Operational Impact

Maintenance. Runtime maintenance is effectively zero — small, stable, no moving parts. Organizational maintenance is the real line item: we are taking on stewardship of a dependency with one maintainer and no downstream user base. The honest framing is "we own this now"; the mitigating fact is that the code is small enough to fork or reimplement in roughly a hundred lines if upstream stops.

Support. No commercial support, no SLA, no vendor escalation. The escalation path is reading the source, which is feasible at this size and is the main reason this is a tolerable risk rather than a disqualifying one.

Scaling. Irrelevant at runtime. No I/O, no caching layer, no network calls — just in-memory structures. Per-object memory overhead is modest but strictly greater than a plain array, so in hot loops or when materializing hundreds of thousands of records, prefer arrays and convert once.

Failure modes.

• Abandonment lock: a future PHP minor breaks the package and blocks our upgrade train. Mitigation: pinned version plus a standing fork-or-replace decision.
• Semantic drift: a developer assumes array semantics and gets coercion instead. Mitigation: the adapter seam and a short internal note.
• Serialization leakage: Record objects crossing into logs, queues, or API responses and exposing fields we did not intend to publish.
• Framework lockstep: if we consume a PSX-generated SDK, our upgrade cadence becomes coupled to PSX's.

Ramp-up. Hours, not days — the API surface is tiny and self-documenting. The true ramp-up cost is social: explaining to the team why a 2-star, zero-dependent package sits in composer.json. If that explanation is not crisp, that is itself the decision signal. Recommendation: adopt only as a contained transit type behind an adapter, or reproduce the handful of behaviors we actually need as first-party DTOs and take no dependency at all.