README

Scafera Layered is an opinionated architecture package for the Scafera framework. It defines and enforces a strict, layered approach for building applications.

Provides: Opinionated layered architecture for Scafera — defines six layers (Controller/, Service/, Repository/, Integration/, Entity/, Command/) with downward-only dependencies, and enforces them at build time via validators, advisors, and code generators run through scafera validate and scafera make:*.

Depends on: A Scafera host project where the kernel discovers this package via extra.scafera-architecture in composer.json. User code lives in the six layer directories under src/.

Extension points:

• Layer directories — user code goes in src/Controller/, src/Service/, src/Repository/, src/Integration/, src/Entity/, src/Command/; each has naming/location rules enforced at build time
• Generators — scafera make:controller, make:service, make:command scaffold a class + test with conventions baked in; support nested names (e.g. Order/Create)
• Validators and advisors — contributed via kernel's scafera.validator and scafera.advisor tags; run by scafera validate in CI
• Kernel primitives — user controllers use #[Route] (kernel), commands use #[AsCommand] (kernel)

Not responsible for: Capability concerns — persistence (scafera/database), presentation (scafera/frontend), authentication (scafera/auth), forms (scafera/form), logging (scafera/log), assets (scafera/asset), external integrations (scafera/integration), translations (scafera/translate), file handling (scafera/file) · implicit execution via event subscribers or listeners (blocked by ImplicitExecutionValidator) · flexible or non-layered architectures (use a different architecture package).

Philosophy

In Scafera, architecture is not a guideline — it is an installed package.

This package enforces every convention at validation time via scafera validate, designed to run in CI. Violations are caught before code ships, not after.

All execution is explicit: no event subscribers, no listeners, no auto-discovered side effects. If behavior is not visible in the code being read, it does not happen.

Architecture model

The package organizes application code into six layers:

Dependencies flow downward. Repository and Integration are siblings — both called by Service, neither depends on the other:

Controller → Service → Repository   → Entity
Command  ↗         ↘ Integration ↗

Validators

Twelve validators enforce the layered conventions:

Advisors

Non-blocking hints that never affect the exit code:

The test sync advisor requires git and gracefully skips with a reason when prerequisites are not met.

Generators

Scaffold new files with conventions baked in:

All generators support nested names (e.g. Order/Create, Report/Generate) and reject convention-violating suffixes like Controller or Command.

Project structure

src/
├── Controller/    ← single-action, attribute routing
│   ├── Home.php
│   └── Order/
│       ├── Create.php
│       └── List.php
├── Command/       ← #[AsCommand], delegate to services
├── Service/       ← all business logic
├── Repository/    ← data access
├── Integration/   ← third-party service wrappers
└── Entity/        ← domain data
tests/
├── Controller/    ← one test per controller
├── Command/       ← one test per command
└── Service/       ← unit tests where needed

When to use

Use this package when you want:

• Strong conventions and predictable structure
• Clear separation of responsibilities
• Automated enforcement of architectural rules

Avoid this package if you require a flexible or custom architecture with minimal constraints.

Installation

composer require scafera/layered

The kernel discovers it automatically via the scafera-architecture Composer extra field.

Requirements

• PHP >= 8.4
• scafera/kernel

License

MIT