Scopes in Eloquent

Wat zijn scopes?

Scopes in Eloquent zijn een mechanisme om querybeperkingen te bundelen en te hergebruiken. Er zijn twee soorten scopes.

Soort	Toepassingsmoment	Toepassing
Globale scopes	Altijd automatisch toegepast	Soft deletes, multitenancy, publicatiefilters
Lokale scopes	Alleen bij expliciete aanroep	Gedeelde filters zoals “populaire posts” of “actieve gebruikers”

Lokale scopes

Definitie

Een lokale scope definieer je door het #[Scope]-attribute op een modelmethode te zetten.

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Attributes\Scope;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    /**
     * Beperken tot gepubliceerde posts
     */
    #[Scope]
    protected function published(Builder $query): void
    {
        $query->where('status', 'published');
    }

    /**
     * Beperken tot populaire posts
     */
    #[Scope]
    protected function popular(Builder $query): void
    {
        $query->where('views', '>', 1000);
    }
}

Het #[Scope]-attribute staat in de namespace Illuminate\Database\Eloquent\Attributes. Het is native syntaxis van PHP 8.0 en later.

Gebruik

Gedefinieerde scopes roep je aan als methodes. Chainen kan ook.

use App\Models\Post;

// Alleen gepubliceerde posts ophalen
$posts = Post::published()->get();

// Gepubliceerde én populaire posts ophalen, nieuwste eerst
$posts = Post::published()->popular()->latest()->get();

Parameters doorgeven

Vanaf het tweede argument van een scopemethode kun je extra parameters definiëren.

#[Scope]
protected function ofStatus(Builder $query, string $status): void
{
    $query->where('status', $status);
}

Bij het aanroepen geef je de argumenten direct door.

$posts = Post::ofStatus('draft')->get();
$posts = Post::ofStatus('published')->get();

Combineren met `orWhere`

Wanneer je scopes met orWhere aan elkaar knoopt, is soms een logische groepering nodig.

// Met een closure (betrouwbaar maar omslachtig)
$users = User::popular()->orWhere(function (Builder $query) {
    $query->active();
})->get();

// Met de higher order methode wordt het simpeler
$users = User::popular()->orWhere->active()->get();

Globale scopes

Werking

Een globale scope is een klasse die de interface Illuminate\Database\Eloquent\Scope implementeert. Deze interface vereist slechts één methode: apply.

// De interfacedefinitie in het framework zelf
// src/Illuminate/Database/Eloquent/Scope.php

interface Scope
{
    public function apply(Builder $builder, Model $model);
}

In de apply-methode voeg je beperkingen toe aan de query builder.

Een globale scopeklasse maken

Genereer een sjabloon met het commando make:scope.

php artisan make:scope ActiveScope

Er wordt een app/Models/Scopes/ActiveScope.php gegenereerd.

<?php

namespace App\Models\Scopes;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;

class ActiveScope implements Scope
{
    /**
     * Past de scope toe op de query builder
     */
    public function apply(Builder $builder, Model $model): void
    {
        $builder->where('is_active', true);
    }
}

Toepassen op een model

Registreren met het #[ScopedBy]-attribute (aanbevolen)

In Laravel 13 is het #[ScopedBy]-attribute het eenvoudigst.

<?php

namespace App\Models;

use App\Models\Scopes\ActiveScope;
use Illuminate\Database\Eloquent\Attributes\ScopedBy;
use Illuminate\Database\Eloquent\Model;

#[ScopedBy([ActiveScope::class])]
class User extends Model
{
    //
}

Meerdere scopes geef je op als array.

#[ScopedBy([ActiveScope::class, TenantScope::class])]
class User extends Model
{
    //
}

Handmatig registreren in de booted()-methode

Je kunt ook de booted-methode overriden en addGlobalScope aanroepen.

<?php

namespace App\Models;

use App\Models\Scopes\ActiveScope;
use Illuminate\Database\Eloquent\Model;

