Core Interfaces Laravel Package

Technical Evaluation

Architecture fit

trinity/core-interfaces is a contracts-only package: PHP interfaces that define the boundaries of the "Trinity Framework." That shape is architecturally attractive in principle — an interfaces package should be a near-zero-runtime-cost dependency that lets application code depend on abstractions rather than concrete implementations. If the interfaces describe service boundaries (repositories, dispatchers, registries) cleanly, they can be adopted independently of the rest of Trinity.

The problem is context. An interfaces package is only meaningful alongside a set of implementations that honor those contracts. With zero dependents on Packagist and no visible ecosystem, there is no evidence that any implementation exists, is maintained, or will ever honor these contracts. A contract with no counterparty is documentation, not architecture. The fit is therefore structural (interfaces compose well with Laravel's container and service-provider model) but unvalidated (no reference consumer).

Integration feasibility

Mechanically trivial: Composer install, PSR-4 autoload, no runtime services, no config, no migrations. There is essentially nothing to wire up. The real cost is not installation but the pre-install diligence — confirming the package's PHP and Composer constraints resolve against our stack, and confirming the interface signatures are actually usable without pulling in the rest of Trinity.

Expect friction here. A package last released in July 2017 carries constraints from the PHP 7.0/7.1 era. If it declares php: ^7.0, modern Composer will refuse to install it on PHP 8.x without --ignore-platform-reqs, which is an unacceptable production posture. Forking and relaxing the constraint is possible under MIT, but that converts a dependency into an owned artifact on day one.

Technical risk

The dominant risk is abandonment, not code quality. Signals are unambiguous: zero stars, zero dependents, no release in roughly eight years. There is no security disclosure channel, no CI badge implying test coverage, and no downstream consumer whose usage patterns would surface defects. Abandoned interfaces are low-severity from a vulnerability standpoint (no I/O, no deserialization, no network surface) but high-severity from a semantic standpoint: if we build against contracts that are subtly wrong, we inherit the wrong abstraction permanently, and interface changes are the most expensive kind of change to retrofit.

Secondary risks: unknown PHP 8 compatibility (reserved-word collisions, missing return types, #[ReturnTypeWillChange] era issues if any interfaces extend SPL); unverified autoload configuration; and license hygiene, though MIT is permissive and low-risk.

Key questions

• Does any implementation of these interfaces exist, publicly or privately, and is it maintained?
• Do the interfaces leak Trinity-specific assumptions (container keys, global helpers, static facades) that would couple us to a framework we are not adopting?
• What are the declared php and illuminate/* constraints, and do they resolve against our target PHP and Laravel versions?
• Is the interface surface coherent and minimal, or is it a grab-bag of unrelated contracts?
• Is there any documentation, even a README, that explains intended usage and lifecycle?

Recommendation: do not adopt as a runtime dependency. Timebox a one-to-two-day spike to read the source and decide whether the interface design is worth re-expressing as in-house contracts. That is the only realistic value path.

Integration Approach

Stack fit

Laravel's service container is interface-friendly: $this->app->bind(MyContract::class, MyImplementation::class) in a service provider is exactly the pattern an interfaces package is meant to serve. If the Trinity contracts are clean, they slot into that pattern without adaptation. If they assume a Trinity-specific container, event bus, or module loader, the fit degrades to "vendored reference material."

Migration path

Three options, in ascending order of ownership cost:

1. Depend directly — rejected. Unmaintained transitive dependency for contracts we can write ourselves in an afternoon.
2. Vendor the interfaces — copy the interface files into our own namespace (App\Contracts or a first-party acme/contracts package), retain the MIT notice, and own them. This preserves the design intent while eliminating the dependency and the abandoned-repo risk entirely. This is the recommended path if the spike finds the contracts genuinely well-factored.
3. Fork and publish — only justified if multiple internal teams need the same contracts. Premature at zero known consumers.

If any existing code already type-hints these interfaces, migration is a mechanical namespace rewrite plus a class-alias shim during transition. If no code depends on them, there is nothing to migrate — which is the likely case.

Compatibility

Verify before anything else: declared PHP constraint, illuminate/support or illuminate/contracts constraints (if any), and whether the code parses under our PHP version. Run composer why-not against our target platform. Absent a passing composer require, treat this as source material rather than a package.

Sequencing

Spike and read the source → classify contracts as keep / rewrite / discard → if keep, vendor into a first-party contracts package with our own tests and CI → bind implementations in a service provider → only then build consumers. Do not let application code type-hint a third-party namespace that we may later have to replace; that inverts the dependency direction we are trying to achieve.

Operational Impact

Maintenance

Effectively zero upstream maintenance. We should assume no releases, no bug fixes, no PHP-version bumps, and no security response ever. Any operational burden transfers entirely to us the moment we depend on it. This is acceptable only for immutable artifacts like pure interface definitions — anything with behavior is not a candidate.

Support

No vendor, no maintainer responsiveness, no community. Internal support means "whoever vendored it owns it." That must be an explicit named owner with a review cadence, not an implicit assumption that interfaces never change.

Scaling

Interfaces do not scale-cost: no runtime overhead, no memory footprint, no query surface, negligible autoload impact. The scaling concern is organizational — every team that type-hints these contracts inherits the abstraction whether or not it fits their bounded context. Premature shared contracts across teams create coupling that is harder to unwind than a shared library, because interface changes ripple through every implementer.

Failure modes

• Silent abandonment: nothing breaks at install, so the risk stays invisible until a PHP upgrade forces a Composer resolution failure across every service that depends on it.
• Wrong abstraction lock-in: contracts designed for a framework we are not running encode assumptions we cannot satisfy, forcing adapter layers that exist only to satisfy a dead package.
• Namespace capture: application code imports Trinity\... types, making a future extraction a cross-cutting refactor.
• Constraint deadlock: an old php or illuminate/* pin blocks an otherwise routine framework upgrade.

Ramp-up

Nearly zero for an engineer to read — the source is a handful of interface files and can be understood in under an hour. Near-zero for an engineer to use — there is no API surface to learn. The ramp-up cost is entirely in the decision: someone senior must adjudicate whether these contracts represent our domain or someone else's, and that judgment cannot be delegated to the implementing engineer. Budget one architect-hour for the verdict, plus one engineer-day for the spike, and treat anything beyond that as over-investment in a package with zero stars, zero dependents, and an eight-year-old last release.