Add 12 Tier 2 PHPStan rules for deeper convention enforcement

Adds method-body analysis, constructor inspection, scope checking, and
cache usage rules. Total rule count is now 29. All rules pass PHPStan
level 8 self-analysis and produce no false positives against phpnomad/cli.

New rules: AdaptersMustImplement, CanSetContainerMustUseTrait,
InitializerUseHasInterfaces, ListenerNoBroadcastInHandle,
DatastoreTypeHintInterface, DatabaseScope, ControllerMustSetStatus,
TaskDispatchViaStrategy, NoCacheStrategyInBusiness,
CacheGetMustCatchException, NoHardcodedTtl, CacheKeyViaInterface.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: alexstandiford

README.md

@@ -2,7 +2,7 @@
 
 Custom [PHPStan](https://phpstan.org/) rules that enforce [PHPNomad](https://github.com/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, and missing interface implementations.
+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
 
@@ -29,6 +29,12 @@ includes:
 | `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 |
@@ -37,12 +43,20 @@ includes:
 | `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`. |
+| `phpnomad.listener.broadcastInHandle` | Listeners must not call `EventStrategy::broadcast()` from within their `handle()` method. Prevents infinite loops. |
 
 ### 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
 
@@ -56,6 +70,14 @@ includes:
 | 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
 
@@ -70,6 +92,16 @@ includes:
 |---|---|
 | `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
 

extension.neon

@@ -20,3 +20,15 @@ rules:
     - PHPNomad\PhpstanRules\Rules\General\NoGlobalKeywordRule
     - PHPNomad\PhpstanRules\Rules\Tasks\TasksMustImplementRule
     - PHPNomad\PhpstanRules\Rules\Tasks\TaskHandlersMustImplementRule
+    - PHPNomad\PhpstanRules\Rules\Adapters\AdaptersMustImplementRule
+    - PHPNomad\PhpstanRules\Rules\Di\CanSetContainerMustUseTraitRule
+    - PHPNomad\PhpstanRules\Rules\Initializers\InitializerUseHasInterfacesRule
+    - PHPNomad\PhpstanRules\Rules\Events\ListenerNoBroadcastInHandleRule
+    - PHPNomad\PhpstanRules\Rules\Database\DatastoreTypeHintInterfaceRule
+    - PHPNomad\PhpstanRules\Rules\Database\DatabaseScopeRule
+    - PHPNomad\PhpstanRules\Rules\Controllers\ControllerMustSetStatusRule
+    - PHPNomad\PhpstanRules\Rules\Tasks\TaskDispatchViaStrategyRule
+    - PHPNomad\PhpstanRules\Rules\Cache\NoCacheStrategyInBusinessRule
+    - PHPNomad\PhpstanRules\Rules\Cache\CacheGetMustCatchExceptionRule
+    - PHPNomad\PhpstanRules\Rules\Cache\NoHardcodedTtlRule
+    - PHPNomad\PhpstanRules\Rules\Cache\CacheKeyViaInterfaceRule

lib/Rules/Adapters/AdaptersMustImplementRule.php

@@ -0,0 +1,77 @@
+<?php
+
+namespace PHPNomad\PhpstanRules\Rules\Adapters;
+
+use PhpParser\Node;
+use PhpParser\Node\Stmt\Class_;
+use PHPStan\Analyser\Scope;
+use PHPStan\Node\InClassNode;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+
+/**
+ * @implements Rule<InClassNode>
+ */
+class AdaptersMustImplementRule implements Rule
+{
+    private const MODEL_ADAPTER_INTERFACE = 'PHPNomad\Datastore\Interfaces\ModelAdapter';
+    private const MUTATION_ADAPTER_INTERFACE = 'PHPNomad\Mutator\Interfaces\MutationAdapter';
+
+    public function getNodeType(): string
+    {
+        return InClassNode::class;
+    }
+
+    public function processNode(Node $node, Scope $scope): array
+    {
+        $classReflection = $node->getClassReflection();
+        $originalNode = $node->getOriginalNode();
+        if (!$originalNode instanceof Class_) {
+            return [];
+        }
+
+        if ($classReflection->isAbstract()) {
+            return [];
+        }
+
+        $className = $classReflection->getName();
+
+        if (!$this->looksLikeAdapter($className, $originalNode)) {
+            return [];
+        }
+
+        if ($classReflection->implementsInterface(self::MUTATION_ADAPTER_INTERFACE)) {
+            return [];
+        }
+
+        if ($classReflection->implementsInterface(self::MODEL_ADAPTER_INTERFACE)) {
+            return [];
+        }
+
+        return [
+            RuleErrorBuilder::message(
+                'Adapter classes must implement PHPNomad\Datastore\Interfaces\ModelAdapter.'
+            )
+                ->identifier('phpnomad.adapter.notImplementing')
+                ->build(),
+        ];
+    }
+
+    private function looksLikeAdapter(string $className, Class_ $node): bool
+    {
+        $shortName = substr($className, strrpos($className, '\\') + 1);
+
+        if (str_ends_with($shortName, 'Adapter')) {
+            return true;
+        }
+
+        if ($node->namespacedName !== null) {
+            $namespace = $node->namespacedName->toString();
+            if (str_contains($namespace, '\Adapters\\')) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}

lib/Rules/Cache/CacheGetMustCatchExceptionRule.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace PHPNomad\PhpstanRules\Rules\Cache;
+
+use PhpParser\Node;
+use PhpParser\Node\Expr\MethodCall;
+use PhpParser\Node\Identifier;
+use PHPStan\Analyser\Scope;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+use PHPStan\Type\ObjectType;
+
+/**
+ * @implements Rule<MethodCall>
+ */
+class CacheGetMustCatchExceptionRule implements Rule
+{
+    private const CACHE_STRATEGY = 'PHPNomad\Cache\Interfaces\CacheStrategy';
+    private const FACADE = 'PHPNomad\Facade\Abstracts\Facade';
+
+    public function getNodeType(): string
+    {
+        return MethodCall::class;
+    }
+
+    public function processNode(Node $node, Scope $scope): array
+    {
+        if (!$node->name instanceof Identifier) {
+            return [];
+        }
+
+        if ($node->name->toString() !== 'get') {
+            return [];
+        }
+
+        $callerType = $scope->getType($node->var);
+        $cacheType = new ObjectType(self::CACHE_STRATEGY);
+
+        if (!$cacheType->isSuperTypeOf($callerType)->yes()) {
+            return [];
+        }
+
+        $classReflection = $scope->getClassReflection();
+
+        if ($classReflection === null) {
+            return [];
+        }
+
+        if ($classReflection->implementsInterface(self::CACHE_STRATEGY)) {
+            return [];
+        }
+
+        $parent = $classReflection->getParentClass();
+        while ($parent !== null) {
+            if ((string) $parent->getName() === self::FACADE) {
+                return [];
+            }
+            $parent = $parent->getParentClass();
+        }
+
+        return [
+            RuleErrorBuilder::message(
+                'CacheStrategy::get() throws CachedItemNotFoundException. Ensure this call is wrapped in a try/catch.'
+            )
+                ->identifier('phpnomad.cache.uncaughtException')
+                ->tip('Catch CachedItemNotFoundException or use the Cache facade\'s load() method instead.')
+                ->build(),
+        ];
+    }
+}

lib/Rules/Cache/CacheKeyViaInterfaceRule.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace PHPNomad\PhpstanRules\Rules\Cache;
+
+use PhpParser\Node;
+use PhpParser\Node\Expr\MethodCall;
+use PhpParser\Node\Identifier;
+use PHPStan\Analyser\Scope;
+use PHPStan\Rules\Rule;
+use PHPStan\Rules\RuleErrorBuilder;
+use PHPStan\Type\ObjectType;
+
+/**
+ * @implements Rule<MethodCall>
+ */
+class CacheKeyViaInterfaceRule implements Rule
+{
+    private const CACHE_STRATEGY = 'PHPNomad\Cache\Interfaces\CacheStrategy';
+
+    private const KEY_METHODS = ['get', 'set', 'delete', 'exists'];
+
+    public function getNodeType(): string
+    {
+        return MethodCall::class;
+    }
+
+    public function processNode(Node $node, Scope $scope): array
+    {
+        if (!$node->name instanceof Identifier) {
+            return [];
+        }
+
+        if (!in_array($node->name->toString(), self::KEY_METHODS, true)) {
+            return [];
+        }
+
+        $callerType = $scope->getType($node->var);
+        $cacheType = new ObjectType(self::CACHE_STRATEGY);
+
+        if (!$cacheType->isSuperTypeOf($callerType)->yes()) {
+            return [];
+        }
+
+        if (count($node->getArgs()) < 1) {
+            return [];
+        }
+
+        $keyArg = $node->getArgs()[0]->value;
+
+        if ($keyArg instanceof \PhpParser\Node\Expr\BinaryOp\Concat
+            || $keyArg instanceof \PhpParser\Node\Scalar\InterpolatedString) {
+            return [
+                RuleErrorBuilder::message(
+                    'Use HasCacheKey interface for cache key generation instead of string concatenation.'
+                )
+                    ->identifier('phpnomad.cache.stringConcatKey')
+                    ->build(),
+            ];
+        }
+
+        return [];
+    }
+}