Laravel Passport traditionally enforces OAuth scopes at the routing level, usually via middleware definitions in
route files.
While this works, it often leads to:
- authorization rules scattered across routes
- controllers coupled to infrastructure concerns
- duplicated or hard-to-review scope requirements
- reduced clarity as APIs grow
Laravel Passport Modern Scopes introduces a different approach.
👉 https://github.com/N3XT0R/laravel-passport-modern-scopes
The idea: declare scopes where they matter
Instead of wiring scopes into routes, this package allows you to declare OAuth scope requirements directly on
controllers or controller actions using PHP 8 attributes.
Authorization intent lives next to the code it protects.
Passport itself remains fully responsible for authentication and token validation.
Example
use N3XT0R\PassportModernScopes\Support\Attributes\RequiresScope;
use N3XT0R\PassportModernScopes\Support\Attributes\RequiresAnyScope;
#[RequiresScope('users:read')]
final class UserController
{
public function index()
{
// Requires users:read
}
#[RequiresAnyScope('users:update', 'users:write')]
public function update()
{
// Requires at least one of the given scopes
}
}
A single middleware inspects controller attributes at runtime and enforces them using Laravel Passport’s native
tokenCan checks.
Authentication itself remains the responsibility of your configured guard (e.g. auth:api).
What this package does
- Enables attribute-based OAuth scope enforcement
- Keeps routes clean and infrastructure-agnostic
- Makes authorization requirements explicit and discoverable
- Works with Passport’s existing scope validation
- Requires no changes to Passport internals
Scopes are declared, not wired.
Why attributes?
Using PHP attributes for authorization requirements has several advantages:
- Declarative and explicit
- No duplication between routes and controllers
- Easier to reason about during code review
- Friendly to static analysis and documentation tools
- No magic strings scattered across route definitions
This keeps authorization intent separate from HTTP wiring.
What this package does not do
To be explicit:
- ❌ It does not replace Laravel Passport
- ❌ It does not implement authentication
- ❌ It does not introduce custom guards
- ❌ It does not enforce business rules
It only resolves and enforces declared OAuth scope requirements.
Where this fits architecturally
Laravel Passport Modern Scopes is intentionally small and focused.
It pairs well with:
- structured scope models (e.g.
resource:action) - domain-level authorization logic
- admin tooling that manages scopes centrally
It can be used standalone or alongside higher-level authorization libraries.
Installation
composer require n3xt0r/laravel-passport-modern-scopes:^2.0
The middleware is automatically registered via the package’s service provider.
Final thoughts
This package is about clarity, not abstraction.
If you prefer:
- explicit authorization requirements
- clean routes
- controllers that express intent clearly
then attribute-based scope enforcement can be a very natural fit.
Feedback and discussion are welcome.