Tested Routes Checker Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony Native Integration: The bundle is designed for Symfony applications (v6.4+, 7.3+, 8.0+), leveraging Symfony’s routing, dependency injection, and console components. This aligns with Laravel’s ecosystem only if wrapped in a Laravel-compatible facade (e.g., a custom bridge or Symfony microkernel integration). The v1.1.0 changes do not alter this fundamental architecture.
• Route-Centric Focus: The package’s core functionality (tracking tested routes via HTTP calls) remains highly relevant for Laravel, where route coverage is a common pain point in testing. Laravel’s route system (RouteServiceProvider, web.php, api.php) can be mapped to Symfony’s routing abstraction.
• Cache-Driven: Uses Symfony’s cache system (var/cache/...) to store route calls. Laravel’s storage/ or bootstrap/cache/ could serve as equivalents, requiring minimal adaptation.
• Version 1.1.0 Baseline Semantics: The new “keep useful entries / drop useless ones when regenerating the baseline” feature materially improves the wrapper design — the Laravel bridge can lean on the package’s regeneration logic rather than reimplementing baseline diffing, reducing the surface area of the wrapper.

Integration Feasibility

• Symfony Dependency Overlap: Laravel lacks Symfony’s Routing and HttpKernel components, necessitating:
  • A custom route collector to mirror Symfony’s RouteCollection.
  • A request interceptor (e.g., middleware) to log route hits during tests (similar to Laravel’s Testing facade).
• PHPUnit Integration: The bundle assumes PHPUnit for test execution. Laravel’s phpunit.xml and tests/ structure are compatible. The v1.1.0 addition of documented ParaTest support provides a concrete parallel-testing reference point, though ParaTest is PHPUnit-based — Laravel’s default parallel runner (PestPHP/phpunit parallel via brianium/paratest) still requires artifact-merging adaptation. The CLI command (bab:tested-routes-checker:check) still needs a Laravel-specific facade (e.g., php artisan bab:check-routes).
• Localization Support: The bundle handles localized routes (e.g., _locale parameters). Laravel’s route localization (via Route::localization() or packages like spatie/laravel-localization) would require mapping to Symfony’s Route objects.
• Platform Portability: v1.1.0 runs CI on Windows, reducing risk that file-path or cache-path assumptions break on non-Linux developer machines — a positive signal for cross-platform Laravel dev teams.
• PHP Version Floor (Breaking): v1.1.0 drops PHP 8.2 and 8.3, effectively raising the minimum to PHP 8.4. This is the most consequential change for a Laravel wrapper: it narrows the set of Laravel versions that can host the package (see Compatibility below).

Technical Risk

• High Adaptation Effort: Rewriting Symfony-specific logic (e.g., RouteCollection, Route objects) for Laravel’s router (Illuminate\Routing\Router) remains non-trivial but manageable with a wrapper layer.
  • Key Risks:
    • Route parameter extraction (named routes vs. URI patterns).
    • Middleware/guard interactions (Symfony’s Route objects include middleware; Laravel’s Route objects do not).
    • Cache storage location (var/cache/ → storage/framework/cache/).
• PHP Floor Risk (New / Elevated): Because v1.1.0 requires PHP 8.4+, any Laravel 10 app (or Laravel 11/12 app pinned below 8.4) is now excluded. The wrapper must either (a) document PHP 8.4+ as a hard prerequisite and target Laravel 12 exclusively, or (b) maintain a v1.x-compatible fork pinned to the previous PHP support. This is a breaking change requiring a decision, not just a compatibility note.
• Baseline Reliability (Improved): v1.1.0 fixes IgnoredRoutesStorage::saveRoutes() “gluing” routes together across successive saves. This directly reduces the risk of corrupted/merged baseline entries — previously an insidious failure mode in the wrapper’s Phase 2 baseline work.
• Baseline Regeneration (Improved): The new “keep useful entries / drop useless ones” behavior reduces manual baseline stewardship and stale-baseline false positives. This lowers the maintenance burden of the wrapper’s baseline layer.
• Testing Overhead: The bundle’s accuracy depends on all test requests being logged. Laravel’s Http::fake() or Testing::fake() might interfere; a custom TestRequestListener is still needed.
• CI/CD Complexity: The GitHub Actions example assumes Symfony’s artifact handling. Laravel’s CI would need adjusted artifact paths (storage/ instead of var/cache/). The now-documented ParaTest scenario is a useful reference but not a drop-in for Pest.