class User extends Model
{
    protected static function booted(): void
    {
        static::addGlobalScope(new ActiveScope);
    }
}

Voeg je een globale scope toe, dan krijgen alle query’s, zoals User::all(), automatisch WHERE is_active = 1.

Globale scopes met anonieme closures

Simpele scopes waarvoor een aparte klasse te veel is, kun je met een closure definiëren.

protected static function booted(): void
{
    static::addGlobalScope('active', function (Builder $builder) {
        $builder->where('is_active', true);
    });
}

Wil je een met een closure gedefinieerde scope later uitsluiten, dan moet je de scopenaam (string) gebruiken in plaats van een klassenaam.

Globale scopes uitsluiten

Soms wil je een scope voor een specifieke query uitschakelen.

use App\Models\Scopes\ActiveScope;

// Een specifieke scope uitsluiten
User::withoutGlobalScope(ActiveScope::class)->get();

// Een met een closure gedefinieerde scope uitsluiten
User::withoutGlobalScope('active')->get();

// Alle globale scopes uitsluiten
User::withoutGlobalScopes()->get();

// Meerdere scopes uitsluiten
User::withoutGlobalScopes([ActiveScope::class, TenantScope::class])->get();

// Alles uitsluiten behalve de opgegeven scopes
User::withoutGlobalScopesExcept([TenantScope::class])->get();

Framework-intern: SoftDeletingScope

Kijk je hoe de standaard SoftDeletes-trait van Laravel globale scopes benut, dan zie je het implementatiepatroon. SoftDeletingScope implementeert de Scope-interface.

// src/Illuminate/Database/Eloquent/SoftDeletingScope.php

class SoftDeletingScope implements Scope
{
    protected $extensions = [
        'Restore', 'RestoreOrCreate', 'CreateOrRestore',
        'WithTrashed', 'WithoutTrashed', 'OnlyTrashed',
    ];

    /**
     * Past de scope toe op de query builder
     * Voegt een beperking toe zodat alleen records met deleted_at = NULL worden opgehaald
     */
    public function apply(Builder $builder, Model $model)
    {
        $builder->whereNull($model->getQualifiedDeletedAtColumn());
    }

    /**
     * Breidt de query builder uit met macro's
     * Hierdoor worden withTrashed() / onlyTrashed() e.d. beschikbaar
     */
    public function extend(Builder $builder)
    {
        foreach ($this->extensions as $extension) {
            $this->{"add{$extension}"}($builder);
        }

        // Overridet de delete()-operatie zodat deleted_at wordt bijgewerkt
        $builder->onDelete(function (Builder $builder) {
            $column = $this->getDeletedAtColumn($builder);
            return $builder->update([
                $column => $builder->getModel()->freshTimestampString(),
            ]);
        });
    }
}

De implementatie van withTrashed() bekijken

withTrashed() roept in werkelijkheid withoutGlobalScope($this) aan. Door de SoftDeletingScope zelf uit te sluiten, worden ook verwijderde records opgehaald.

protected function addWithTrashed(Builder $builder)
{
    $builder->macro('withTrashed', function (Builder $builder, $withTrashed = true) {
        if (! $withTrashed) {
            return $builder->withoutTrashed();
        }

        return $builder->withoutGlobalScope($this);
    });
}

Ook onlyTrashed() sluit de scope zelf uit en voegt daarbovenop whereNotNull('deleted_at') toe.

protected function addOnlyTrashed(Builder $builder)
{
    $builder->macro('onlyTrashed', function (Builder $builder) {
        $model = $builder->getModel();

        $builder->withoutGlobalScope($this)->whereNotNull(
            $model->getQualifiedDeletedAtColumn()
        );

        return $builder;
    });
}

De Scope-interface definieert geen extend-methode, maar de builder van Eloquent roept extend automatisch aan als de scope die methode heeft. Handig wanneer je eigen macro’s wilt toevoegen.

Praktische use cases

Multitenancy: automatisch filteren op tenant-ID

