├── README.md
├── images
    ├── logo-english.png
    └── logo-russian.png
└── russian.md


/README.md:
--------------------------------------------------------------------------------
  1 | ![Boas Práticas Laravel](/images/logo-english.png?raw=true)
  2 | 
  3 | > Talvez você deva checar o [real-world Laravel example application](https://github.com/alexeymezenin/laravel-realworld-example-app)
  4 | 
  5 | O que é descrito aqui não é uma adaptação ao principio SOLID, padrões e etc. Aqui você irá encontrar as melhores práticas que geralmente são ignoradas em um projeto Laravel na vida real.
  6 | 
  7 | ## Conteúdo
  8 | 
  9 | [Princípio da responsabilidade única](#princípio-da-responsabilidade-única)
 10 | 
 11 | [Models gordos, controllers finos](#models-gordos-controllers-finos)
 12 | 
 13 | [Validação](#validação)
 14 | 
 15 | [Lógica de negócio deve ser posta em classes](#lógica-de-negócio-deve-ser-posta-em-classes)
 16 | 
 17 | [Não se repita (Don't repeat yourself: DRY)](#não-se-repita-dont-repeat-yourself-dry)
 18 | 
 19 | [Usar o Eloquent em vez de Query Builder e consultas SQL puras (raw SQL). Usar collections no lugar de arrays](#usar-o-eloquent-em-vez-de-query-builder-e-consultas-sql-puras-raw-sql-usar-collections-no-lugar-de--arrays)
 20 | 
 21 | [Atribuição em massa](#atribuição-em-massa)
 22 | 
 23 | [Não executar consultas no Blade templates e usar eager loading (N + 1)](#não-executar-consultas-no-blade-templates-e-usar-eager-loading-n--1)
 24 | 
 25 | [Use chunk para tarefas de dados pesadas](#use-chunk-para-tarefas-de-dados-pesadas)
 26 | 
 27 | [Comente seu código, mas prefira um método descritivo e nomes de variáveis em vez de comentários](#comente-seu-código-mas-prefira-um-método-descritivo-e-nomes-de-variáveis-em-vez-de--comentários)
 28 | 
 29 | [Não coloque JS e CSS em templates Blade. Não coloque HTML em classes PHP](#não-coloque-js-e-css-em-templates-blade-não-coloque-html-em-classes-php)
 30 | 
 31 | [Use arquivos de linguagem e configuração. Constantes em vez de texto no código](#use-arquivos-de-linguagem-e-configuração-constantes-em-vez-de-texto-no-código)
 32 | 
 33 | [Use ferramentas padrões do Laravel aceitas pela comunidade](#use-ferramentas-padrões-do-laravel-aceitas-pela-comunidade)
 34 | 
 35 | [Siga a convenção de nomes usada no Laravel](#siga-a-convenção-de-nomes-usada-no-laravel)
 36 | 
 37 | [Tente sempre usar sintaxes pequenas e legíveis](#tente-sempre-usar-sintaxes-pequenas-e-legíveis)
 38 | 
 39 | [Use contaneirs IoC (inversão de controle) ou facades no lugar de classes](#use-contaneirs-ioc-inversão-de-controle-ou-facades-no-lugar-de-classes)
 40 | 
 41 | [Não recupere informações diretamente do `.env`](#não-recupere-informações-diretamente-do-env)
 42 | 
 43 | [Armazene datas em formatos padrões. Use "accessors" e "mutators" para modificar o formato das datas](#armazene-datas-em-formatos-padrões-use-accessors-and-mutators-para-modificar-o-formato-das-datas)
 44 | 
 45 | [Outras boas práticas](#outras-boas-práticas)
 46 | 
 47 | ### **Princípio da responsabilidade única**
 48 | 
 49 | Classes e métodos devem possuir somente uma responsabilidade.
 50 | 
 51 | Ruim:
 52 | 
 53 | ```php
 54 | public function getFullNameAttribute()
 55 | {
 56 |     if (auth()->user() && auth()->user()->hasRole('client') && auth()->user()->isVerified()) {
 57 |         return 'Sr. ' . $this->first_name . ' ' . $this->middle_name . ' ' . $this->last_name;
 58 |     } else {
 59 |         return $this->first_name[0] . '. ' . $this->last_name;
 60 |     }
 61 | }
 62 | ```
 63 | 
 64 | Bom:
 65 | 
 66 | ```php
 67 | public function getFullNameAttribute()
 68 | {
 69 |     return $this->isVerifiedClient() ? $this->getFullNameLong() : $this->getFullNameShort();
 70 | }
 71 | 
 72 | public function isVerifiedClient()
 73 | {
 74 |     return auth()->user() && auth()->user()->hasRole('client') && auth()->user()->isVerified();
 75 | }
 76 | 
 77 | public function getFullNameLong()
 78 | {
 79 |     return 'Sr. ' . $this->first_name . ' ' . $this->middle_name . ' ' . $this->last_name;
 80 | }
 81 | 
 82 | public function getFullNameShort()
 83 | {
 84 |     return $this->first_name[0] . '. ' . $this->last_name;
 85 | }
 86 | ```
 87 | 
 88 | [🔝 Voltar para o início](#conteúdo)
 89 | 
 90 | ### **Models gordos, controllers finos**
 91 | 
 92 | Coloque toda a lógica relacionada a banco em modelos Eloquent ou em repositórios caso você esteja usando Query Builder ou consultas SQL.
 93 | 
 94 | Ruim:
 95 | 
 96 | ```php
 97 | public function index()
 98 | {
 99 |     $clients = Client::verified()
100 |         ->with(['orders' => function ($q) {
101 |             $q->where('created_at', '>', Carbon::today()->subWeek());
102 |         }])
103 |         ->get();
104 | 
105 |     return view('index', ['clients' => $clients]);
106 | }
107 | ```
108 | 
109 | Bom:
110 | 
111 | ```php
112 | public function index()
113 | {
114 |     return view('index', ['clients' => $this->client->getWithNewOrders()]);
115 | }
116 | 
117 | class Client extends Model
118 | {
119 |     public function getWithNewOrders()
120 |     {
121 |         return $this->verified()
122 |             ->with(['orders' => function ($q) {
123 |                 $q->where('created_at', '>', Carbon::today()->subWeek());
124 |             }])
125 |             ->get();
126 |     }
127 | }
128 | ```
129 | 
130 | [🔝 Voltar para o início](#conteúdo)
131 | 
132 | ### **Validação**
133 | 
134 | Não use validações em controllers e sim em classes de Requisição.
135 | 
136 | Ruim:
137 | 
138 | ```php
139 | public function store(Request $request)
140 | {
141 |     $request->validate([
142 |         'title' => 'required|unique:posts|max:255',
143 |         'body' => 'required',
144 |         'publish_at' => 'nullable|date',
145 |     ]);
146 | 
147 |     ....
148 | }
149 | ```
150 | 
151 | Bom:
152 | 
153 | ```php
154 | public function store(PostRequest $request)
155 | {
156 |     ....
157 | }
158 | 
159 | class PostRequest extends Request
160 | {
161 |     public function rules()
162 |     {
163 |         return [
164 |             'title' => 'required|unique:posts|max:255',
165 |             'body' => 'required',
166 |             'publish_at' => 'nullable|date',
167 |         ];
168 |     }
169 | }
170 | ```
171 | 
172 | [🔝 Voltar para o início](#conteúdo)
173 | 
174 | ### **Lógica de negócio deve ser posta em classes**
175 | 
176 | Controllers devem ter somente uma responsabilidade, então mova lógica de negócio para outros serviços.
177 | 
178 | Ruim:
179 | 
180 | ```php
181 | public function store(Request $request)
182 | {
183 |     if ($request->hasFile('image')) {
184 |         $request->file('image')->move(public_path('images') . 'temp');
185 |     }
186 | 
187 |     ....
188 | }
189 | ```
190 | 
191 | Bom:
192 | 
193 | ```php
194 | public function store(Request $request)
195 | {
196 |     $this->articleService->handleUploadedImage($request->file('image'));
197 | 
198 |     ....
199 | }
200 | 
201 | class ArticleService
202 | {
203 |     public function handleUploadedImage($image)
204 |     {
205 |         if (!is_null($image)) {
206 |             $image->move(public_path('images') . 'temp');
207 |         }
208 |     }
209 | }
210 | ```
211 | 
212 | [🔝 Voltar para o início](#conteúdo)
213 | 
214 | ### **Não se repita (Don't repeat yourself: DRY)**
215 | 
216 | Reutilize seu código sempre que possível. A ideia da responsabilidade única ajuda você a evitar duplicação. Isso serve também para templates Blade.
217 | 
218 | Ruim:
219 | 
220 | ```php
221 | public function getActive()
222 | {
223 |     return $this->where('verified', 1)->whereNotNull('deleted_at')->get();
224 | }
225 | 
226 | public function getArticles()
227 | {
228 |     return $this->whereHas('user', function ($q) {
229 |             $q->where('verified', 1)->whereNotNull('deleted_at');
230 |         })->get();
231 | }
232 | ```
233 | 
234 | Bom:
235 | 
236 | ```php
237 | public function scopeActive($q)
238 | {
239 |     return $q->where('verified', 1)->whereNotNull('deleted_at');
240 | }
241 | 
242 | public function getActive()
243 | {
244 |     return $this->active()->get();
245 | }
246 | 
247 | public function getArticles()
248 | {
249 |     return $this->whereHas('user', function ($q) {
250 |             $q->active();
251 |         })->get();
252 | }
253 | ```
254 | 
255 | [🔝 Voltar para o início](#conteúdo)
256 | 
257 | ### **Usar o Eloquent em vez de Query Builder e consultas SQL puras (raw SQL). Usar collections no lugar de arrays**
258 | 
259 | Eloquent permite que você escreva código legível e manutenível. Além disso, Eloquent possui ferramentas ótimas para implementar "soft deletes", eventos, escopos e etc.
260 | 
261 | Ruim:
262 | 
263 | ```sql
264 | SELECT *
265 | FROM `articles`
266 | WHERE EXISTS (SELECT *
267 |               FROM `users`
268 |               WHERE `articles`.`user_id` = `users`.`id`
269 |               AND EXISTS (SELECT *
270 |                           FROM `profiles`
271 |                           WHERE `profiles`.`user_id` = `users`.`id`)
272 |               AND `users`.`deleted_at` IS NULL)
273 | AND `verified` = '1'
274 | AND `active` = '1'
275 | ORDER BY `created_at` DESC
276 | ```
277 | 
278 | Bom:
279 | 
280 | ```php
281 | Article::has('user.profile')->verified()->latest()->get();
282 | ```
283 | 
284 | [🔝 Voltar para o início](#conteúdo)
285 | 
286 | ### **Atribuição em massa**
287 | 
288 | Ruim:
289 | 
290 | ```php
291 | $article = new Article;
292 | $article->title = $request->title;
293 | $article->content = $request->content;
294 | $article->verified = $request->verified;
295 | // Adicionar categoria em artigos
296 | $article->category_id = $category->id;
297 | $article->save();
298 | ```
299 | 
300 | Bom:
301 | 
302 | ```php
303 | $category->article()->create($request->all());
304 | ```
305 | 
306 | [🔝 Voltar para o início](#conteúdo)
307 | 
308 | ### **Não executar consultas no Blade templates e usar eager loading (N + 1)**
309 | 
310 | Ruim (para 100 usuários, 101 consultas são feitas):
311 | 
312 | ```php
313 | @foreach (User::all() as $user)
314 |     {{ $user->profile->name }}
315 | @endforeach
316 | ```
317 | 
318 | Bom (para 100 usuários, duas consultas são feitas):
319 | 
320 | ```php
321 | $users = User::with('profile')->get();
322 | 
323 | ...
324 | 
325 | @foreach ($users as $user)
326 |     {{ $user->profile->name }}
327 | @endforeach
328 | ```
329 | 
330 | [🔝 Voltar para o início](#conteúdo)
331 | 
332 | ### **Use chunk para tarefas de dados pesadas**
333 | 
334 | Ruim ():
335 | 
336 | ```php
337 | $users = $this->get();
338 | 
339 | foreach ($users as $user) {
340 |     ...
341 | }
342 | ```
343 | 
344 | Bom:
345 | 
346 | ```php
347 | $this->chunk(500, function ($users) {
348 |     foreach ($users as $user) {
349 |         ...
350 |     }
351 | });
352 | ```
353 | 
354 | [🔝 Voltar para o início](#conteúdo)
355 | 
356 | ### **Comente seu código, mas prefira um método descritivo e nomes de variáveis em vez de comentários**
357 | 
358 | Ruim:
359 | 
360 | ```php
361 | if (count((array) $builder->getQuery()->joins) > 0)
362 | ```
363 | 
364 | Melhor:
365 | 
366 | ```php
367 | // Determine se há algum join.
368 | if (count((array) $builder->getQuery()->joins) > 0)
369 | ```
370 | 
371 | Bom:
372 | 
373 | ```php
374 | if ($this->hasJoins())
375 | ```
376 | 
377 | [🔝 Voltar para o início](#conteúdo)
378 | 
379 | ### **Não coloque JS e CSS em templates Blade. Não coloque HTML em classes PHP**
380 | 
381 | Ruim:
382 | 
383 | ```php
384 | let article = `{{ json_encode($article) }}`;
385 | ```
386 | 
387 | Melhor:
388 | 
389 | ```php
390 | <input id="article" type="hidden" value="{{ json_encode($article) }}">
391 | 
392 | Ou
393 | 
394 | <button class="js-fav-article" data-article="{{ json_encode($article) }}">{{ $article->name }}<button>
395 | ```
396 | 
397 | No javascript:
398 | 
399 | ```php
400 | let article = $('#article').val();
401 | ```
402 | 
403 | 
404 | [🔝 Voltar para o início](#conteúdo)
405 | 
406 | ### **Use arquivos de linguagem e configuração. Constantes em vez de texto no código**
407 | 
408 | Ruim:
409 | 
410 | ```php
411 | public function isNormal()
412 | {
413 |     return $article->type === 'normal';
414 | }
415 | 
416 | return back()->with('message', 'Your article has been added!');
417 | ```
418 | 
419 | Bom:
420 | 
421 | ```php
422 | public function isNormal()
423 | {
424 |     return $article->type === Article::TYPE_NORMAL;
425 | }
426 | 
427 | return back()->with('message', __('app.article_added'));
428 | ```
429 | 
430 | [🔝 Voltar para o início](#conteúdo)
431 | 
432 | ### **Use ferramentas padrões do Laravel aceitas pela comunidade**
433 | 
434 | Preferir usar funcionalidades do próprio Laravel e pacotes da comunidade em vez de pacotes de terceiros. Qualquer desenvolvedor que irá trabalhar em seu sistema terá que aprender novas ferramentas no futuro. Além disso, ter ajuda da comunidade do Laravel se torna significativamente menor quando você utiliza um pacote ou ferramenta de terceiros.
435 | 
436 | Tarefas | Ferramentas padrões | Pacotes de terceiros
437 | ------------ | ------------- | -------------
438 | Autorização | Policies | Entrust, Sentinel e outros pacotes
439 | Compilar assets | Laravel Mix | Grunt, Gulp, pacotes de terceiros
440 | Ambiente de desenvolvimento | Homestead, Laradock | Docker
441 | Deployment | Laravel Forge | Deployer e outras soluções
442 | Testes unitários | PHPUnit, Mockery | Phpspec
443 | Teste em navegador | Laravel Dusk | Codeception
444 | DB | Eloquent | SQL, Doctrine
445 | Templates | Blade | Twig
446 | Trabalhando com dados | Laravel collections | Arrays
447 | Validação de formulários | Request classes | pacotes de terceiros, validação no controller
448 | Autenticação | Nativo | pacotes de terceiros, sua propria solução
449 | Autenticação API | Laravel Passport | JWT e pacotes OAuth
450 | Criar API | Nativo | Dingo API e similares
451 | Trabalhando com estrutura de DB | Migrações | Trabalhar com banco diretamente
452 | Localização | Nativo | pacotes de terceiros
453 | Interface em tempo real | Laravel Echo, Pusher | pacotes de terceiros e trabalhar com WebSockets diretamente
454 | Gerar dados de teste | Seeder classes, Model Factories, Faker | Criar testes manualmente
455 | Agendar tarefas | Laravel Task Scheduler | Scripts e pacotes de terceiros
456 | DB | MySQL, PostgreSQL, SQLite, SQL Server | MongoDB
457 | 
458 | [🔝 Voltar para o início](#conteúdo)
459 | 
460 | ### **Siga a convenção de nomes usada no Laravel**
461 | 
462 |  Siga [PSR standards](http://www.php-fig.org/psr/psr-2/).
463 | 
464 |  Siga também a convenção de nomes aceita pelo a comunidade Laravel:
465 | 
466 | O que | Como | Bom | Ruim
467 | ------------ | ------------- | ------------- | -------------
468 | Controller | singular | ArticleController | ~~ArticlesController~~
469 | Route | plural | articles/1 | ~~article/1~~
470 | Named route | snake_case with dot notation | users.show_active | ~~users.show-active, show-active-users~~
471 | Model | singular | User | ~~Users~~
472 | hasOne or belongsTo relationship | singular | articleComment | ~~articleComments, article_comment~~
473 | All other relationships | plural | articleComments | ~~articleComment, article_comments~~
474 | Table | plural | article_comments | ~~article_comment, articleComments~~
475 | Pivot table | singular model names in alphabetical order | article_user | ~~user_article, articles_users~~
476 | Colunas em tabelas | snake_case without model name | meta_title | ~~MetaTitle; article_meta_title~~
477 | Model property | snake_case | $model->created_at | ~~$model->createdAt~~
478 | Foreign key | singular model name with _id suffix | article_id | ~~ArticleId, id_article, articles_id~~
479 | Chaves primárias | - | id | ~~custom_id~~
480 | Migrações | - | 2017_01_01_000000_create_articles_table | ~~2017_01_01_000000_articles~~
481 | Métodos | camelCase | getAll | ~~get_all~~
482 | Métodos em controllers | [table](https://laravel.com/docs/master/controllers#resource-controllers) | store | ~~saveArticle~~
483 | Métodos e classes de teste | camelCase | testGuestCannotSeeArticle | ~~test_guest_cannot_see_article~~
484 | Variáveis | camelCase | $articlesWithAuthor | ~~$articles_with_author~~
485 | Collection | descriptive, plural | $activeUsers = User::active()->get() | ~~$active, $data~~
486 | Object | descriptive, singular | $activeUser = User::active()->first() | ~~$users, $obj~~
487 | Config e arquivos de linguagem | snake_case | articles_enabled | ~~ArticlesEnabled; articles-enabled~~
488 | View | kebab-case | show-filtered.blade.php | ~~showFiltered.blade.php, show_filtered.blade.php~~
489 | Config | snake_case | google_calendar.php | ~~googleCalendar.php, google-calendar.php~~
490 | Contract (interface) | adjective or noun | Authenticatable | ~~AuthenticationInterface, IAuthentication~~
491 | Trait | adjective | Notifiable | ~~NotificationTrait~~
492 | 
493 | [🔝 Voltar para o início](#conteúdo)
494 | 
495 | ### **Tente sempre usar sintaxes pequenas e legíveis**
496 | 
497 | Ruim:
498 | 
499 | ```php
500 | $request->session()->get('cart');
501 | $request->input('name');
502 | ```
503 | 
504 | Bom:
505 | 
506 | ```php
507 | session('cart');
508 | $request->name;
509 | ```
510 | 
511 | Mais exemplos:
512 | 
513 | Sintaxe comum | Pequena e mais legível
514 | ------------ | -------------
515 | `Session::get('cart')` | `session('cart')`
516 | `$request->session()->get('cart')` | `session('cart')`
517 | `Session::put('cart', $data)` | `session(['cart' => $data])`
518 | `$request->input('name'), Request::get('name')` | `$request->name, request('name')`
519 | `return Redirect::back()` | `return back()`
520 | `is_null($object->relation) ? null : $object->relation->id` | `optional($object->relation)->id`
521 | `return view('index')->with('title', $title)->with('client', $client)` | `return view('index', compact('title', 'client'))`
522 | `$request->has('value') ? $request->value : 'default';` | `$request->get('value', 'default')`
523 | `Carbon::now(), Carbon::today()` | `now(), today()`
524 | `App::make('Class')` | `app('Class')`
525 | `->where('column', '=', 1)` | `->where('column', 1)`
526 | `->orderBy('created_at', 'desc')` | `->latest()`
527 | `->orderBy('age', 'desc')` | `->latest('age')`
528 | `->orderBy('created_at', 'asc')` | `->oldest()`
529 | `->select('id', 'name')->get()` | `->get(['id', 'name'])`
530 | `->first()->name` | `->value('name')`
531 | 
532 | [🔝 Voltar para o início](#conteúdo)
533 | 
534 | ### **Use contaneirs IoC (inversão de controle) ou facades no lugar de classes**
535 | 
536 | "new Class" sintaxe cria maior acoplamento de classes e teste. Use IoC ou facades em vez disso.
537 | 
538 | Ruim:
539 | 
540 | ```php
541 | $user = new User;
542 | $user->create($request->all());
543 | ```
544 | 
545 | Bom:
546 | 
547 | ```php
548 | public function __construct(User $user)
549 | {
550 |     $this->user = $user;
551 | }
552 | 
553 | ....
554 | 
555 | $this->user->create($request->all());
556 | ```
557 | 
558 | [🔝 Voltar para o início](#conteúdo)
559 | 
560 | ### **Não recupere informações diretamente do `.env`**
561 | 
562 | Coloque os dados em arquivos de configuração e recupere através do helper `config()`.
563 | 
564 | Ruim:
565 | 
566 | ```php
567 | $apiKey = env('API_KEY');
568 | ```
569 | 
570 | Bom:
571 | 
572 | ```php
573 | // config/api.php
574 | 'key' => env('API_KEY'),
575 | 
576 | // Use data
577 | $apiKey = config('api.key');
578 | ```
579 | 
580 | [🔝 Voltar para o início](#conteúdo)
581 | 
582 | ### **Armazene datas em formatos padrões. Use "accessors" e "mutators" para modificar o formato das datas**
583 | 
584 | Ruim:
585 | 
586 | ```php
587 | {{ Carbon::createFromFormat('Y-d-m H-i', $object->ordered_at)->toDateString() }}
588 | {{ Carbon::createFromFormat('Y-d-m H-i', $object->ordered_at)->format('m-d') }}
589 | ```
590 | 
591 | Bom:
592 | 
593 | ```php
594 | // Model
595 | protected $dates = ['ordered_at', 'created_at', 'updated_at']
596 | public function getSomeDateAttribute($date)
597 | {
598 |     return $date->format('m-d');
599 | }
600 | 
601 | // View
602 | {{ $object->ordered_at->toDateString() }}
603 | {{ $object->ordered_at->some_date }}
604 | ```
605 | 
606 | [🔝 Voltar para o início](#conteúdo)
607 | 
608 | ### **Outras boas práticas**
609 | 
610 | Nunca coloque lógica em arquivos de rota.
611 | 
612 | Minimize o uso de vanilla PHP em templates Blade.
613 | 
614 | [🔝 Voltar para o início](#conteúdo)
615 | 


--------------------------------------------------------------------------------
/images/logo-english.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/jonaselan/laravel-best-practices/0f24736f53f2a6e41c5b065ea31391ab4325b9fc/images/logo-english.png


--------------------------------------------------------------------------------
/images/logo-russian.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/jonaselan/laravel-best-practices/0f24736f53f2a6e41c5b065ea31391ab4325b9fc/images/logo-russian.png


--------------------------------------------------------------------------------
/russian.md:
--------------------------------------------------------------------------------
  1 | ![Хорошие практики Laravel](/images/logo-russian.png?raw=true)
  2 | 
  3 | Это не пересказ лучших практик вроде SOLID, паттернов и пр. с адаптацией под Laravel. Здесь собраны именно практики, которые игнорируются в реальных Laravel проектах. Также, рекомендую ознакомитсья с [хорошими практиками в контексте PHP](https://github.com/jupeter/clean-code-php). Смотрите также [обсуждение хороших практик Laravel](https://laravel.ru/forum/viewforum.php?id=17).
  4 | 
  5 | ## Содержание
  6 | 
  7 | [Принцип единственной ответственности (Single responsibility principle)](#Принцип-единственной-ответственности-single-responsibility-principle)
  8 | 
  9 | [Тонкие контроллеры, толстые модели](#Тонкие-контроллеры-толстые-модели)
 10 | 
 11 | [Валидация](#Валидация)
 12 | 
 13 | [Бизнес логика в сервис-классах](#Бизнес-логика-в-сервис-классах)
 14 | 
 15 | [Не повторяйся (DRY)](#Не-повторяйся-dry)
 16 | 
 17 | [Предпочитайте Eloquent конструктору запросов (query builder) и сырым запросам в БД. Предпочитайте работу с коллекциями работе с массивами](#Предпочитайте-eloquent-конструктору-запросов-query-builder-и-сырым-запросам-в-БД-Предпочитайте-работу-с-коллекциями-работе-с-массивами)
 18 | 
 19 | [Используйте массовое заполнение (mass assignment)](#Используйте-массовое-заполнение-mass-assignment)
 20 | 
 21 | [Не выполняйте запросы в представлениях и используйте нетерпеливую загрузку (проблема N + 1)](#Не-выполняйте-запросы-в-представлениях-и-используйте-нетерпеливую-загрузку-проблема-n--1)
 22 | 
 23 | [Комментируйте код, предпочитайте читаемые имена методов комментариям](#Комментируйте-код-предпочитайте-читаемые-имена-методов-комментариям)
 24 | 
 25 | [Выносите JS и CSS из шаблонов Blade и HTML из PHP кода](#Выносите-js-и-css-из-шаблонов-blade-и-html-из-php-кода)
 26 | 
 27 | [Используйте инструменты и практики принятые сообществом](#Используйте-инструменты-и-практики-принятые-сообществом)
 28 | 
 29 | [Соблюдайте соглашения сообщества об именовании](#Соблюдайте-соглашения-сообщества-об-именовании)
 30 | 
 31 | [Конфиги, языковые файлы и константы вместо текста в коде](#Конфиги-языковые-файлы-и-константы-вместо-текста-в-коде)
 32 | 
 33 | [Короткий и читаемый синтаксис там, где это возможно](#Короткий-и-читаемый-синтаксис-там-где-это-возможно)
 34 | 
 35 | [Используйте IoC или фасады вместо new Class](#Используйте-ioc-или-фасады-вместо-new-class)
 36 | 
 37 | [Не работайте с данными из файла `.env` напрямую](#Не-работайте-с-данными-из-файла-env-напрямую)
 38 | 
 39 | [Храните даты в стандартном формате. Используйте читатели и преобразователи для преобразования формата](#Храните-даты-в-стандартном-формате-Используйте-читатели-и-преобразователи-для-преобразования-формата)
 40 | 
 41 | [Другие советы и практики](#Другие-советы-и-практики)
 42 | 
 43 | ### **Принцип единственной ответственности (Single responsibility principle)**
 44 | 
 45 | Каждый класс и метод должны выполнять лишь одну функцию.
 46 | 
 47 | Плохо:
 48 | 
 49 | ```
 50 | public function getFullNameAttribute()
 51 | {
 52 |     if (auth()->user() && auth()->user()->hasRole('client') && auth()->user()->isVerified()) {
 53 |         return 'Mr. ' . $this->first_name . ' ' . $this->middle_name . ' ' . $this->last_name;
 54 |     } else {
 55 |         return $this->first_name[0] . '. ' . $this->last_name;
 56 |     }
 57 | }
 58 | ```
 59 | 
 60 | Хорошо:
 61 | 
 62 | ```
 63 | public function getFullNameAttribute()
 64 | {
 65 |     return $this->isVerifiedClient() ? $this->getFullNameLong() : $this->getFullNameShort();
 66 | }
 67 | 
 68 | public function isVerifiedClient()
 69 | {
 70 |     return auth()->user() && auth()->user()->hasRole('client') && auth()->user()->isVerified();
 71 | }
 72 | 
 73 | public function getFullNameLong()
 74 | {
 75 |     return 'Mr. ' . $this->first_name . ' ' . $this->middle_name . ' ' . $this->last_name;
 76 | }
 77 | 
 78 | public function getFullNameShort()
 79 | {
 80 |     return $this->first_name[0] . '. ' . $this->last_name;
 81 | }
 82 | ```
 83 | 
 84 | [🔝 Наверх](#Содержание)
 85 | 
 86 | ### **Тонкие контроллеры, толстые модели**
 87 | 
 88 | По своей сути, это лишь один из частных случаев принципа единой ответственности. Выносите работу с данными в модели при работе с Eloquent или в репозитории при работе с Query Builder или "сырыми" SQL запросами.
 89 | 
 90 | Плохо:
 91 | 
 92 | ```
 93 | public function index()
 94 | {
 95 |     $clients = Client::verified()
 96 |         ->with(['orders' => function ($q) {
 97 |             $q->where('created_at', '>', Carbon::today()->subWeek());
 98 |         }])
 99 |         ->get();
100 | 
101 |     return view('index', ['clients' => $clients]);
102 | }
103 | ```
104 | 
105 | Хорошо:
106 | 
107 | ```
108 | public function index()
109 | {
110 |     return view('index', ['clients' => $this->client->getWithNewOrders()]);
111 | }
112 | 
113 | class Client extends Model
114 | {
115 |     public function getWithNewOrders()
116 |     {
117 |         return $this->verified()
118 |             ->with(['orders' => function ($q) {
119 |                 $q->where('created_at', '>', Carbon::today()->subWeek());
120 |             }])
121 |             ->get();
122 |     }
123 | }
124 | ```
125 | 
126 | [🔝 Наверх](#Содержание)
127 | 
128 | ### **Валидация**
129 | 
130 | Следуя принципам тонкого контроллера и SRP, выносите валидацию из контроллера в Request классы.
131 | 
132 | Плохо:
133 | 
134 | ```
135 | public function store(Request $request)
136 | {
137 |     $request->validate([
138 |         'title' => 'required|unique:posts|max:255',
139 |         'body' => 'required',
140 |         'publish_at' => 'nullable|date',
141 |     ]);
142 | 
143 |     ....
144 | }
145 | ```
146 | 
147 | Хорошо:
148 | 
149 | ```
150 | public function store(PostRequest $request)
151 | {    
152 |     ....
153 | }
154 | 
155 | class PostRequest extends Request
156 | {
157 |     public function rules()
158 |     {
159 |         return [
160 |             'title' => 'required|unique:posts|max:255',
161 |             'body' => 'required',
162 |             'publish_at' => 'nullable|date',
163 |         ];
164 |     }
165 | }
166 | ```
167 | 
168 | [🔝 Наверх](#Содержание)
169 | 
170 | ### **Бизнес логика в сервис-классах**
171 | 
172 | Контроллер должен выполнять только свои прямые обязанности, поэтому выносите всю бизнес логику в отдельные классы и сервис классы.
173 | 
174 | Плохо:
175 | 
176 | ```
177 | public function store(Request $request)
178 | {
179 |     if ($request->hasFile('image')) {
180 |         $request->file('image')->move(public_path('images') . 'temp');
181 |     }
182 |     
183 |     ....
184 | }
185 | ```
186 | 
187 | Хорошо:
188 | 
189 | ```
190 | public function store(Request $request)
191 | {
192 |     $this->articleService->handleUploadedImage($request->file('image'));
193 | 
194 |     ....
195 | }
196 | 
197 | class ArticleService
198 | {
199 |     public function handleUploadedImage($image)
200 |     {
201 |         if (!is_null($image)) {
202 |             $image->move(public_path('images') . 'temp');
203 |         }
204 |     }
205 | }
206 | ```
207 | 
208 | [🔝 Наверх](#Содержание)
209 | 
210 | ### **Не повторяйся (DRY)**
211 | 
212 | Этот принцип призывает вас переиспользовать код везде, где это возможно. Если вы следуете принципу SRP, вы уже избегаете повторений, но Laravel позволяет вам также переиспользовать представления, части Eloquent запросов и т.д.
213 | 
214 | Плохо:
215 | 
216 | ```
217 | public function getActive()
218 | {
219 |     return $this->where('verified', 1)->whereNotNull('deleted_at')->get();
220 | }
221 | 
222 | public function getArticles()
223 | {
224 |     return $this->whereHas('user', function ($q) {
225 |             $q->where('verified', 1)->whereNotNull('deleted_at');
226 |         })->get();
227 | }
228 | ```
229 | 
230 | Хорошо:
231 | 
232 | ```
233 | public function scopeActive($q)
234 | {
235 |     return $q->where('verified', 1)->whereNotNull('deleted_at');
236 | }
237 | 
238 | public function getActive()
239 | {
240 |     return $this->active()->get();
241 | }
242 | 
243 | public function getArticles()
244 | {
245 |     return $this->whereHas('user', function ($q) {
246 |             $q->active();
247 |         })->get();
248 | }
249 | ```
250 | 
251 | [🔝 Наверх](#Содержание)
252 | 
253 | ### **Предпочитайте Eloquent конструктору запросов (query builder) и сырым запросам в БД. Предпочитайте работу с коллекциями работе с массивами**
254 | 
255 | Eloquent позволяет писать максимально читаемый код, а изменять функционал приложения несоизмеримо легче. У Eloquent также есть ряд удобных и мощных инструментов.
256 | 
257 | Плохо:
258 | 
259 | ```
260 | SELECT *
261 | FROM `articles`
262 | WHERE EXISTS (SELECT *
263 |               FROM `users`
264 |               WHERE `articles`.`user_id` = `users`.`id`
265 |               AND EXISTS (SELECT *
266 |                           FROM `profiles`
267 |                           WHERE `profiles`.`user_id` = `users`.`id`) 
268 |               AND `users`.`deleted_at` IS NULL)
269 | AND `verified` = '1'
270 | AND `active` = '1'
271 | ORDER BY `created_at` DESC
272 | ```
273 | 
274 | Хорошо:
275 | 
276 | ```
277 | Article::has('user.profile')->verified()->latest()->get();
278 | ```
279 | 
280 | [🔝 Наверх](#Содержание)
281 | 
282 | ### **Используйте массовое заполнение (mass assignment)**
283 | 
284 | Плохо:
285 | 
286 | ```
287 | $article = new Article;
288 | $article->title = $request->title;
289 | $article->content = $request->content;
290 | $article->verified = $request->verified;
291 | // Привязать статью к категории.
292 | $article->category_id = $category->id;
293 | $article->save();
294 | ```
295 | 
296 | Хорошо:
297 | 
298 | ```
299 | $category->article()->create($request->all());
300 | ```
301 | 
302 | [🔝 Наверх](#Содержание)
303 | 
304 | ### **Не выполняйте запросы в представлениях и используйте нетерпеливую загрузку (проблема N + 1)**
305 | 
306 | Плохо (будет выполнен 101 запрос в БД для 100 пользователей):
307 | 
308 | ```
309 | @foreach (User::all() as $user)
310 |     {{ $user->profile->name }}
311 | @endforeach
312 | ```
313 | 
314 | Хорошо (будет выполнено 2 запроса в БД для 100 пользователей):
315 | 
316 | ```
317 | $users = User::with('profile')->get();
318 | 
319 | ...
320 | 
321 | @foreach ($users as $user)
322 |     {{ $user->profile->name }}
323 | @endforeach
324 | ```
325 | 
326 | [🔝 Наверх](#Содержание)
327 | 
328 | ### **Комментируйте код, предпочитайте читаемые имена методов комментариям**
329 | 
330 | Плохо:
331 | 
332 | ```
333 | if (count((array) $builder->getQuery()->joins) > 0)
334 | ```
335 | 
336 | Лучше:
337 | 
338 | ```
339 | // Determine if there are any joins.
340 | if (count((array) $builder->getQuery()->joins) > 0)
341 | ```
342 | 
343 | Хорошо:
344 | 
345 | ```
346 | if ($this->hasJoins())
347 | ```
348 | 
349 | [🔝 Наверх](#Содержание)
350 | 
351 | ### **Выносите JS и CSS из шаблонов Blade и HTML из PHP кода**
352 | 
353 | Плохо:
354 | 
355 | ```
356 | let article = `{{ json_encode($article) }}`;
357 | ```
358 | 
359 | Лучше:
360 | 
361 | ```
362 | <input id="article" type="hidden" value="{{ json_encode($article) }}">
363 | 
364 | Или
365 | 
366 | <button class="js-fav-article" data-article="{{ json_encode($article) }}">{{ $article->name }}<button>
367 | ```
368 | 
369 | В Javascript файле:
370 | 
371 | ```
372 | let article = $('#article').val();
373 | ```
374 | 
375 | Еще лучше использовать специализированный пакет для передачи данных из бэкенда во фронтенд.
376 | 
377 | [🔝 Наверх](#Содержание)
378 | 
379 | ### **Конфиги, языковые файлы и константы вместо текста в коде**
380 | 
381 | Непосредственно в коде не должно быть никакого текста.
382 | 
383 | Плохо:
384 | 
385 | ```
386 | public function isNormal()
387 | {
388 |     return $article->type === 'normal';
389 | }
390 | 
391 | return back()->with('message', 'Ваша статья была успешно добавлена');
392 | ```
393 | 
394 | Хорошо:
395 | 
396 | ```
397 | public function isNormal()
398 | {
399 |     return $article->type === Article::TYPE_NORMAL;
400 | }
401 | 
402 | return back()->with('message', __('app.article_added'));
403 | ```
404 | 
405 | [🔝 Наверх](#Содержание)
406 | 
407 | ### **Используйте инструменты и практики принятые сообществом**
408 | 
409 | Laravel имеет встроенные инструменты для решения часто встречаемых задач. Предпочитайте пользоваться ими использованию сторонних пакетов и инструментов. Laravel разработчику, пришедшему в проект после вас, придется изучать и работать с новым для него инструментом, со всеми вытекающими последствиями. Получить помощь от сообщества будет также гораздо труднее. Не заставляйте клиента или работодателя платить за ваши велосипеды.
410 | 
411 | Задача | Стандартные инструмент | Нестандартные инструмент
412 | ------------ | ------------- | -------------
413 | Авторизация | Политики | Entrust, Sentinel и др. пакеты, собственное решение
414 | Работа с JS, CSS и пр. | Laravel Mix | Grunt, Gulp, сторонние пакеты
415 | Среда разработки | Homestead | Docker
416 | Разворачивание приложений | Laravel Forge | Deployer и многие другие
417 | Тестирование | Phpunit, Mockery | Phpspec
418 | e2e тестирование | Laravel Dusk | Codeception
419 | Работа с БД | Eloquent | SQL, построитель запросов, Doctrine
420 | Шаблоны | Blade | Twig
421 | Работа с данными | Коллекции Laravel | Массивы
422 | Валидация форм | Request классы | Сторонние пакеты, валидация в контроллере
423 | Аутентификация | Встроенный функционал | Сторонние пакеты, собственное решение
424 | Аутентификация API | Laravel Passport | Сторонние пакеты, использующие JWT, OAuth
425 | Создание API | Встроенный функционал | Dingo API и другие пакеты
426 | Работа со структурой БД | Миграции | Работа с БД напрямую
427 | Локализация | Встроенный функционал | Сторонние пакеты
428 | Обмен данными в реальном времени | Laravel Echo, Pusher | Пакеты и работа с веб сокетами напрямую
429 | Генерация тестовых данных | Seeder классы, фабрики моделей, Faker | Ручное заполнение и пакеты
430 | Планирование задач | Планировщик задач Laravel | Скрипты и сторонние пакеты
431 | БД | MySQL, PostgreSQL, SQLite, SQL Server | MongoDb
432 | 
433 | [🔝 Наверх](#Содержание)
434 | 
435 | ### **Соблюдайте соглашения сообщества об именовании**
436 | 
437 |  Следуйте [стандартам PSR](http://www.php-fig.org/psr/psr-2/) при написании кода.
438 |  
439 |  Также, соблюдайте другие cоглашения об именовании:
440 | 
441 | Что | Правило | Принято | Не принято
442 | ------------ | ------------- | ------------- | -------------
443 | Контроллер | ед. ч. | ArticleController | ~~ArticlesController~~
444 | Маршруты | мн. ч. | articles/1 | ~~article/1~~
445 | Имена маршрутов | snake_case | users.show_active | ~~users.show-active, show-active-users~~
446 | Модель | ед. ч. | User | ~~Users~~
447 | Отношения hasOne и belongsTo | ед. ч. | articleComment | ~~articleComments, article_comment~~
448 | Все остальные отношения | мн. ч. | articleComments | ~~articleComment, article_comments~~
449 | Таблица | мн. ч. | article_comments | ~~article_comment, articleComments~~
450 | Pivot таблица | имена моделей в алфавитном порядке в ед. ч. | article_user | ~~user_article, articles_users~~
451 | Столбец в таблице | snake_case без имени модели | meta_title | ~~MetaTitle; article_meta_title~~
452 | Свойство модели | snake_case | $model->created_at | ~~$model->createdAt~~
453 | Внешний ключ | имя модели ед. ч. и _id | article_id | ~~ArticleId, id_article, articles_id~~
454 | Первичный ключ | - | id | ~~custom_id~~
455 | Миграция | - | 2017_01_01_000000_create_articles_table | ~~2017_01_01_000000_articles~~
456 | Метод | camelCase | getAll | ~~get_all~~
457 | Метод в контроллере ресурсов | [таблица](https://laravel.com/docs/master/controllers#resource-controllers) | store | ~~saveArticle~~
458 | Метод в тесте | camelCase | testGuestCannotSeeArticle | ~~test_guest_cannot_see_article~~
459 | Переменные | camelCase | $articlesWithAuthor | ~~$articles_with_author~~
460 | Коллекция | описательное, мн. ч. | $activeUsers = User::active()->get() | ~~$active, $data~~
461 | Объект | описательное, ед. ч. | $activeUser = User::active()->first() | ~~$users, $obj~~
462 | Индексы в конфиге и языковых файлах | snake_case | articles_enabled | ~~ArticlesEnabled; articles-enabled~~
463 | Представление | snake_case | show_filtered.blade.php | ~~showFiltered.blade.php, show-filtered.blade.php~~
464 | Конфигурационный файл | snake_case | google_calendar.php | ~~googleCalendar.php, google-calendar.php~~
465 | Контракт (интерфейс) | прилагательное или существительное | Authenticatable | ~~AuthenticationInterface, IAuthentication~~
466 | Трейт | прилагательное | Notifiable | ~~NotificationTrait~~
467 | 
468 | [🔝 Наверх](#Содержание)
469 | 
470 | ### **Короткий и читаемый синтаксис там, где это возможно**
471 | 
472 | Плохо:
473 | 
474 | ```
475 | $request->session()->get('cart');
476 | $request->input('name');
477 | ```
478 | 
479 | Хорошо:
480 | 
481 | ```
482 | session('cart');
483 | $request->name;
484 | ```
485 | 
486 | Еще примеры:
487 | 
488 | Часто используемый синтаксис | Более короткий и читаемый синтаксис
489 | ------------ | -------------
490 | `Session::get('cart')` | `session('cart')`
491 | `$request->session()->get('cart')` | `session('cart')`
492 | `Session::put('cart', $data)` | `session(['cart' => $data])`
493 | `$request->input('name'), Request::get('name')` | `$request->name, request('name')`
494 | `return Redirect::back()` | `return back()`
495 | `is_null($object->relation) ? $object->relation->id : null }` | `optional($object->relation)->id`
496 | `return view('index')->with('title', $title)->with('client', $client)` | `return view('index', compact('title', 'client'))`
497 | `$request->has('value') ? $request->value : 'default';` | `$request->get('value', 'default')`
498 | `Carbon::now(), Carbon::today()` | `now(), today()`
499 | `App::make('Class')` | `app('Class')`
500 | `->where('column', '=', 1)` | `->where('column', 1)`
501 | `->orderBy('created_at', 'desc')` | `->latest()`
502 | `->orderBy('age', 'desc')` | `->latest('age')`
503 | `->orderBy('created_at', 'asc')` | `->oldest()`
504 | `->select('id', 'name')->get()` | `->get(['id', 'name'])`
505 | `->first()->name` | `->value('name')`
506 | 
507 | [🔝 Наверх](#Содержание)
508 | 
509 | ### **Используйте IoC или фасады вместо new Class**
510 | 
511 | Внедрение классов через синтаксис new Class создает сильное сопряжение между частями приложения и усложняет тестирование. Используйте контейнер или фасады.
512 | 
513 | Плохо:
514 | 
515 | ```
516 | $user = new User;
517 | $user->create($request->all());
518 | ```
519 | 
520 | Хорошо:
521 | 
522 | ```
523 | public function __construct(User $user)
524 | {
525 |     $this->user = $user;
526 | }
527 | 
528 | ....
529 | 
530 | $this->user->create($request->all());
531 | ```
532 | 
533 | [🔝 Наверх](#Содержание)
534 | 
535 | ### **Не работайте с данными из файла `.env` напрямую**
536 | 
537 | Передайте данные из `.env` файла в кофигурационный файл и используйте `config()` в приложении, чтобы использовать эти данными.
538 | 
539 | Плохо:
540 | 
541 | ```
542 | $apiKey = env('API_KEY');
543 | ```
544 | 
545 | Хорошо:
546 | 
547 | ```
548 | // config/api.php
549 | 'key' => env('API_KEY'),
550 | 
551 | // Используйте данные в приложении
552 | $apiKey = config('api.key');
553 | ```
554 | 
555 | [🔝 Наверх](#Содержание)
556 | 
557 | ### **Храните даты в стандартном формате. Используйте читатели и преобразователи для преобразования формата**
558 | 
559 | Плохо:
560 | 
561 | ```
562 | {{ Carbon::createFromFormat('Y-d-m H-i', $object->ordered_at)->toDateString() }}
563 | {{ Carbon::createFromFormat('Y-d-m H-i', $object->ordered_at)->format('m-d') }}
564 | ```
565 | 
566 | Хорошо:
567 | 
568 | ```
569 | // Модель
570 | protected $dates = ['ordered_at', 'created_at', 'updated_at']
571 | // Читатель (accessor)
572 | public function getSomeDateAttribute($date)
573 | {
574 |     return $date->format('m-d');
575 | }
576 | 
577 | // Шаблон
578 | {{ $object->ordered_at->toDateString() }}
579 | {{ $object->ordered_at->some_date }}
580 | ```
581 | 
582 | [🔝 Наверх](#Содержание)
583 | 
584 | ### **Другие советы и практики**
585 | 
586 | Не размещайте логику в маршрутах.
587 | 
588 | Старайтесь не использовать "сырой" PHP в шаблонах Blade.
589 | 
590 | [🔝 Наверх](#Содержание)
591 | 


--------------------------------------------------------------------------------