Index of every page on this site: llms.txt
All skills
labrodev avatar

/labrodev-authorization

@4e3053b
Run it yourself

Use when creating or reviewing authorization in a Labrodev Laravel project: writing a {Model}Policy class, defining permission constants, wiring #[UsePolicy] on a model, adding #[Authorize] to an invokable controller, or deciding how any endpoint checks who may view/create/update/remove a resource.

  • 1 file
  • 8.5 KB
  • MIT
  • Updated 2 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/labrodev/laravel-playbook/labrodev-authorization

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈81 tokens for metadata: the name and description. ≈2.1k when used: this file.

Description uses 4.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈324 characters, or 4.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Authorization: Policies, #[UsePolicy], #[Authorize]

Part of the Labrodev playbook. The law for this component lives in the always-on labrodev-authorization guideline (musts, must-nots); the per-file checklist is rules/policies.md. This skill holds the craft: anatomy, canonical templates, and edge cases.

Authorization is one cluster with three pieces that must always be wired together:

  1. Policy — final class {Model}Policy in Core/Domain/{Domain}/Policies/, answering "may this user perform this action on this object?" in business terms.
  2. Model wiring — #[UsePolicy({Model}Policy::class)] attribute on the model class.
  3. Controller wiring — class-level #[Authorize(...)] attribute on every invokable controller.

The constant contract (critical)

The permission constant's value is the string the Gate uses to find the policy method:

public const string PERMISSION_VIEW = 'view';     // resolves to view()
public const string PERMISSION_UPDATE = 'update'; // resolves to update()

#[Authorize(BookingPolicy::PERMISSION_UPDATE, 'booking')] only works because 'update' is a method on BookingPolicy. Two distinct string universes exist and must never be mixed:

String Universe Where it lives
'view', 'update' Gate ability = policy method name Constant values; #[Authorize] arguments
'booking.bookings.view' Dotted RBAC permission key (e.g. spatie/laravel-permission) Inside method bodies only, via $user->hasPermissionTo(...) (optional)

Method signature convention

The user parameter is ALWAYS the contract type: ?Authenticatable $user (Illuminate\Contracts\Auth\Authenticatable). Never App\Models\User — Policies are Core classes and Core imports no App\ class (→ labrodev-core) — and never the Core mirror User either: the policy asks "who is acting?", which is an auth-contract question, not a persistence one.

  • Class-level abilities (list/create — no bound instance): method takes only ?Authenticatable $user and layers $user !== null (plus optional RBAC) → {Model}Rule::canCreate(...).
  • Instance abilities (update/remove — a bound model): method takes (?Authenticatable $user, {Model} ${model}) and layers non-null user → ownership/scope → {Model}Rule::canUpdate(...) / canRemove(...).

The Policy is where the can-trio is enforced — a request that fails a Rule gate dies here with 403, before the Action runs. Invariants that depend on submitted input (which the gate middleware cannot see) stay in the Action as domain-exception guards → see the labrodev-action skill.

Policy template

Naming pattern: {Model}Policy in Core/Domain/{Domain}/Policies/. Worked example — Booking domain:

<?php

declare(strict_types=1);

namespace Core\Domain\Booking\Policies;

use Core\Domain\Booking\Models\Booking;
use Core\Domain\Booking\Rules\BookingRule;
use Illuminate\Contracts\Auth\Authenticatable;

final class BookingPolicy
{
    public const string PERMISSION_VIEW = 'view';

    public const string PERMISSION_CREATE = 'create';

    public const string PERMISSION_UPDATE = 'update';

    public const string PERMISSION_REMOVE = 'remove';

    public function view(?Authenticatable $user): bool
    {
        return $user !== null;
    }

    public function create(?Authenticatable $user): bool
    {
        return $user !== null
            && BookingRule::canCreate();
    }

    public function update(?Authenticatable $user, Booking $booking): bool
    {
        return $user !== null
            && BookingRule::canUpdate($booking);
    }

    public function remove(?Authenticatable $user, Booking $booking): bool
    {
        return $user !== null
            && BookingRule::canRemove($booking);
    }
}

