Enhanced Router Laravel Package

Getting Started

Install via Composer, pinning to the 1.x line (the package was abandoned in 2013 and has no later releases):

composer require jasonlewis/enhanced-router:1.0.*

This is a router replacement, not an add-on. In app/config/app.php, comment out Laravel's default Illuminate\Routing\RoutingServiceProvider and register the package's provider instead — do not register both, or you'll end up with two routers bound in the container and confusing resolution behaviour:

'providers' => array(
    // 'Illuminate\Routing\RoutingServiceProvider',
    'JasonLewis\EnhancedRouter\EnhancedRouterServiceProvider',
),

Where to look first. Read the three classes you'll actually be touching — everything else is Laravel 4 plumbing:

• src/JasonLewis/EnhancedRouter/Router.php — subclasses Illuminate\Routing\Router; this is the object Route:: resolves to.
• src/JasonLewis/EnhancedRouter/Route.php — the enhanced route object (group attribute handling, cache serialization).
• src/JasonLewis/EnhancedRouter/RouteCollection.php — ordering and the compiled-route loading path.

First real use case. On a large app with a few hundred routes, the biggest daily win is route caching: the collection is compiled to a PHP file and loaded on boot instead of re-executing app/routes.php (and its closures/Route:: calls) on every request. Get a working routes.php first, verify with php artisan routes, then turn caching on.

Implementation Patterns

Rich route groups

The core value is that group attributes actually merge — prefix, domain, before/after filters, and where patterns stack predictably through nested groups, which core Laravel 4 handled inconsistently:

Route::group(['prefix' => 'admin', 'before' => 'auth'], function () {
    Route::group(['domain' => '{account}.example.com', 'before' => 'account'], function () {
        Route::get('dashboard', 'AdminController@dashboard')
            ->where('account', '[a-z0-9\-]+');
    });
});

Sub-domain / parameter routing

Sub-domain parameters ({account}.example.com) are treated like any other route parameter, so they participate in where() constraints and are appended to the controller action arguments. Bind them early (in a before filter) so downstream filters can rely on them.

Route caching workflow

1. Develop normally with caching off.
2. Freeze the app: run the package's cache command (or the equivalent Route::cache() call from your bootstrap, depending on the version) to write the compiled collection to storage.
3. Ship the compiled file with the deploy; the provider loads it during boot.
4. On every deploy that touches routes, rebuild the cache as a deploy step — never by hand.

Loading routes from files/directories

Rather than one giant routes.php, split by concern (routes/admin.php, routes/api.php, routes/web.php) and load them from the main file. Keeps diffs reviewable and lets you cache a stable set of files.

Parameter constraints as an array

Apply where() once for a set of routes via group attributes instead of repeating it per route — this is the pattern that saves the most typing day-to-day.

Gotchas and Tips

• Closures break caching. Cached routes are serialized; PHP cannot serialize closures. If caching silently fails or throws on boot, the culprit is almost always a Route::get('/', function () {...}). Convert closure routes to controller actions before enabling the cache — this is the single most common onboarding failure with this package.
• Stale cache is invisible. A cached app ignores edits to routes.php entirely. If a route "doesn't exist" after you added it, clear/rebuild the route cache before debugging anything else.
• Don't mix with Laravel 4.2's built-in route:cache. 4.2 shipped its own route cache; running both produces two competing compiled collections and unpredictable order. Pick one — on 4.2, prefer the core one and only use this package for the group/domain features.
• Container singleton mismatch. Any other package that type-hints Illuminate\Routing\Router gets the core binding unless it resolves the router alias. If a third-party package behaves oddly, check which router instance it received.
• Order still matters. The enhanced collection preserves registration order; cache-then-add-routes at runtime will not behave as you expect because the compiled collection is authoritative.
• Version pinning is mandatory. No releases after 2013, no Laravel 5+ support, and it will not run on modern PHP. Treat it as a locked dependency; any composer update on the framework is a breaking change.
• Extension points: if you need behaviour the package doesn't expose, subclass JasonLewis\EnhancedRouter\Router, override the relevant method, and rebind router in your own service provider — cheaper than patching vendor/.
• Debugging aid: dump Route::getRoutes() (the enhanced collection) and inspect the compiled cache file on disk; comparing the two immediately shows whether you're running against a stale build.