اسکوپ

Scope یا اسکوپ در توسعه نرم‌افزار چند کاربرد دارد. در لاراول الوکوئنت، اسکوپ روشی برای تعریف شرط‌های قابل استفاده مجدد روی کوئری مدل است. در زبان‌های برنامه‌نویسی نیز Scope به محدوده دسترسی به متغیرها و نام‌ها گفته می‌شود. این دو معنی مرتبط‌اند، اما نباید با یکدیگر اشتباه گرفته شوند.

اسکوپ محلی در الوکوئنت لاراول

فرض کنید در فروشگاه فقط محصولاتی را می‌خواهیم که فعال هستند و موجودی مثبت دارند. با اسکوپ، شرط در یک جای مشخص تعریف می‌شود و در گزارش‌ها و کنترلرهای مختلف دوباره استفاده خواهد شد. در نسخه‌های جدید لاراول می‌توان از ویژگی #[Scope] استفاده کرد.

// app/Models/Product.php — Laravel 12/13
use Illuminate\Database\Eloquent\Attributes\Scope;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;

class Product extends Model
{
    #[Scope]
    protected function available(Builder $query): void
    {
        $query->where('is_active', true)->where('stock', '>', 0);
    }
}

$products = Product::available()->orderByDesc('id')->get();

در نسخه‌های قدیمی‌تر لاراول، تعریف public function scopeAvailable(Builder $query) رایج بود. ابتدا نسخه فریم‌ورک را بررسی کنید و سپس Syntax مناسب همان نسخه را انتخاب کنید.

اسکوپ پارامتردار

// Inside the Product model
#[Scope]
protected function minimumPrice(Builder $query, int $amount): void
{
    $query->where('price', '>=', $amount);
}

// In a controller or service
$products = Product::available()->minimumPrice(500_000)->get();

اسکوپ سراسری (Global Scope)

اسکوپ سراسری به‌طور پیش‌فرض روی تمام کوئری‌های مدل اعمال می‌شود. برای مثال در سیستم چندمستاجری می‌توان داده‌ها را براساس شناسه Tenant محدود کرد، اما این محدودیت جایگزین کنترل دسترسی و بررسی امنیتی نیست. حذف Global Scope به‌صورت آگاهانه با withoutGlobalScope() امکان‌پذیر است.

Scope متغیر در زبان‌های دیگر

const price = 100;
if (price > 0) {
  const discount = 10;
  console.log(discount); // 10
}
// discount is not accessible here

def checkout():
    total = 250_000  # local scope
    return total

print(checkout())

اصطلاحات فنی: الوکوئنت، کوئری، کلوژر، میدلور.

مستندات رسمی: اسکوپ‌های Eloquent در لاراول.