در لاراول ۱۳، استفاده از قابلیت اتریبیوتهای PHP به شکل گستردهتری دنبال شده است.
ویژگیهایی مانند $fillable، $guarded و $hidden که سالها در مدلهای الوکوئنت تعریف میکردیم، اکنون میتوانند بهصورت اتریبیوتهای سطح کلاس (Class-Level Attributes) نیز تعریف شوند:
#[Fillable]#[Guarded]#[Hidden]
این رویکرد به تنظیمات مربوط به Jobها، سیگنچر کامندهای کنسول (Console Commands)، میدلورها (Middleware) و بخشهای دیگری از فریمورک نیز گسترش پیدا کرده است.
در این مقاله، تمام اتریبیوتهای PHP قابلاستفاده در لاراول ۱۳ را بررسی میکنیم، هم اتریبیوتهایی که در این نسخه معرفی شدهاند و هم مواردی که از نسخههای قبلی در دسترس بودهاند. برای هرکدام نیز مثالهای کاربردی ارائه خواهیم کرد.
نکته مهم
استفاده از این اتریبیوتها اجباری نیست و در تمام موارد همچنان میتوانید از روش قدیمی استفاده کنید. این تغییرات باعث ناسازگاری با کدهای قبلی (Breaking Changes) نمیشوند، بلکه صرفاً روشهای جایگزین و جدیدتری برای تعریف تنظیمات در اختیار توسعهدهندگان قرار میدهند.
بخش اول: اتریبیوتهای معرفیشده در لاراول ۱۳
۱. اتریبیوتهای مدل الوکوئنت
این اتریبیوتها امکان جایگزینی پراپرتیهای آشنایی را فراهم میکنند که سالها در مدلهای الوکوئنت تعریف میکردیم.
البته همانطور که گفته شد، استفاده از این روش کاملاً اختیاری است.
۱. #[Fillable] — تعریف فیلدهای مجاز برای انتساب انبوه (Mass Assignment)
با استفاده از این اتریبیوت میتوان مشخص کرد کدام فیلدهای مدل اجازه دارند از طریق قابلیت Mass Assignment مقداردهی شوند.
روش قبلی:
class Post extends Model
{
protected $fillable = ['title', 'body', 'status'];
}
روش جدید با Attribute:
use Illuminate\Database\Eloquent\Attributes\Fillable;
#[Fillable(['title', 'body', 'status'])]
class Post extends Model
{
}
در این مثال، فیلدهای title، body و status برای Mass Assignment مجاز هستند.
۲. #[Guarded] — تعریف فیلدهای محافظتشده
با استفاده از این اتریبیوت مشخص میکنیم کدام فیلدهای مدل نباید از طریق Mass Assignment مقداردهی شوند.
روش قبلی:
class User extends Model
{
protected $guarded = ['id', 'is_admin'];
}
روش جدید:
use Illuminate\Database\Eloquent\Attributes\Guarded;
#[Guarded(['id', 'is_admin'])]
class User extends Model
{
}
در این مثال، فیلدهای id و is_admin در برابر Mass Assignment محافظت میشوند.
۳. #[Unguarded] — غیرفعالکردن محافظت Mass Assignment
این اتریبیوت از نوع نشانگر (Marker Attribute) است و نیازی به دریافت پارامتر ندارد.
با استفاده از آن، محافظت Mass Assignment برای مدل غیرفعال میشود.
روش قبلی:
class Setting extends Model
{
protected $guarded = [];
}
روش جدید:
use Illuminate\Database\Eloquent\Attributes\Unguarded;
#[Unguarded]
class Setting extends Model
{
}
۴. #[Hidden] — مخفیکردن فیلدها هنگام سریالسازی (Serialization)
این اتریبیوت مشخص میکند کدام فیلدهای مدل هنگام تبدیل مدل به آرایه یا JSON نمایش داده نشوند.
برای مثال، معمولاً اطلاعات حساسی مانند رمز عبور و توکن یادآوری ورود نباید در خروجی API نمایش داده شوند.
روش قبلی:
class User extends Model
{
protected $hidden = ['password', 'remember_token'];
}
روش جدید:
use Illuminate\Database\Eloquent\Attributes\Hidden;
#[Hidden(['password', 'remember_token'])]
class User extends Model
{
}
۵. #[Visible] — تعریف صریح فیلدهای قابلنمایش
این اتریبیوت برخلاف Hidden مشخص میکند کدام فیلدها اجازه دارند هنگام سریالسازی (سریالیزیشن یا Serialization) مدل نمایش داده شوند.
روش قبلی:
class User extends Model
{
protected $visible = ['id', 'name', 'email'];
}
روش جدید:
use Illuminate\Database\Eloquent\Attributes\Visible;
#[Visible(['id', 'name', 'email'])]
class User extends Model
{
}
در این مثال، فقط فیلدهای id، name و email در خروجی سریالسازی مدل قابلمشاهده خواهند بود.
۶. #[Appends] — اضافهکردن خودکار Accessorها به خروجی JSON
با استفاده از این اتریبیوت میتوان مشخص کرد کدام Accessorها بهصورت خودکار به خروجی آرایه یا JSON مدل اضافه شوند.
روش قبلی:
class User extends Model
{
protected $appends = ['full_name', 'is_active'];
public function getFullNameAttribute(): string
{
return $this->first_name.' '.$this->last_name;
}
}
روش جدید:
use Illuminate\Database\Eloquent\Attributes\Appends;
#[Appends(['full_name', 'is_active'])]
class User extends Model
{
public function getFullNameAttribute(): string
{
return $this->first_name.' '.$this->last_name;
}
}
در این مثال، مقادیر full_name و is_active بهصورت خودکار به خروجی مدل اضافه میشوند.
۷. #[Table] — تنظیم نام جدول و پیکربندی کلید اصلی
این اتریبیوت کاربردیتر از موارد قبلی است،زیرا میتواند چندین پراپرتی مدل را بهصورت همزمان جایگزین کند.
از جمله:
$table: نام جدول دیتابیس$primaryKey: نام کلید اصلی$keyType: نوع کلید اصلی$incrementing: مشخصکردن خودکارافزایشیبودن کلید$timestamps: فعال یا غیرفعالکردن Timestampها$dateFormat: قالب ذخیرهسازی تاریخ
روش قبلی:
class Post extends Model
{
protected $table = 'blog_posts';
protected $primaryKey = 'post_id';
}
روش جدید:
use Illuminate\Database\Eloquent\Attributes\Table;
#[Table('blog_posts', key: 'post_id')]
class Post extends Model
{
}
استفاده از تمام گزینهها:
class ExternalOrder extends Model
{
protected $table = 'external_orders';
protected $primaryKey = 'uuid';
protected $keyType = 'string';
public $incrementing = false;
public $timestamps = false;
}
معادل آن با استفاده از Attribute:
#[Table(
name: 'external_orders',
key: 'uuid',
keyType: 'string',
incrementing: false,
timestamps: false,
)]
class ExternalOrder extends Model
{
}
همانطور که مشاهده میکنید، تنظیمات مختلف مدل را میتوان در یک اتریبیوت متمرکز کرد.
۸. #[Connection] — تعیین اتصال دیتابیس مدل
با استفاده از این اتریبیوت میتوان مشخص کرد یک مدل باید از کدام اتصال دیتابیس استفاده کند.
روش قبلی:
class PageView extends Model
{
protected $connection = 'analytics';
}
روش جدید:
use Illuminate\Database\Eloquent\Attributes\Connection;
#[Connection('analytics')]
class PageView extends Model
{
}
در این مثال، مدل PageView از اتصال دیتابیسی با نام analytics استفاده میکند.
۹. #[Touches] — بهروزرسانی Timestamp مدل والد
در الوکوئنت قابلیتی به نام Touch وجود دارد که با استفاده از آن میتوان هنگام تغییر یک مدل، مقدار updated_at مدل مرتبط با آن را نیز بهروزرسانی کرد.
روش قبلی:
class Comment extends Model
{
protected $touches = ['post'];
public function post(): BelongsTo
{
return $this->belongsTo(Post::class);
}
}
روش جدید:
use Illuminate\Database\Eloquent\Attributes\Touches;
#[Touches(['post'])]
class Comment extends Model
{
public function post(): BelongsTo
{
return $this->belongsTo(Post::class);
}
}
در این مثال، هر زمان که یک Comment تغییر کند، Timestamp مدل Post مرتبط با آن نیز بهروزرسانی خواهد شد.
۲. اتریبیوتهای Queue و Job
با استفاده از این اتریبیوتها میتوان تنظیمات Jobها را بهصورت اعلانی (Declarative) تعریف کرد، بهجای اینکه برای هر تنظیم، یک پراپرتی جداگانه داخل کلاس ایجاد کنیم.
۱۰. #[Tries] — تعیین حداکثر تعداد تلاش برای اجرای Job
این اتریبیوت حداکثر تعداد دفعاتی را مشخص میکند که سیستم صف اجازه دارد یک Job را اجرا کند.
روش قبلی:
class ProcessPayment implements ShouldQueue
{
public $tries = 3;
}
روش جدید:
use Illuminate\Queue\Attributes\Tries;
#[Tries(3)]
class ProcessPayment implements ShouldQueue
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
}
در این مثال، Job حداکثر سه بار برای اجرا تلاش خواهد کرد.
۱۱. #[Timeout] — تعیین محدودیت زمانی اجرای Job
با استفاده از این اتریبیوت میتوان حداکثر زمان مجاز برای اجرای یک Job را تعیین کرد.
روش قبلی:
class GenerateReport implements ShouldQueue
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
public $timeout = 120;
}
روش جدید:
use Illuminate\Queue\Attributes\Timeout;
#[Timeout(120)]
class GenerateReport implements ShouldQueue
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
}
در این مثال، Job حداکثر ۱۲۰ ثانیه فرصت اجرا دارد.
۱۲. #[Backoff] — تعیین فاصله زمانی بین تلاشهای مجدد
این اتریبیوت مشخص میکند در صورت شکست اجرای Job، سیستم چه مدت باید قبل از تلاش مجدد منتظر بماند.
روش قبلی:
class SyncInventory implements ShouldQueue
{
public $backoff = 30;
// یا برای Backoff نمایی:
// public $backoff = [10, 30, 60];
}
روش جدید:
تعیین فاصله زمانی ثابت:
use Illuminate\Queue\Attributes\Backoff;
#[Backoff(30)]
class SyncInventory implements ShouldQueue
{
}
تعیین فاصله زمانی متفاوت برای تلاشهای مجدد:
#[Backoff([10, 30, 60])]
class SyncInventory implements ShouldQueue
{
}
در مثال دوم، فاصله زمانی تلاشهای مجدد بهترتیب ۱۰، ۳۰ و ۶۰ ثانیه خواهد بود.
۱۳. #[MaxExceptions] — تعیین حداکثر تعداد Exceptionهای مجاز
این اتریبیوت مشخص میکند یک Job قبل از اینکه ناموفق (Failed) در نظر گرفته شود، حداکثر چند Exception میتواند ایجاد کند.
روش قبلی:
class ImportCsvRows implements ShouldQueue
{
public $maxExceptions = 3;
}
روش جدید:
use Illuminate\Queue\Attributes\MaxExceptions;
#[MaxExceptions(3)]
class ImportCsvRows implements ShouldQueue
{
}
در این مثال، حداکثر سه Exception برای این Job مجاز خواهد بود.
۱۴. #[Queue] — تعیین نام صف اجرای Job
با استفاده از این اتریبیوت میتوان مشخص کرد یک Job در کدام صف اجرا شود.
روش قبلی:
class SendWelcomeEmail implements ShouldQueue
{
public $queue = 'high';
}
روش جدید:
use Illuminate\Queue\Attributes\Queue;
#[Queue('high')]
class SendWelcomeEmail implements ShouldQueue
{
}
در این مثال، Job در صفی با نام high قرار میگیرد.
۱۵. #[Connection] — تعیین اتصال صف
این اتریبیوت مشخص میکند Job باید از کدام اتصال Queue استفاده کند.
روش قبلی:
class ProcessWebhook implements ShouldQueue
{
public $connection = 'redis';
}
روش جدید:
use Illuminate\Queue\Attributes\Connection;
#[Connection('redis')]
class ProcessWebhook implements ShouldQueue
{
}
در این مثال، اتصال Redis برای اجرای Job استفاده خواهد شد.
۱۶. #[UniqueFor] — تعیین مدت اعتبار قفل Job یکتا
در لاراول میتوان با استفاده از قابلیت Unique Job از اجرای همزمان Jobهای تکراری جلوگیری کرد.
این اتریبیوت مدت زمانی را مشخص میکند که قفل یکتایی Job باید معتبر باقی بماند.
روش قبلی:
class RebuildSearchIndex implements ShouldQueue, ShouldBeUnique
{
public $uniqueFor = 3600;
}
روش جدید:
use Illuminate\Queue\Attributes\UniqueFor;
use Illuminate\Contracts\Queue\ShouldBeUnique;
#[UniqueFor(3600)]
class RebuildSearchIndex implements ShouldQueue, ShouldBeUnique
{
}
در این مثال، قفل یکتایی Job به مدت ۳۶۰۰ ثانیه، یعنی یک ساعت، معتبر خواهد بود.
۱۷. #[FailOnTimeout] — شکست Job بهجای تلاش مجدد در صورت Timeout
این اتریبیوت مشخص میکند اگر اجرای Job به دلیل عبور از محدودیت زمانی متوقف شد، Job مستقیماً Failed شود و دوباره برای اجرای آن تلاش نشود.
روش قبلی:
class CallExternalApi implements ShouldQueue
{
public $failOnTimeout = true;
}
روش جدید:
use Illuminate\Queue\Attributes\FailOnTimeout;
#[FailOnTimeout]
class CallExternalApi implements ShouldQueue
{
}
ترکیب چند Attribute در یک Job
یکی از مزیتهای این روش، امکان ترکیب چند اتریبیوت برای پیکربندی کامل یک Job است.
برای مثال:
use Illuminate\Queue\Attributes\{Connection, Queue, Tries, Timeout, Backoff};
#[Connection('redis')]
#[Queue('high')]
#[Tries(3)]
#[Timeout(60)]
#[Backoff([5, 15, 30])]
class ProcessPayment implements ShouldQueue
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
}
در این مثال:
- اتصال اجرای Job برابر Redis است.
- Job در صف high قرار میگیرد.
- حداکثر سه بار برای اجرای آن تلاش میشود.
- حداکثر زمان اجرای آن ۶۰ ثانیه است.
- فاصله تلاشهای مجدد بهترتیب ۵، ۱۵ و ۳۰ ثانیه خواهد بود.
۳. اتریبیوتهای کامندهای کنسول (Console Command Attributes)
با استفاده از این اتریبیوتها میتوان دستورات آرتیسان را بدون تعریف پراپرتیهای $signature، $description و $help پیادهسازی کرد.
۱۸. #[Signature] — تعریف سیگنچر کامند آرتیسان
این اتریبیوت برای تعریف نام کامند، آرگومانها و آپشنهای آن استفاده میشود.
روش قبلی:
class PruneUsers extends Command
{
protected $signature = 'users:prune {--days=30 : Days of inactivity}';
protected $description = 'Prune inactive user accounts';
}
روش جدید:
use Illuminate\Console\Attributes\Signature;
use Illuminate\Console\Attributes\Description;
#[Signature('users:prune {--days=30 : Days of inactivity}')]
#[Description('Prune inactive user accounts')]
class PruneUsers extends Command
{
public function handle(): void
{
$days = $this->option('days');
// ...
}
}
اتریبیوت Signature امکان تعریف نامهای مستعار (Aliases) را نیز فراهم میکند.
برای مثال:
#[Signature('cache:warm', aliases: ['warm-cache'])]
class WarmCache extends Command
{
}
در این مثال، دستور cache:warm با نام مستعار warm-cache نیز قابل اجرا خواهد بود.
۱۹. #[Description] — تعریف توضیحات کامند
با استفاده از این اتریبیوت میتوان توضیحاتی برای یک کامند آرتیسان تعریف کرد.
روش قبلی:
class SendMarketingEmails extends Command
{
protected $description = 'Send scheduled marketing emails';
}
روش جدید:
use Illuminate\Console\Attributes\Description;
#[Description('Send scheduled marketing emails')]
class SendMarketingEmails extends Command
{
}
۲۰. #[Help] — تعریف متن راهنمای کامند
این اتریبیوت برای تعریف توضیحات تکمیلی و راهنمای استفاده از یک کامند کنسول کاربرد دارد.
روش قبلی:
class ProcessOrders extends Command
{
protected $help = 'This command processes all pending orders and sends confirmation emails. Run during off-peak hours.';
}
روش جدید:
use Illuminate\Console\Attributes\Help;
#[Help('This command processes all pending orders and sends confirmation emails. Run during off-peak hours.')]
class ProcessOrders extends Command
{
}
۲۱. #[Hidden] — مخفیکردن کامند از فهرست کامندها
با استفاده از این اتریبیوت میتوان یک کامند آرتیسان را از فهرست کامندهای قابلمشاهده مخفی کرد.
روش قبلی:
class DebugInternals extends Command
{
protected $hidden = true;
}
روش جدید:
use Illuminate\Console\Attributes\Hidden;
#[Hidden]
class DebugInternals extends Command
{
}
۲۲. #[Usage] — تعریف مثالهای استفاده از کامند
این اتریبیوت برای نمایش نمونههای مختلف استفاده از یک کامند کاربرد دارد.
یکی از ویژگیهای آن این است که میتوان چندین بار از آن در یک کلاس استفاده کرد (Repeatable Attribute).
روش قبلی:
class PruneUsers extends Command
{
protected $help = <<<'HELP'
Usage examples:
users:prune --days=60
users:prune --days=30 --dry-run
HELP;
}
روش جدید:
use Illuminate\Console\Attributes\Usage;
#[Usage('users:prune --days=60')]
#[Usage('users:prune --days=30 --dry-run')]
class PruneUsers extends Command
{
}
۴. اتریبیوتهای Routing و Controller
۲۳. #[Middleware] — اختصاص میدلور به کنترلر
با استفاده از این اتریبیوت میتوان میدلورها را در سطح کلاس، متد یا هر دو تعریف کرد.
این اتریبیوت از نوع Repeatable است، یعنی امکان استفاده چندباره از آن وجود دارد.
روش قبلی:
class DashboardController extends Controller
{
public function __construct()
{
$this->middleware(['auth', 'verified']);
}
public function index()
{
return view('dashboard');
}
}
روش جدید:
use Illuminate\Routing\Attributes\Controllers\Middleware;
#[Middleware('auth')]
#[Middleware('verified')]
class DashboardController extends Controller
{
public function index()
{
return view('dashboard');
}
}
همچنین میتوان میدلور را فقط برای متدهای مشخصی اعمال کرد.
برای این کار از پارامترهای only و except استفاده میکنیم.
#[Middleware('auth')]
#[Middleware('admin', only: ['destroy'])]
#[Middleware('throttle:60,1', except: ['index', 'show'])]
class PostController extends Controller
{
// ...
}
در این مثال:
- میدلور مربوط به
authبرای تمام متدهای کنترلر اعمال میشود. - میدلور مربوط به
adminفقط برای متدdestroyاجرا میشود. - میدلور مربوط به
throttle:60,1بهجز متدهایindexوshowروی سایر متدها اعمال خواهد شد.
همچنین میتوان میدلور را مستقیماً روی یک متد مشخص تعریف کرد.
class ReportController extends Controller
{
#[Middleware('cache.headers:public;max_age=3600')]
public function show(Report $report)
{
return view('reports.show', compact('report'));
}
}
۲۴. #[Authorize] — اعمال مجوز دسترسی در کنترلر
این اتریبیوت امکان تعریف مجوزهای دسترسی (Authorization) را در سطح کنترلر یا متد فراهم میکند.
روش قبلی:
class PostController extends Controller
{
public function __construct()
{
$this->authorizeResource(Post::class, 'post');
}
public function edit(Post $post)
{
return view('posts.edit', compact('post'));
}
}
روش جدید:
use Illuminate\Routing\Attributes\Controllers\Authorize;
#[Authorize('viewAny', Post::class)]
class PostController extends Controller
{
#[Authorize('update', Post::class)]
public function edit(Post $post)
{
return view('posts.edit', compact('post'));
}
}
همچنین میتوان مجوز دسترسی را فقط برای متدهای مشخصی تعریف کرد.
#[Authorize('manage-users', only: ['edit', 'update', 'destroy'])]
class UserController extends Controller
{
}
در این مثال، مجوز manage-users فقط برای متدهای edit، update و destroy بررسی میشود.
۵. اتریبیوتهای Form Request
۲۵. #[ErrorBag] — تعیین نام Error Bag
لاراول برای نگهداری خطاهای اعتبارسنجی از ساختاری به نام Error Bag استفاده میکند.
با این اتریبیوت میتوان نام مشخصی برای مجموعه خطاهای یک Form Request تعیین کرد.
روش قبلی:
class CreatePostRequest extends FormRequest
{
protected $errorBag = 'createPost';
}
روش جدید:
use Illuminate\Foundation\Http\Attributes\ErrorBag;
#[ErrorBag('createPost')]
class CreatePostRequest extends FormRequest
{
public function rules(): array
{
return ['title' => 'required|max:255'];
}
}
۲۶. #[RedirectTo] — تعیین آدرس انتقال در صورت شکست اعتبارسنجی
با استفاده از این اتریبیوت میتوان مشخص کرد در صورت ناموفقبودن اعتبارسنجی، کاربر به چه آدرسی هدایت شود.
روش قبلی:
class StorePostRequest extends FormRequest
{
protected $redirect = '/posts/create';
public function rules(): array
{
return ['title' => 'required'];
}
}
روش جدید:
use Illuminate\Foundation\Http\Attributes\RedirectTo;
#[RedirectTo('/posts/create')]
class StorePostRequest extends FormRequest
{
public function rules(): array
{
return ['title' => 'required'];
}
}
۲۷. #[RedirectToRoute] — انتقال به یک Route نامگذاریشده در صورت شکست اعتبارسنجی
این اتریبیوت مشابه مورد قبلی است، با این تفاوت که بهجای آدرس مستقیم، نام یک Route را برای انتقال کاربر مشخص میکنیم.
روش قبلی:
class StorePostRequest extends FormRequest
{
protected $redirectRoute = 'posts.create';
public function rules(): array
{
return ['title' => 'required'];
}
}
روش جدید:
use Illuminate\Foundation\Http\Attributes\RedirectToRoute;
#[RedirectToRoute('posts.create')]
class StorePostRequest extends FormRequest
{
public function rules(): array
{
return ['title' => 'required'];
}
}
۲۸. #[StopOnFirstFailure] — توقف اعتبارسنجی پس از اولین خطا
بهصورت پیشفرض، لاراول میتواند اعتبارسنجی را ادامه دهد و تمام خطاهای مربوط به فیلدهای مختلف را جمعآوری کند.
با استفاده از این اتریبیوت میتوان تعیین کرد که در صورت مشاهده اولین خطای اعتبارسنجی، فرآیند بررسی متوقف شود.
روش قبلی:
class ImportRequest extends FormRequest
{
protected $stopOnFirstFailure = true;
public function rules(): array
{
return [
'file' => 'required|file|mimes:csv',
'mapping' => 'required|array',
];
}
}
روش جدید:
use Illuminate\Foundation\Http\Attributes\StopOnFirstFailure;
#[StopOnFirstFailure]
class ImportRequest extends FormRequest
{
public function rules(): array
{
return [
'file' => 'required|file|mimes:csv',
'mapping' => 'required|array',
];
}
}
۶. اتریبیوتهای HTTP Resource
۲۹. #[Collects] — تعیین نوع Resource در مجموعه
با استفاده از این اتریبیوت میتوان مشخص کرد یک Resource Collection از چه نوع ریسورسی برای تبدیل دادهها استفاده کند.
روش قبلی:
class PostCollection extends ResourceCollection
{
public $collects = PostResource::class;
}
روش جدید:
use Illuminate\Http\Resources\Attributes\Collects;
#[Collects(PostResource::class)]
class PostCollection extends ResourceCollection
{
}
۳۰. #[PreserveKeys] — حفظ کلیدهای آرایه در Collection
بهصورت پیشفرض ممکن است هنگام تبدیل Collection به خروجی JSON، کلیدهای اصلی آرایه حفظ نشوند.
با استفاده از این اتریبیوت میتوان مشخص کرد کلیدهای اصلی آرایه در خروجی نیز حفظ شوند.
روش قبلی:
class CountryResource extends JsonResource
{
public $preserveKeys = true;
public function toArray(Request $request): array
{
return [
'code' => $this->code,
'name' => $this->name,
];
}
}
روش جدید:
use Illuminate\Http\Resources\Attributes\PreserveKeys;
#[PreserveKeys]
class CountryResource extends JsonResource
{
public function toArray(Request $request): array
{
return [
'code' => $this->code,
'name' => $this->name,
];
}
}
۷. اتریبیوتهای Factory
۳۱. #[UseModel] — اتصال Factory به یک مدل
با استفاده از این اتریبیوت میتوان مشخص کرد یک فکتوری برای تولید دادههای آزمایشی مربوط به کدام مدل استفاده میشود.
روش قبلی:
class PostFactory extends Factory
{
protected $model = Post::class;
public function definition(): array
{
return [
'title' => fake()->sentence(),
'body' => fake()->paragraphs(3, true),
];
}
}
روش جدید:
use Illuminate\Database\Eloquent\Factories\Attributes\UseModel;
#[UseModel(Post::class)]
class PostFactory extends Factory
{
public function definition(): array
{
return [
'title' => fake()->sentence(),
'body' => fake()->paragraphs(3, true),
];
}
}
در این مثال، فکتوری به مدل Post متصل شده است.
۸. اتریبیوتهای Testing
۳۲. #[Seed] — اجرای Seeder پیشفرض برای یک کلاس تست
با استفاده از این اتریبیوت میتوان مشخص کرد که قبل از اجرای تستهای یک کلاس، سیدر پیشفرض دیتابیس اجرا شود.
روش قبلی:
class ProductPageTest extends TestCase
{
protected $seed = true;
public function test_products_page_shows_seeded_data(): void
{
$this->get('/products')->assertOk();
}
}
روش جدید:
use Illuminate\Foundation\Testing\Attributes\Seed;
#[Seed]
class ProductPageTest extends TestCase
{
public function test_products_page_shows_seeded_data(): void
{
$this->get('/products')->assertOk();
}
}
۳۳. #[Seeder] — اجرای یک Seeder مشخص
این اتریبیوت مشابه مورد قبلی است، اما بهجای اجرای سیدر پیشفرض، امکان تعیین یک سیدر مشخص را فراهم میکند.
روش قبلی:
class AdminAccessTest extends TestCase
{
protected $seeder = RoleAndPermissionSeeder::class;
public function test_admin_can_access_dashboard(): void
{
$admin = User::factory()->admin()->create();
$this->actingAs($admin)->get('/admin')->assertOk();
}
}
روش جدید:
use Illuminate\Foundation\Testing\Attributes\Seeder;
#[Seeder(RoleAndPermissionSeeder::class)]
class AdminAccessTest extends TestCase
{
public function test_admin_can_access_dashboard(): void
{
$admin = User::factory()->admin()->create();
$this->actingAs($admin)->get('/admin')->assertOk();
}
}
۳۴. #[SetUp] — مشخصکردن متد راهاندازی تست
در تستهای PHPUnit و لاراول معمولاً از متد setUp() برای آمادهسازی شرایط اولیه تست استفاده میکنیم.
با استفاده از این اتریبیوت میتوان یک متد را بهعنوان Hook مربوط به راهاندازی تست معرفی کرد، بنابراین دیگر محدود به نام متد setUp() نیستیم.
روش قبلی:
class OrderTest extends TestCase
{
private User $user;
protected function setUp(): void
{
parent::setUp();
$this->user = User::factory()->create();
}
public function test_user_can_place_order(): void
{
$this->actingAs($this->user)
->post('/orders', ['product_id' => 1])
->assertCreated();
}
}
روش جدید:
use Illuminate\Foundation\Testing\Attributes\SetUp;
class OrderTest extends TestCase
{
private User $user;
#[SetUp]
public function createUser(): void
{
$this->user = User::factory()->create();
}
public function test_user_can_place_order(): void
{
$this->actingAs($this->user)
->post('/orders', ['product_id' => 1])
->assertCreated();
}
}
در این مثال، متد createUser با استفاده از #[SetUp] بهعنوان متد راهاندازی تست شناخته میشود.
۳۵. #[TearDown] — مشخصکردن متد پاکسازی پس از تست
این اتریبیوت برای معرفی متدی استفاده میشود که پس از اجرای تست باید فراخوانی شود.
به کمک آن میتوان عملیات پاکسازی منابع، حذف دادههای موقت و آزادسازی منابع استفادهشده را انجام داد.
روش قبلی:
class ExternalApiTest extends TestCase
{
protected function tearDown(): void
{
Cache::tags('external-api')->flush();
parent::tearDown();
}
}
روش جدید:
use Illuminate\Foundation\Testing\Attributes\TearDown;
class ExternalApiTest extends TestCase
{
#[TearDown]
public function clearApiCache(): void
{
Cache::tags('external-api')->flush();
}
}
در این مثال، متد clearApiCache پس از اجرای تستها فراخوانی میشود.
بخش دوم: اتریبیوتهایی که پیش از لاراول ۱۳ وجود داشتند
تمام اتریبیوتهایی که در این بخش معرفی میکنیم، از نسخههای ۱۱ و ۱۲ لاراول در دسترس بودهاند و در لاراول ۱۳ نیز همچنان قابلاستفاده هستند.
۱. اتریبیوتهای قبلی الوکوئنت
#[ObservedBy] — اتصال Observer به مدل
با استفاده از این اتریبیوت میتوان یک آبزرورِ مدل را به مدل متصل کرد.
آبزرورها برای مدیریت رویدادهای مختلف چرخه حیات مدل (Model Lifecycle Events) مانند ایجاد، بهروزرسانی یا حذف رکوردها استفاده میشوند.
use Illuminate\Database\Eloquent\Attributes\ObservedBy;
#[ObservedBy(PostObserver::class)]
class Post extends Model
{
}
#[ScopedBy] — اعمال Global Scope
این اتریبیوت امکان اعمال اسکوپ گلوبال را روی یک مدل فراهم میکند.
اسکوپهای گلوبال شرطهایی هستند که بهصورت خودکار روی کوئریهای مربوط به یک مدل اعمال میشوند.
use Illuminate\Database\Eloquent\Attributes\ScopedBy;
#[ScopedBy(ActiveScope::class)]
class Subscription extends Model
{
}
#[CollectedBy] — استفاده از Collection سفارشی
با استفاده از این اتریبیوت میتوان نوع کالکشن مورد استفاده برای یک مدل را مشخص کرد.
use Illuminate\Database\Eloquent\Attributes\CollectedBy;
#[CollectedBy(PostCollection::class)]
class Post extends Model
{
}
#[UseFactory] — اتصال مدل به فکتوری
این اتریبیوت مشخص میکند برای تولید نمونههای یک مدل از کدام فکتوری استفاده شود.
use Illuminate\Database\Eloquent\Attributes\UseFactory;
#[UseFactory(PostFactory::class)]
class Post extends Model
{
}
#[UseEloquentBuilder] — استفاده از Query Builder سفارشی
با استفاده از این اتریبیوت میتوان یک Eloquent Builder سفارشی را به مدل متصل کرد.
این قابلیت زمانی کاربرد دارد که بخواهیم منطق مربوط به کوئریهای مدل را در یک کلاس مستقل و قابلاستفاده مجدد قرار دهیم.
use Illuminate\Database\Eloquent\Attributes\UseEloquentBuilder;
#[UseEloquentBuilder(PostBuilder::class)]
class Post extends Model
{
}
#[UsePolicy] — اتصال Policy به مدل
این اتریبیوت برای اتصال یک Authorization Policy به مدل استفاده میشود.
use Illuminate\Database\Eloquent\Attributes\UsePolicy;
#[UsePolicy(PostPolicy::class)]
class Post extends Model
{
}
#[UseResource] و #[UseResourceCollection]
با استفاده از این دو اتریبیوت میتوان Resource و Resource Collection مربوط به یک مدل را مشخص کرد.
use Illuminate\Database\Eloquent\Attributes\UseResource;
use Illuminate\Database\Eloquent\Attributes\UseResourceCollection;
#[UseResource(PostResource::class)]
#[UseResourceCollection(PostCollection::class)]
class Post extends Model
{
}
#[Boot] و #[Initialize] — مدیریت Hookهای چرخه حیات مدل
این دو اتریبیوت امکان تعریف Hookهای مربوط به چرخه حیات مدل را مستقیماً روی متدهای آن فراهم میکنند.
#[Boot]
این اتریبیوت برای مشخصکردن متدهای استاتیکی استفاده میشود که هنگام Boot شدن مدل باید اجرا شوند.
use Illuminate\Database\Eloquent\Attributes\Boot;
class Post extends Model
{
#[Boot]
public static function registerEvents(): void
{
static::creating(fn (Post $post) => $post->slug = Str::slug($post->title));
}
}
در این مثال، هنگام ایجاد یک Post جدید، مقدار Slug بهصورت خودکار از روی عنوان آن ساخته میشود.
#[Initialize]
این اتریبیوت برای تعریف متدهایی استفاده میشود که هنگام مقداردهی اولیه نمونه مدل اجرا میشوند.
use Illuminate\Database\Eloquent\Attributes\Initialize;
class Post extends Model
{
#[Initialize]
public function setDefaults(): void
{
$this->attributes['status'] ??= 'draft';
}
}
در این مثال، اگر مقدار status از قبل تعیین نشده باشد، مقدار پیشفرض draft برای آن در نظر گرفته میشود.
#[Scope] — تعریف Local Scope روی متدها
با استفاده از این اتریبیوت میتوان یک متد را بهعنوان لوکال اسکوپ در مدل معرفی کرد.
اسکوپهای لوکال به ما اجازه میدهند کوئریهای پرکاربرد را در متدهای قابلاستفاده مجدد تعریف کنیم.
use Illuminate\Database\Eloquent\Attributes\Scope;
use Illuminate\Database\Eloquent\Builder;
class Post extends Model
{
#[Scope]
public function published(Builder $query): void
{
$query->whereNotNull('published_at');
}
}
در این مثال، اسکوپ مربوط به published فقط پستهایی را برمیگرداند که مقدار published_at آنها خالی نیست.
۲. اتریبیوتهای قبلی Queue
#[DeleteWhenMissingModels] — حذف Job در صورت پیدا نشدن مدل
گاهی ممکن است یک Job به مدلی از دیتابیس وابسته باشد که تا زمان اجرای Job حذف شده است.
با استفاده از این اتریبیوت میتوان مشخص کرد در صورت پیدا نشدن مدل موردنیاز، Job حذف شود.
use Illuminate\Queue\Attributes\DeleteWhenMissingModels;
#[DeleteWhenMissingModels]
class SendOrderConfirmation implements ShouldQueue
{
public function __construct(private Order $order) {}
}
#[WithoutRelations] — حذف Relationshipها پیش از Serialization
هنگامی که یک مدل را به Job ارسال میکنیم، ممکن است Relationshipهای بارگذاریشده آن نیز همراه مدل سریالسازی شوند.
این موضوع میتواند باعث افزایش حجم دادههای موردنیاز برای انتقال و پردازش Job شود.
با استفاده از این اتریبیوت میتوان Relationshipها را پیش از سریالیزیشن حذف کرد.
use Illuminate\Queue\Attributes\WithoutRelations;
#[WithoutRelations]
class ProcessOrder implements ShouldQueue
{
public function __construct(private Order $order) {}
}
۳. اتریبیوتهای Container و Dependency Injection
این اتریبیوتها معمولاً روی پارامترهای Constructor یا متدها قرار میگیرند و نحوه Resolve شدن وابستگیها (Dependencies) توسط Service Container لاراول را کنترل میکنند.
#[CurrentUser] — تزریق کاربر احراز هویتشده
با استفاده از این اتریبیوت میتوان کاربر فعلی سیستم را مستقیماً به متد تزریق کرد.
use Illuminate\Container\Attributes\CurrentUser;
class DashboardController extends Controller
{
public function index(#[CurrentUser] User $user)
{
return view('dashboard', compact('user'));
}
}
در این مثال، کاربر احراز هویتشده بهصورت خودکار در پارامتر $user قرار میگیرد.
#[Config] — تزریق مقدار تنظیمات
این اتریبیوت امکان دریافت مستقیم یک مقدار از فایلهای پیکربندی لاراول را فراهم میکند.
use Illuminate\Container\Attributes\Config;
class PaymentService
{
public function __construct(
#[Config('services.stripe.secret')] private string $stripeSecret,
) {
}
}
در این مثال، مقدار services.stripe.secret از فایلهای تنظیمات لاراول دریافت و به متغیر $stripeSecret تزریق میشود.
#[Auth] — تزریق Auth Guard
با استفاده از این اتریبیوت میتوان یک Auth Guard مشخص را به کلاس تزریق کرد.
use Illuminate\Container\Attributes\Auth;
use Illuminate\Contracts\Auth\Guard;
class ApiController extends Controller
{
public function __construct(
#[Auth('api')] private Guard $auth,
) {
}
}
در این مثال، Guard مربوط به api به متغیر $auth تزریق میشود.
#[Cache] — تزریق Cache Store
این اتریبیوت برای تزریق یک Cache Store مشخص استفاده میشود.
use Illuminate\Container\Attributes\Cache;
use Illuminate\Contracts\Cache\Repository;
class ReportService
{
public function __construct(
#[Cache('redis')] private Repository $cache,
) {
}
}
در این مثال، Cache Store مربوط به Redis به کلاس تزریق میشود.
#[DB] — تزریق اتصال دیتابیس
با استفاده از این اتریبیوت میتوان یک اتصال دیتابیس مشخص را به کلاس تزریق کرد.
use Illuminate\Container\Attributes\DB;
use Illuminate\Database\Connection;
class AnalyticsService
{
public function __construct(
#[DB('analytics')] private Connection $db,
) {
}
}
در این مثال، اتصال دیتابیس analytics در اختیار کلاس قرار میگیرد.
#[Log] — تزریق کانال لاگ
این اتریبیوت امکان تزریق یک Log Channel مشخص را فراهم میکند.
use Illuminate\Container\Attributes\Log;
use Psr\Log\LoggerInterface;
class PaymentService
{
public function __construct(
#[Log('payments')] private LoggerInterface $logger,
) {
}
}
در این مثال، کانال لاگ payments به سرویس پرداخت تزریق میشود.
#[Storage] — تزریق Filesystem Disk
با استفاده از این اتریبیوت میتوان یک Disk مشخص از سیستم فایل لاراول را به کلاس تزریق کرد.
use Illuminate\Container\Attributes\Storage;
use Illuminate\Contracts\Filesystem\Filesystem;
class UploadService
{
public function __construct(
#[Storage('s3')] private Filesystem $disk,
) {
}
}
در این مثال، Disk مربوط به S3 در اختیار سرویس آپلود قرار میگیرد.
#[Tag] — تزریق سرویسهای دارای Tag مشترک
در سرویس کانتینر لاراول میتوان چند سرویس را با یک Tag مشترک ثبت کرد.
این اتریبیوت امکان تزریق تمام سرویسهای دارای یک Tag مشخص را فراهم میکند.
use Illuminate\Container\Attributes\Tag;
class NotificationSender
{
public function __construct(
#[Tag('notification.channels')] private iterable $channels,
) {
}
}
در این مثال، تمام سرویسهایی که با Tag به نام notification.channels ثبت شدهاند، در متغیر $channels قرار میگیرند.
#[RouteParameter] — تزریق پارامتر Route
این اتریبیوت امکان دریافت یک پارامتر مشخص از Route را مستقیماً در متد کنترلر فراهم میکند.
use Illuminate\Container\Attributes\RouteParameter;
class InvoiceController extends Controller
{
public function show(#[RouteParameter('invoice')] string $invoiceId)
{
// ...
}
}
در این مثال، مقدار پارامتر Route با نام invoice به متغیر $invoiceId تزریق میشود.
#[Give] — تعیین پیادهسازی مشخص برای یک وابستگی
گاهی یک اینترفیس داریم که چندین پیادهسازی مختلف دارد و میخواهیم در یک نقطه مشخص، یک پیادهسازی خاص به آن تزریق شود.
این اتریبیوت چنین امکانی را فراهم میکند.
use Illuminate\Container\Attributes\Give;
class OrderProcessor
{
public function __construct(
#[Give(StripePaymentGateway::class)] private PaymentGateway $gateway,
) {
}
}
در این مثال، بهجای هر پیادهسازی دیگری از PaymentGateway، کلاس StripePaymentGateway برای این وابستگی انتخاب میشود.
#[Authenticated] — تزریق کاربر احراز هویتشده از طریق Guard
این اتریبیوت نیز برای دریافت کاربر احراز هویتشده استفاده میشود، با این تفاوت که امکان تعیین Guard موردنظر را فراهم میکند.
use Illuminate\Container\Attributes\Authenticated;
use Illuminate\Contracts\Auth\Authenticatable;
class ProfileController extends Controller
{
public function edit(#[Authenticated('web')] Authenticatable $user)
{
return view('profile.edit', compact('user'));
}
}
در این مثال، کاربر احراز هویتشده از طریق Guard مربوط به web دریافت میشود.
#[Context] — تزریق مقدار از Context Repository
این اتریبیوت برای دریافت مقادیر ذخیرهشده در Context Repository استفاده میشود.
use Illuminate\Container\Attributes\Context;
class RequestHandler
{
public function __construct(
#[Context('request_id')] private string $requestId,
) {
}
}
در این مثال، مقدار request_id از Context دریافت و به متغیر $requestId تزریق میشود.
#[Database] — تزریق اتصال دیتابیس (نام جایگزین)
این اتریبیوت نیز برای تزریق یک اتصال دیتابیس مشخص استفاده میشود و در واقع یک نام جایگزین برای این نوع تزریق است.
use Illuminate\Container\Attributes\Database;
use Illuminate\Database\Connection;
class LegacyService
{
public function __construct(
#[Database('legacy_mysql')] private Connection $db,
) {
}
}
در این مثال، اتصال دیتابیس legacy_mysql به کلاس تزریق میشود.
۴. اتریبیوتهای Container و ثبت سرویسها
برخلاف اتریبیوتهای بخش قبلی که معمولاً روی پارامترهای متد یا Constructor قرار میگرفتند، این موارد روی تعریف کلاس قرار میگیرند.
هدف آنها کنترل نحوه ثبت و مدیریت سرویسها در سرویس کانتینر لاراول است.
#[Bind] — اتصال خودکار کلاس به Container
با استفاده از این اتریبیوت میتوان یک کلاس را بهصورت خودکار در سرویس کانتینر ثبت کرد.
use Illuminate\Container\Attributes\Bind;
#[Bind]
class InvoiceGenerator
{
public function generate(Order $order): Invoice
{
// هر بار که این کلاس Resolve شود، یک نمونه جدید ساخته میشود.
}
}
در این مثال، با هر بار Resolve شدن کلاس، یک نمونه جدید از آن ایجاد میشود.
#[Singleton] — ثبت سرویس بهصورت Singleton
با استفاده از این اتریبیوت میتوان مشخص کرد که یک کلاس بهصورت سینگلتون در کانتینر ثبت شود.
در این حالت، کانتینر یک نمونه مشترک از کلاس ایجاد میکند و در Resolveهای بعدی همان نمونه را برمیگرداند.
use Illuminate\Container\Attributes\Singleton;
#[Singleton]
class FeatureFlagService
{
private array $flags = [];
public function isEnabled(string $flag): bool
{
return $this->flags[$flag] ?? false;
}
}
در این مثال، سرویس FeatureFlagService بهصورت Singleton مدیریت میشود.
#[Scoped] — ثبت سرویس بهصورت Scoped
این اتریبیوت برای ثبت سرویسهایی استفاده میشود که باید در محدوده یک چرخه مشخص، مانند یک درخواست HTTP، یک نمونه مشترک داشته باشند.
use Illuminate\Container\Attributes\Scoped;
#[Scoped]
class RequestContext
{
public ?string $traceId = null;
}
در این مثال، سرویس RequestContext بهصورت Scoped ثبت میشود.
جمعبندی
در لاراول ۱۳، تعداد زیادی اتریبیوت جدید معرفی شدهاند که به توسعهدهندگان اجازه میدهند بخشهای مختلف برنامه را با استفاده از اتریبیوتهای PHP پیکربندی کنند.
در این مقاله، ۳۶ کلاس Attribute جدید که به لاراول اضافه شدهاند را بررسی کردیم. همچنین تعداد کل اتریبیوتهای قابلاستفاده در این فریمورک به بیش از ۵۰ مورد رسیده است.
مهمترین تغییرات و مزایای این قابلیتها عبارتاند از:
۱. اتریبیوتهای مدل (Model Attributes)
اتریبیوتهایی مانند:
#[Fillable]#[Table]#[Hidden]
باعث میشوند تعریف و پیکربندی مدلهای الوکوئنت سادهتر و خواناتر شود و نیاز کمتری به تعریف پراپرتیهای مختلف داشته باشیم.
۲. اتریبیوتهای Job
اتریبیوتهایی مانند:
#[Tries]#[Timeout]#[Queue]
امکان پیکربندی Jobها را بهصورت مستقیم و Declarative فراهم میکنند.
۳. اتریبیوتهای Console
اتریبیوتهایی مانند:
#[Signature]#[Description]
امکان تعریف دستورات آرتیسان را بدون نیاز به تعریف پراپرتیهای رشتهای فراهم میکنند.
۴. اتریبیوتهای Controller
اتریبیوتهایی مانند:
#[Middleware]#[Authorize]
امکان تعریف میدلور و مجوزهای دسترسی را به شکلی منظمتر و خواناتر فراهم میکنند.
نکته پایانی:
روش سنتی مبتنی بر تعریف پراپرتیها همچنان در لاراول قابلاستفاده است. اتریبیوتهای PHP قرار نیست جایگزین اجباری روش قبلی شوند، بلکه یک روش جایگزین در اختیار توسعهدهندگان قرار میدهند.
بنابراین، انتخاب بین روش سنتی و روش مبتنی بر Attribute به سلیقه تیم توسعه و استانداردهای پروژه بستگی دارد.
مهمترین نکته این است که در یک پروژه، تا حد امکان از یک سبک مشخص و یکپارچه استفاده کنید تا خوانایی و نگهداری کد در طول زمان آسانتر شود.

دیدگاهها
ثبت دیدگاه