Key Questions

1. PHP Floor Decision: Is the team prepared to require PHP 8.4+ (and therefore target Laravel 12, or Laravel 11/12 on 8.4), or must the wrapper fork/stay on the last PHP-8.2/8.3-compatible release?
2. Parallel Testing Fit: Does the documented ParaTest approach translate cleanly to Pest’s parallelizer and Laravel’s php artisan test --parallel artifact layout, or does the wrapper need its own merge step?
3. Baseline Regeneration Contract: What exactly does “keep useful entries / drop useless ones” consider “useful”? Wrapper authors need this contract stabilized before building baseline tooling on top of it.
4. Route Granularity: Does Laravel’s route system support the same level of route identification as Symfony (e.g., named routes with parameters)? How are dynamic routes ({id}) handled?
5. Middleware/Guard Coverage: Will route checks account for auth, throttle, and other guards that may block routes during testing?
6. Performance Impact: What is the overhead of logging every route hit during test execution?
7. Baseline File Format: How does .bab-trc-baseline map to Laravel test exclusions? The v1.1.0 regeneration behavior change should be reflected in this mapping.
8. Artisan Command Integration: How will bab:tested-routes-checker:check be exposed as an Artisan command?
9. Multi-Environment Support: How does the bundle handle Laravel environment-specific routes and route caching?

Integration Approach

Stack Fit

• PHP Runtime: PHP 8.4+ is now a hard floor following v1.1.0. Plan the wrapper around Laravel 11/12 running on PHP 8.4+, or explicitly pin to the last pre-v1.1.0 release if the org remains on 8.2/8.3.
• Laravel Compatibility:
  • Router: Replace Symfony’s RouteCollection with Laravel’s Router instance, adapting route parameter extraction.
  • Cache: Use Laravel’s FileCache or ArrayCache to store tested routes in storage/framework/cache/bab_tested_routes.
  • Console: Expose the checker as an Artisan command (php artisan bab:check-routes).
  • Testing: Integrate with Laravel’s Testing facade to intercept HTTP calls during test execution.
• Dependencies:
  • Symfony Components: Only symfony/routing and symfony/http-kernel are critical. Replace with Laravel’s native classes or minimal polyfills.
  • PHPUnit/ParaTest: Laravel’s PHPUnit setup is compatible; the documented ParaTest recipe in v1.1.0 is a useful starting point, but Pest parallelization requires an additional adapter.

Migration Path

1. Phase 0: PHP Floor Gate
   • Confirm PHP 8.4+ availability across target environments. If not achievable, pin to v1.0.x and defer wrapper work; do not silently upgrade.
2. Phase 1: Proof of Concept
   • Create a Laravel wrapper package (e.g., bab/laravel-tested-routes-checker) that:
     • Extends Laravel’s Router to log route hits.
     • Replaces Symfony’s RouteCollection with a Laravel-compatible version.
     • Implements a custom Artisan command.
   • Test with a small Laravel app (e.g., laravel/laravel skeleton) on PHP 8.4.
3. Phase 2: Core Functionality
   • Adapt route storage to Laravel’s cache.
   • Map the baseline file (.bab-trc-baseline) to config/bab-trc.php, leveraging v1.1.0’s improved regeneration semantics instead of hand-rolling merging logic.
   • Add middleware to ensure route logging works with Laravel’s test helpers.
   • Exploit the v1.1.0 IgnoredRoutesStorage fix by treating ignored-route accumulation as now-safe across successive test runs.
4. Phase 3: CI/CD Integration
   • Update the GitHub Actions example for Laravel’s artifact paths.
   • Adapt the documented ParaTest pattern for Pest/PHPUnit parallel jobs; verify artifact merge across workers.
5. Phase 4: Advanced Features
   • Localization support (Laravel route localization → Symfony format).
   • Middleware/guard awareness (extend Laravel’s Route object to include guard info).

