Companies House Bundle Laravel Package

Technical Evaluation

Architecture fit. The package is a Symfony bundle, not a Laravel package, and that distinction drives most of the assessment. Symfony bundles rely on bundle registration in config/bundles.php, a DependencyInjection/*Extension class, service definitions in YAML/XML, and a Configuration tree for semantic config. Laravel has no bundle loader, no compiler passes, and a materially different container and config model. The bundle's value — pre-wired services, autoconfiguration, tagged services — is therefore not portable as-is. What is actually reusable is the thin domain logic that maps Companies House REST endpoints (company profile, registered office, officers, persons with significant control, filing history, search, document metadata) to PHP value objects.

Integration feasibility. Composer will install it into a Laravel project, but nothing will register the services automatically. Even after manual wiring, the bundle will likely pull in Symfony components (http-client, serializer, event-dispatcher, config) that duplicate or conflict with Laravel's equivalents. Feasibility is rated low for direct adoption and moderate for a targeted salvage: read the source, extract the endpoint paths, request shapes, and response mapping, then reimplement against Laravel's HTTP client. That is a days-scale effort for one engineer, not a weeks-scale one, but it produces a fork you own rather than a dependency you inherit.

Technical risk.

• Maturity signals are uniformly negative. Two stars, zero dependents, and a composite score of 0.16 indicate no production adoption, no downstream validation, and no ecosystem pressure to keep it current.
• Abandonment risk is high. With no dependents there is no incentive for the author to maintain compatibility with new PHP or Symfony releases. Expect pinned, aging version constraints.
• Security posture is unknown. No visible security policy, no evidence of a CVE response process, and an unmaintained transitive dependency graph. Given the API requires an HTTP Basic API key, credential handling in the bundle warrants direct code review before any use.
• Correctness risk in a regulated context. Companies House data typically feeds KYC/AML, onboarding, or beneficial-ownership checks. Silent schema drift or a swallowed 404 that returns an empty company object is a compliance defect, not just a bug. The bundle gives no indication it distinguishes "not found" from "unauthorized" from "rate limited."
• Testability is unverified. No badge or visible test suite means the response-mapping assumptions must be validated from scratch against the live API.

Key questions.

1. Which Companies House endpoints does the bundle actually cover, and which does the product need (search, profile, officers, PSC, filing history, document download)?
2. What are the composer constraints on PHP and Symfony, and do they intersect with the Laravel version in use?
3. How does it handle authentication, API key injection, and key rotation?
4. Does it implement the 600-requests-per-5-minute rate limit, backoff, and 429 handling, or does it leave that to the caller?
5. Is response data mapped to typed objects or returned as raw arrays?
6. What is the license, and is forking and vendoring acceptable to legal?
7. Is the API key a shared secret across environments, and how is it stored?

Integration Approach

Stack fit. Poor as a direct dependency. The recommendation is to treat the repository as a reference implementation and specification source, not as a runtime dependency. The valuable artifact is the encoded knowledge of Companies House endpoint URLs, request parameters, and response field names — that knowledge is cheap to port and expensive to rediscover.

Migration path. Three viable routes, in ascending order of effort:

1. Extract and reimplement. Read the bundle's service classes, lift the endpoint constants and mapping logic, and rebuild as a small Laravel-native client using Illuminate\Support\Facades\Http behind a CompaniesHouseClient interface. Lowest total cost, cleanest result.
2. Vendor and wrap. Fork the repository, add a Laravel service provider that registers the bundle's classes manually, and delete Symfony-specific coupling. Faster to first green test, but leaves you owning a fork with a foreign architecture.
3. Regenerate. The Companies House REST API publishes an OpenAPI specification. Generating a typed client from it yields better coverage than the bundle and removes the fork entirely. Slightly more upfront setup, best long-term position.

Route 1 is the default recommendation; route 3 is the better answer if the integration is on a critical path or covers more than a handful of endpoints.

Compatibility. Before any decision, confirm the PHP constraint. A bundle written for Symfony 3 or 4 will typically declare PHP 7.x, which will not install alongside a modern Laravel runtime. Also check whether it depends on symfony/http-client (which Laravel does not use), symfony/serializer (overlapping with Laravel's casting), and any PSR-18/PSR-17 implementations that may collide. Conflicts here are a hard blocker, not a nuisance.

Sequencing.

1. Spike (1–2 days). Clone, install in a throwaway Symfony or bare PHP harness, and exercise the endpoints the product needs against a Companies House test account. Record actual request/response pairs.
2. Contract first. Define the interface the application depends on — company lookup, officer list, PSC list, search — with typed DTOs and explicit error semantics (NotFound, Unauthorized, RateLimited, UpstreamError). The bundle is now an implementation detail.
3. Implement. Build the Laravel client against the interface using the recorded fixtures. Port the mapping logic from the bundle where it is correct; do not port its error handling uncritically.
4. Contract tests. Run the suite against recorded fixtures in CI and against the live sandbox on a schedule. This is what protects you from schema drift after the bundle is gone.
5. Cut over behind a feature flag. Keep the legacy path available until the new client has handled production traffic for a full release cycle.
6. Record the decision. A short ADR explaining why the bundle was not adopted prevents the question resurfacing.

Operational Impact

Maintenance. The bundle transfers no maintenance obligation off your team — it adds one. Any bug, PHP upgrade, or API change requires patching a dependency with no upstream activity and no other consumers to share the cost. A small in-house client is fewer lines of code than the workaround layer a Symfony bundle in Laravel would require, and it belongs to the team that already owns the feature. Budget ongoing effort for API drift review: Companies House does evolve its schema, and an unmaintained library will not absorb those changes.

Support. There is no vendor, no support contract, and effectively no community. With two stars and zero dependents, the realistic support channel is reading the source. Factor that into on-call: anyone paged for a Companies House outage or a failed onboarding must be able to diagnose the integration without documentation. That argues strongly for owning the code.

Scaling. The binding constraint is the Companies House rate limit (roughly 600 requests per five minutes per API key) rather than CPU or memory. Design implications:

• Cache aggressively. Company profiles and officer lists change rarely; cache with a TTL measured in hours and invalidate on filing events rather than on read.
• Queue non-interactive lookups. Bulk enrichment and periodic re-screening belong on a queue with a token-bucket limiter, not in the request path.
• Isolate the key. One API key per environment, and a plan for what happens when two features contend for the same budget.
• Consider a local mirror if screening volume grows; a nightly delta sync converts a rate-limited API into an internal read.

Failure modes. Enumerate and handle each explicitly, because the bundle likely collapses them:

• 401/403 — invalid or rotated API key. Should alert, not silently degrade.
• 404 — company number not found. A legitimate business outcome and must not be treated as an error; also must not be confused with an outage.
• 429 — rate limited. Requires backoff with jitter and should surface as a transient failure, never as "no data."
• 5xx / timeouts — upstream instability. Retry with bounded attempts; fail the operation rather than returning partial compliance data.
• Schema drift — a renamed or removed field deserializing to null. This is the most dangerous mode in a compliance context: the system reports success while omitting data. Contract tests against live responses are the mitigation.
• Credential exposure — the API key in logs or error payloads. Verify redaction explicitly.

Ramp-up. Low technical complexity, moderate context cost. The Companies House domain model — company numbers, officer roles, PSC natures of control, filing types — carries more learning burden than the HTTP integration itself. The bundle's source is a reasonable onboarding artifact for that vocabulary even if it is never installed. Plan for half a day of domain reading plus the spike; a competent Laravel engineer can deliver the replacement client within a sprint. The larger cost is social: someone must be nominated as owner of the integration and the decision record, or the fork will quietly rot in the same way the original did.