README

Custom PHPStan rules that enforce PHPNomad framework conventions.

These rules catch architectural anti-patterns at static analysis time, including models with inline serialization, service locator usage, raw SQL, singleton abuse, missing interface implementations, database scope violations, cache misuse, and more.

Installation

composer require --dev phpnomad/phpstan-rules

If you use phpstan/extension-installer, the rules activate automatically.

Otherwise, add to your phpstan.neon:

includes:
    - vendor/phpnomad/phpstan-rules/extension.neon

Rules

Models

Identifier	Description
`phpnomad.model.notFinal`	Models implementing `DataModel` must be declared `final`.
`phpnomad.model.setter`	Models must not have setter methods (`set*`). Models are immutable.
`phpnomad.model.arrayMethod`	Models must not have `toArray()` or `fromArray()`. Use a separate adapter class.

Adapters

Identifier	Description
`phpnomad.adapter.notImplementing`	Classes named `*Adapter` or in `Adapters` namespaces must implement `ModelAdapter`. Exempts `MutationAdapter` implementations.

Events

Identifier	Description
`phpnomad.event.notImplementing`	Classes in `Events` namespaces or named `*Event` must implement `PHPNomad\Events\Interfaces\Event`.
`phpnomad.event.notFinal`	Event classes should be declared `final`.
`phpnomad.event.notReadonly`	Event properties and promoted constructor parameters should be `readonly`.
`phpnomad.listener.notImplementing`	Classes in `Listeners` namespaces or named `*Listener` must implement `CanHandle`.

DI / Container

Identifier	Description
`phpnomad.di.serviceLocator`	`InstanceProvider::get()` must not be called inside business classes. Use constructor injection. Calls inside initializers and bootstrappers are allowed.
`phpnomad.di.missingTrait`	Classes implementing `CanSetContainer` must use the `HasSettableContainer` trait.

Initializers

Identifier	Description
`phpnomad.initializer.useInterface`	Initializers should use `Has*` interfaces (e.g., `HasListeners`, `HasTaskHandlers`) instead of manually calling registration methods like `EventStrategy::attach()`.

Facades

Identifier	Description
`phpnomad.facade.notExtending`	Classes in `Facades` namespaces or named `*Facade` must extend `PHPNomad\Facade\Abstracts\Facade`.
`phpnomad.facade.noAbstractInstance`	Concrete Facade subclasses must implement `abstractInstance()`.

Database

Identifier	Description
`phpnomad.database.rawSql`	Raw SQL strings (`SELECT ... FROM`, `INSERT INTO`, etc.) must not appear in code. Use PHPNomad datastore patterns.
`phpnomad.database.scope`	`QueryBuilder`, `ClauseBuilder`, and `QueryStrategy` must only be used inside Datastore classes.
`phpnomad.database.concreteTableHint`	Constructor parameters should type-hint the `Datastore` interface, not concrete `Table` subclasses.

Controllers

Identifier	Description
`phpnomad.controller.noStatus`	Controller `getResponse()` must explicitly set an HTTP status code via `setStatus()` or `setError()`.

Console

Identifier	Description
`phpnomad.command.notImplementing`	Classes in `Commands` namespaces or named `*Command` must implement `PHPNomad\Console\Interfaces\Command`.
`phpnomad.command.handleReturnType`	Command `handle()` methods must declare an `int` return type.

Tasks

Identifier	Description
`phpnomad.task.notImplementing`	Classes in `Tasks` namespaces or named `*Task` must implement `PHPNomad\Tasks\Interfaces\Task`.
`phpnomad.taskHandler.notImplementing`	Task handler classes must implement `PHPNomad\Tasks\Interfaces\CanHandleTask`.
`phpnomad.task.directHandle`	Task handlers must be dispatched via `TaskStrategy::dispatch()`, not by calling `handle()` directly.

Cache

