[12.x] Add NamedScope attribute

[shaedrich]

Instead of

class User extends Model
{
    public scopeActive(Builder $builder)
    {
        // …
    }
}

you can now write

use Illuminate\Database\Eloquent\Attributes\NamedScope;

class User extends Model
{
    #[NamedScope]
    public active(Builder $builder)
    {
        // …
    }
}

similar to #40022

class User extends Model
{
    public getActiveAttribute()
    {
        // …
    }
}

and

class User extends Model
{
    public active()
    {
        return Attribute::make(
            get: fn() => // …
        );
    }
}

Complements #50034

FAQs

What if I already have a method that has the same name as a scope?

Your application will not be broken because the method does not have the NamedScope attribute, which did not exist before this pull request.

Will the old, multi-method approach of defining local scopes go away?

No. This is just an alternative approach.

[taylorotwell]

Drafting pending for @crynobone - please mark as ready for review once reviewed.

[crynobone]

@shaedrich using public method here means the method can be called directly and it would be common the pass the instance of Illuminate\Database\Eloquent\Builder. IDE with autocomplete would assume the first parameter to be Builder while we usually can pass something else.

[shaedrich]

I can make it private/protected—no problem 👍🏻

[crynobone]

Do you think we need to check if $method return false for incorrect usage such as abstract method or public function?

[shaedrich]

In lines 1638 – 1640, we test if the method exists—isn't that enough, meaning do we care about how the method is implemented?

[crynobone]

Need to also test if child model can utilise attribute named scope defined in parent model.

method need to be updated to protected and contains parameter as example to real usage

[shaedrich]

I'm afraid, I can't follow you? Can you elaborate on that?

[crynobone]

This would be the actual usage, correct?

[shaedrich]

Correct 👍🏻

[crynobone]

Given the following example:

<?php

namespace App\Models;

// use Illuminate\Contracts\Auth\MustVerifyEmail;
use Illuminate\Contracts\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Attributes\NamedScoped;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    /** @use HasFactory<\Database\Factories\UserFactory> */
    use HasFactory, Notifiable;

    /**
     * The attributes that are mass assignable.
     *
     * @var list<string>
     */
    protected $fillable = [
        'name',
        'email',
        'password',
    ];

    /**
     * The attributes that should be hidden for serialization.
     *
     * @var list<string>
     */
    protected $hidden = [
        'password',
        'remember_token',
    ];

    /**
     * Get the attributes that should be cast.
     *
     * @return array<string, string>
     */
    protected function casts(): array
    {
        return [
            'email_verified_at' => 'datetime',
            'password' => 'hashed',
        ];
    }

    #[NamedScoped]
    public function verified(Builder $builder, bool $email = true)
    {
        return $builder->when(
            $email === true,
            fn ($query) => $query->whereNotNull('email_verified_at'),
            fn ($query) => $queryu->whereNull('email_verified_at'),
        );
    }

    public function scopeVerifiedUser(Builder $builder, bool $email = true)
    {
        return $builder->when(
            $email === true,
            fn ($query) => $query->whereNotNull('email_verified_at'),
            fn ($query) => $queryu->whereNull('email_verified_at'),
        );
    }
}

Accessing named scope via query builder:

Accessing named scope statically:

Converting public function verified to protected function verified

[crynobone]

Added failing tests based on above finding

[Bosphoramus]

Wouldnt #[LocalScope] be a better name for the attribute?

[antonkomarev]

#[QueryBuilderScope]

[shaedrich]

Wouldnt #[LocalScope] be a better name for the attribute?

#[QueryBuilderScope]

Yeah, I thought about this, too.

• #[LocalScope]: While this may be the "correct" name to differentiate it from global scopes, this might sound like a variable scope and therefore might be confusing without further context.
• #[QueryBuilderScope]: While this avoids the ambiguity described above, it, in turn, doesn't differentiate between local and global scopes

@taylorotwell @crynobone What do you think?