Query Scopes در لاراول یکی از ویژگی‌های قدرتمند Eloquent هستند که به شما این امکان را می‌دهند تا کدهای مربوط به پرس‌و‌جوهای تکراری را در مدل‌ها به صورت جداگانه تعریف کنید و سپس از آن‌ها در هر جایی از برنامه استفاده کنید. با استفاده از Query Scopes، می‌توانید شرایط خاصی را به راحتی به کوئری‌ها اضافه کنید.

Query Scopes به دو نوع تقسیم می‌شوند:

1. Global Scopes (حالت سراسری)

2. Local Scopes (حالت محلی)

⚡ Local Scopes (حالت محلی)

Local Scopes به شما این امکان را می‌دهند که متدهای عمومی برای اعمال شرایط خاص به کوئری‌ها در مدل‌ها تعریف کنید. این متدها می‌توانند به راحتی در کوئری‌های Eloquent شما استفاده شوند.

ایجاد یک Local Scope

برای ایجاد یک Local Scope در لاراول، کافی است یک متد در مدل خود ایجاد کنید که معمولاً به صورت scope با نامی که می‌خواهید در کوئری استفاده کنید، نام‌گذاری می‌شود. برای مثال، اگر بخواهید یک scope برای فیلتر کردن کاربران فعال ایجاد کنید، می‌توانید اینگونه عمل کنید:

1. تعریف Local Scope

php
CopyEdit
// در مدل User
class User extends Model
{
    // تعریف یک Local Scope برای فیلتر کردن کاربران فعال
    public function scopeActive($query)
    {
        return $query->where('status', 'active');
    }
}

در اینجا، متد scopeActive به شما این امکان را می‌دهد که کاربران فعال را از کوئری‌های خود فیلتر کنید.

2. استفاده از Local Scope

پس از تعریف scope، می‌توانید از آن در کوئری‌های خود استفاده کنید:

php
CopyEdit
// استفاده از Local Scope در کوئری
$activeUsers = User::active()->get();

در اینجا، با استفاده از User::active()، کوئری فیلتر شده برای دریافت کاربران فعال اجرا می‌شود.

3. چندین Scope به طور همزمان

شما می‌توانید چندین scope را به طور همزمان در یک کوئری استفاده کنید:

php
CopyEdit
// استفاده از چندین Local Scope
$activeUsersInCity = User::active()->where('city', 'New York')->get();

این کوئری کاربران فعال را که در شهر نیویورک هستند، برمی‌گرداند.

⚡ Global Scopes (حالت سراسری)

Global Scopes برای اعمال شرایط به تمامی کوئری‌ها به طور پیش‌فرض استفاده می‌شوند. برای مثال، ممکن است بخواهید یک شرط کلی را به تمام کوئری‌های یک مدل اضافه کنید، مانند فیلتر کردن رکوردهای حذف شده.

ایجاد یک Global Scope

برای ایجاد یک Global Scope، شما باید یک کلاس جدید تعریف کرده و از رابط Scope لاراول استفاده کنید.

1. تعریف Global Scope

ابتدا باید یک کلاس برای scope خود بسازید. به عنوان مثال، اگر بخواهید رکوردهای حذف شده را همیشه فیلتر کنید، می‌توانید یک scope به این صورت تعریف کنید:

php
CopyEdit
// در app/Scopes/ActiveScope.php
namespace App\Scopes;

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

class ActiveScope implements Scope
{
    public function apply(Builder $builder, Model $model)
    {
        $builder->where('status', 'active');
    }
}

2. استفاده از Global Scope در مدل

پس از تعریف scope، شما باید آن را در مدل خود ثبت کنید تا به تمامی کوئری‌ها اعمال شود.

php
CopyEdit
// در مدل User
use App\Scopes\ActiveScope;

class User extends Model
{
    // ثبت Global Scope در مدل
    protected static function booted()
    {
        parent::booted();

        static::addGlobalScope(new ActiveScope);
    }
}

در اینجا، ActiveScope به‌طور خودکار به تمام کوئری‌های User اعمال می‌شود.

3. حذف Global Scope

اگر بخواهید در یک کوئری خاص، scope را حذف کنید، می‌توانید از متد withoutGlobalScope() استفاده کنید:

php
CopyEdit
// حذف Global Scope برای یک کوئری خاص
$allUsers = User::withoutGlobalScope(ActiveScope::class)->get();

⚡ Query Scopes در عمل

1. استفاده از Local Scope در یک پروژه

فرض کنید که یک مدل Post دارید و می‌خواهید مقالات منتشر شده را فیلتر کنید. ابتدا یک Local Scope به نام scopePublished ایجاد می‌کنید:

php
CopyEdit
// در مدل Post
public function scopePublished($query)
{
    return $query->where('status', 'published');
}

سپس، می‌توانید از این scope در هر جایی از پروژه خود استفاده کنید:

php
CopyEdit
$publishedPosts = Post::published()->get();

2. استفاده از Global Scope در یک پروژه

فرض کنید که می‌خواهید به طور پیش‌فرض همه‌ی رکوردها را فیلتر کنید که حذف شده نباشند (مثلاً فیلتر کردن رکوردهای با ستون deleted_at).

اول، یک کلاس Global Scope به نام NonDeletedScope می‌سازید:

php
CopyEdit
// در app/Scopes/NonDeletedScope.php
namespace App\Scopes;

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

class NonDeletedScope implements Scope
{
    public function apply(Builder $builder, Model $model)
    {
        $builder->whereNull('deleted_at');
    }
}

سپس در مدل Post آن را ثبت می‌کنید:

php
CopyEdit
// در مدل Post
use App\Scopes\NonDeletedScope;

class Post extends Model
{
    protected static function booted()
    {
        parent::booted();

        static::addGlobalScope(new NonDeletedScope);
    }
}

حالا، همه‌ی کوئری‌هایی که برای مدل Post اجرا می‌کنید، به‌طور خودکار رکوردهای حذف شده را فیلتر می‌کنند.

📋 جمع‌بندی

1. Local Scopes: متدهایی هستند که می‌توانند به‌طور انتخابی به کوئری‌ها اضافه شوند.

   • تعریف می‌شوند با استفاده از متد scope{ScopeName} در مدل.

   • می‌توانید از آن‌ها به راحتی در کوئری‌های خود استفاده کنید.

2. Global Scopes: شرایطی هستند که به تمامی کوئری‌ها به‌طور پیش‌فرض اعمال می‌شوند.

   • تعریف می‌شوند با استفاده از یک کلاس جداگانه و پیاده‌سازی رابط Scope.

   • برای ثبت آن‌ها باید از متد addGlobalScope() استفاده کنید.

3. حذف Global Scopes: می‌توانید از متد withoutGlobalScope() برای حذف scope در کوئری‌های خاص استفاده کنید.

Query Scopes در لاراول ابزار قدرتمندی برای مدیریت کوئری‌های پیچیده هستند و می‌توانند به شما کمک کنند که کدهای خود را تمیزتر، قابل نگهداری‌تر و مقیاس‌پذیرتر بنویسید.