[maniaba]

Description

RouteCollection::group() passes the current collection instance to its callback with $callback($this). However, its PHPDoc declares that callback as callable(self): void. Here, self resolves to RouteCollection, even when group() is called on a subclass.

As a result, PHPStan rejects callbacks that correctly accept the application's collection subclass:

class CustomRoutes extends RouteCollection
{
}

function registerAdminRoutes(CustomRoutes $routes): void
{
    $routes->group('admin', static function (CustomRoutes $routes): void {
        $routes->get('users', 'Users::index');
    });
}

The reported error is that Closure(CustomRoutes): void does not satisfy callable(RouteCollection): void. At runtime, the callback receives the CustomRoutes instance on which group() was called, so this is valid usage.

This changes the annotation to callable(static): void. The late-static type follows the concrete collection class and therefore accurately describes the object passed to the callback. Applications can keep subclass-specific callback parameter types without overriding group(), adding application-level @method annotations, or suppressing the analysis error.

The method's implementation and native signature remain unchanged. Callbacks accepting the base RouteCollection continue to work, including when used with a subclass.

The regression test uses explicitly typed subclass callbacks for both an outer group and a nested group. It also verifies instance identity, registered routes, inherited filters, and restoration of group options afterward. These calls produce two PHPStan argument.type errors with the original self annotation and pass with static.

Validation

• Focused PHPStan analysis of RouteCollection.php and RouteCollectionTest.php: passed.
• vendor/bin/phpunit --no-coverage tests/system/Router/RouteCollectionTest.php: 117 tests, 167 assertions passed on PHP 8.3.35.
• File-scoped PHP-CS-Fixer and Rector checks: passed.
• The full CI matrix is left to GitHub Actions. No dependencies or analysis baselines were changed.

Checklist

• Securely signed commit
• PHPDoc corrected to describe the callback argument precisely
• Regression test included, with the static-analysis failure reproduced before the fix
• Conforms to the style guide
• User guide changelog updated under Bugs Fixed for the upcoming 4.7.6 release; no upgrading instructions are needed

[michalsn]

Overall, LGTM!

[michalsn]

Can we also make it a one-liner?