In SaaS-applicaties is het belangrijk om op alle query’s automatisch een filter op tenant-ID toe te passen.

<?php

namespace App\Models\Scopes;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;

class TenantScope implements Scope
{
    public function apply(Builder $builder, Model $model): void
    {
        if ($tenantId = auth()->user()?->tenant_id) {
            $builder->where('tenant_id', $tenantId);
        }
    }
}

use App\Models\Scopes\TenantScope;
use Illuminate\Database\Eloquent\Attributes\ScopedBy;

#[ScopedBy([TenantScope::class])]
class Post extends Model
{
    //
}

Nu geeft alleen al het aanroepen van Post::all() uitsluitend de tenantdata van de ingelogde gebruiker terug.

Openbaar/privé-filter

Voor als je in het beheerpaneel ook niet-gepubliceerde posts wilt tonen, maar in de frontend alleen gepubliceerde.

<?php

namespace App\Models\Scopes;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;

class PublishedScope implements Scope
{
    public function apply(Builder $builder, Model $model): void
    {
        $builder->where('status', 'published')
                ->where('published_at', '<=', now());
    }
}

In het beheerpaneel sluit je de scope uit met withoutGlobalScope.

// Frontend: alleen gepubliceerd (PublishedScope wordt automatisch toegepast)
$posts = Post::latest()->get();

// Beheerpaneel: alle posts tonen
$posts = Post::withoutGlobalScope(PublishedScope::class)->latest()->get();

Gebruik `addSelect` in plaats van `select`

Wil je in een globale scope kolommen toevoegen, gebruik dan addSelect in plaats van select. Met select overschrijf je de kolommen die de aanroepende query al selecteert.

// Slecht voorbeeld: overschrijft de select van de aanroeper
public function apply(Builder $builder, Model $model): void
{
    $builder->select('id', 'tenant_id', 'name');
}

// Goed voorbeeld: voegt toe aan de bestaande select
public function apply(Builder $builder, Model $model): void
{
    $builder->addSelect('tenant_id');
}

Volgende stap

Custom casts van Eloquent

Leer hoe je omzettingslogica voor attributen implementeert als custom cast en het value-objectpatroon toepast.

AI-ontwikkeling

Design patterns

Package-ontwikkeling

Applicatiestructuur

Nieuwe functies in Laravel 13

Eloquent in detail

Validatie-uitbreidingen

Authenticatie uitbreiden

Beveiliging

Queues

Testen

Wat zijn scopes?

Lokale scopes

Definitie

Gebruik

Parameters doorgeven

Combineren met `orWhere`

Globale scopes

Werking

Een globale scopeklasse maken

Toepassen op een model

Globale scopes met anonieme closures

Globale scopes uitsluiten

Framework-intern: SoftDeletingScope

Praktische use cases

Multitenancy: automatisch filteren op tenant-ID

Openbaar/privé-filter

Gebruik `addSelect` in plaats van `select`

Volgende stap

Custom casts van Eloquent

​Wat zijn scopes?

​Lokale scopes

​Definitie

​Gebruik

​Parameters doorgeven

​Combineren met orWhere

​Globale scopes

​Werking

​Een globale scopeklasse maken

​Toepassen op een model

​Globale scopes met anonieme closures

​Globale scopes uitsluiten

​Framework-intern: SoftDeletingScope

​Praktische use cases

​Multitenancy: automatisch filteren op tenant-ID

​Openbaar/privé-filter

​Gebruik addSelect in plaats van select

​Volgende stap

Custom casts van Eloquent

Wat zijn scopes?

Lokale scopes

Definitie

Gebruik

Parameters doorgeven

Combineren met `orWhere`

Globale scopes

Werking

Een globale scopeklasse maken

Toepassen op een model

Globale scopes met anonieme closures

Globale scopes uitsluiten

Framework-intern: SoftDeletingScope

Praktische use cases

Multitenancy: automatisch filteren op tenant-ID

Openbaar/privé-filter

Gebruik `addSelect` in plaats van `select`

Volgende stap