You might also want to check out the real-world Laravel example application

ترجمه ها:

فهرست مطالب

اصل تک وظیفه ای بودن
مدل های بزرگ،‌ کنترلرهای کوچک!
اعتبارسنجی
منطق برنامه باید در service class باشد.
اصل DRY یا خودت را تکرار نکن!
به جای استفاده از Query Builder و raw SQL queries از Eloquent ORM استفاده کنید. همچنین به جای استفاده از Arrays از Collections استفاده کنید.
ایجاد یک مدل
به جای نوشتن query ها در blade از eager loading استفاده کنید. (مسئله N+1)
کامنت گذاری بکنید، ولی اسامی متدها یا متغیرها را توصیفی و معنادار در نظر بگیرید.
در تمپلیت های Blade از js و css استفاده نکنید و هیچگونه کد HTML ای را در class های PHP استفاده نکنید.
به جای استفاده مستقیم از متن ها در کد، از فایل های config و languages استفاده کنید!
از ابزارهای استاندارد لاراول که مورد تایید جامعه کاربری آن میباشد، استفاده کنید.
از قرارداد های لاراول برای نامگذاری ها استفاده کنید.
تا حد ممکن در کدتان، از Syntax های معنادار و کوتاه استفاده کنید.
به جای ایجاد یک object با new، از IoC container و facades استفاده کنید.
از فایل .env هیچ وقت مستقیم داده ای دریافت نکنید.
تاریخ و زمان را در قالب استاندارد ذخیره کنید. از Accessors & Mutators ها برای دستکاری در نمایش تاریخ و زمان استفاده کنید.
دیگر روش ها

اصل تک وظیفه ای بودن

هر class و هر method باید یک وظیفه داشته باشد.

❌ روش اشتباه:

public function getFullNameAttribute(): string
{
    if (auth()->user() && auth()->user()->hasRole('client') && auth()->user()->isVerified()) {
        return 'Mr. ' . $this->first_name . ' ' . $this->middle_name . ' ' . $this->last_name;
    } else {
        return $this->first_name[0] . '. ' . $this->last_name;
    }
}

✔️ روش قابل قبول:

public function getFullNameAttribute(): string
{
    return $this->isVerifiedClient() ? $this->getFullNameLong() : $this->getFullNameShort();
}

public function isVerifiedClient(): bool
{
    return auth()->user() && auth()->user()->hasRole('client') && auth()->user()->isVerified();
}

public function getFullNameLong(): string
{
    return 'Mr. ' . $this->first_name . ' ' . $this->middle_name . ' ' . $this->last_name;
}

public function getFullNameShort(): string
{
    return $this->first_name[0] . '. ' . $this->last_name;
}

🔝 بازگشت به فهرست

مدل های بزرگ،‌ کنترلرهای کوچک!

اگر از Query Builder یا raw SQL queries استفاده میکنید، تمام منطق پایگاه داده را در model ها یا Repository classes قرار بدهید.

❌ روش اشتباه:

public function index()
{
    $clients = Client::verified()
        ->with(['orders' => function ($q) {
            $q->where('created_at', '>', Carbon::today()->subWeek());
        }])
        ->get();

    return view('index', ['clients' => $clients]);
}

✔️ روش قابل قبول:

public function index()
{
    return view('index', ['clients' => $this->client->getWithNewOrders()]);
}

class Client extends Model
{
    public function getWithNewOrders()
    {
        return $this->verified()
            ->with(['orders' => function ($q) {
                $q->where('created_at', '>', Carbon::today()->subWeek());
            }])
            ->get();
    }
}

🔝 بازگشت به فهرست

اعتبارسنجی

اعتبارسنجی ها را در Request classes انجام دهید نه در controllers.

❌ روش اشتباه:

public function store(Request $request)
{
    $request->validate([
        'title' => 'required|unique:posts|max:255',
        'body' => 'required',
        'publish_at' => 'nullable|date',
    ]);

    ...
}

✔️ روش قابل قبول:

public function store(PostRequest $request)
{
    ...
}

class PostRequest extends Request
{
    public function rules()
    {
        return [
            'title' => 'required|unique:posts|max:255',
            'body' => 'required',
            'publish_at' => 'nullable|date',
        ];
    }
}

🔝 بازگشت به فهرست

منطق برنامه باید در service class باشد

هر کنترلر باید یک وظیفه داشته باشد، بنابراین منطق برنامه را در service classes بنویسید.

