Spatie Laravel Php Standards

Spatie Laravel & PHP Guidelines

Overview

Apply Spatie's Laravel and PHP guidelines to keep code style consistent and Laravel-native.

When to Activate

• Activate this skill for any Laravel or PHP coding work, even if the user does not explicitly mention Spatie.
• Activate this skill when asked to generate, edit, format, refactor, review, or align Laravel/PHP code.
• Activate this skill when working on .php or .blade.php files, routes, controllers, models, config, validation, migrations, or tests.

Scope

• In scope: .php, .blade.php, Laravel conventions (routes, controllers, config, validation, migrations, tests).
• Out of scope: JS/TS, CSS, infrastructure, database schema design, non-Laravel frameworks.

Workflow

1. Identify the artifact (controller, route, config, model, Blade, test, etc.). 2. Read references/spatie-laravel-php-guidelines.md and focus on the relevant sections. 3. Apply the core Laravel principle first, then PHP standards, then section-specific rules. 4. If a rule conflicts with existing project conventions, follow Laravel conventions and keep changes consistent.

Core Rules (Summary)

• Follow Laravel conventions first.
• Follow PSR-1, PSR-2, and PSR-12.
• Prefer typed properties and explicit return types (including void).
• Use short nullable syntax like ?string.
• Prefer early returns and avoid else when possible.
• Always use curly braces for control structures.
• Use string interpolation over concatenation.

Do and Don't

Do:

• Use kebab-case URLs, camelCase route names, and camelCase route parameters.
• Use array notation for validation rules.
• Use config() and avoid env() outside config files.

Don't:

• Add docblocks when full type hints already exist.
• Use fully qualified classnames in docblocks.
• Use @lang instead of __().

Examples

if (! $user) {
    return null;
}

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

$name = $isFoo ? 'foo' : 'bar';

@if($condition)
    Something
@endif

References

• references/spatie-laravel-php-guidelines.md

Spatie Laravel & PHP Guidelines (Reference)

Table of Contents

• Core Laravel Principle
• PHP Standards
• Class Structure
• Type Declarations and Docblocks
• Control Flow
• Laravel Conventions
• Strings and Formatting
• Enums
• Comments
• Whitespace
• Validation
• Blade Templates
• Authorization
• Translations
• API Routing
• Testing
• Quick Reference

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
• Use constructor property promotion when all properties can be promoted
• Use one trait per line

Type Declarations and 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 its 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: prefer multiple if statements over compound conditions
• Always use curly brackets even for single statements
• Ternary operators: each part on its 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();

Laravel Conventions

Routes

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

Controllers

• Use 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 an 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 and Formatting

• Use string interpolation over concatenation

Enums

• Use PascalCase for enum values

Comments

• Avoid comments; write expressive code instead
• When needed, use proper formatting:

// Single line with space after //

/*
 * Multi-line blocks start with single *
 */

• Refactor comments into descriptive function names

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 and 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 and Transformers: plural + Resource or 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
• Use string interpolation over concatenation
• Always use curly braces for control structures

---

Source: https://spatie.be/guidelines/laravel-php