Two project-specific slots exist and are filled without comments (the no-comments law → labrodev-core): with RBAC, view() becomes $user !== null && $user->hasPermissionTo('booking.bookings.view'); in projects with an ownership model, update()/remove() add the ownership/scope check between the null check and the Rule gate (e.g. $user->organisation_id === $booking->organisation_id).

For the BookingRule class itself (what canCreate/canUpdate/canRemove contain) → see the labrodev-action skill.

Wiring piece 2: #[UsePolicy] on the model

<?php

declare(strict_types=1);

namespace Core\Domain\Booking\Models;

use Core\Domain\Booking\Policies\BookingPolicy;
use Core\Shared\Models\BaseModel;
use Illuminate\Database\Eloquent\Attributes\UsePolicy;

#[UsePolicy(BookingPolicy::class)]
final class Booking extends BaseModel
{
    // ...
}

This attribute is the only policy registration. For everything else about the model (casts(), relations, other attributes) → see the labrodev-model skill.

Wiring piece 3: #[Authorize] on invokable controllers

Two argument forms, matching Gate::authorize semantics:

Form A — ability + Model::class for endpoints without a bound instance (index, create, store):

<?php

declare(strict_types=1);

namespace App\Layer\Dashboard\Booking\Controllers;

use App\Http\Controllers\Controller;
use Core\Domain\Booking\Models\Booking;
use Core\Domain\Booking\Policies\BookingPolicy;
use Illuminate\Routing\Attributes\Controllers\Authorize;

#[Authorize(BookingPolicy::PERMISSION_VIEW, Booking::class)]
final class BookingIndexController extends Controller
{
    // ...
}

Form B — ability + route-parameter name string for route-model-bound endpoints (show, edit, update, delete). The string is the route parameter name, which matches the {booking:uuid} segment in the route definition (UUID binding is the blessed convention):

#[Authorize(BookingPolicy::PERMISSION_UPDATE, 'booking')]
final class BookingUpdateController extends Controller
{
    public function __invoke(
        Booking $booking,
        BookingData $bookingData,
        BookingUpdate $bookingUpdate,
    ): RedirectResponse {
        // ...
    }
}

Route: Route::put('bookings/{booking:uuid}', BookingUpdateController::class)->name('bookings.update');

The attribute runs the gate as controller middleware, before __invoke() — the bound Booking instance is passed to BookingPolicy::update() automatically. For the rest of the controller body (Data injection, Action invocation, Inertia::flash + to_route()) → see the labrodev-controller skill.

Edge cases

Runtime-setup exception. When the subject is only known after runtime setup — e.g. the controller first resolves a ConfigurationSet via a fetcher service, with no route-model binding available — the class-level attribute cannot express the check. Authorize in the method body instead, immediately after the subject is resolved:

use Illuminate\Support\Facades\Gate;

final class ConfigurationSetEditController extends Controller
{
    public function __invoke(ConfigurationSetFetcher $configurationSetFetcher): Response
    {
        $configurationSet = $configurationSetFetcher();

        Gate::authorize(ConfigurationSetPolicy::PERMISSION_UPDATE, $configurationSet);

        // ...
    }
}

This is the only accepted reason to skip #[Authorize]. If the subject is bindable via {model:uuid}, use Form B instead.

Cross-domain policy reuse. A Layer controller in one domain module may authorize against another domain's policy (e.g. an invoice endpoint checking BookingPolicy::PERMISSION_VIEW on a bound booking). This is allowed — policies are Core classes, and App/Layer → Core dependency direction permits it. Do not duplicate the policy in the second domain.

Nullable user. Signatures take ?Authenticatable deliberately: policy methods run for guests too, and each method makes the $user !== null check explicit rather than relying on framework guest-denial magic. Typing the parameter User (concrete model) instead of the contract is the review flag — it breaks the Core dependency law and silently changes guest behavior.

Non-CRUD abilities. Custom endpoints get custom permissions following the same contract: public const string PERMISSION_CANCEL = 'cancel'; with a cancel(?Authenticatable $user, Booking $booking): bool method. Never overload an existing ability with unrelated meaning.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at 4e3053b. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 2 months ago
metadata
{
  "author": "labrodev"
}

README badge

README badge for labrodev/laravel-playbook/labrodev-authorization