Spatie PHP 编码规范与 Laravel 最佳实践指南 - 提升代码质量与团队协作

🇺🇸English

Core Laravel Principle

Follow Laravel conventions first. If Laravel has a documented way to do something, use it. Only deviate when you have a clear justification.

PHP Standards

• Follow PSR-1, PSR-2, and PSR-12
• Use camelCase for non-public-facing strings
• Use short nullable notation: ?string not string|null
• Always specify void return types when methods return nothing

Class Structure

• Use typed properties, not docblocks:
• Constructor property promotion when all properties can be promoted:
• One trait per line:

Type Declarations & Docblocks

• Use typed properties over docblocks

• Specify return types including void

• Use short nullable syntax: ?Type not Type|null

• Document iterables with generics:

  /** @return Collection<int, User> */
  public function getUsers(): Collection
  

Docblock Rules

• Don't use docblocks for fully type-hinted methods (unless description needed)

• Always import classnames in docblocks - never use fully qualified names:

  use \Spatie\Url\Url;
  /** @return Url */
  

• Use one-line docblocks when possible: /** @var string */

• Most common type should be first in multi-type docblocks:

  /** @var Collection|SomeWeirdVendor\Collection */
  

• If one parameter needs docblock, add docblocks for all parameters

• For iterables, always specify key and value types:

  /**
   * @param array<int, MyObject> $myArray
   * @param int $typedArgument 
   */
  function someFunction(array $myArray, int $typedArgument) {}
  

• Use array shape notation for fixed keys, put each key on it's own line:

  /** @return array{
     first: SomeClass, 
     second: SomeClass
  } */
  

Control Flow

• Happy path last : Handle error conditions first, success case last

• Avoid else : Use early returns instead of nested conditions

• Separate conditions : Split compound if statements that use && into nested if statements for better readability

• Always use curly brackets even for single statements

• Ternary operators : Each part on own line unless very short

  // Happy path last if (! $user) { return null; }

  if (! $user->isActive()) { return null; }

  // Process active user...

  // Short ternary $name = $isFoo ? 'foo' : 'bar';

  // Multi-line ternary $result = $object instanceof Model ? $object->name : 'A default value';

  // Ternary instead of else $condition ? $this->doSomething() : $this->doSomethingElse();

  // Bad: compound condition with && if ($user->isActive() && $user->hasPermission('edit')) { $user->edit(); }

  // Good: nested ifs if ($user->isActive()) { if ($user->hasPermission('edit')) { $user->edit(); } }

Laravel Conventions

Routes

• URLs: kebab-case (/open-source)
• Route names: camelCase (->name('openSource'))
• Parameters: camelCase ({userId})
• Use tuple notation: [Controller::class, 'method']

Controllers

• Plural resource names (PostsController)
• Stick to CRUD methods (index, create, store, show, edit, update, destroy)
• Extract new controllers for non-CRUD actions

Configuration

• Files: kebab-case (pdf-generator.php)
• Keys: snake_case (chrome_path)
• Add service configs to config/services.php, don't create new files
• Use config() helper, avoid env() outside config files

Artisan Commands

• Names: kebab-case (delete-old-records)

• Always provide feedback ($this->comment('All ok!'))

• Show progress for loops, summary at end

• Put output BEFORE processing item (easier debugging):

  $items->each(function(Item $item) {
      $this->info("Processing item id `{$item->id}`...");
      $this->processItem($item);
  });
  
  $this->comment("Processed {$items->count()} items.");
  

Strings & Formatting

• String interpolation over concatenation:

Enums

• Use PascalCase for enum values:

Comments

Be very critical about adding comments as they often become outdated and can mislead over time. Code should be self-documenting through descriptive variable and function names.

Adding comments should never be the first tactic to make code readable.

Instead of this:

// Get the failed checks for this site
$checks = $site->checks()->where('status', 'failed')->get();

Do this:

$failedChecks = $site->checks()->where('status', 'failed')->get();

Guidelines:

• Don't add comments that describe what the code does - make the code describe itself
• Short, readable code doesn't need comments explaining it
• Use descriptive variable names instead of generic names + comments
• Only add comments when explaining why something non-obvious is done, not what is being done
• Never add comments to tests - test names should be descriptive enough

Whitespace

• Add blank lines between statements for readability
• Exception: sequences of equivalent single-line operations
• No extra empty lines between {} brackets
• Let code "breathe" - avoid cramped formatting

Validation

• Use array notation for multiple rules (easier for custom rule classes):

  public function rules() {
      return [
          'email' => ['required', 'email'],
      ];
  }
  

• Custom validation rules use snake_case:

  Validator::extend('organisation_type', function ($attribute, $value) {
      return OrganisationType::isValid($value);
  });
  

Blade Templates

• Indent with 4 spaces

• No spaces after control structures:

  @if($condition)
      Something
  @endif
  

Authorization

• Policies use camelCase: Gate::define('editPost', ...)
• Use CRUD words, but view instead of show

Translations

• Use __() function over @lang:

API Routing

• Use plural resource names: /errors

• Use kebab-case: /error-occurrences

• Limit deep nesting for simplicity:

  /error-occurrences/1
  /errors/1/occurrences
  

Testing

• Keep test classes in same file when possible
• Use descriptive test method names
• Follow the arrange-act-assert pattern

Quick Reference

Naming Conventions

• Classes : PascalCase (UserController, OrderStatus)
• Methods/Variables : camelCase (getUserName, $firstName)
• Routes : kebab-case (/open-source, /user-profile)
• Config files : kebab-case (pdf-generator.php)
• Config keys : snake_case (chrome_path)
• Artisan commands : kebab-case (php artisan delete-old-records)

File Structure

• Controllers: plural resource name + Controller (PostsController)
• Views: camelCase (openSource.blade.php)
• Jobs: action-based (CreateUser, SendEmailNotification)
• Events: tense-based (UserRegistering, UserRegistered)
• Listeners: action + Listener suffix (SendInvitationMailListener)
• Commands: action + Command suffix ()

Migrations

• do not write down methods in migrations, only up methods

Code Quality Reminders

PHP

• Use typed properties over docblocks
• Prefer early returns over nested if/else
• Use constructor property promotion when all properties can be promoted
• Avoid else statements when possible
• Split compound if conditions using && into nested if statements
• Use string interpolation over concatenation
• Always use curly braces for control structures
• Always import namespaces with use statements — never use inline fully qualified class names (e.g. \Exception, \Illuminate\Support\Facades\Http)
• Never use single-letter variable names — use descriptive names (e.g. $exception not $e, not )

Weekly Installs

110

Repository

freekmurze/dotfiles

GitHub Stars

892

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

opencode95

codex87

claude-code87

github-copilot86

gemini-cli85

cursor78