Download the PHP package nckrtl/waymaker without Composer

Waymaker

This Laravel packages lets you generate a routes file based on your public controller methods. This package works particularly well with Laravel Wayfinder, as it allows you to reference controller methods instead of just routes. Based on the method signature in your controllers we could generate a routes file, automating route management entirely.

Installation

You can install the package via composer:

Requirements

• PHP 8.4+
• Laravel 10, 11, or 12
• vite-plugin-run (for automatic route generation during development)

Install the vite plugin:

Usage

Update your vite config to include an additional run command:

Next, update your main routes file to include the generated routes with:

Now you're all set. Running vite dev should now generate the routes based on your controller methods. On file change of any controller the routes file will be regenerated.

Route definition structure

The way routes are generated are pretty opionated. The naming convention of routes is inspired by how Laravel Wayfinder exposes routes/actions.

Important: As of version 2.0, explicit route attributes are required on all controller methods that should generate routes. Methods without route attributes will be ignored.

For this controller:

The generated route definition will look like:

Smart Route Grouping

Waymaker intelligently groups routes to reduce duplication and improve readability:

• Routes with the same prefix and middleware are automatically grouped
• Prefixes and middleware are applied at the group level
• Individual routes within groups use relative URIs (no leading slash)
• Route-specific middleware is still applied to individual routes

Smart URI Generation

Waymaker intelligently generates URIs based on your controller structure:

• Controller name becomes the base URI (e.g., ArticleController → /article)
• Route prefixes are applied to all routes in the controller
• Custom URIs in attributes are appended to the base/prefix
• Route parameters can be specified in the attribute

This automatic URI generation helps maintain consistent URL structures across your application.

Setting route parameters and other properties

Route attributes are required for all controller methods that should generate routes. You can use specific HTTP method attributes to define routes. For example, you can define a route parameter like so:

Available HTTP Method Attributes

Waymaker provides specific attributes for each HTTP method:

• #[Get] - For GET requests
• #[Post] - For POST requests
• #[Put] - For PUT requests
• #[Patch] - For PATCH requests
• #[Delete] - For DELETE requests

Each attribute supports the following properties:

• uri - Custom URI path (optional, appended to base/prefix)
• name - Custom route name (optional)
• parameters - Route parameters array (optional)
• middleware - Route-specific middleware (optional, applied on the individual route)
• middlewareGroup - Named middleware group for the route (optional, e.g. web, static, api)

Note: Methods without a route attribute will not generate any routes.

Middleware groups (e.g. Cloudflare / cookie-free pages)

Use a middleware group when routes must not sit on the default web stack (sessions, CSRF cookies). This is required for edge HTML caching (Cloudflare): responses with Set-Cookie are not cacheable.

Controller-wide:

Per route (overrides the controller default):

Generated output looks like:

Important: if you register Waymaker::routes() inside Laravel’s web routes file, a static group is still nested under web (session cookies remain). Load Waymaker from then: so groups are top-level:

Define static however you like; for Cloudflare HTML caching it must not include StartSession / cookie encryption that queues Set-Cookie.

Examples

Other route properties are also supported like middleware. Besides setting middleware on specific methods you can also set them at the controller level, just as a prefix or middleware group:

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Feel free to contribute. Make sure to add/update tests for new or improved features.

Troubleshooting

Routes not being generated

1. Missing route attribute: Ensure all controller methods have a route attribute (#[Get], #[Post], etc.). Methods without attributes are ignored.
2. Controller not in expected directory: Waymaker scans app/Http/Controllers by default. Ensure your controllers are in this directory or a subdirectory.
3. Vite not running: The vite-plugin-run only triggers during vite dev. Run php artisan waymaker:generate manually for production builds.

Duplicate route error

If you see a RuntimeException about duplicate routes:

• Check that you don't have multiple methods with the same HTTP method and URI
• Ensure route prefixes don't create conflicts between controllers
• Use unique route names if needed via the name parameter

Routes file not included

Make sure your routes/web.php (or appropriate routes file) includes:

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• nckrtl
• All Contributors

License

The MIT License (MIT). Please see License File for more information.