❌ روش اشتباه:

public function store(Request $request)
{
    if ($request->hasFile('image')) {
        $request->file('image')->move(public_path('images') . 'temp');
    }
    
    ...
}

✔️ روش قابل قبول:

public function store(Request $request)
{
    $this->articleService->handleUploadedImage($request->file('image'));

    ...
}

class ArticleService
{
    public function handleUploadedImage($image)
    {
        if (!is_null($image)) {
            $image->move(public_path('images') . 'temp');
        }
    }
}

🔝 بازگشت به فهرست

اصل DRY یا خودت را تکرار نکن!

تا حد ممکن از کد ها بازاستفاده کنید. تک وظیفه ای شدن به شما کمک میکند تا کار تکراری نکنید. همچنین در Blade template حتما این اصل را رعایت کنید و در model ها از Eloquent scopes استفاده کنید و ... .

❌ روش اشتباه:

public function getActive()
{
    return $this->where('verified', 1)->whereNotNull('deleted_at')->get();
}

public function getArticles()
{
    return $this->whereHas('user', function ($q) {
            $q->where('verified', 1)->whereNotNull('deleted_at');
        })->get();
}

✔️ روش قابل قبول:

public function scopeActive($q)
{
    return $q->where('verified', 1)->whereNotNull('deleted_at');
}

public function getActive()
{
    return $this->active()->get();
}

public function getArticles()
{
    return $this->whereHas('user', function ($q) {
            $q->active();
        })->get();
}

🔝 بازگشت به فهرست

به جای استفاده از Query Builder و raw SQL queries از Eloquent ORM استفاده کنید. همچنین به جای استفاده از Arrays از Collections استفاده کنید.

Eloquent به شما این قابلیت را میدهد که کدهای خوانا و قابل توسعه بنویسید. همچنین دارای ویژگی های داخلی کاربردی مثل soft deletes یا events یا scopes و .. میباشد.

❌ روش اشتباه:

SELECT *
FROM `articles`
WHERE EXISTS (SELECT *
              FROM `users`
              WHERE `articles`.`user_id` = `users`.`id`
              AND EXISTS (SELECT *
                          FROM `profiles`
                          WHERE `profiles`.`user_id` = `users`.`id`) 
              AND `users`.`deleted_at` IS NULL)
AND `verified` = '1'
AND `active` = '1'
ORDER BY `created_at` DESC

✔️ روش قابل قبول:

Article::has('user.profile')->verified()->latest()->get();

🔝 بازگشت به فهرست

ایجاد یک مدل

[منظور نویسنده از این بخش این میباشد که برای راحتی کار و کوتاه تر شدن کد، در html طوری مقادیر name هر input یا ... را نامگذاری کنید که با column های جدول مربوطه یکسان باشد تا laravel آن ها رو با یک کامند خیلی سریع مپ و ذخیره کند.]

❌ روش اشتباه:

$article = new Article;
$article->title = $request->title;
$article->content = $request->content;
$article->verified = $request->verified;

// Add category to article
$article->category_id = $category->id;
$article->save();

✔️ روش قابل قبول:

$category->article()->create($request->all());

🔝 بازگشت به فهرست

به جای نوشتن query ها در blade از eager loading استفاده کنید. (مسئله N+1)

❌ روش اشتباه (برای ۱۰۰ کاربر، ما ۱۰۱ کوئری را اجرا میکنیم!):

@foreach (User::all() as $user)
    {{ $user->profile->name }}
@endforeach

✔️ روش قابل قبول (برای ۱۰۰ کاربر، ما فقط ۲ کوئری اجرا کردیم!):

$users = User::with('profile')->get();

@foreach ($users as $user)
    {{ $user->profile->name }}
@endforeach

🔝 بازگشت به فهرست

کامنت گذاری بکنید، ولی اسامی متدها یا متغیرها را توصیفی و معنادار در نظر بگیرید.

❌ روش اشتباه:

if (count((array) $builder->getQuery()->joins) > 0)

❗️ قابل قبول:

// Determine if there are any joins.
if (count((array) $builder->getQuery()->joins) > 0)

✔️ روش قابل قبول:

if ($this->hasJoins())

🔝 بازگشت به فهرست

در تمپلیت های Blade از js و css استفاده نکنید و هیچگونه کد HTML ای را در class های PHP استفاده نکنید.

❌ روش اشتباه:

let article = `{{ json_encode($article) }}`;

