FW Ecosystem: Static Analysis Guidelines

The FW framework is built natively for absolute strictness, meaning the codebase must be optimized for static analysis and AST parsing.

1. Zero "Magic", 100% Static Analysis

Implicit resolution or dynamic mixins make code difficult to discover or analyze cleanly.

• Extreme Strictness: FW enforces maximum strictness by default. If it doesn't pass Psalm Level 1 and PHPStan Max Level, it does not compile.
• Compile-Time Rejection: The php vendor/bin/fw build command will automatically run static analysis under the hood. If your PHP code is ambiguous, build will fail. This prevents bad code from ever reaching the persistent runtime.
• Strict Typing: All files must declare declare(strict_types=1);.
• Explicit Imports: Everything must be imported. No global helpers that hide dependency injection.
• Readonly Classes: State mutation is a source of bugs for AI. Models and DTOs should be immutable (readonly class in PHP 8.2+).

2. Granular, Predictable Structure

Developers and automated tools perform best when modifying small, isolated files rather than gigantic Controller classes.

• One Handler per Endpoint: The Action Route -> Handler mapping means you only need to read one small [Name]Handler.php file to understand an endpoint.

3. Machine-Readable Artifacts

Because FW uses a build step (php vendor/bin/fw build), the framework can natively emit structured metadata:

• build/ast.json: An abstract syntax tree dump of the routing and DI graph.
• build/openapi.json: OpenAPI schemas auto-generated from code to provide an instant understanding of the API surface.

4. DTOs and Payload Typing

Instead of grabbing inputs via $request->get('name'), inputs map natively to typed DTOs.

readonly class CreateUserProtocol {
    public function __construct(
        public string $email,
        public int $age
    ) {}
}

The framework's Request Pipeline automatically parses JSON, validates it against the types, and injects the DTO.