README

Laravel-specific coding standards, static-analysis rules, and code-quality tooling for Sine Macula's Laravel repositories.

Install this only in Laravel projects. Framework-agnostic, language-wide standards live in sinemacula/coding-standards; this package adds the Laravel-specific layer. Non-Laravel repos simply don't install it - that is how the Laravel rules stay scoped to Laravel projects (no runtime framework detection).

Installation

composer require --dev sinemacula/coding-standards-laravel

This brings sinemacula/coding-standards with it. You also need squizlabs/php_codesniffer, dealerdirect/phpcodesniffer-composer-installer, and slevomat/coding-standard in your dev deps (as you already do for the base standard).

Usage

Wire it into the PHP tools through the same Qlty plugin setup you already use for the base standard (package_file = "composer.json" with package_filters = ["sinemacula", ...] in .qlty/qlty.toml - the "sinemacula" filter already matches this package, so Qlty installs it into the linter tool environments automatically).

PHPCS

Two standards ship; reference exactly one (each pulls in SineMacula, so it replaces it - don't reference both):

SineMaculaLaravel - for applications. The full standard, including the role-based structure rules (placement and naming of controllers, models, providers, …) and the controller rules.
SineMaculaLaravelPackage - for libraries and packages. The same standard with the app-skeleton rules (Structure.*, Controllers.*) excluded, since a package is organised by domain rather than Laravel's app directory layout. Composition only - it redefines nothing.

<?xml version="1.0"?>
<ruleset name="Project">
    <rule ref="SineMaculaLaravel"/>
    <file>src</file>
    <file>tests</file>
</ruleset>

PHPStan

The Laravel rules are auto-included via this package's extra.phpstan.includes (resolved by phpstan/extension-installer), alongside the base config. Your project's phpstan.neon only needs its own level / paths.

PHP CS Fixer

If Laravel-specific fixer rules are present, reference the Laravel factory from your .php-cs-fixer.dist.php; otherwise keep using the base PhpCsFixerConfig::make().

Rules

These are the Laravel-specific rules this package adds on top of the base sinemacula/coding-standards. A deliberate exception can be bypassed with the native directive - // phpcs:ignore <code> for a sniff, @phpstan-ignore <identifier> for a rule.

PHPCS sniffs

Sniff	Enforces
`SineMaculaLaravel.Architecture.DisallowServiceLocation`	No service location (`app()`, `resolve()`, `App::make()`) inside a class body - inject collaborators instead. Targets production code: test files, container-wiring classes (service providers and registrars), and dynamic resolution of a runtime variable (`app($class)`, a factory that cannot be injected) are exempt.
`SineMaculaLaravel.Configuration.DisallowEnvOutsideConfig`	`env()` only inside `config/` files (test code exempt); use `config()` everywhere else.
`SineMaculaLaravel.Controllers.DisallowDatabaseAccess`	No `DB::` facade or direct Eloquent model queries in a controller - read through a repository.
`SineMaculaLaravel.Controllers.DisallowInlineValidation`	No inline validation (`$request->validate()`, `Validator::make()`) in a controller - use a form request.
`SineMaculaLaravel.Controllers.DisallowNonRestActions`	A controller's candidate actions (public, non-static instance methods) must be REST verbs or `__invoke`; statics, the constructor and framework overrides are auto-exempt. Mark a method `@non-rest-action` (a deliberate non-CRUD action) or `@utility` (not an action) to allow it.
`SineMaculaLaravel.Debug.DisallowDebugStatements`	No debug calls (`dd`, `dump`, `ray`, `var_dump`, `print_r`) in committed code.
`SineMaculaLaravel.Eloquent.DisallowLegacyAttributeAccessor`	No legacy `getXAttribute()` / `setXAttribute()` accessors on an Eloquent model - use `Attribute::make()`. Gated on both model identity (base class) and accessor arity, so look-alike methods on other classes are clean.
`SineMaculaLaravel.Routing.CollapseResourceRoutes`	Individual routes for one controller that together form a whole resource (`GET`/`POST` on the base, `GET`/`PUT`/`PATCH`/`DELETE` on `base/{param}`, each dispatched to the canonical action) are flagged to collapse into a single `Route::apiResource(...)->only([...])`. Conservative: any extra or nested route, a renamed action, an inconsistent parameter, or a per-route modifier beyond the URI-constraint family leaves the group untouched, and routes are only grouped within their enclosing `group()` closure.
`SineMaculaLaravel.Services.DisallowHttpAbort`	No `abort()` / `abort_if` / `abort_unless` / `HttpException` in a service - throw a domain exception.
`SineMaculaLaravel.Structure.RequireBladeLocation`	A `*.blade.php` template must live under a `resources/views` (or module `Resources/views`) directory.
`SineMaculaLaravel.Structure.RequireRoleDirectory`	A class whose role is recognised by identity (what it extends/implements) must live under that role's directory - a controller under `Http/Controllers`; an entry-point provider may sit at the package root.
`SineMaculaLaravel.Structure.RequireRoleNaming`	A class is named for its role: controllers/providers/form-requests/resources/policies require a suffix, models forbid `Model`/`Entity`, and the rest (jobs, listeners, events, mailables, middleware, commands, casts, rules) stay bare.
`SineMaculaLaravel.Structure.RoutesLocation`	A `routes.php` file, if present, must sit at the root of an `Http` directory.
`SineMaculaLaravel.TypeHints.PropertyTypeHint`	A class property declares a native type - except the framework-magic properties (`$table`, `$fillable`, `$signature`, `$model`, …, the configurable `magicProperties` set) that override an untyped parent and so cannot be typed, or a property marked `@untypeable`.
`SineMaculaLaravel.TypeHints.ParameterTypeHint`	A function or method parameter declares a native type - except where a parent fixes the signature: a method carrying `#[\Override]`, or a non-private trait method (whose effective parent is the consuming class's, invisible to a token sniff).
`SineMaculaLaravel.TypeHints.ReturnTypeHint`	A function, method or closure declares a native return type - except constructors/destructors/clone handlers and methods carrying `#[\Override]`.

Role-based structure

RequireRoleNaming and RequireRoleDirectory resolve a class's role by identity first - what it extends, implements, uses or is attributed with - and fall back to its location (a concrete class under a role directory, minus exempt sub-namespaces such as Concerns/Support/Contracts). A class with neither is unconstrained, so genuine domain classes are never flagged.

The default role table is convention-correct for Laravel: it never requires a suffix the framework leaves bare, and the idiomatic bare User model is honoured (the Model role's identity covers Authenticatable and Pivot). Every list - roleIdentities, roleLocations, requireSuffix, forbidSuffix, exemptNamespaces, moduleRootRoles - is a public sniff property a ruleset can override. Identity is matched on the immediate base by short name, so a project's own intermediate base (e.g. a BaseController) is supported by adding it to roleIdentities. An identity entry containing \ instead matches the qualified name resolved through the file's imports, which keeps same-named traits distinct: the Job role's Bus\Dispatchable entry identifies a sync job without ever matching the Events Dispatchable an idiomatic event uses. Test classes - by name, test-case base, or a tests/ path - play no role at all, so a test mirroring a role namespace (Tests\Unit\Policies\...) is never constrained.

Opt a class out entirely with an @role-exempt docblock tag or a #[NotARole] attribute (matched by short name; SineMacula\CodingStandardsLaravel\Attributes\NotARole ships so the reference also resolves under static analysis). Both hatches work with other attributes present on the class.

Type hints

The TypeHints.* sniffs replace the base standard's Slevomat native-type requirements with Laravel-aware equivalents (the base Slevomat MissingNativeTypeHint / MissingAnyTypeHint codes are excluded; the traversable-specification checks are kept). They are needed because the Slevomat sniffs are inheritance-blind: PHP forbids typing a property that overrides an untyped parent ($table, $fillable, …) or changing an inherited method signature, so the original rules force types that fatal at class load. Native types are still required everywhere else. The exempt property set is the configurable magicProperties list on PropertyTypeHint, and an overriding method opts its signature out with the native #[\Override] attribute. A non-private trait method is also exempt from the parameter requirement, since its effective parent is whatever the consuming class extends and a token sniff cannot resolve that.

magicProperties covers the framework base classes an application extends - models, factories, commands, migrations, API resources, middleware, the HTTP/console kernels, service providers and the exception handler. It cannot know about third-party or application base classes, so a property whose untyped parent declaration is out of the list's reach is marked @untypeable on its own docblock:

/**
 * The vendor base class declares this untyped, so PHP forbids typing it here.
 *
 * @untypeable
 */
protected $view;

Readonly properties

The base standard requires every public property to be readonly. An Eloquent model is exempt: it overrides the framework's public magic properties ($timestamps, $incrementing, …), which are declared non-readonly on the base class, and PHP forbids making an inherited property readonly. This standard sets the base sniff's ignoredParentClasses to the model bases (Model, Authenticatable, Pivot), matched by the immediate parent name as written.

PHPStan rules

Identifier	Enforces
`sineMaculaLaravel.castsProperty`	No `$casts` property on an Eloquent model (a class extending `Model`/`Authenticatable`/`Pivot`) - use the `casts()` method. A non-model class with its own `$casts` is left alone.
`sineMaculaLaravel.datesProperty`	No `$dates` property on a model (deprecated) - cast dates via `casts()`.
`sineMaculaLaravel.massAssignment`	Every concrete production model declares mass assignment explicitly via `$fillable`/`$guarded` or the `#[Fillable]`/`#[Guarded]` attribute; models declared in tests are exempt.
`sineMaculaLaravel.fillableCasts`	Every `$fillable` attribute (or `#[Fillable]` entry) on a model declares a matching cast in `casts()` (or a `$casts` property), documenting each settable field's type. Runs only on a concrete model directly extending `Model`/`Authenticatable`/`Pivot`; a `$fillable` or `casts()` that is not a plain enumerable literal (built from a variable, or merging `parent::casts()`) is skipped, and models declared in tests are exempt.
`sineMaculaLaravel.relationshipReturnType`	A relationship method declares a return-type hint.
`sineMaculaLaravel.modelAttribute`	Prefer a model attribute over its legacy property/method form, for the attributes a project enables (default `#[Table]`/`#[Fillable]`/`#[Hidden]`, configurable via `sineMaculaLaravel.modelAttributes`). The 13.2-only attributes are enforced only when the project's Laravel floor reaches 13.2 - taken from `sineMaculaLaravel.minLaravelVersion` or detected from the nearest `composer.json`; below that, or when undetectable, the property form is left alone.
`sineMaculaLaravel.modelAttributeLaggingFloor`	The legacy form of a 13.2-only attribute in a project whose `composer.lock` already resolves to 13.2 or above while its declared floor does not. Reported instead of the silence that would otherwise defer the whole migration to the day the floor is raised. A library that deliberately supports older versions can ignore this identifier and keep the enforcement one.
`sineMaculaLaravel.migrationMethods`	A migration defines both `up()` and `down()`.
`sineMaculaLaravel.schemaNaming`	Table and column names in a migration use snake_case. Inspects the literal name arguments of the `Schema` table calls and the Blueprint column/index methods (value arguments and dynamic names are left alone). Digits are allowed (`line_1`, `oauth2`); only casing is enforced.
`sineMaculaLaravel.formRequestRules`	A form request (under `Http\Requests`) defines a `rules()` method. Classes declared in tests, where the namespace merely mirrors the production tree, are exempt.
`sineMaculaLaravel.factoryTimestamps`	A factory `definition()` must not set `created_at` / `updated_at`.
`sineMaculaLaravel.resourceFieldNaming`	Field keys in a resource's `toArray()` result use snake_case, nested arrays included. Inspects the string-literal keys of the array returned directly from `toArray()` on a `JsonResource`; computed keys, a non-literal return, and non-resource classes are left alone. Digits are allowed (`line_1`); only casing is enforced.

Builder calls under the strict rules

Larastan reflects every method forwarded onto an Eloquent builder - the query methods and any #[Scope] - as a static method, so phpstan-strict-rules reads ordinary query code as a dynamic call to a static one:

Dynamic call to static method Illuminate\Database\Eloquent\Builder<App\Models\Credential>::whereNull().

That lands on essentially every query in a project, so this standard ignores it, scoped to the framework builders rather than turning the rule off - a genuine dynamic call to a static method elsewhere is still reported.

A model pointing at its own builder with #[UseEloquentBuilder] is reported against that class instead, which no shipped pattern can name. Add the matching entry to the project's own config:

parameters:
    ignoreErrors:
        -
            identifier: staticMethod.dynamicCall
            message: '#^Dynamic call to static method App\\Builders\\#'

Requirements

PHP ^8.3

Testing

composer test                # PHPUnit sniff/rule suite
composer test:coverage       # suite with Clover coverage output (requires Xdebug)
composer test:mutation       # Infection mutation gate (min MSI 90)
composer test:mutation:full  # full mutation suite without thresholds
composer analyse             # PHPStan over the package's own sniffs and rules
composer check               # static analysis and lint via qlty
composer format              # format via qlty
composer smells              # duplication / complexity smells via qlty

Changelog

See CHANGELOG.md for a list of notable changes.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines on branching, commits, code quality, and pull requests.

Security

If you discover a security vulnerability, please report it responsibly. See SECURITY.md for the disclosure policy and contact details.

License

Licensed under the Apache License, Version 2.0.

sinemacula / coding-standards-laravel

Maintainers

Package info

Statistics

Security

README

Installation

Usage

PHPCS

PHPStan

PHP CS Fixer

Rules

PHPCS sniffs

Role-based structure

Type hints

Readonly properties

PHPStan rules

Builder calls under the strict rules

Requirements

Testing

Changelog

Contributing

Security

License