❗️ قابل قبول:

<input id="article" type="hidden" value='@json($article)'>

Or

<button class="js-fav-article" data-article='@json($article)'>{{ $article->name }}<button>

در فایل JavaScript:

let article = $('#article').val();

بهترین راه استفاده از پکیج مخصوص انتقال داده از php به js میباشد.

🔝 بازگشت به فهرست

به جای استفاده مستقیم از متن ها در کد، از فایل های config و languages استفاده کنید!

❌ روش اشتباه:

public function isNormal()
{
    return $article->type === 'normal';
}

return back()->with('message', 'مقاله شما ایجاد گردید!');

✔️ روش قابل قبول:

public function isNormal()
{
    return $article->type === Article::TYPE_NORMAL;
}

return back()->with('message', __('app.article_added'));

🔝 بازگشت به فهرست

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

به جای استفاده از ابزارها و پکیج های غیررسمی لاراول از ابزارها و قابلیت های داخلی و رسمی لاراول استفاده کنید. هر توسعه دهنده [لاراولی] ای که در آینده بخواهد با کدهای شما کار کند، باید ابزارهای جدید یاد بگیرد. همچنین اگر شما از ابزارهای غیررسمی استفاده کنید، شانس دریافت کمک از جامعه کاربری لاراول به طرز قابل توجهی کمتر میشود. این هزینه را به گردن مشتریان خود نیندازید! [منظور نویسنده این هست که تو کارهای بزرگ و مهمتون از ابزارهای جدید و پراکنده استفاده نکنید. همیشه سعی کنید از ابزارهای داخلی و یا پکیج های رسمی لاراول استفاده کنید مگر این که چاره دیگری نباشد! شما با پراکنده کردن ابزارها هزینه فنی/مالی توسعه محصول را برای آینده زیادتر میکنید!]

نیاز	ابزارهای رسمی لاراول	ابزارهای غیررسمی لاراول
Authorization	Policies	Entrust, Sentinel and other packages
Compiling assets	Laravel Mix, Vite	Grunt, Gulp, 3rd party packages
Development Environment	Laravel Sail, Homestead	Docker
Deployment	Laravel Forge	Deployer and other solutions
Unit testing	PHPUnit, Mockery	Phpspec, Pest
Browser testing	Laravel Dusk	Codeception
DB	Eloquent	SQL, Doctrine
Templates	Blade	Twig
Working with data	Laravel collections	Arrays
Form validation	Request classes	3rd party packages, validation in controller
Authentication	Built-in	3rd party packages, your own solution
API authentication	Laravel Passport, Laravel Sanctum	3rd party JWT and OAuth packages
Creating API	Built-in	Dingo API and similar packages
Working with DB structure	Migrations	Working with DB structure directly
Localization	Built-in	3rd party packages
Realtime user interfaces	Laravel Echo, Pusher	3rd party packages and working with WebSockets directly
Generating testing data	Seeder classes, Model Factories, Faker	Creating testing data manually
Task scheduling	Laravel Task Scheduler	Scripts and 3rd party packages
DB	MySQL, PostgreSQL, SQLite, SQL Server	MongoDB

🔝 بازگشت به فهرست

از قرارداد های لاراول برای نامگذاری ها استفاده کنید

از استاندارد های php که به PSR معروف است استفاده کنید.

همچنین روش های نامگذاری مورد قبول جامعه کاربری لاراول:

