Common Laravel Package

Technical Evaluation

Architecture fit

• What this actually is: a convention layer, not a capability. Traits, base classes, string/array/env helpers, service providers and config scaffolding. Its value is consistency across a package portfolio — something a TPM buys with a policy, not a dependency.
• There is a signal conflict to resolve before scoping anything. The repository slug (krystal-sf) and prior review material describe it as "Common files for Krystal Symfony Projects," while the supplied description claims support for "Laravel and standalone projects." Only the require block in composer.json settles this, and it materially changes the estimate: illuminate/* means a plausible Laravel fit; symfony/* means the framework-facing parts are inert in our apps and the reuse surface collapses to "maybe some helpers." Plan the default case as Symfony.
• Where this genuinely fits a product roadmap: as prior art for internal platform work. If a quarter's roadmap includes a shared-foundation library across N PHP services, reviewing how another team factored that out is a cheap input to the build-vs-borrow decision. It does not fit any customer-facing capability, latency, or differentiation objective.
• Net: this is a reading task, not an integration task. The TPM deliverable is a decision record, not a merged dependency.

Integration feasibility

• Feasibility is gated on discovery, not engineering effort. Four facts decide it, each roughly a one-hour lookup: presence of a LICENSE, tagged releases and cadence, composer.json PHP/framework constraints, and whether it resolves from Packagist or requires a vcs/path entry pointing at Krystal's GitLab.
• The private-VCS path is a policy decision, not a technical one: it pulls a third party's credentials and availability into our build pipeline in exchange for a package with zero dependents. Most dependency allow-lists reject that outright.
• Feasible posture to plan against: vendored source for a handful of pure-PHP helpers. Infeasible posture: a Composer dependency, absent a named internal owner who accepts maintenance.

Technical risk

• Provenance/abandonment: zero stars, zero dependents, no visible release signal. We would be the first external consumer to hit any defect, with no community triage to lean on.
• Stack mismatch: Symfony bundle/DI conventions do not execute in Laravel. Base classes, compiler passes, and YAML service definitions may be dead weight, shrinking reuse to an unverified subset.
• Hidden internal assumptions — env var names, filesystem layout, log formats — that surface only at runtime and are invisible in a code skim.
• Supply-chain exposure: third-party VCS in the build path for marginal benefit; retag, force-push, or deletion is unconstrained.
• License exposure: no license visible in the metadata; unlicensed code is all-rights-reserved by default and blocks commercial use.
• Opportunity cost: the utility value is likely re-implementable in hours, which sets the bar any adoption case must clear.

Key questions — send as one message; these are the gate, not a wish list

• Does composer.json require illuminate/* or symfony/*?
• Is there a LICENSE, and does it permit commercial use and modification?
• Are there tagged releases, and what is the cadence over the last 12 months?
• Packagist, or VCS/path repository only — and if not published, why not?
• Composition and rough size: src vs. config vs. CI assets?
• Does it depend on other Krystal-internal packages, creating a transitive private chain?
• Who at Krystal owns it, and is there any stated commitment to external consumers?
• Do we ourselves run any Symfony services where this would be a native fit rather than an adapter?

Integration Approach

Stack fit

• Default posture: reference implementation. Read the repository, extract useful patterns or isolated functions, re-implement locally with our own tests and license headers.
• If adoption is later justified, constrain it to a leaf package: pure PHP classes with no container awareness, no bundles, no service providers, no bootstrapping. Anything framework-coupled is excluded by policy rather than debated per-file.
• If we operate Symfony services internally, the calculus shifts slightly — but zero stars and zero dependents still argue for fork-and-own over depending upstream.

Migration path

1. Discovery spike (0.5–1 engineer-day): clone, inventory composer.json, license, tags, and source tree; classify contents into reusable pure PHP / framework-coupled / non-code assets.
2. Compatibility probe (0.5 day): throwaway branch, add the VCS repository, run composer update --dry-run against our pinned PHP and Laravel versions. A constraint conflict here closes the item for the cost of half a day.
3. Decision record (2 hours): write a one-page ADR — adopt / vendor / fork / reject — with license and constraint findings attached. This is the durable TPM artifact; the code evaluation is disposable.
4. Extraction, if warranted (1–2 days): vendor the specific helpers into an internal namespace with attribution headers, unit tests, and a named owner in CODEOWNERS.
5. Fork, fallback only (2–4 days plus ongoing): fork to our GitLab, relax constraints, accept the maintenance burden explicitly.

Compatibility

• The binding constraint is Symfony component versions versus Laravel's illuminate/* requirements. A hard Composer conflict on a current Laravel release is likely and cannot be resolved without a fork.
• Check the PHP floor — ^7.4/^8.0 pins suggest code predating modern typing and readonly — and any ext-* requirements absent from our runtime images.
• Treat "Laravel and standalone" in the description as a claim, not evidence, until the require block is read.

Sequencing

• Keep it off the critical path and out of sprint commitments. It is a background spike, parallelizable with backlog work, with an explicit stop gate: valid license and clean dry-run resolve and a named internal owner. Fail any one, close the ticket.
• If it feeds a shared-foundation roadmap item, sequence the pattern review before we design our own package — it is cheap and lands early — while deferring the code-level evaluation to whenever that roadmap item is actually prioritized.

Operational Impact

Maintenance

• Assume zero upstream maintenance guarantee. Pin to a commit SHA, mirror internally, and register the SHA in the dependency inventory — or sever the link entirely by vendoring.
• Budget if dependent: roughly 2–4 hours per quarter for drift review, plus unbounded unplanned work the first time an untagged upstream change alters behavior. Budget if vendored: near-zero.

Support

• No issue-tracker engagement, no SLA, no community to escalate into. The only realistic support model is internal ownership, which is a headcount and on-call decision — disproportionate for a helper library, and a conversation worth having explicitly rather than discovering later.

Scaling

• Not a hot-path concern; utilities rarely scale badly. The scaling risk is organizational: every additional consumer of an unmaintained internal package enlarges the eventual migration surface. Cap adoption at one or two services if it proceeds at all.
• The genuinely scalable play is the inverse: one thin internal package we control, with semver, a changelog, and an owner. Same consistency benefit, none of the provenance risk.

Failure modes — each becomes a risk-register line with an owner

• Composer resolve failure on our next Laravel or PHP upgrade, blocking unrelated dependency updates until the package is ripped out. Highest likelihood, highest day-to-day annoyance.
• Upstream deletion, force-push, or retag breaking fresh CI builds that resolve from the VCS source — mitigated by SHA pinning and an internal mirror.
• Private-repo credential expiry producing intermittent CI failures that are slow to diagnose precisely because the package is invisible on the critical path.
• Silent behavior change on an untagged branch constraint.
• Late license discovery forcing an emergency removal after integration.

Ramp-up

• Low code ramp-up, high investigative ramp-up: roughly 1–2 engineer-days to establish provenance, license, and intent before a single line of integration work, plus a day to onboard an owner for a fork.
• Compare against the recommended alternative: 0.5–2 engineer-days to write and test the handful of helpers ourselves, with ownership, licensing, and BC policy settled by default. Framed as a like-for-like effort comparison, the case for depending on this package is negative.
• Stakeholder line: "Half a day of reading, a one-page decision record, done. No new dependency, no new vendor relationship, no new supply-chain surface — and a reusable design input for our own shared library."