Groups

Grouping routes simplifies route definitions and speeds up route matching in the application. RouterRegister supports route grouping at two levels; the application level and the controller level.

This section describes how to define and use route Groups.

Application Level Grouping

If an application has a number of logical sections, for example API, backend, frontend, each can be a group.

Application level groups are defined using a string backed Enumeration that implements GroupInterface; GroupTrait provides an implementation of GroupInterface (both are part of the RouterRegister package).

There is one Group Enumeration in an application.

Group Enumeration

Each case in the Enumeration defines a group.

The case name defines the group name prefix.

The case value defines the group route prefix.

As an example, for an application with a frontend and backend, with the backend having the group prefix admin, the enumeration will be:

                enum GroupEnum: string implements GroupInterface
                {
                    use GroupTrait;

                    case backend = 'admin';
                    case frontend = '';
                }
            

The generated groups will be:

                return [
                    Group::create()
                        ->namePrefix('frontend.')
                        ->routes(...(require __DIR__ . '/routes/frontend.php'))
                    ,
                    Group::create('/admin')
                        ->namePrefix('backend.')
                        ->routes(...(require __DIR__ . '/routes/backend.php'))
                    ,
                ];
            

Group Prefix

A prefix common to all Groups can be defined by applying the Prefix Attribute to the Enumeration. It is prepended to the Case prefixes - the Case value.

The parameter passed to the attribute is either a string or an array. If a string it is the prefix, if an array, the keys are integers or strings and values are strings: (non-empty-array<int|string, string>). How the value is interpreted depends on the key type:

integer key: Value is a string literal
string key: Key is a parameter name, value is the parameter pattern

Array entries are prefixed to the route in the order defined.

The example below defines a route prefix that defines a literal and the locale route parameter as two lower-case letters (e.g. ISO-3166 Alpha-2 codes).

                enum GroupEnum: string implements GroupInterface
                {
                    use GroupTrait;

                    case backend = 'admin';
                    #[Prefix(['example', 'locale' => '[a-z]{2}'])]
                    case frontend = '';
                }
            

The generated groups will be:

                return [
                    Group::create('/admin')
                        ->namePrefix('backend.')
                        ->routes(...(require __DIR__ . '/routes/backend.php'))
                    ,
                        Group::create('/example/{locale:[a-z]{2}}')
                                ->namePrefix('frontend.')
                                ->routes(...(require __DIR__ . '/routes/frontend.php'))
                    ,
                ];
            

GroupInterface and GroupTrait

GroupInterface

GroupInterface defines methods used when generating URLs when routes are grouped. The application Group Enumeration must implement GroupInterface.

Group Interface defines the following methods:

getName(): Returns the Group name
getNamePrefix(): Returns the Group name prefix
getRoutePrefix(): Returns the Group route prefix

GroupTrait

GroupTrait implements GroupInterface and can be used in the application Group Enumeration.

Controller Level Grouping

RouterRegister implements Controller Level Grouping by grouping routes defined in Route Enumerations using the Group Attribute. The name parameter defines the group name prefix; typically this is the name of the associated controller. The optional parent parameter takes a Group Enumeration Case; this places the route group in the parent group.

Most controller level route groups will require a route prefix. As with application groups, this is defined using the Prefix attribute.

The example below defines a Group with a name and route prefix of post that belongs to the backend parent Group.

            #[Group(name: 'post', parent: GroupEnum::backend)]
            #[Prefix('post')]
            enum PostRoute: string implements RouteInterface
            {
                use RouteTrait;

                case index = '';
                case create = '/create';
                case update = '/update/{id}';
                case view = '/{id}';
            }
        

The resulting post Group definition is; this Group is a child of backend Group: (how the HTTP methods and route patterns are determined are explained in the next section)

            Group::create('/post')
                ->namePrefix('post.')
                ->routes(
                    Route::methods(['GET'], '')
                        ->name('index')
                        ->action([PostController::class, 'index'])
                    ,
                    Route::methods(['GET', 'POST'], '/create')
                        ->name('create')
                        ->action([PostController::class, 'create'])
                    ,
                    Route::methods(['GET', 'POST'], '/update/{id: [1-9]\d*}')
                        ->name('update')
                        ->action([PostController::class, 'update'])
                    ,
                    Route::methods(['GET'], '/view/{id: [1-9]\d*}')
                        ->name('view')
                        ->action([PostController::class, 'view'])
                    ,
                )
        

The route names and URLs are:

Case	Name	URL
index	{group name prefix}post.index	{group route prefix}/post
create	{group name prefix}post.create	{group route prefix}/post/create
update	{group name prefix}post.update	{group route prefix}/post/update/<id>
view	{group name prefix}post.view	{group route prefix}/post/<id>

Other Attributes

Other Attributes that can be applied to Groups are:

Cors: Cors defines CORS middleware for a group
Host: Host defines a host that routes in the group respond to
Middleware: Middleware defines middleware for a group or ancestor group middleware to disable for a group

Last modified: 28 November 2025