README

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:

composer require hardimpactdev/waymaker

Requirements

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

Install the vite plugin:

npm install -D vite-plugin-run

Usage

Update your vite config to include an additional run command:

import { run } from "vite-plugin-run";

export default defineConfig({
    plugins: [
        run([
            {
                name: "waymaker",
                run: ["php", "artisan", "waymaker:generate"],
                pattern: ["app/**/Http/**/*.php"],
            },
        ]),
    ],
});

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

use HardImpact\Waymaker\Facades\Waymaker;

Waymaker::routes();

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:

<?php

namespace App\Http\Controllers;

use HardImpact\Waymaker\Get;

class ContactController extends Controller
{
    #[Get(uri: '{id}')]
    public function show(): \Inertia\Response
    {
        return inertia('Contact');
    }
}

The generated route definition will look like:

Route::prefix('contact')->group(function () {
    Route::get('{id}', [\App\Http\Controllers\ContactController::class, 'show'])->name('Controllers.ContactController.show');
});

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:

use HardImpact\Waymaker\Get;

...

#[Get(parameters: ['article:slug'])]
public function show(Article $article): \Inertia\Response
{
    return inertia('Article/Show', [
        'article' => $article->data->forDisplay(),
    ]);
}

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)

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

Examples

use HardImpact\Waymaker\{Get, Post, Put, Delete};

class ArticleController extends Controller
{
    #[Get]
    public function index(): \Inertia\Response
    {
        // GET /articles
    }

    #[Post(middleware: 'throttle:5,1')]
    public function store(Request $request): RedirectResponse
    {
        // POST /articles with rate limiting
    }

    #[Put(parameters: ['article:slug'])]
    public function update(Request $request, Article $article): RedirectResponse
    {
        // PUT /articles/{article:slug}
    }

    #[Delete(name: 'articles.remove')]
    public function destroy(Article $article): RedirectResponse
    {
        // DELETE /articles/{id} with custom route name
    }
}

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:

class ArticleController extends Controller
{
    protected static string $routePrefix = 'articles';
    protected static string $routeMiddleware = 'auth:verified';

    ...

Testing

composer test

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

Missing route attribute: Ensure all controller methods have a route attribute (#[Get], #[Post], etc.). Methods without attributes are ignored.
Controller not in expected directory: Waymaker scans app/Http/Controllers by default. Ensure your controllers are in this directory or a subdirectory.
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:

use HardImpact\Waymaker\Facades\Waymaker;

Waymaker::routes();

hardimpactdev / waymaker

Maintainers

Details