Weave Code
Laravel Route File Macro Laravel Package
kirschbaum-development/laravel-route-file-macro
Laravel Route File Macro adds a simple Route::file() macro so you can split large route files into smaller, dedicated files and load them on demand—keeping route definitions organized without extra service providers or manual includes.
Route macro that easily loads a route file without unnecessary method calls.
Frequently asked questions about Laravel Route File Macro
- What is kirschbaum-development/laravel-route-file-macro and how does Route::file() work?
- It is a small Laravel package that registers a single macro on the framework's router, letting you write Route::file('routes/admin.php') instead of Route::group([], base_path('routes/admin.php')). Internally the macro is a thin wrapper: it resolves your path through base_path() and hands it to Route::group() together with any attributes you pass. It ships as one auto-discovered service provider with no configuration or migrations, so the macro exists as soon as Composer finishes. All work happens once at route registration, not during the request lifecycle.
- How do I install laravel-route-file-macro?
- Run composer require kirschbaum-development/laravel-route-file-macro and let Laravel's package auto-discovery register the service provider; there is nothing to publish, migrate, or wire up manually. Pin an exact tagged release rather than a branch, since release metadata should be verified on Packagist first. Run php artisan route:list afterwards to confirm your split route files actually load. If your app or another package already defines a Route::file macro, one registration silently wins, so check for a collision with a quick smoke test.
- Which Laravel and PHP versions does laravel-route-file-macro support?
- Check the composer.json constraint on Packagist for the authoritative answer, since the package is a framework extension point with a narrow version surface. Release notes for 1.4 mention Laravel 13 support, but that claim and its release date should be reconciled against Packagist before you pin it in production. Run your own CI matrix against the exact Laravel and PHP versions you deploy, and treat the upper bound as unverified until you do.
- Does Route::file() work with php artisan route:cache?
- Because the macro only executes at route registration, the routes it loads get baked into the cached route table exactly like any other route. The risk is path resolution: base_path() is evaluated at registration time, so cold boot and route:cache can diverge in containerized or symlinked deploy layouts. Gate this in CI by running route:cache and diffing route:list output against a cold boot, including middleware and route ordering. Do not assume parity just because the package is small.
- How is Route::file() different from Route::group([], base_path('routes/x.php'))?
- Functionally it is the same call, just shorter and more expressive: the package collapses Route::group($attributes, base_path($path)) into Route::file($path, $attributes). It adds no middleware, prefixing, or naming behaviour of its own, so anything Route::group does still applies. The value is readability and intent, which matters when routes/web.php is meant to read like a table of contents. Prove behavioural parity for middleware inheritance, prefix and name concatenation, and route ordering with a test before refactoring existing route files.
- Can I pass middleware, prefix, name, or domain attributes to Route::file()?
- Yes. The second argument is a plain attributes array forwarded straight to Route::group(), so middleware, prefix, as, domain, and where all behave as they do in the framework. For example Route::file('routes/admin.php', ['middleware' => ['auth'], 'prefix' => 'admin', 'as' => 'admin.']) gives you the same grouping semantics you already know. Keep attribute arrays consistent across files so route names and middleware stacks stay predictable as the app grows.
- How should I split a large routes/web.php into multiple route files with this package?
- Create dedicated files such as routes/admin.php, routes/billing.php, or routes/api-v2.php, then reference each one from routes/web.php with a Route::file() call that carries its own middleware, prefix, and name group. The main file becomes a table of contents, which is a genuine comprehension win for onboarding and code review. The package fits best when you carry roughly three to ten logical route files; with a single tiny web.php there is nothing to abstract, and if you already have a house routing convention, a second pattern adds cognitive load without paying for itself.
- What happens if the route file path is missing or unreadable?
- The macro delegates to Route::group(), which includes the resolved file, so a missing path generally surfaces as an error during registration, meaning route:list or route:cache fails rather than requests failing later. That fail-fast behaviour is what you want, but confirm the exact failure mode in your pinned version with an explicit test. The dangerous scenario is a path that resolves differently in your deploy pipeline, where routes go silently absent instead of raising loudly. Cache routes during deploy and diff the route table between environments to catch it.
- Does laravel-route-file-macro work with Octane, containerized deploys, or symlinked current/ releases?
- Since base_path() resolves relative to the application root at registration time, symlinked release directories and containers are fine as long as routes are cached or loaded after the symlink and working directory are in place. The package touches no request lifecycle, container bindings, config, or persistence, so it cannot change how Octane serves requests once the route table is built. The remaining hazard is purely path resolution, so build or cache routes in the same layout you run in. Verify with a route:list diff between build and runtime environments.
- Is laravel-route-file-macro actively maintained, and should I write my own Route::file macro instead?
- It is a single-purpose utility from Kirschbaum Development with a very small surface area, so check Packagist for release cadence, dependent counts, and a stated support policy before adopting. The entire behaviour is reproducible in roughly ten lines in AppServiceProvider, which makes the fork or vendor escape hatch trivial and the bus-factor risk easy to document. Frame the choice as a micro-dependency policy decision rather than a build-versus-buy analysis, because both paths are cheap. Pick one deliberately and record why in the decision log.
Weaver
How can I help you explore Laravel packages today?