Simple Router Laravel Package

Technical Evaluation

What it is. pecee/simple-router is a standalone, MIT-licensed PHP router that deliberately mimics Laravel's routing API — route groups, prefixes, named routes, parameter regex constraints, middleware, resource routing, subdomains — but ships without a container, ORM, or application skeleton. It is PSR-7/PSR-15/PSR-17 aware and works as the dispatch layer in any PHP process.

Architecture fit. Fit is highly context-dependent and mostly inverse to how "Laravel" the target codebase is:

The package's value proposition is familiarity without a framework, not replacing Laravel. Any proposal framed as "use this instead of Laravel's router" should be rejected at intake.

Integration feasibility. Composer-only install, no extensions, no service dependencies. It requires a PSR-7 implementation (e.g. nyholm/psr7 or guzzlehttp/psr7) plus PSR-17 factories, which the team must choose and own. Adapter work is the real cost: resolving route handlers through your DI container, translating your exception handler into its IExceptionHandler, and reconciling middleware ordering conventions (PSR-15 process() vs Laravel's handle()).

Technical risk. The dominant risk is lifecycle, not code quality:

• Bus factor of one. Single maintainer, and the last tagged release is December 2023 — roughly two years of no release cadence.
• PHP version drift. PHP 8.3/8.4 compatibility is unverified for the current tag; a future runtime upgrade could block us with no upstream fix.
• Zero dependents in the dataset. Thin third-party validation: few battle-tested integration patterns and little community troubleshooting to draw on.
• Major-version churn. Prior majors raised the PHP floor and shifted PSR expectations; a v5 could do so again.
• Security surface is small but real — parameter regex handling, URL generation/encoding, optional CSRF helper, subdomain trust behind proxies.

The composite score (19.8) and opportunity score (30.8) are consistent with this read: a competent, low-momentum utility that is right for a narrow band of problems and wrong as a strategic dependency.

Key questions.

1. Is the target application a Laravel app? If yes, why is the native router insufficient — performance, bootstrapping, or a non-HTTP entry point?
2. Who owns the PSR-7/PSR-17 implementation choice, and does it conflict with an existing HTTP client stack?
3. What is our patch path if a CVE lands upstream and the maintainer is unresponsive — fork, vendor, or replace?
4. Which PHP versions must we support over the next 24 months, and does the pinned tag run clean on the newest two?
5. Have we quantified the routing hot path (routes × requests/sec) to confirm the absence of route caching is acceptable?

Integration Approach

Stack fit. Adopt only where the router is genuinely the missing piece: a legacy monolith being strangled toward a framework, a set of small PHP services that share conventions, or a CLI/queue worker that needs URL matching without a full HTTP kernel. Do not introduce it alongside Laravel's router in the same request lifecycle — two routers means ambiguous 404/405 semantics and duplicated middleware.

Migration path. Use a strangler pattern rather than a rewrite:

1. Stand up simple-router as the front controller with a catch-all fallback that proxies unmatched requests to the legacy dispatcher.
2. Port route groups one at a time, highest-traffic and lowest-risk first (health checks, static pages, then read-only endpoints).
3. Keep both route tables authoritative behind a feature flag; diff responses in staging before each cutover.
4. Retire the legacy dispatcher once the fallback route records zero traffic for a full release cycle.

Compatibility. Pin an exact version in composer.json (no caret range) and record it in the platform dependency register. Validate on the oldest and newest PHP versions in the support matrix, in CI, not locally. If the app already runs a PSR-7 stack, reuse those instances rather than adding a second implementation; if it does not, choose the PSR-7 library the rest of the org already standardizes on.

Sequencing. Four gates, roughly two to three sprints of effort for a mid-sized surface:

• Gate 1 — Spike (3–5 days). Ten representative routes, including one regex-constrained and one subdomain route, plus a 404 and a 405. Confirm behaviour parity with the incumbent.
• Gate 2 — Adapter layer. Container resolution, exception handler, middleware bridge, and a single place where the router is instantiated. This is the component we own and must test.
• Gate 3 — Pilot. One product area in production behind the proxy fallback, with latency and error-rate comparison against baseline.
• Gate 4 — Broad rollout. Route-by-route, with a documented rollback that flips the front controller back.

Treat Gates 1–2 as a go/no-go: if the adapter layer starts absorbing framework-grade complexity, the migration has lost its justification.

Operational Impact

Maintenance. Assume we own the code in practice. Budget a recurring line item for dependency review each PHP minor release, and keep a named owner and a documented fork procedure (mirror the repo, apply security patches, publish under an internal namespace if needed). Pin the version and let Renovate/Dependabot open PRs that a human reviews — do not auto-merge.

Support. No commercial backing and no SLA; support is GitHub issues with no guaranteed response. Internal developers become the de facto second line. Ramp-up for a Laravel-fluent engineer is one to two days — the API is intentionally familiar — but they also need working PSR-7/PSR-15 literacy, which is the actual learning cost.

Scaling. Route matching is linear in the number of registered routes and negligible relative to typical controller work, so per-request overhead is fine at normal API volumes. The structural gap is the absence of Laravel-style compiled route caching: every request re-registers and matches routes. For high-QPS services with hundreds of routes, measure before committing; if it shows up, mitigate by splitting the route table per service rather than fighting the library. Horizontal scaling is otherwise unaffected — the router is stateless.

Failure modes to instrument and pre-plan for:

• Trailing-slash and case-sensitivity mismatches producing 404s that the old router accepted.
• Middleware ordering differences silently skipping auth or CORS on newly ported groups.
• Catastrophic backtracking in user-supplied route parameter regexes.
• PSR-7 immutability mistakes in custom middleware (mutating a request and discarding the returned instance).
• Subdomain and scheme detection incorrect behind load balancers and reverse proxies.
• Exception handler swallowing errors into generic 500s, erasing the previous router's error taxonomy.
• A future PHP upgrade breaking the pinned tag with no upstream patch — the highest-probability operational event.

Ramp-up and recommendation. Low onboarding cost, low ongoing feature velocity upstream. Adopt for legacy/standalone PHP services where the alternative is hand-rolled routing; decline inside Laravel proper. Record it as a tactical dependency with an explicit review date tied to the next PHP minor release, and a standing replace-with-native-router trigger if upstream activity does not resume.