Upgrade guide

July 30, 2026 · View on GitHub

This document lists the breaking changes you need to address when upgrading PHPArkitect, ordered from the most recent version to the oldest.

If a release is not listed here, it contains no breaking changes and you can upgrade to it without modifying your configuration.

1.3.0

`--ignore-baseline-linenumbers` is deprecated

Baseline matching no longer depends on line numbers: a violation is identified by its class and by what it reports, so an edit above the offending line does not reopen a known violation, and two violations of the same rule in the same class stay distinct. The option that used to select this behaviour has no effect and prints a deprecation notice, both from the CLI and from phparkitect.php:

- phparkitect check --ignore-baseline-linenumbers
+ phparkitect check

- $config->ignoreBaselineLinenumbers(true);
+ $config;

It will be removed in the next major version.

generate-baseline now always writes line numbers — the option no longer strips them. Existing baselines keep working and need no regeneration, whether or not they store line numbers, and prune-baseline still preserves the format it finds.

`check --generate-baseline` is now the `generate-baseline` command

Generating a baseline was an action disguised as a check option: it ran a different flow, printed no violations and always exited successfully. It is now a dedicated command:

- phparkitect check --generate-baseline
+ phparkitect generate-baseline

- phparkitect check --generate-baseline my-baseline.json
+ phparkitect generate-baseline my-baseline.json

The optional filename is now an argument (still defaulting to phparkitect-baseline.json), and the command accepts the same --config, --target-php-version and --autoload options as before. The check-only options that never affected generation (--stop-on-failure, --format, --use-baseline, --skip-baseline) are no longer accepted.

check --generate-baseline is kept as a failing stub that points to the new command, so an old CI invocation fails loudly with a migration hint instead of silently doing nothing.

1.0.0

PHP 7 support dropped

The minimum supported PHP version is now 8.0. If you are still on PHP 7.x, stay on the 0.8.x line.

`--autoload` is mandatory when running as a Phar

When running the Phar, you must now pass the autoload file explicitly:

- php phparkitect.phar check
+ php phparkitect.phar check --autoload vendor/autoload.php

`*` in `excludePath()` no longer crosses directory separators

ClassSet::excludePath() was reworked so that * matches within a single directory segment. Use the new ** wildcard to restore the previous greedy behaviour that matched across any number of directory levels:

- $set->excludePath('src/*/Test.php');   // used to match src/A/B/C/Test.php
+ $set->excludePath('src/**/Test.php');  // matches at any depth

Most simple patterns (Tests/*, *Test.php) are unaffected, because they are consumed as a substring match.

User-defined classes in the global namespace are now evaluated

PHP core classes are now auto-excluded from dependency checks via reflection (isInternal()) — you no longer need to list \Exception, \DateTime, MongoDB\Driver\Manager, etc. in your rules.

As a consequence, the previous "skip everything in the root namespace" shortcut in DependsOnlyOnTheseNamespaces and NotDependsOnTheseNamespaces was removed. User-defined classes in the global namespace are now evaluated against your rules — they used to be silently skipped.

- new DependsOnlyOnTheseNamespaces('App\Domain', 'App\Infrastructure')
+ new DependsOnlyOnTheseNamespaces(['App\Domain', 'App\Infrastructure'])

- new NotDependsOnTheseNamespaces('App\Domain', 'App\Infrastructure')
+ new NotDependsOnTheseNamespaces(['App\Domain', 'App\Infrastructure'])