Skip to content

Released: StructArmed 0.20.0

Choose a tag to compare

@samsonasik samsonasik released this 29 Oct 17:01
· 275 commits to main since this release
0.20.0
f137d01

ci build PHPStan

StructArmed 0.20.0 introduces a new Stability preset, modular architecture configuration, and an option to run analysis without persistent caching.

This release introduces:

  • the new Preset::STABILITY() for protecting public APIs from internal implementation details;
  • isApi and isInternal properties on ClassNode for custom rule development;
  • Architecture::import() for splitting architecture configuration across multiple files;
  • --no-cache for running analysis without persistent caching;
  • improved PSR-4 validation and cache cleanup safety.

New Stability Preset

StructArmed introduces a new preset for enforcing API stability:

Preset::STABILITY()

The preset includes two new rules:

  • ApiMayNotBeInternalRule — prevents declarations from being marked with both @api and @internal.
  • ApiMayNotExtendInternalRule — prevents @api classes and interfaces from extending @internal declarations, directly or through inheritance.

For example:

/** @internal */
class InternalService
{
}

/** @api */
class PublicService extends InternalService
{
}

The Stability preset reports an architecture violation because a public API extends an internal implementation.

Enable the preset with:

use Boundwize\StructArmed\Preset\Preset;

->withPreset(Preset::STABILITY())

Or initialize a new configuration:

vendor/bin/structarmed init --preset=stability

API and Internal Detection on ClassNode

ClassNode now exposes two new boolean properties:

  • $classNode->isApi — indicates whether the declaration has an @api PHPDoc tag.
  • $classNode->isInternal — indicates whether the declaration has an @internal PHPDoc tag.

These properties are available to custom architecture rules, making it easier to enforce project-specific API stability and visibility conventions.

For example:

public function appliesTo(ClassNode $classNode): bool
{
    return $classNode->isApi && ! $classNode->isInternal;
}

The properties are populated automatically during analysis for scanned class-like declarations, including classes, interfaces, traits, and enums.

Import Architecture Configuration

StructArmed now supports organizing architecture configuration across multiple files using Architecture::import().

For example:

use Boundwize\StructArmed\Architecture;

return Architecture::define()
    ->import(__DIR__ . '/module/Foo/structarmed.php')
    ->import(__DIR__ . '/module/Bar/structarmed.php');

Each imported file returns a callable that receives the root Architecture instance:

use Boundwize\StructArmed\Architecture;

return static function (Architecture $architecture): void {
    $architecture->layer('Foo', 'module/Foo/src/');
};

This allows architecture rules and layers to be organized by module while sharing the same configuration.

Imported configurations support:

  • nested imports with circular import protection;
  • paths resolved relative to the project root;
  • automatic analysis cache invalidation when imported files change.

This makes StructArmed easier to configure and maintain in modular applications and larger projects.

New --no-cache Option

StructArmed introduces a new CLI option:

vendor/bin/structarmed analyse --no-cache

This option runs analysis without reading from or writing to the persistent analysis cache.

It is useful for debugging, validating uncached analysis, and environments where persistent caching is not desired.

The option supports both sequential and parallel analysis.

--no-cache cannot be combined with --clear-cache.

Bug Fixes and Internal Improvements

  • Fix PSR-4 validation for .class.php files.
  • Report files that map to invalid PSR-4 class names.
  • Improve temporary cache directory cleanup after parallel --no-cache analysis.
  • Prevent cache directory removal races between concurrent runs.
  • Update documentation and test coverage.

What's Changed

  • Add --no-cache option in #507.
  • Add the new Stability preset, API rules, and ClassNode API/internal detection in #510.
  • Clean up temporary cache directories after parallel --no-cache analysis in #513.
  • Fix PSR-4 validation for .class.php files in #516.
  • Report invalid PSR-4 class names in #517.
  • Add modular architecture configuration imports in #522.
  • Fix concurrent cache directory cleanup in #523.

Full Changelog: 0.19.10...0.20.0