RouteCollection get method has wrong return type in PHPDoc

[abdel-aouby]

Laravel Version

11.x

PHP Version

8.4

Database Driver & Version

Mysql

Description

RouteCollection get method has wrong return type in PHPDoc
resulting in warnings in static analytics and code sniffers and other tools

The method \Illuminate\Routing\RouteCollection::get

/**
     * Get routes from the collection by method.
     *
     * @param  string|null  $method
     * @return \Illuminate\Routing\Route[]
     */
    public function get($method = null)
    {
        return is_null($method) ? $this->getRoutes() : Arr::get($this->routes, $method, []);
    }

says it returns an array of Route but actually it can also return a route object

if you take a look at the implementation of Arr::get($this->routes, $method, []) it return mixed

it seems that all if conditions will return an array of Route

except for this one which can iterate to the deepest level of the array and return the Route object

if (static::accessible($array) && static::exists($array, $segment)) {
      $array = $array[$segment];
  }

this can give warnings in static analytics and code sniffers and other tools
please correct me if I'm wrong

so I guess that the return type should be \Illuminate\Routing\Route | \Illuminate\Routing\Route[][]

Steps To Reproduce

• declare a simple route

Route::view('about, 'about') ->name('about');

somewhere in the code call
$route = $this->get(GET./about);

if according to the PHPDoc you assume that the return value is an array of route and you try to access $route[0] it will throw an error
Cannot use object of type Illuminate\Routing\Route as array

[rodrigopedra]

The doc block says:

Get routes from the collection by method.

And the parameter is called $method.

Why are you querying using dot notation?

Maybe we could filter out valid methods (GET, POST, etc.) and error out if and invalid string, such as GET./about, is given.

From the method's documentation, and expectations, there are no unexpected outcomes.

[abdel-aouby]

Yes the doc description and the parameter names are clear.
However, the function is still allowing us to search by dot notation.
If you look at the implementation of Arr::get($this->routes, $method, [])
You will see that it check for the dot notation and return the route as object

So i would say that doc description and parameter name does not match with what the actual implementation do.

It actually do return array of routes if you search by method and will return one route as object if you search by mehod.uri

[rodrigopedra]

I see what you mean.

But bear in mind, this class implements against an interface. Not just the PHP docs, but an actual interface/contract (Illuminate\Routing\RouteCollectionInterface).

So I would say the implementation needs to be fixed to comply with the interface expectations, and not the interface to be loosened to allow for an implementation oversight.

Also, there are other implementations (e.g. CompiledRouteCollection), and 3rd-party packages might be even providing their own.

You can propose a PR to fix the implementation. I guess instead of using Arr::get() we could use the null-coalescing operator instead.

In the meanwhile, just don't use the dot notation. It is not meant to be used by like that.

[abdel-aouby]

Exactly, I agree with you.
The method is just doing too much than it promise from its name and parameter.
I will prepare a PR for tha matter

Thanks for the discussion.

[abdel-aouby]

PR mrged
#54672