Attribute-based Routing

[AmirHkrg]

Hello everyone,

I'd like to propose a new feature that embraces modern PHP by adding support for attribute-based routing. This would serve as a powerful method that works in conjunction with the traditional file-based routing system, allowing developers to co-locate route definitions with their controller logic.

The Problem

Currently, route definitions in routes/*.php are physically separate from their controller logic. While this is a powerful and flexible system, in large applications, it can lead to frequent context switching between files and can sometimes make it harder to see the full picture of a controller's responsibilities at a glance.

The Proposed Solution

I propose adding a new fluent method, withAttributeRouting(), to the ApplicationBuilder. To enable the feature, a developer would call this method in bootstrap/app.php and provide the paths to be scanned.

1. Fluent Configuration API
   The feature is opt-in. If the method is not called, the feature remains completely disabled.

// bootstrap/app.php

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
    )
    // Enable attribute routing by providing paths for each group.
    ->withAttributeRouting(
        web: app_path('Http/Controllers'),
        api: app_path('Http/Api')
    )
    ->withMiddleware(...)
    ->create();

2. Controller Attributes
   To be discovered, a controller would simply implement a marker interface, AttributeRouteController. Here is an example of what a controller would look like:

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Routing\Attributes\{Get, Group, Post};
use Illuminate\Contracts\Routing\AttributeRouteController;

#[Group(prefix: 'users', name: 'users.')]
class UserController extends Controller implements AttributeRouteController
{
    #[Get('/', name: 'index')]
    public function index() { /* ... */ }

    #[Get('/{user}', name: 'show', where: ['user' => '[0-9]+'])]
    public function show(User $user) { /* ... */ }
}

Performance Considerations

We acknowledge that this feature may introduce a negligible performance impact of a few milliseconds in local development due to the file scanning process. However, this is completely mitigated in production. Once routes are cached with php artisan route:cache, there is zero performance overhead, leaving only the benefits of simplicity and a more enjoyable development experience.

Key Features & Benefits

• Co-location: Route definitions live directly with the controller logic, improving code organization.
• Clean API: Expressive and fluent configuration in bootstrap/app.php.
• DRY: Centralized group configuration avoids repetition of prefixes or middleware.
• Developer Experience: An --attributes flag for the make:controller command will be added to instantly scaffold a controller ready for attribute routing.
• Opt-in: The feature is off by default and has zero impact unless explicitly enabled.
• Full Feature Parity: All standard HTTP verbs (Get, Post, etc.), helpers like Any and Matches, and all standard route options (name, middleware, where, etc.) are supported.

Implementation Status

I have a full, working implementation of this feature ready, including tests. I've created this discussion to gather feedback from the community and the core team before submitting a Pull Request.

What are your thoughts on this proposal? I'm open to any feedback or suggestions.

Thanks for your time and consideration!

[henzeb]

Should we be able to disable this and use the regular routing?

What about custom file structures, for instance when the setup is domain driven?

[AmirHkrg]

Thanks for the great questions!

Regarding your first point—which you likely realized after posting—yes, you're absolutely right. Both traditional file-based routing and this new attribute-based routing are designed to work together seamlessly. The attribute feature is also entirely opt-in; if you don't call withAttributeRouting(), it's completely disabled.

Fortunately, this feature is also designed to support custom structures like DDD.

->withAttributeRouting(
    web: [
        base_path('src/Invoicing/UI/Web'),
        base_path('src/Customers/UI/Web'),
    ],
    api: [
        base_path('src/Invoicing/UI/Api'),
        base_path('src/Customers/UI/Api'),
    ]
)

The main purpose of this discussion is precisely to improve the idea with valuable feedback like yours. I'm still actively refining the API structure, so I'm very open to any other thoughts or suggestions you might have.