Architecture & Plugins

## What an arch() test is An **architecture test** in Pest is a test that inspects the *structure* of your code rather than its behaviour. You start it with the `arch()` function instead of `test()` or `it()`, point it at a namespace (or a class, or a function name) with `expect()`, and chain one or more **arch expectations** such as `toUse()`, `toOnlyUse()`, `toOnlyBeUsedIn()`, `toExtend()` or `toBeFinal()`. Architecture testing relies on `pestphp/pest-plugin-arch`, a required dependency of Pest 5, so no extra install is needed. The target strings are namespaces like `'App\Http\Controllers'`, fully qualified class names like `'PDO'`, or global function names like `'mysqli_query'`. Since Pest 3.8 a target may also contain wildcards, such as `'App\*\Traits'`. ## Two ways to state "controllers must not touch the database" The rule can be written from either side of the dependency, and the two are not equivalent. | Form | Reads as | Catches | |---|---|---| | `expect('App\Http\Controllers')->not->toUse([...])` | these consumers may not reference those things | controllers only | | `expect('App\Database')->toOnlyBeUsedIn([...])` | only these namespaces may reference the layer | every other namespace, including new ones | | `expect('App\Http\Controllers')->toOnlyUse([...])` | these consumers may reference nothing else | controllers, against a strict allow-list | - The **consumer-side** rule (`not->toUse`) is a blacklist written about controllers. It is easy to read in a code review, but a queue job or a console command that opens `PDO` directly is outside its target and passes. - The **provider-side** rule (`toOnlyBeUsedIn`) is a whitelist written about the database layer. Anything outside the listed namespaces that references the layer fails, which makes it the stronger boundary. - `toOnlyUse()` is the strictest: the target may depend *only* on what is listed. It suits a small domain namespace; on controllers it tends to produce a long allow-list. Not every expectation can be negated: `not->toOnlyBeUsedIn()` throws an `InvalidExpectation` error in Pest 5, and `toBeUsed()` only works in its negated form, `not->toBeUsed()`. ## What the check sees, and what it does not 1. It looks at the files of the target namespace and the names they reference: imported classes, fully qualified names, global functions. 2. It does **not** follow calls. A controller that calls `OrderService::place()`, which in turn uses `PDO`, passes a `not->toUse('PDO')` rule on controllers. The layering rule has to be written for every layer that matters, not just the top one. 3. It does not execute your controllers, so it needs no database, HTTP kernel or fixtures, and it is cheap enough to run on every commit. ## Exceptions without eroding the rule Real codebases have a legacy class that breaks the rule today. The `ignoring()` modifier excludes named namespaces or classes from one expectation: ```php arch('controllers stay off the database layer') ->expect('App\Http\Controllers') ->not->toUse(['PDO', 'App\Database']) ->ignoring('App\Http\Controllers\LegacyReportController'); ``` The exception is now visible in the test file, reviewable, and removable in a later refactor. That is better than dropping the whole rule or moving the offender into another namespace to dodge it. ## Growing one rule into a layering set One boundary rarely describes an architecture. Teams usually end up with a handful of small rules, each stating one dependency direction: - `expect('App\Http\Controllers')->not->toUse(['PDO', 'App\Database'])` keeps HTTP code off persistence. - `expect('App\Domain')->not->toUse('App\Http')` keeps the domain free of request and response types. - `expect('App\ValueObjects')->toUseNothing()` states that value objects depend on nothing at all. - `expect('App\Database')->toOnlyBeUsedIn(['App\Repositories', 'App\Database'])` closes the persistence layer from the provider side. Written this way, a failure names exactly which direction was violated and in which file, so the fix is obvious from the CI log. One large rule that tries to express the whole architecture fails with a list nobody can act on. ## Where these tests live in a suite - Put them in an ordinary test file, for example `tests/Architecture/LayersTest.php`, so they run with every `./vendor/bin/pest` invocation and in CI. - Give each `arch()` call a description, `arch('controllers stay off the database layer')`, because the description is what the failure output and the CI log show. - Keep rules small and single-purpose: one boundary per `arch()` call gives one clear failure message listing the offending files. - Pair a layering rule with a naming or type rule when it helps, for example `expect('App\Http\Controllers')->toHaveSuffix('Controller')`. The value interviewers look for is that the boundary stops being a convention written in a wiki and becomes a failing test the moment someone adds `new PDO(...)` to a controller.