بخش مربوطه	قاعده اسم گذاری	✔️ روش قابل قبول	❌ روش اشتباه
Controller	اسامی مفرد	ArticleController	~~ArticlesController~~
Route	اسامی جمع	articles/1	~~article/1~~
Route name	روش snake_case همراه با نقاط اتصال	users.show_active	~~users.show-active, show-active-users~~
Model	اسامی مفرد	User	~~Users~~
hasOne or belongsTo relationship	اسامی مفرد	articleComment	~~articleComments, article_comment~~
All other relationships	اسامی جمع	articleComments	~~articleComment, article_comments~~
Table	اسامی جمع	article_comments	~~article_comment, articleComments~~
Pivot table	نام مدل ها با اسامی مفرد و ترتیب الفبایی	article_user	~~user_article, articles_users~~
Table column	روش snake_case بدون اسم مدل	meta_title	~~MetaTitle; article_meta_title~~
Model property	روش snake_case	$model->created_at	~~$model->createdAt~~
Foreign key	اسامی مفرد model name with _id suffix	article_id	~~ArticleId, id_article, articles_id~~
Primary key	-	id	~~custom_id~~
Migration	-	2017_01_01_000000_create_articles_table	~~2017_01_01_000000_articles~~
Method	روش camelCase	getAll	~~get_all~~
Method in resource controller	table	store	~~saveArticle~~
Method in test class	روش camelCase	testGuestCannotSeeArticle	~~test_guest_cannot_see_article~~
Variable	روش camelCase	$articlesWithAuthor	~~$articles_with_author~~
Collection	توصیفی و اسامی جمع	$activeUsers = User::active()->get()	~~$active, $data~~
Object	توصیفی و اسامی مفرد	$activeUser = User::active()->first()	~~$users, $obj~~
Config and language files index	snake_case	articles_enabled	~~ArticlesEnabled; articles-enabled~~
View	kebab-case	show-filtered.blade.php	~~showFiltered.blade.php, show_filtered.blade.php~~
Config	snake_case	google_calendar.php	~~googleCalendar.php, google-calendar.php~~
Contract (interface)	صفت یا اسم	AuthenticationInterface	~~Authenticatable, IAuthentication~~
Trait	صفت	Notifiable	~~NotificationTrait~~
Trait (PSR)	adjective	NotifiableTrait	~~Notification~~
Enum	singular	UserType	~~UserTypes~~, ~~UserTypeEnum~~
FormRequest	singular	UpdateUserRequest	~~UpdateUserFormRequest~~, ~~UserFormRequest~~, ~~UserRequest~~
Seeder	singular	UserSeeder	~~UsersSeeder~~

🔝 بازگشت به فهرست

تا حد ممکن در کدتان، از Syntax های معنادار و کوتاه استفاده کنید

❌ روش اشتباه:

$request->session()->get('cart');
$request->input('name');

✔️ روش قابل قبول:

session('cart');
$request->name;

مثال های بیشتر:

سینتکس متداول	سینتکس کوتاه‌تر و خواناتر
`Session::get('cart')`	`session('cart')`
`$request->session()->get('cart')`	`session('cart')`
`Session::put('cart', $data)`	`session(['cart' => $data])`
`$request->input('name'), Request::get('name')`	`$request->name, request('name')`
`return Redirect::back()`	`return back()`
`is_null($object->relation) ? null : $object->relation->id`	`optional($object->relation)->id`
`return view('index')->with('title', $title)->with('client', $client)`	`return view('index', compact('title', 'client'))`
`$request->has('value') ? $request->value : 'default';`	`$request->get('value', 'default')`
`Carbon::now(), Carbon::today()`	`now(), today()`
`App::make('Class')`	`app('Class')`
`->where('column', '=', 1)`	`->where('column', 1)`
`->orderBy('created_at', 'desc')`	`->latest()`
`->orderBy('age', 'desc')`	`->latest('age')`
`->orderBy('created_at', 'asc')`	`->oldest()`
`->select('id', 'name')->get()`	`->get(['id', 'name'])`
`->first()->name`	`->value('name')`

🔝 بازگشت به فهرست

به جای ایجاد یک object با new، از IoC container و facades استفاده کنید.

به‌جای این که آبجکت‌ها را مستقیما در هرجایی با کلمه کلیدی new ایجاد و استفاده کنید، از امکان IoC لاراول استفاده کنید. چرا که با این کار عملا dependency های هر چیزی را در صورت نیاز آن inject‌ میکنیم که به ما قدرت استفاده از مفهوم تست‌نویسی را میدهد.

❌ روش اشتباه:

$user = new User;
$user->create($request->all());

✔️ روش قابل قبول:

public function __construct(User $user)
{
    $this->user = $user;
}

...

$this->user->create($request->all());

🔝 بازگشت به فهرست

از فایل .env هیچ وقت مستقیم داده ای دریافت نکنید.

اطلاعات موجود در .env را در صورت نیاز به استفاده، در فایل های config لود کنید و سپس با استفاده از helper function فایل های کانفیگ یعنی config() با آن در نرم افزار خود کار کنید.

❌ روش اشتباه:

$apiKey = env('API_KEY');

✔️ روش قابل قبول:

// config/api.php
'key' => env('API_KEY'),

// Use the data
$apiKey = config('api.key');

🔝 بازگشت به فهرست

تاریخ و زمان را در قالب استاندارد ذخیره کنید. از Accessors & Mutators ها برای دستکاری در نمایش تاریخ و زمان استفاده کنید.