Compatibility

• PHP: 8.4+ required as of v1.1.0 (breaking).
• Laravel Versions: Target Laravel 12 primarily; Laravel 11 acceptable only on PHP 8.4. Laravel 10 is no longer viable for a v1.1.0-based wrapper.
• Testing Frameworks: PHPUnit (ParaTest documented upstream), Pest requires its own parallel adapter.
• Route Service Providers: Ensure compatibility with Laravel’s RouteServiceProvider and API route groups.
• Cache Drivers: Support file, database, and redis cache drivers.
• OS: Linux/macOS/Windows now all viable upstream (Windows CI added in v1.1.0).

Sequencing

1. PHP Floor Gate (new, precedes all work).
2. Route Logging: Modify Laravel’s Testing facade or create a TestedRoutesServiceProvider.
3. Storage Layer: Implement a TestedRouteStorage class using Laravel’s cache; validate against the baseline regeneration contract.
4. Artisan Command: Build CheckRoutesCommand.
5. CI/CD Pipeline: Integrate into Laravel’s test workflow, including artifact merging for parallel workers (ParaTest as reference).
6. Localization/Middleware: Add support for Laravel’s route attributes (middleware, name).

Operational Impact

Maintenance

• PHP Version Tracking: v1.1.0’s PHP 8.2/8.3 drop establishes a pattern of aggressive PHP floor movement. The wrapper team should budget for PHP-version-coupled releases and align with Laravel’s PHP support windows.
• Baseline Stewardship (Reduced): v1.1.0’s “keep useful / drop useless” regeneration and the IgnoredRoutesStorage fix significantly reduce manual baseline editing and the risk of corrupted/glued ignore entries. This is a concrete net positive for day-to-day maintenance.
• Dependency Updates: Laravel’s router and cache systems are stable, but breaking changes (e.g., Laravel 11 route system) may require updates. Symfony components must track Laravel’s PHP version.
• Route Schema Changes: Adding/removing routes will still require baseline or test-suite updates, but regeneration behavior in v1.1.0 eases this.
• Test Suite Maintenance: Developers must ensure all routes are tested; untested routes still trigger CI failures.

Support

• Upstream Health (Improved): Weekly CI (v1.1.0) and Windows coverage indicate active maintenance. This improves the wrapper’s supply-chain confidence relative to the earlier assessment.
• Parallel Testing Docs (Improved): Upstream ParaTest documentation lowers the ramp-up cost for parallel CI configuration, though Pest-specific gaps remain.
• Debugging Untested Routes: The bundle provides a CLI report; integrate with Laravel’s route:list for deeper insights.
• False Positives/Negatives: Routes blocked by middleware may appear untested; document handling explicitly.
• Community Support: Limited dependents (0) and stars (12) still indicate niche adoption. Laravel-specific support remains on the wrapper maintainers.

Scaling

• Large Route Counts: Route storage could grow with thousands of routes. Laravel’s cache drivers (Redis) mitigate this; v1.1.0’s improved baseline pruning reduces baseline bloat.
• Parallel Testing: ParaTest documentation (v1.1.0) gives a concrete reference; Laravel/Pest parallelization still needs artifact-merge logic.
• Performance: Route logging adds overhead. Benchmark to ensure test runtime does not grow >10%.

Failure Modes

• PHP Floor Mismatch (New): Attempting to install v1.1.0 on PHP 8.2/8.3 will fail outright — this is the most likely upgrade failure and should be caught at the Phase 0 gate.
• Incomplete Route Logging: If tests use Http::fake() or Testing::ignore(), routes may not be logged. Clear documentation and a dedicated listener are required.
• Baseline Corruption (Mitigated): The IgnoredRoutesStorage::saveRoutes() gluing bug is fixed in v1.1.0; wrappers upgrading from earlier versions should re-verify previously suspect baselines.
• Over-Pruning on Regeneration (New): The “drop useless entries” behavior could remove entries the wrapper treats as intentional exclusions if the “useful” definition is misunderstood. Validate against a representative baseline before relying on it in CI.