Download the PHP package boundwize/structarmed without Composer

StructArmed

Configurable PHP architecture guards — define your layers and rules, then keep them enforced.

Turn architecture rules into executable checks

• Make architecture decisions executable, not just documented.
• Start with ready-made presets for common architecture styles.
• Tune, override, or skip individual preset rules in native PHP code.
• Catch boundary violations before they quietly become conventions.

Installation

Quick start

Generates a structarmed.php in your project root. Edit it to match your structure, then run:

If violations are found, the output reports each one:

If everything passes, you get a clean summary:

Configuration

Default

Multiple presets

Cache directory

StructArmed stores analysis cache in the system temp directory by default. You can configure a project cache directory:

Relative cache directories are resolved from the project root. --config also controls the cache directory used by analyse and --clear-cache.

Custom layers and rules

Inside skip(), string entries skip files or directories unless they match a registered rule key, keyed entries skip paths for one specific rule, and rule key constants skip that rule entirely. You can also use skipPath() / skipPaths() and skipRule() / skipRules() when you prefer the explicit methods.

Use replaceRule() to swap a preset rule's configuration — it throws RuleNotFoundException if the key does not exist, so a typo is caught immediately. Use rule() to add new custom rules; it can also overwrite an existing key, but silently, with no verification that the target exists.

Layer resolution

Layers are resolved by file path — no attributes needed on classes:

Layer patterns (namespace-based layers)

When your architecture is expressed through namespace conventions rather than directory structure, use layerPattern() to resolve layers by matching the fully-qualified class name against a regex:

An optional third argument excludes classes whose FQN matches a second regex, even when the first matches:

Declarative ruleset

Once layers are defined (via layer() or layerPattern()), declare which layers each layer is allowed to depend on. Any dependency that resolves to a layer not in the allowed list is a violation:

Layers absent from the ruleset keys are not checked. Dependencies on external (non-registered) classes are always allowed.

Same-layer dependencies are always allowed regardless of the ruleset.

Skipping class-level violations

When a specific class-to-class dependency is a known exception, suppress it without disabling the whole layer rule:

The first argument is the fully-qualified violating class name; the second is one or more dependency FQNs to ignore for that class.

Excluding paths from ruleset checks only

Test files often cross layer boundaries by design. Use skipPathsForRuleset() to exclude paths from ruleset evaluation while still scanning them for all other rules (e.g. PSR-4 namespace checks):

This is different from skipPaths() / skipPath(), which exclude files from all analysis.

Custom presets

A custom preset is a class that implements Boundwize\StructArmed\Preset\PresetInterface. Inside apply(), add the layers and rules you want to reuse:

Register it in structarmed.php:

Preset constructor parameters

Available presets

PHPUnit extension

Run architecture checks as part of your test suite:

Violations cause the test run to fail before any tests execute.

CLI analyse commands

Tips

Rule key constants

Every preset rule has a public constant. Use constants, never raw strings:

Adopting existing projects

Fix reported violations where practical before reaching for a baseline. If the remaining findings are too large to resolve in one pass, generate a baseline to record the known violations:

Then reference it from your config:

Baseline entries are matched against future analysis results, so existing violations stay quiet while new violations still fail the run.

Do not use a baseline to hide issues you can fix now; treat it as a migration aid for legacy findings that should be reduced over time.