Statamic Toasty Laravel Package

Technical Evaluation

Architecture fit

• No artifact data was supplied with this release beyond a one-line changelog ("Initial release"), so architecture fit is currently unverified. The only confirmed facts are: it is a Laravel/PHP package, and it is versioned 0.0.1.
• Version 0.0.1 is a pre-1.0 marker. Under SemVer conventions this signals no API stability guarantee — service provider registration, config keys, facade names, and public classes may all change without a major-version bump.
• Working assumption for planning purposes: the package is a Composer-installable Laravel library that auto-discovers a service provider and optionally publishes config/migrations. This assumption must be confirmed before any design work commits to it.
• Fit against our application should be judged on whether it integrates as a library (additive, low blast radius) or as a scaffold/opinionated subsystem (intrusive, requires adopting its conventions). The distinction drives everything downstream.

Integration feasibility

• Low-friction path exists in principle: Composer require, package auto-discovery, publish config, done. That is the optimistic case and should not be assumed.
• Real feasibility questions that gate the estimate:
  • Does it require our Laravel and PHP versions to be within a supported matrix, or does it pin loosely and fail at runtime?
  • Does it require a specific database engine, queue driver, cache driver, or filesystem?
  • Does it make outbound network calls, register its own routes/middleware, or ship a service provider that alters global bootstrapping?
  • Does it introduce a second source of truth (its own tables, its own auth path) that we would then have to reconcile with existing domain models?
• Without a code read, treat the integration estimate as unbounded — do not commit a sprint allocation until the provider and Composer constraints have been inspected.

Technical risk

• High, concentrated in unknowns. The risk here is not that the package is bad; it is that a 0.0.1 release has had essentially no external exposure, so we are the testers.
• Specific risks:
  1. API churn — pre-1.0 packages routinely break on patch/minor releases. Any wrapper code we write is at risk each upgrade.
  2. Maintenance abandonment — single initial commit is a common profile for packages that go dormant. Bus-factor of one is the default assumption.
  3. Security surface — an unvetted package runs in-process with full application privileges. No audit exists.
  4. Transitive dependency drag — an unbudgeted constraint conflict with our existing Composer graph is a realistic blocker.
  5. Documentation debt — a one-line changelog usually correlates with thin docs, which shifts discovery cost onto our engineers.
• Mitigation posture: acceptable for a spike or a non-critical internal tool; not acceptable for a customer-facing or payment/auth-adjacent path at 0.0.1 without a code review and a fork-or-vendor contingency.

Key questions

• What problem does this solve that our existing stack does not, and is that problem on our roadmap this quarter?
• Who maintains it, and is there a commit history, issue tracker, and release cadence outside this single release?
• What is the supported Laravel/PHP version matrix, and where are we in it?
• Is it a library or a scaffold — and does it own data, routes, or middleware?
• What are its transitive dependencies, and do they conflict with our lockfile?
• What is the license, and does it permit our intended use (including any commercial/SaaS redistribution)?
• Is there a test suite, and what is its coverage on the paths we would rely on?
• What is the exit cost — can we remove it cleanly, or does it leave migrations and data behind?

Integration Approach

Stack fit

• Target stack is our standard Laravel application (Composer, service provider auto-discovery, Eloquent, config publishing). The package is nominally aligned with that standard, but alignment is asserted, not demonstrated.
• Decide up front whether this is:
  • Adopt — used directly in production paths.
  • Wrap — used behind our own interface so the package is replaceable.
  • Spike — evaluated in a branch and discarded if it disappoints.
• Given 0.0.1, default to Wrap or Spike. Direct adoption should require an explicit, documented exception.

Migration path

• No migration is required to evaluate — this is greenfield, so the "migration" is really an adoption path:
  1. Install in an isolated branch or a throwaway Laravel skeleton, not in the main application.
  2. Exercise the happy path end to end against realistic data.
  3. Only then attempt installation into the main application with the lockfile committed separately for easy revert.
• If the package ships migrations, run them in a scratch database first and inspect the schema it creates. Understand its table ownership before it touches anything we care about.
• If any existing code path is replaced, keep the old path behind a feature flag until the new one has run in production for at least one full cycle.

