Companies House Laravel Laravel Package

Technical Evaluation

Architecture fit. This is an anti-corruption layer, not a domain model. The package wraps the UK Companies House REST API behind a Laravel facade and a publishable config file: no migrations, no Eloquent entities, no tables. That framing is the single most important thing a TPM can hold steady with stakeholders, because it determines the decision shape — adoption is a tactical integration with near-zero architectural gravity, so the question worth spending time on is whether company verification belongs on the roadmap, not whether this is the right wrapper.

Where a TPM extracts value. The commercially meaningful capability is entity validation and enrichment at the moments trust is decided: B2B signup, supplier onboarding, marketplace seller checks, internal admin lookups. Concretely — validate a company number at signup, pre-fill registered name and address, flag dissolved or dormant status, surface officers and filing history for a due-diligence view. These map to KYB-adjacent, vendor-risk, and fraud-reduction outcomes, and they are the profile of work a TPM should sequence as a small, flag-gated experiment ahead of any system build.

Integration feasibility. Conventional Laravel install and service-provider registration; API key stays server-side via config and is environment-swappable. A spike against three endpoints is hours, not days. The honest cost sits outside the package: caching, rate-limit budgeting, retry/backoff, filing-history pagination, and a coherent error taxonomy are all ours. Net: the package is the entry point to a small feature, not the feature.

Technical risk.

• Staleness is the headline. Last release September 2021, 22 stars, zero dependents, one maintainer. PHP/Laravel constraint ceilings against current lines are unverified, and there is no ecosystem evidence of production use to lean on.
• Thin wrapper, low moat. Value is roughly one service class plus config. Forking or reimplementing is contained work — which cuts both ways: low lock-in, low justification to carry the dependency.
• Error semantics are product-visible. Companies House enforces per-window quotas and returns 429s. Collapsing "company not found" (a legitimate validation outcome) into "API unavailable" (an error) is a defect users will see.
• Legal and governance. Officer data is personal data under UK GDPR, and the register carries caching, display, and attribution terms plus accuracy disclaimers we cannot contradict in UI copy. No security policy, no DPA — procurement will not be satisfied by the library either way.
• Thin evidence base. The 2.0.4 note is one line with no linked PR or test evidence. Treat all behaviour claims as hypotheses for the spike.

Key questions for the spike.

1. Does it persist anything, or purely return DTOs/arrays? Config only, or migrations too?
2. Does it cache, and can we inject our own store and TTL?
3. How do 401/404/429/5xx surface — typed exceptions we can map, or raw HTTP client exceptions?
4. Is pagination (start_index/items_per_page) supported for search and filing history? Without it, list features are capped.
5. Is the company-number validator offline (format/checksum) or API-dependent? Offline is far more useful in a signup form.
6. What are the PHP/Laravel constraints in composer.json, and is there a supported-version policy?
7. Is there a fake/mock mode so test suites do not hit the live API?
8. What do Companies House terms require for caching, re-display, and attribution?

Integration Approach

Stack fit. Assume Laravel on PHP 8.x, but read composer.json first — a 2021 package may declare Laravel 8/9 ceilings. If we are on a newer framework line, the answer is a fork or a reimplementation, not --ignore-platform-reqs. Because the package is stateless, multi-tenancy is not a package concern; it becomes ours only in cache keys and in attributing which tenant's onboarding triggered a lookup.

Migration path. No data migration, because there is no schema — the low-risk property that makes trialling easy. The only real migration is behavioural: consolidate scattered hand-rolled Http::get('api.company-information.service.gov.uk/...') calls behind one interface. Inventory those first; the usual win is deleting duplicated plumbing and inconsistent error handling, not adding capability.

Compatibility. Two concrete checks before commitment: framework/PHP constraints against our pinned versions, and whether the suite runs without live credentials. If the package cannot be faked, price that in as a testability tax rather than absorbing it silently.

Sequencing.

1. Timeboxed spike (half a day). Scratch app, publish config, hit search, company profile, and officers. Record exact response shapes and error behaviour in the ticket. Answer the eight questions above.
2. Decide wrap versus reimplement. Clean and compatible → adopt behind our own CompanyRegistry interface so facade calls never reach controllers or Blade. Incompatible → reimplement the two or three endpoints we actually need; the MIT licence makes forking legitimate and low-drama.
3. Build caching and error mapping ourselves. Company profiles change on the order of days. Cache by company number with an hours-scale TTL, and map upstream results onto our own domain outcomes: Verified / NotFound / Dissolved / Unavailable. These are distinct product states and must not collapse into one.
4. Ship behind a feature flag, with a go/no-go gate tied to the funnel or deal it is meant to unblock.
5. Only then invest in persistence, monitoring, and rate-limit budgeting — as a separate, separately-justified decision.

Operational Impact

Maintenance. Effectively unmaintained upstream: one maintainer, no release since September 2021, no security policy, no changelog discipline. Budget for owning it. Practically that means pinning the exact version, vendoring or forking under MIT, and reading the few hundred lines of source so we are not debugging blind. Treat replacement as a contained afternoon, not a migration project — that is the escape hatch, and it should be written down before adoption rather than discovered after.

Support. There is no SLA beyond GitHub issues and no maintainer commitment. Support for the feature is therefore entirely internal: whoever owns the CompanyRegistry interface owns the behaviour, the error taxonomy, and the on-call story. Escalation to the upstream project does not exist as a real path.

Scaling. Scaling concerns are almost entirely upstream, not in the package. Companies House enforces per-window quotas and returns 429s; without caching, every page view or signup attempt spends quota. Caching keyed by company number with an hours-scale TTL is the primary lever and also the primary cost control. Watch for: uncached lookups triggered from list views, filing-history pagination that fans out into request storms, and any flow that re-checks the same entity repeatedly within a session. Rate-limit budgeting and backoff are ours to design and monitor — the package provides none.

Failure modes.

• Upstream outage or throttling → 429/5xx surfacing as raw exceptions and a broken signup step. Needs explicit handling and a graceful "cannot verify right now" state that does not block the user.
• Framework drift → a Laravel upgrade silently breaks the package. Pin, and add a compatibility check to the upgrade checklist.
• Not-found vs. unavailable conflation → users told their real company is invalid, or invalid companies accepted. This is a trust-damaging defect and the reason the error taxonomy is non-negotiable.
• Stale data presented as live → if we ever snapshot rather than look up live, the UI must say so. Companies House data changes without webhooks; freshness is a product decision we own.
• Abandonment → no releases, no fixes. Mitigated by vendoring and the fork option.
• Data-protection exposure → officer names are personal data; retention and display rules apply regardless of library. Legal review must precede customer-facing launch, not follow it.

Ramp-up. Low. Any Laravel developer can integrate this in an afternoon; the learning curve is in the Companies House API's pagination, rate limits, and terms, not in the wrapper. The genuine ramp-up cost is organisational: getting a legal read on UK GDPR and register terms, and agreeing an error taxonomy with product before code ships. Plan for the legal review to be on the critical path — it is the item most likely to delay a launch that engineering considers finished.