Identifier	Description
`phpnomad.cache.directStrategy`	Business classes should not inject `CacheStrategy` directly. Use `CacheableService` or a Facade.
`phpnomad.cache.uncaughtException`	`CacheStrategy::get()` throws `CachedItemNotFoundException`. Ensure the call is wrapped in a try/catch.
`phpnomad.cache.hardcodedTtl`	Do not hardcode TTL values as integer literals. Use a `CachePolicy` or configuration constant.
`phpnomad.cache.stringConcatKey`	Use the `HasCacheKey` interface for cache key generation instead of string concatenation.

General

Identifier	Description
`phpnomad.general.singletonInBusiness`	`::instance()` singleton calls must not be used outside of Facade classes. Use dependency injection.
`phpnomad.general.globalKeyword`	The `global` keyword must not be used. Use dependency injection.

Stack Elevator (layer purity)

Enforces the Stack Elevator doctrine (Novatorius coding standards KB: initiatives-nomadic-development-coding-standards-the-stack-elevator): code is layered Core (pure business concepts) → Service (implementation logic) → Platform (system integration), and dependencies only point upward (Platform → Service → Core). Layers are marked by namespace segments; because a layer name can also appear as a domain name (e.g. Novatorius\Quartermaster\Platform\Core\...), the last matching segment in a namespace determines its layer.

Identifier	Description
`phpnomad.stackElevator.coreDependsOnService`	Core-layer code must not import or reference Service-layer symbols.
`phpnomad.stackElevator.coreDependsOnPlatform`	Core-layer code must not import or reference Platform-layer symbols.
`phpnomad.stackElevator.coreDenylist`	Core-layer code must not reference denylisted third-party namespaces.
`phpnomad.stackElevator.serviceDependsOnPlatform`	Service-layer code must not import or reference Platform-layer symbols.
`phpnomad.stackElevator.serviceDenylist`	Service-layer code must not reference denylisted third-party namespaces.

Checked references: use statements, extends/implements, trait uses, property/parameter/return types, instantiations, static calls and constant fetches, instanceof, catch types, attributes, and fully qualified function calls. Doc-block-only references are not checked.

Adopting layer purity on its own

The Stack Elevator rules live in a self-contained stack-elevator.neon. To enforce layer purity without the rest of the convention ruleset (useful when first onboarding an existing codebase), disable the auto-loaded extension for this package and include only the layer-purity file:

"extra": {
    "phpstan/extension-installer": {
        "ignore": ["phpnomad/phpstan-rules"]
    }
}

includes:
    - vendor/phpnomad/phpstan-rules/stack-elevator.neon

The full extension.neon already includes stack-elevator.neon, so the default (all rules) behavior is unchanged.

All settings are configurable via phpstan.neon (defaults shown):

parameters:
    phpNomadStackElevator:
        checkCoreLayer: true
        checkServiceLayer: true
        namespaceRoots:            # vendor roots the convention applies to
            - Novatorius
            - PHPNomad
        coreSegments: [Core]       # namespace segments marking each layer
        serviceSegments: [Service]
        platformSegments: [Platform, WordPress, Integration]
        excludeNamespaces: []      # grandfathered namespace prefixes ("*" wildcards allowed)
        coreDenylist: []           # third-party prefixes Core may never reference
        serviceDenylist: []        # third-party prefixes Service may never reference

Existing repos will have violations when first enabling these rules. Grandfather them with excludeNamespaces (e.g. a composition root such as Novatorius\Quartermaster\Service, whose job is to wire all layers together) or a PHPStan baseline, then shrink the list over time.

Suppressing Rules

Use PHPStan's built-in ignore syntax:

// @phpstan-ignore phpnomad.model.notFinal
class User implements DataModel
{
    // ...
}

Or suppress in phpstan.neon via baseline:

vendor/bin/phpstan --generate-baseline

Requirements

PHP 8.2+
PHPStan 2.0+

License

MIT

phpnomad / phpstan-rules

Maintainers

Package info

Statistics

Security