Uri Laravel Package

Technical Evaluation

Architecture fit. psx/uri is a narrow, dependency-light utility library that models URI, URL, and URN as immutable value objects. Architecturally that is a good shape for Laravel: value objects map cleanly onto form requests, casts, DTOs, and domain entities, and immutability removes a class of aliasing bugs when URLs are passed through middleware, jobs, and queues. The catch is that it is a leaf library with no Laravel awareness — no service provider, no facade, no config, no validation rule — so it enters the codebase as raw PHP rather than as framework furniture. It also does not define the application's boundaries; it only gives you a typed representation of a string. That makes it a candidate for a thin internal wrapper, not for direct use scattered across the codebase.

Integration feasibility. Composer-installable, PSR-4 autoloaded, Apache-2.0 (permissive, no copyleft exposure, safe for commercial distribution). Integration effort is measured in hours, not sprints: bind an interface in a service provider, add a Cast for Eloquent attributes, add a validation rule that delegates to the parser. The real feasibility question is not "can we install it" but "should this be our canonical URI type" — and against league/uri (mature, widely adopted, PSR-7/PSR-17 aware) and Laravel's own Illuminate\Support\Uri, this package has no differentiating capability that justifies being the default.

Technical risk. High, and concentrated in supply chain rather than code quality. Four stars and zero dependents mean essentially no ecosystem validation: no third-party bug reports, no downstream compatibility testing, no community pressure to fix edge cases. Single-maintainer projects inside a larger framework (PSX) tend to be maintained for the framework's needs first. Specific risks: parsing/normalization divergence from WHATWG or browser behavior on malformed, percent-encoded, IDN, or scheme-relative inputs; unclear PSR-7 UriInterface interoperability; unknown PHP version ceiling; and abandonment without a fork plan. None of these are catastrophic for a bounded internal use, but each is disqualifying for a security-sensitive path such as SSRF allowlisting or OAuth redirect validation if adopted unexamined.

Key questions.

• Does it implement Psr\Http\Message\UriInterface, and can it round-trip with Guzzle/PSR-7 without lossy conversion?
• What is the normalization policy — does it lowercase hosts, strip default ports, resolve dot segments, and how does that compare to browser behavior?
• Which PHP versions are supported, and is there a CI matrix we can inspect?
• How does it handle invalid input: exceptions, null, or best-effort parse? Is failure mode explicit and catchable?
• What is the maintainer's stated support window, and is there a tagged release cadence?
• Does it pull transitive dependencies that could conflict with Laravel's constraint set?

Integration Approach

Stack fit. Fits as an infrastructure-layer detail, not a domain contract. The right pattern is an application-owned interface (UriParser, CanonicalUrl) with psx/uri as one swappable implementation behind it. That keeps the framework-facing surface stable if we later move to league/uri or Illuminate\Support\Uri. It should not appear in controllers, models, or Blade templates directly.

Migration path. Since there is nothing to migrate from at package level, treat this as an adoption decision with a pre-built exit. Wrap the constructor and parse calls in an adapter, write contract tests against that adapter using a corpus of real URLs from logs, then swap implementations behind the same tests if needed. If we already use league/uri, the honest recommendation is to keep it and skip this package entirely — the marginal benefit does not cover a second URI implementation in the same runtime.

Compatibility. Verify against the Laravel and PHP versions actually pinned in composer.json before any spike results are trusted. Check for PSR-7/PSR-17 interop if requests or HTTP clients will cross the boundary; a value object that cannot be handed to Guzzle without conversion is friction on every outbound call. Confirm license headers and NOTICE obligations are satisfied (Apache-2.0 is low-friction but not obligation-free).

Sequencing.

1. One-day spike: install in a scratch branch, parse a corpus of production URLs, diff results against the current string-based handling and against league/uri.
2. Decision gate: if the diff shows normalization differences that touch routing, redirects, or allowlists, stop.
3. If it passes, land the adapter interface plus cast and validation rule in a single PR with tests.
4. Pilot in one bounded context — preferably internal URL canonicalization for logging or webhook dispatch — for one release cycle.
5. Only then consider broader use. Never first-adopt on auth, redirect, or SSRF-sensitive paths.

Operational Impact

Maintenance. The code volume we own is small (an adapter, a cast, a rule), but the dependency is effectively unmaintained by proxy: with 4 stars and 0 dependents, upstream fixes arrive on the maintainer's schedule or not at all. Budget for the possibility of forking. Track it in the dependency register with an explicit "vendor or replace" trigger, and pin the version rather than floating it.

Support. No commercial support, no meaningful issue-tracker history to lean on, no Stack Overflow corpus. Internal support means one or two engineers reading the source. That is acceptable for a utility of this size and unacceptable if the team expects vendor-style answers during an incident.

Scaling. Performance is a non-issue — pure string parsing and allocation, negligible next to I/O. It scales horizontally for free and adds no runtime service, no network hop, no cache. Memory profile is trivial for request-scoped value objects; watch only for accidental retention of parsed objects in long-lived workers.

Failure modes. The realistic failures are (a) uncaught parse exceptions on malformed user input reaching an unguarded code path, (b) silent normalization mismatches producing cache-key or allowlist divergence, (c) a Composer constraint conflict forcing an upgrade under time pressure, and (d) abandonment leaving a known parsing bug unfixed. Mitigations are uniform: fail closed at the adapter boundary, contract-test against a production URL corpus, pin and audit the version, and keep the swap path exercised.

Ramp-up. Low for anyone comfortable with URI semantics — the API surface is small and the value-object idiom is familiar. The conceptual cost is higher than the API cost: engineers must internalize normalization rules and know when a URI is a string versus a typed object. Budget a short internal write-up and a lint rule discouraging raw parse_url alongside the new type, otherwise the codebase ends up with three ways to handle URLs.

TPM recommendation. Do not adopt as a strategic dependency. Approve only as a behind-an-interface implementation for a bounded, non-security-critical use case, with a one-day spike and a documented exit to league/uri or Illuminate\Support\Uri. The 0.02 score and 4-star/0-dependent profile are consistent with that: technically workable, operationally thin, and not a bet worth making on the critical path.