Repository navigation
Released: StructArmed 0.21.0
StructArmed 0.21.0 introduces a new Enum preset, stronger API stability checks, signature type analysis for custom rules, and improved enum formatting support.
This release introduces:
- the new
Preset::ENUM()for validating string-backed enum case values; ApiMayNotExposeInternalRulefor preventing public APIs from exposing internal types;ClassSignatureandSignatureTypesAwareRuleInterfacefor analyzing member signature types;- the new fixable
EnumCaseMustBeOnOwnLineRulein the PER preset; - improved backed enum value resolution and analysis cache support.
New Enum Preset
StructArmed introduces a new preset for validating string-backed enum case values:
Preset::ENUM()The preset includes two new rules:
EnumCaseValueMustNotBeEmptyRule— prevents empty string-backed enum values.EnumCaseValueMustNotHaveSurroundingWhitespaceRule— prevents leading or trailing whitespace in string-backed enum values.
For example:
enum Status: string
{
case Pending = '';
case Active = ' active ';
case Completed = 'completed';
}The first two cases produce violations, while Completed is valid.
The rules check statically resolved string-backed values. Pure enums and integer-backed enums are unaffected.
These rules do not support --fix, as changing backing values could break existing APIs or persisted data.
Enable the preset with:
use Boundwize\StructArmed\Preset\Preset;
// In your architecture configuration:
->withPreset(Preset::ENUM())Or initialize a new configuration:
vendor/bin/structarmed init --preset=enumAPI Stability Improvements
The Stability preset now includes ApiMayNotExposeInternalRule, preventing @api declarations from exposing @internal types through public or protected signatures.
For example:
/** @internal */
class InternalService
{
}
/** @api */
class PublicService
{
public function getService(): InternalService
{
return new InternalService();
}
}The rule reports an architecture violation because the public method exposes an internal implementation.
The rule checks:
- public and protected method parameter types;
- public and protected method return types;
- public and protected property types;
- constructor-promoted parameters that expose internal types.
Private implementation details remain unrestricted, except when exposed through a public or protected constructor parameter.
Only types within the scanned project are checked, since external declarations may not have available PHPDoc information.
New Signature Type Analysis
StructArmed introduces ClassSignature and SignatureTypesAwareRuleInterface for analyzing types referenced in class-like member signatures.
Each ClassSignature provides:
type— fully qualified referenced type;name— originating property, parameter, or method;kind— property, parameter, or method;visibility— public, protected, or private;line— source line.
Custom rules can implement SignatureTypesAwareRuleInterface to access signature information through $classNode->signatures.
Custom Rule Example
For example, prevent public repository methods from returning Doctrine's QueryBuilder:
<?php
declare(strict_types=1);
namespace App\Architecture\Rules;
use Boundwize\StructArmed\Analyser\ClassNode;
use Boundwize\StructArmed\Analyser\ClassSignature;
use Boundwize\StructArmed\Rule\RuleViolation;
use Boundwize\StructArmed\Rule\SignatureTypesAwareRuleInterface;
use Doctrine\ORM\QueryBuilder;
final readonly class MayNotReturnQueryBuilderRule implements SignatureTypesAwareRuleInterface
{
public function appliesTo(ClassNode $classNode): bool
{
return $classNode->nameEndsWith('Repository');
}
public function evaluate(ClassNode $classNode): ?RuleViolation
{
foreach ($classNode->signatures as $signature) {
if (
$signature->kind !== ClassSignature::METHOD
|| $signature->visibility !== 'public'
|| $signature->type !== QueryBuilder::class
) {
continue;
}
return new RuleViolation(
message: 'Public repository methods must not return QueryBuilder',
file: $classNode->file,
line: $signature->line,
className: $classNode->className,
layer: $classNode->layer,
);
}
return null;
}
}With this rule, the following method produces a violation:
final class UserRepository
{
public function createQuery(): QueryBuilder
{
// ...
}
}This allows repositories to use QueryBuilder internally without exposing it through their public APIs.
Signature collection is enabled only when an active rule implements SignatureTypesAwareRuleInterface, avoiding unnecessary analysis overhead and cache storage.
The collector supports nullable, union, intersection, and DNF types, including constructor-promoted properties.
PER Coding Style Improvements
The PER preset now includes EnumCaseMustBeOnOwnLineRule, requiring each enum case to be declared on its own line.
For example:
enum Status
{
case Pending; case Active;
}The rule supports automatic fixing:
vendor/bin/structarmed analyse --fixResult:
enum Status
{
case Pending;
case Active;
}The fixer preserves associated comments when moving enum cases, including comments on shared lines.
Bug Fixes and Internal Improvements
- Improve backed enum value resolution for local constants, including forward references.
- Add
EnumCaseNode::sharesLinefor detecting enum cases that share a line with another member or enum brace. - Improve comment preservation when automatically formatting enum cases.
- Extend analysis caching to support optional signature collection.
- Update documentation and test coverage.
What's Changed
- Add API signature exposure analysis and
ClassSignaturesupport in #524 and #526. - Improve backed enum value resolution in #529.
- Add fixable enum case formatting to the PER preset in #530.
- Introduce the new Enum preset and validation rules in #536 and #537.
- Preserve comments when moving enum cases onto separate lines in #538.
- Prepare the 0.21.0 release in #525.
Full Changelog: 0.20.5...0.21.0