Reference Caps Laravel Package

Technical Evaluation

Architecture fit

• This is a domain reference-data package, not infrastructure. It supplies headwear size definitions ("Библиотека размеров головных уборов"). Its architectural role is a read-only lookup table sitting beside the product catalog — it does not own inventory, pricing, or checkout logic.
• Fit is therefore narrow and shallow: it is only justified if headwear sizing is a genuine catalog dimension. For a general-purpose Laravel application the package has no architectural surface to attach to and should be rejected outright.
• Framework claim is unverified. The README shows only composer require baks-dev/reference-caps and a one-line Russian description. No service provider, facade, config, or namespace is documented. The "Laravel package" framing comes from the request, not from the artifact. The BaksDev family is commonly Doctrine/entity-oriented, which would be a materially different integration story. This must be confirmed before the fit assessment is treated as valid.
• Version and provenance anomaly: the badge and release note say 7.4.3, while the metadata reports a last release of 2026-08-14 — a future date. Combined with 0 stars, 0 dependents, and no issue history, this is a red flag on release provenance, not just maturity.

Integration feasibility

• Technically trivial in the best case: one Composer require, no schema migration, no external service, no credentials. Worst case it pulls in Doctrine ORM or other baks-dev/* packages and drags a competing persistence layer into an Eloquent application — that is the actual integration risk, and it is a dependency-graph question, not a code question.
• PHP 8.4+ floor is the hard gate. Any application on 8.2/8.3 must upgrade the runtime before this single lookup table can be installed. That cost will dwarf the package's value for most teams.

Technical risk

• Documentation risk is the dominant risk. There is no usage example, no API listing, no data-shape description, no English documentation. Every method signature in prior internal notes (CapSize::find(), findByCircumference(), tolerance config, HasCapSize trait) is unverified inference and must not be treated as an API contract. Building against assumed methods is the most likely failure mode here.
• Abandonment risk is high and effectively unmitigated. 0 dependents means no downstream pressure to fix defects; 0 stars means no community triage. A single-maintainer, single-purpose, Russian-language package with no visible tests is not a supportable dependency.
• Correctness risk: sizing data is business-critical when displayed to customers. Unvalidated reference data (wrong cm-to-label mapping) produces returns and support tickets rather than exceptions — silent failure, which is worse.

Key questions

1. What is the actual public API, and what is the data shape (enum, DTO, array, Doctrine entity)?
2. What does composer why / the dependency tree pull in? Any Doctrine, Symfony, or other baks-dev/* packages?
3. Does it ship migrations or require persistence, or is it static in-memory data?
4. Is the size data authoritative for any market we sell into, and who validates it?
5. Why is the release dated in the future, and is the package actually published on Packagist today?
6. Is the dataset extendable, or must we fork to add sizes?

Integration Approach

Stack fit

• Good fit only where: Laravel (or plain PHP 8.4+), a headwear-heavy catalog, and a need for standardized size labels or filters. Poor fit everywhere else.
• This is a catalog-attribute concern, so it belongs behind our own interface — e.g. a CapSizeResolver contract with the package as one adapter — not called directly from controllers, Blade templates, or API resources. That single decision caps our exposure if the package is abandoned or turns out to be Doctrine-bound.

Migration path

1. Verify before adopting. Run composer require --dry-run in a scratch container to inspect the resolved dependency graph and confirm no framework conflict. Read src/ and any composer.json require block directly — do not rely on the README.
2. If it is a clean, dependency-free data package: wrap it. Implement our own resolver interface, adapt the package behind it, and seed the values into a cap_sizes table if we need joins, filtering, or admin editing. Do not let catalog queries depend on the package at request time.
3. If it drags in Doctrine or is otherwise unsuitable: extract the size table itself (data is not copyrightable in most jurisdictions; MIT covers the code), reimplement it as a seeder or config file in ~half a day, and drop the dependency. Given the package's size, this is the likely best path.

Compatibility

• Confirm PHP 8.4 availability in every environment: CI image, staging, production, and any queue/worker containers. A partial rollout creates a split where one service cannot boot.
• Confirm the Laravel version matrix — no claim is made in the README.
• Pin the version explicitly and commit composer.lock. Never float on ^7 for a package with zero dependents; an unexpected patch could break a catalog page with no upstream testing to catch it.

Sequencing

1. Spike (1–2 days): install in a throwaway branch, inventory the API and dependency tree, dump the dataset, and have a merchandising stakeholder review the size mappings against our actual SKUs.
2. Decision gate: adopt-as-dependency, adopt-as-data (fork/seed), or reject. Reject is a legitimate and probably likely outcome — a package with 0 stars, no docs, and no dependents should have to earn its place.
3. Pilot: one catalog surface (size filter on a cap category) behind our adapter interface.
4. Rollout: only after the pilot proves the data is correct and the adapter is the sole call site.
5. Documentation: internal one-pager covering the API as we actually use it, not as the README implies.

Operational Impact

Maintenance

• Low ongoing effort if the package is inert data. But "low effort" is not "no ownership": with no upstream activity, we are the de facto maintainers. Budget for a fork on day one — vendoring the dataset internally removes the abandonment question entirely and costs little.
• Treat every version bump as a manual review. There are no tests upstream to catch regressions, so our own adapter tests are the only safety net.

Support

• Effectively no support channel. No issues, no discussions, no dependents, Russian-only docs. Escalation path is "read the source."
• Requires a named internal owner (a backend engineer with catalog context) accountable for the data's correctness and for the fork decision. Without that owner, this becomes an orphan dependency.

Scaling

• Negligible runtime cost if the data is static or cached — a size lookup is not a scaling concern. The real scaling concern is blast radius: because it sits in the catalog read path, any failure surfaces on high-traffic product pages and affects conversion, not just a background job.
• If persisted, index the size column and cache the resolved table per request lifecycle or in the framework cache.

Failure modes

Ramp-up

• Engineering: low once the API is known — a lookup table takes an hour to wrap.
• Domain: the real ramp-up is merchandising review of the size data against our SKUs and target markets (EU/US/UK headwear conventions, cm vs. inches). That review is the critical path, not the code.
• Overall recommendation: treat as a candidate data source, not a dependency. Spend the spike validating whether the data is worth extracting; expect the answer to be "extract the table, skip the package," which eliminates 100% of the operational risk above at roughly the same cost.