[9.x] Reinvents route:list command

[nunomaduro]

This pull request proposes a brand new route:list command - for Laravel 9 - regarding the way displays the application routes on the console.

What problem does this pull request solves?

Well, it's known that on Laravel applications with a huge and complex list of routes, the existing route:list artisan command don't display the routes properly:

Proposed changes

This pull request changes the way we display routes on the route:list artisan command, and essentially there are two modes: default and verbose.

Default (non-verbose)

The default - non-verbose - is the mode we get when running: php artisan route:list, and it looks like this:

Now, in this mode, the following information is displayed: method, domain@uri, and action. In addition, we ensure that the console output is always pretty, even in small terminals:

As you can see, the new display ensures we truncate the action at the end of the line, ensuring this way things are always properly displayed.

Verbose

The verbose is the mode we get when using the option -v: php artisan route:list -v, and it looks like this:

Now, in this mode, the following information is displayed: method, domain@uri, name, action, and list of middleware. In addition, we don't truncate any kind of information.

As you can see, in this mode, we display the name just next to the domain@uri, and we display a list of middleware used by the route.

Displayed actions are abbreviated

One more thing regarding this new route:list artisan command, is the way we display actions:

In this example, you can see that App\Http\Controllers\SearchController got abbreviated to SearchController and Laravel\Sanctum\Http\ControllersCsrfCookieController@show got abbreviated to Laravel\Sanctum › CsrfCookieController@show.

Domains

Domains are displayed right before actions:

---

Finally, it's important to mention that all the options - json, sort, etc - work just like in the past. Except for the options compact and columns that got removed.

Also, this pull request it's originally inspired by https://github.com/Wulfheart/pretty-routes, but of course, the display and features at this point are a little bit different.

---

Edit 1: There is a breaking change, regarding the Illuminate/Contracts/Routing/UrlGenerator contract that needs to be documented on the upgrade guide, this pull request gets merged.

---

Edit 2: After reading the community feedback, we decided to add the name just before the action.

[adamhopkinson]

@nunomaduro this is really nice work. Two suggestions, if I may?

1. As someone who frequently has to refer back to route:list, I think name should be in the default (non-verbose) view. I know you're trying to maintain readability, but could you accommodate this by shortening the http methods to G|H|P|D or similar?

