[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?

[CWAscend]

I like this idea, and appreciate that this is trying to align with the changes to model accessors. I'm wondering if we can more closely align them though - this implementation relies on PHP attributes, whereas the Attribute acccessor doesn't.

Just thinking out loud here, but what about something like this, where Reflection is used to determine the method based on the QueryScope return type, rather than method attributes?

public function verified(bool $email = true): QueryScope
{
    return QueryScope::make(
        query: fn (Builder $query) => $query->when(
            $email,
            fn ($query) => $query->whereNotNull('email_verified_at'),
            fn ($query) => $query->whereNull('email_verified_at'),
        )
    );
}

Not overly fussed either way though, was just my initial thoughts!

[shaedrich]

@CWAscend I actually considered that, however, I felt, this would be more in line with the #[ScopedBy] attribute for global scopes

[taylorotwell]

@shaedrich this is working pretty well for me. If we took the return type approach, I wonder what the return type would actually be and what the user would return?

[shaedrich]

@taylorotwell Thanks for merging! You mean @CWAscend's approach? I assume, QueryScope would work quite similar to Eloquent's Attributes—did you see any problems or challenges that may arise from this? Are you asking because you consider providing yet an alternative approach or just entertaining the idea in general?

[jasonmccreary]

Nice contribution @shaedrich. Going to add this refactor to Shift.

[shaedrich]

Nice, thanks, @jasonmccreary. Lookin forward to it.

[decadence]

Renamed to Scope

[shaedrich]

@decadence Please do not just suggest to rename something that has already been merged with its name. Please instead read the discussion above surrounding the naming as this has already been subject of debate and only reopen the debate if you have reasonable and new arguments for it. Thank you

[decadence]

@shaedrich What are you talking about? I'm not suggesting, I warn future readers. PR name is "Add NamedScope attribute" while real attribute is called Scope now. And there is no mention about it in thread. Except @newtonjob examples.

[shaedrich]

Ah, damn, sorry—Taylor snuck that in, which wasn't obvious from the commit messages 😅 My bad ^^

[shaedrich]

fyi: Another issue just arose with static analysis (thanks to @DarkGhostHunter for reporting it 👍🏻)
https://mastodon.social/@darkghosthunter/114446232883864791

namespace App\Models;

use App\ValueObjects\Item;
use App\ValueObjects\Discount;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Attributes\Scope;

/**
 * @method \Illuminate\Database\Eloquent\Builder<static>|static admins()
 */
class Cart extends Model
{
    #[Scope]
    protected function admins (Builder query)
    {
        $query->where('is_admin', true);
    }
}

Cart::admins()->get();

// Error: Accessing a protected property "admins()" publicly.
// Error: Method "admins" requires the parameter "$query" to be a "...Builder" instance.
// Error: Method "admins" on PHPDoc doesn't match the signature on the class.