❌ روش اشتباه:

{{ Carbon::createFromFormat('Y-d-m H-i', $object->ordered_at)->toDateString() }}
{{ Carbon::createFromFormat('Y-d-m H-i', $object->ordered_at)->format('m-d') }}

✔️ روش قابل قبول:

// Model
protected $casts = [
    'ordered_at' => 'datetime',
];

public function getSomeDateAttribute($date)
{
    return $date->format('m-d');
}

// View
{{ $object->ordered_at->toDateString() }}
{{ $object->ordered_at->some_date }}

🔝 بازگشت به فهرست

در فایل های route خود هیچوقت منطق برنامه را قرار ندهید.

❌ روش اشتباه:

// Route
Route::get('user/1', function (User $user) {
    return new UserResource($user);
});

✔️ روش قابل قبول:

// Route
Route::get('users/1', 'UserController@show');

// Controlelr
class UserController extends Controller 
{
    public function show(User $user) {
        return new UserResource($user);
    }
}

🔝 بازگشت به فهرست

تا حد ممکن از PHP خام در فایل های blade استفاده نکنید.

🔝 بازگشت به فهرست

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

persian.md

persian.md

فهرست مطالب

اصل تک وظیفه ای بودن

مدل های بزرگ،‌ کنترلرهای کوچک!

اعتبارسنجی

منطق برنامه باید در service class باشد

اصل DRY یا خودت را تکرار نکن!

به جای استفاده از Query Builder و raw SQL queries از Eloquent ORM استفاده کنید. همچنین به جای استفاده از Arrays از Collections استفاده کنید.

ایجاد یک مدل

به جای نوشتن query ها در blade از eager loading استفاده کنید. (مسئله N+1)

کامنت گذاری بکنید، ولی اسامی متدها یا متغیرها را توصیفی و معنادار در نظر بگیرید.

در تمپلیت های Blade از js و css استفاده نکنید و هیچگونه کد HTML ای را در class های PHP استفاده نکنید.

به جای استفاده مستقیم از متن ها در کد، از فایل های config و languages استفاده کنید!

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

از قرارداد های لاراول برای نامگذاری ها استفاده کنید

تا حد ممکن در کدتان، از Syntax های معنادار و کوتاه استفاده کنید

به جای ایجاد یک object با new، از IoC container و facades استفاده کنید.

از فایل .env هیچ وقت مستقیم داده ای دریافت نکنید.

تاریخ و زمان را در قالب استاندارد ذخیره کنید. از Accessors & Mutators ها برای دستکاری در نمایش تاریخ و زمان استفاده کنید.

در فایل های route خود هیچوقت منطق برنامه را قرار ندهید.

تا حد ممکن از PHP خام در فایل های blade استفاده نکنید.

Files

persian.md

Latest commit

History

persian.md

File metadata and controls

فهرست مطالب

اصل تک وظیفه ای بودن

مدل های بزرگ،‌ کنترلرهای کوچک!

اعتبارسنجی

منطق برنامه باید در service class باشد

اصل DRY یا خودت را تکرار نکن!

به جای استفاده از Query Builder و raw SQL queries از Eloquent ORM استفاده کنید. همچنین به جای استفاده از Arrays از Collections استفاده کنید.

ایجاد یک مدل

به جای نوشتن query ها در blade از eager loading استفاده کنید. (مسئله N+1)

کامنت گذاری بکنید، ولی اسامی متدها یا متغیرها را توصیفی و معنادار در نظر بگیرید.

در تمپلیت های Blade از js و css استفاده نکنید و هیچگونه کد HTML ای را در class های PHP استفاده نکنید.

به جای استفاده مستقیم از متن ها در کد، از فایل های config و languages استفاده کنید!

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

از قرارداد های لاراول برای نامگذاری ها استفاده کنید

تا حد ممکن در کدتان، از Syntax های معنادار و کوتاه استفاده کنید

به جای ایجاد یک object با new، از IoC container و facades استفاده کنید.

از فایل .env هیچ وقت مستقیم داده ای دریافت نکنید.

تاریخ و زمان را در قالب استاندارد ذخیره کنید. از Accessors & Mutators ها برای دستکاری در نمایش تاریخ و زمان استفاده کنید.

در فایل های route خود هیچوقت منطق برنامه را قرار ندهید.

تا حد ممکن از PHP خام در فایل های blade استفاده نکنید.