Compatibility

• Compatibility is the single largest unresolved item. Concretely: Laravel version, PHP version, and whether it assumes conventions from a specific Laravel era (e.g. older container resolution or facade patterns).
• Transitive dependency conflict is the most likely reason the integration fails outright. Run composer require --dry-run early — a conflict discovered on day one costs an hour, a conflict discovered on day eight costs a sprint.
• Check whether it publishes config that we would need to keep in sync across environments; unpublishable or non-overridable config is a recurring integration tax.

Sequencing

• Recommended order, each step a go/no-go gate:
  1. Read the source — provider, composer.json, tests. Cheap, and it answers most of the key questions above.
  2. Dry-run install — resolve dependency conflicts without committing.
  3. Isolated spike — happy path plus one failure path in a throwaway app.
  4. Wrap — if it passes, place it behind our own interface so the dependency is swappable.
  5. Production pilot — non-critical surface, feature-flagged, instrumented.
  6. Broader rollout — only after the pilot has survived a real release cycle.
• Do not parallelize steps 1–3 with production integration work. The whole point of the sequence is to fail cheaply.

Operational Impact

Maintenance

• Pre-1.0 dependencies are a standing maintenance tax: upgrades are frequent, breaking, and loosely documented. Budget recurring time for upgrade review rather than treating this as a one-time install.
• If we wrap the package, maintenance becomes tractable — upgrades happen behind our interface. If we adopt directly, upgrade cost is proportional to how deeply its types appear in our code.
• Pin the exact version in composer.json (not a caret range) until the package reaches 1.0 or demonstrates a stable release cadence.

Support

• Support model is the weak point. A 0.0.1 with a one-line changelog implies no vendor, no SLA, and no community to escalate to. Our own engineers are the support tier.
• Practical consequence: any production dependency on this package should have a named internal owner who understands the code, plus a documented fallback if the package goes dormant or is abandoned.
• If the package is business-critical, the support conversation must include a fork contingency — verify the license permits it and that we can realistically maintain a fork.

Scaling

• Scaling behavior is unknown and should be characterized before relying on it under load: query patterns, N+1 risk, cache usage, synchronous outbound calls in request paths, and any unbounded in-memory work.
• The package's own scaling profile matters less than whether it imposes scaling constraints on us — e.g. forcing a table scan, requiring a specific queue driver, or holding state that breaks horizontal scaling.
• Treat any synchronous I/O in a request path as a scaling red flag until measured.

Failure modes

• Expected failure modes, in rough order of likelihood:
  1. Silent breakage on upgrade — pre-1.0 change alters behavior without an error. Mitigate with a pin and a smoke test in CI.
  2. Dependency conflict — blocks an unrelated upgrade elsewhere in the app. Mitigate by isolating adoption.
  3. Abandonment — no fixes for a future Laravel/PHP compatibility break. Mitigate with fork readiness.
  4. Runtime failure under edge-case data — untested paths in a young package surface in production. Mitigate with a pilot and instrumentation.
  5. Difficult removal — installed migrations and persisted data make extraction expensive. Mitigate by inspecting schema ownership before installation.
• Each of these is survivable if we wrap and feature-flag; several are not if we adopt directly into a critical path.

Ramp-up

• Engineering ramp-up is the hidden cost. Thin documentation means discovery time lands on the team rather than on the package author.
• Estimate ramp-up as: source read (hours) + spike (days) + wrapper design (days) for a first integration. Scale upward if the package is opinionated.
• The ramp-up cost is also our bus factor: if only one engineer understands the package, that is a single point of failure, and the pilot should be staffed with at least two people.
• Recommend a short internal write-up after the spike — what it does, how to use it, what to watch for — so the knowledge survives the spike. Without that artifact, the ramp-up cost gets paid twice.

TPM recommendation: Proceed to a bounded spike, not to adoption. The information available — an initial 0.0.1 release with a one-line changelog and no supporting artifact data — is insufficient to justify production commitment, and the unknowns are cheap to resolve in step 1 of the sequencing above. Revisit this assessment with source-level findings and a completed dependency dry-run before any roadmap commitment.