Download the PHP package kirago/laravel-routify without Composer

Laravel Routify

Auto-discover and register Laravel route files spread across multiple folders. Configurable glob patterns, middleware groups, stacks (web / api / console / channels — or your own), opt-in filesystem cache, and a fluent builder for the cases the config can't express.

Why this package

The pain: routes/api.php rots

In a fresh Laravel app, every API route lives in routes/api.php. That file keeps growing. By the time the app has billing, auth, inventory, users, notifications and a few admin endpoints, it looks like this:

Pull-request reviews on this file are painful. Merge conflicts are constant. Finding "where is the route for X" requires grep. Multiply by web.php, console.php, channels.php and any custom stack (admin, internal, …) and the boilerplate compounds.

The disciplined workaround that's still painful

The seasoned move is to split per feature and require each piece manually from a central group:

Or worse — the same boilerplate inflated inside a RouteServiceProvider with five Route::group(…)->group(__DIR__.'/…') chains, one per feature folder.

It's better than the giant file, but every new module forces a touch on this central index. Forget the line and the routes silently disappear in production. That last part is the killer: there's no compiler error, no test failure unless you remembered to write one — just a 404 on staging at 9 PM the day before launch.

What Routify does

Point Routify at a folder, drop your route files anywhere underneath, stop maintaining the index:

• Add a module → its routes are picked up. No central file to edit.
• Delete a module → its routes disappear with it. No dangling require.
• Version your API by creating api-v2.php next to api.php. The default glob pattern api*.php matches both.
• Need a custom stack (admin, internal, webhooks, tenant-api)? Declare it in config/routify.php and Routify treats it like a first-class citizen.

The "register every file by hand" tax is gone.

Installation

The package auto-registers via Laravel's package discovery. Publish the config to customise it:

Requires PHP 8.2+ and Laravel 11, 12 or 13.

Zero-crash install — the shipped config has paths => []. The package is wired but does nothing until you point it at the directories your app uses. No surprise exceptions on first boot.

Quick start

1. Add your route directories to config/routify.php:

2. Drop route files anywhere under those roots:

…and they all become api/invoices, api/v2/* etc. with the api middleware group applied. With auto_discover_on_boot = true (the default), that's it — no extra wiring.

Folder-based discovery — drop a file, get a route

Since 1.1, you don't have to name your route files api*.php or web*.php anymore. Drop them in a folder named after the stack and Routify picks them up. The two modes coexist; pick whichever fits.

The rule is: under any paths[] directory, a .php file whose relative path contains a segment exactly equal to a declared stack key (api, web, your own admin, …) belongs to that stack — at any depth, with that stack's middleware, prefix, name prefix and domain applied automatically.

Conventions are simpler than configs: no rename of existing files, no central index to maintain, and a custom stack works as soon as the folder exists.

Migration note. If a folder under your scanned paths[] happens to be named after a stack key (api/, web/, …) and contains non-route PHP files (helpers, classes you forgot to namespace, …), those files will now be loaded as routes. Either narrow your paths config or rename the folder.

Explicit discovery for advanced setups

For explicit control, set auto_discover_on_boot => false and call from your AppServiceProvider::boot() (recommended location — facades are guaranteed to be ready there):

Configuration

config/routify.php:

Custom stacks

Declare anything you want — routify does not assume web and api are the only valid stacks:

Then load it explicitly:

Multiple paths

Each path is scanned independently. If two paths overlap, the same file is registered exactly once.

Fluent builder

For the cases the config can't express:

Every method returns the builder, so order is irrelevant. load() is the terminal call.

Artisan commands

routify:cache, routify:clear and routify:optimize only do useful work when routify.cache.enabled is true (typically ROUTIFY_CACHE=true in production). The cache is on the filesystem scan — Laravel's own route:cache is orthogonal and complementary.

Production deployment

In production, scanning the filesystem on every boot is wasteful. Enable the cache and warm it at deploy time:

Add the warm-up to the deployment script alongside the standard Laravel optimisations:

CI/CD via Composer scripts

To trigger Routify's cache refresh automatically on composer install / composer update, add this to your application's composer.json (not the package — Composer scripts live in the consuming app):

The routify:optimize call is a no-op when the cache is disabled, so it is safe to keep enabled across all environments.

Security considerations

Routify requires the route files it discovers. The same trust model as Laravel's own routes/ directory applies — with one important shift: the list of paths now comes from your config, so the surface for misconfig is larger. Keep these in mind:

• Never put a writable directory in routify.paths. Anything an attacker can write to (uploads dir, runtime cache, tmp) becomes a code execution vector at boot if Routify scans it.
• Symlinks are followed by default (Symfony Finder behaviour). On multi-tenant or shared-hosting setups where tenant-controlled directories live under your scan paths, audit the symlinks.
• Cache poisoning = boot RCE. If routify.cache.enabled = true and the cache backend is compromised, an attacker can inject arbitrary file paths into the cache. This is the standard Laravel cache trust model — protect your Redis/Memcached/database cache the same way you protect bootstrap/cache/.

In short: treat routify.paths like you treat the routes/ directory. Don't stage anything writable by the runtime web user under it.

Testing

Architecture

The why-and-how of every architectural choice is documented as Architecture Decision Records under docs/adr/ (in French). Start with ADR-0001 — Layered architecture for the big picture.

Roadmap

Post-1.0 ideas, not committed:

• per-stack Route::scopeBindings()
• OpenAPI doc generation from discovered routes
• pestphp/pest-plugin-laravel assertions (expect()->toHaveDiscoveredRoute('api.users.index'))
• multi-tenant dynamic paths
• bridging the discovery cache into Laravel's native route:cache mechanism

Contributing

Issues and pull requests on GitHub are welcome. Please run composer test and composer format:test before submitting.

License

MIT — see Simo Joel.