Feature Suggestion: Laravel Middleware documentation

[knuckleswtf]

Feature Suggestion: Laravel Middleware documentation

[shalvah]

And your problem isn't really a middleware problem, but a metadata problem—"how do I add this custom metadata (roles/permissions) automatically?" Still the same solution: use a custom metadata strategy and customise the views.

Hopefully v3 brings in a structure that would make it more straightforward than that, but right now, that's it.

[krikru95]

What i've done for my project is looking like this:

In the tags are the names of the middlewares. I think it's pretty useful if you are using something like https://github.com/spatie/laravel-permission to manage your users premissions. With these output we can directly see our nessesary roles or permissions for an endpoint

[shalvah]

On the contrary, I'm not convinced. I still think that, while there are some use cases, in most cases this will be leaking unnecessary implementation details to the end user. I don't think I'll be adding it to Scribe anytime soon.

However, it's fairly straightforward to customise your local installation of Scribe to include it yourself: Write your own metadata strategy (just extend the default one) that captures the middleware, then extend the vendor views to show the middleware.

Perhaps for v3, we'll look into providing easier ways to add your own metadata or labels, but no promises!

[shalvah]

Did you read my response? I didn't say to manually write it. I've put a lot of work into making Scribe as extensible as it is. Take some time and look up the documentation on writing a custom strategy. I even created a template and collated some examples. All you need to do is grab the route middleware and add it to the returned array. The rest of the work is customising one Blade file, which is also quite easy, considering I've already provided the badge components.

I've got a lot of things on my plate right now, so I really can't spend time debating this. But the tools are in place for you to get it done for yourself.

[shalvah]

What's an example of what such documentation would look like?

[shalvah]

I agree that it's useful in the scenario you describe, but generally, I think it would be a minus. Middleware are typically an internal, implementation detail. For instance, if we were printing out the names of included Laravel middleware, you'd probably see things like bindings, and throttle:60,1. Not very friendly for the user.

[gazben]

That depends on, who the user is. If we are talking about developers, it can be helpful.

[shalvah]

No, it's not about skillset, but about perspective. As an end-user, I would only be confused if I saw things like ConvertEmptyStringsToNull, and TrustProxies listed there.

That said, I'm all for extracting as much information as possible from the framework, so, if we're going to do this, how can we:

1. avoid showing the user unnecessary information?
2. present it in a friendly format?

[krikru95]

We could make the feature optional over a setting in the config so it's only generated if you want it. As for the presentation i would be open for your suggestions. In our case it's enough to know the middleware names since we have only developers as users

[tsndp]

I agree, this is very much needed. please add in new version 2.0

[tsndp]

My reason: say suppose we have 100+ routes out of which only 20 are for RoleA and 5 are for RoleB so on so forth. Now other developers need to know which route is given access to which role. Manually write this in all routes is too much work.

Maybe we can do the same approach like include and exclude, eg include Middleware starting with "role" only (referring to Spatie lib)