Maintaining Context & Developer Experience

FW solves common architectural challenges through Explicit Compilation and Strict Typing.

How Developers and Agents Maintain Project Awareness

1. Declarative Truth over Imperative Discovery: Instead of needing to read dozens of PHP files to understand the routing matrix or the database schema, developers only need to read two files:

   • database/schema.yaml: The absolute truth of the data layer.
   • api/*.yaml: The absolute truth of the external API surface. Running fw build:api and fw build:db guarantees the underlying PHP code correctly reflects those changes.

2. Zero Runtime Reflection (Static Container): Because the dependency injection container (build/container.php) is generated at compile time, static analysis tools (or PHPStan/Psalm) can analyze exactly what dependencies are injected where, without needing to execute the application.

3. Strict Data Mapper ORM (No N+1): By using strictly typed readonly class Models (e.g., UserModel), you know exactly what data is available. Accidental N+1 queries are eliminated entirely, as queries must be explicitly formulated in the Repository.

Standard Tools & Workflows

When working on an FW application, you should rely on these tools:

1. FW CLI (php fw):

   • fw build:api: Regenerates routes, handlers, and DTOs from api/*.yaml.
   • fw build:db: Regenerates typed models and repository interfaces from database/schema.yaml.
   • fw build:migrations: Dumps pure SQL schema diffs.
   • fw build:container: Autowires the entire dependency graph via AST/Reflection into a static file.

2. PHPStan (Level 8 or 9) & Psalm (Level 1): FW is designed to pass strict static analysis seamlessly. Since everything is explicitly typed and compiled, running vendor/bin/phpstan analyse will instantly tell you if your assumptions about types or method signatures are wrong.

3. Modular Architecture: We enforce a strict modules/ directory structure. Context can be isolated to modules/User/ without needing to ingest the entire modules/Orders/ domain.

MSPs (Modular Service Providers) in Development

While developing the FW framework itself (or applications using it), having continuous background tools is highly beneficial:

• File Watchers: A tool like chokidar or npm run watch (if set up) that listens to file changes and automatically triggers:
  1. php fw build:container
  2. docker compose restart app (to refresh the Swoole memory loop)
  3. vendor/bin/phpstan analyse
• Continuous Testing: A background worker running pest or phpunit immediately on save.

By relying on compilation and strict typing, you never have to "guess" how the application will behave at runtime.