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 (PublishScheduledPostsCommand )

• Mailables: purpose + Mail suffix (AccountActivatedMail )

• Resources/Transformers: plural + Resource /Transformer (UsersResource )

• Enums: descriptive name, no prefix (OrderStatus , BookingType )

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 , $request not $r )