2. Currently when I run Psalm on my local environment I can click on the file path in an error to open that file in my IDE. In verbose mode, you could add a path to the action file under the action (to the right of the middleware list). I get that this might be niche behaviour (and don't ask me how I set it up)!

[tontonsb]

1. As someone who frequently has to refer back to route:list, I think name should be in the default (non-verbose) view. I know you're trying to maintain readability, but could you accommodate this by shortening the http methods to G|H|P|D or similar?

Came here to suggest the same. Name is paramount.

[taylorotwell]

@nunomaduro let's try adding the name to the default view.

[nunomaduro]

@taylorotwell done.

[dillingham]

@nunomaduro might look less cluttered aligned beside the endpoint.

GET | HEAD users/{user}/followers followers.index.................FollowerController@index

Personally.. I think name is better fit for --v.. there is enough info here for quick glance purposes.

If i want to "know more" or see "meta" info.. I add -v I get it

[vpratfr]

I agree with one of the comments above that http verbs could be shortened to a single letter by default (maybe leave them expanded when using the verbose flag).

There are only a few of them and they all have a different first letter.

GET | HEAD users/{user}/follow

G users/{user}/follow

With the color codes it looks readable enough. And verbose mode gives you full info.

[Putzy]

Absolutely love this!

I'm not convinced that single letter verbs is the way forward though, considering that POST, PUT, PATCH all exist. With the colour coding it's probably fine, but for accessibility etc, it's not something that can be guaranteed.

[vpratfr]

Could be shortened to a 3 letter code to differentiate put/post/patch. Just noting here that the `|head` part is considerably pushing the whole to the right.

[morrislaptop]

Hey! I created https://github.com/morrislaptop/laravel-route-menu

The one key feature I’d love added to this would be printing the file path in verbose mode.

It’s great for an IDE terminal to jump to the relevant file.

[dammy001]

Well done man 👍 @morrislaptop

[martenkoetsier]

Great work, improving het route:list output. For many projects, I use a customized version because the original version doesn't cut it. I really like the use of various colors to highlight things like parameters.

I do see advantages of letting the fixed columns go and just let the text reach where-ever it needs to. However, I also like the name info (thanks for putting it back in the non-verbose output!) to be aligned, especially since the names are usually "grouped".
Thinking of it, I find the name information often even more important than the URI!
I also would always make route:list output the middleware information. For me, route:list is for quickly looking up which routes exist, where they are handled and which middlewares (or groups) are used.

So, here's my thought: would it be possible to make the output more customizable and include options from e.g. the .env or some /config/route-list.php file? Things I would like to see configurable for the regular call (just artisan route:list, without options):

• column-view or ragged view (this PR)
• which columns/info to show, in which order and with what alignment
• (Perhaps what info to "highlight" with which colors)

Also, some other thoughts:

1. As horizontal space is often a concern, I usually replace Controller in the Action column by © which saves 9 characters (and indeed I also remove the App\Http\Controllers\ part).

2. I like the use of the middleware aliases (and group names) instead of the full classname of the middlewares. IMHO the classname would be something you lookup if needed and the route:list info should provide a quick overview of which ones are used, not all their details.

3. Similar to the removal of the controller path, I also removed the full path from the can-middleware specifiers. In my current output they look like can:create,User and can:update,user (with lower case for policy methods requiring a model and studly case for policy methods not requiring a model).

4. Maybe a wild idea, but for a more horizontally consensed view, I would suggest: 2 lines for every route.
   Line 1 (in 3 fixed columns, with bright color): Method, URI, Name;
   Line 2 (in 2 fixed columns, less bright color): Action, Middleware (aliases)

[theriddleofenigma]

@nunomaduro I suggest, how about adding additional params to filter the list. Like,
-r for listing only the redirects,
-i for controllers with single __invoke method,
-a for action routes,
-n for named routes,
-c for routes declared in closure.

And arguments like --method=get to list only the routes which are declared in Get method.

[adjarriawan]

this looks more pleasing to the eye, can this also be applied to previous versions ?

[driesvints]

@adjarriawan no, this PR contains breaking changes.

[rodrigopedra]

A bit late to the party, but could the gray shade be improved so the contrast ratio is increased for better readability?

Right now contrast ratio between the text color (#6c7280) and the background color used in the examples (#15141a) is 3.8:1.

Although different OSes have different terminal background color, I tried with pure black, and ratio is 4.36:1.

WCAG 2.1 recommends a minimum contrast ratio of 4.5:1 for text:

https://www.w3.org/TR/WCAG21/#contrast-minimum

More info can be found here:

https://webaim.org/articles/contrast/

Although it could seem as being a nitty-picky request, I personally had difficulties reading the grayed out text on the screenshot samples. Maybe are my eyes showing their age.

A text color of #858c99 would provide a contrast ratio of 5.41:1 over the background color used in the screenshots, a 4.51:1 on my setup (#232627 as the default background color for Konsole, terminal emulator shipped on KDE Plasma), and a 6.21:1 ratio over pure black (#000000). As seen below:

For instance, I came up with that color by moving the lightness slider until it matched at least a 4.5:1 on all 3 background colors listed above.

The tool used is Kontrast , but it is only available for Linux. Similar tools are easy to find over the web.

Personally I would prefer a brighter shade of gray, such as #98a0b4 which would have a 7:1 contrast ratio on the sample screenshots, as called as AAA level by the same WACG 2.1 document (https://www.w3.org/TR/WCAG21/#contrast-enhanced).

But I understand it could make the aesthetics less appealing. The suggested shade already seems much better for my eyes.

Thanks in advance for considering this. :)

ping @nunomaduro

[chu121su12]

Is there --ansi support for this? /cc @nunomaduro