Skip to content

Allow glob patterns in includes - #7099

Closed
westonruter wants to merge 7 commits into
phpstan:2.3.xfrom
westonruter:glob-includes
Closed

westonruter wants to merge 7 commits into
phpstan:2.3.xfrom
westonruter:glob-includes

Conversation

@westonruter

@westonruter westonruter commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

An entry in includes can now be a glob pattern, which includes every matching file in alphabetical order, as if each had been listed in its place:

includes:
	- modules/*/phpstan.neon
	- baselines/*.neon

This lets a config pull in a set of files whose membership changes over time without keeping an explicit list in sync. Two cases motivate it:

Behavior

  • Matches are sorted with sort() rather than relying on glob()'s order, since the order of includes decides how values merge. Later files override earlier ones, as with consecutive explicit entries.
  • Only files are included; a directory that happens to match (e.g. foo.neon/) is skipped.
  • A pattern that matches nothing includes nothing. This lets the last file in a directory be deleted, e.g. once a baseline has been fixed to zero. But the directory the pattern is matched in (the part before the segment with the first metacharacter, like modules/ in modules/*/phpstan.neon) has to exist, so that a typo like baseline/*.neon fails like a missing plain include does, rather than silently including nothing.
  • Only the entry as written is a pattern. The directory of the including file, which a relative entry resolves against, is escaped before it goes to glob(), so a project under a path like Projects [old]/ works, and a missing plain include there is still reported as missing.
  • An entry that names an existing file is never treated as a pattern, so a file whose name contains *, ?, or [ can still be included as before. Pattern detection looks for the same characters as FileExcluder::isFnmatchPattern(), but with strpbrk() rather than a regex, since every include is checked whenever the config is loaded.
  • Only entries in includes are expanded, not top-level config files such as those given with --configuration.
  • The files being loaded at the time are left out of the matches. So a loader can sit among the files it includes, like baselines/_loader.neon containing includes: [*.neon], without including itself. Passing that loader's path as the target, as in --generate-baseline=baselines/_loader.neon, skips it along with every file it matches, so the whole split baseline is regenerated in one run.
  • --generate-baseline still skips its target file when a pattern matches it.
  • Parameters such as %currentWorkingDirectory% are expanded before the pattern is matched, and relative patterns resolve against the including file, just like plain entries.

Implementation

Includes are followed in two places, and both expand patterns through a shared IncludedFilePattern helper:

  • NeonLoader, which builds the config. Nette's Loader::load() calls expandIncludedFile() with each entry as written and passes the result back to load(), so NeonLoader overrides both: the first matches the pattern, and the second loads the matched files. The parent's load() doesn't have to be reimplemented.
  • ContainerFactory::getConfigFiles(), which collects the config files. These feed the container cache key, so adding or removing a matched file recompiles the container.

The merge in NeonLoader uses Nette\Schema\Helpers::merge() like ContainerFactory does, so it gets the same staticMethod.internalClass baseline entry.

Testing

  • IncludedFilePatternTest covers ordering, non-file matches, empty matches, missing directories, existing files with metacharacters in their names, an including directory with metacharacters in its path, and leaving out the files being loaded.
  • GlobIncludesTest builds a container from fixtures and checks the merged ignoreErrors, the override order, and allConfigFiles, and that a top-level config path is not expanded.
  • On WordPress core, replacing its 31 explicitly listed baseline includes with tests/phpstan/baselines/*.neon gives identical dump-parameters output, apart from the name of the top-level config file.

🤖 Generated with Claude Code using Claude Opus 5.5 (medium effort)

westonruter and others added 6 commits November 16, 2026 13:01
An entry in `includes` can now be a glob pattern, like
`baselines/*.neon`, which includes every matching file in alphabetical
order, as if each were listed in its place. This makes a baseline split
into one file per error identifier (or per directory) a single line in
the config, so that files can be added or deleted as errors are fixed
without also editing the list of includes.

A pattern that matches nothing includes nothing, so the last baseline
file can be deleted once its errors are fixed. A path that names an
existing file is never treated as a pattern, so a file whose name
contains a glob metacharacter can still be included.

Both places that follow includes expand the pattern: `NeonLoader`, which
builds the config, and `ContainerFactory::getConfigFiles()`, which
collects the config files. The latter feeds the container cache key, so
adding or removing a matched file recompiles the container.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tnky3HeNQTYTAish2dfgd9
Claude-Code-Session-Id: 020072d9-40ca-4276-af5c-1783ac89d13b
A loader that sits among the files it includes, like
`baselines/_loader.neon` with `includes: [*.neon]`, matched itself.
`ContainerFactory::getConfigFiles()` has no guard against recursive
includes, so it recursed until memory ran out, and Nette's loader would
have thrown "Recursive included file" instead.

The pattern now leaves out the file with the includes and every file
that includes it in turn, so such a loader includes only its siblings.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tnky3HeNQTYTAish2dfgd9
Claude-Code-Session-Id: 020072d9-40ca-4276-af5c-1783ac89d13b
Whether an include was a pattern was decided after the directory of the
including file had been prepended, so a `[`, `]`, `*` or `?` in that
directory counted as a metacharacter:

* A pattern under a directory like `Projects [old]/` matched nothing,
  because `[old]` was read as a character class, and the files it was
  meant to include were dropped silently.
* A missing plain include under such a directory was taken for a
  pattern that matches nothing, so it was dropped too, where it used to
  fail as a missing file.

Now only the entry as written is checked for metacharacters, and the
directory it is resolved against is escaped before it goes to glob().

`NeonLoader` matches the pattern in `expandIncludedFile()`, which Nette's
loader calls with the entry as written, and `load()` loads the matched
files. As a result, a top-level config file, which never goes through
`expandIncludedFile()`, is no longer expanded as a pattern either.
`ContainerFactory::getConfigFiles()` never expanded those, so the
container cache key could have left out files that were loaded.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tnky3HeNQTYTAish2dfgd9
Claude-Code-Session-Id: 020072d9-40ca-4276-af5c-1783ac89d13b
realpath() returns false for a file it cannot resolve, like PHPStan's
own config files inside phpstan.phar, which are among the files being
loaded whenever a project config is. With false in the list, a match
whose realpath() also failed would have been taken for a file being
loaded and left out of the pattern's matches.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tnky3HeNQTYTAish2dfgd9
Claude-Code-Session-Id: 020072d9-40ca-4276-af5c-1783ac89d13b
A pattern that matches nothing still includes nothing, so that the last
file in a directory can be deleted, such as a baseline fixed down to
zero. But a pattern whose directory does not exist, like
`baseline/*.neon` for `baselines/`, is more likely a typo, and it used to
disable the files it was meant to include without a word.

It now fails like a missing plain include does, with Nette's
FileNotFoundException naming the directory and the pattern. The
directory is the one before the segment with the first metacharacter,
so `modules/*/phpstan.neon` needs `modules/` to exist.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tnky3HeNQTYTAish2dfgd9
Claude-Code-Session-Id: 020072d9-40ca-4276-af5c-1783ac89d13b
LoaderFactoryBench::benchLoadConfigAgain measured 4.7 % more
instructions than expected, from the work this branch added to every
include and every loaded file, whether a pattern is used or not:

* IncludedFilePattern::expand() checked each include for metacharacters
  with the regex in FileExcluder::isFnmatchPattern(). strpbrk() finds the
  same characters without a regex.
* NeonLoader::load() wrapped each file in try/finally to pop the stack of
  files being loaded. Nette's own Loader::load() unsets its $loadedFiles
  without finally, since a config that failed to load leaves the loader
  with nothing to continue with, so the stack is now popped the same way.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tnky3HeNQTYTAish2dfgd9
Claude-Code-Session-Id: 020072d9-40ca-4276-af5c-1783ac89d13b
@westonruter
westonruter marked this pull request as ready for review November 17, 2026 01:47
@phpstan-bot

Copy link
Copy Markdown
Collaborator

This pull request has been marked as ready for review.

LoaderFactoryBench::benchLoadConfigAgain still measured 3.7 % more
instructions than expected. NeonLoader::expandIncludedFile() called
IncludedFilePattern::expand() for every include, only for it to find no
metacharacters in nearly all of them. It now looks for them itself and
calls the helper only when one is found, through a shared
IncludedFilePattern::METACHARACTERS constant so the two checks cannot
drift apart.

Co-Authored-By: Claude Opus 5.5 (medium effort) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Tnky3HeNQTYTAish2dfgd9
Claude-Code-Session-Id: 020072d9-40ca-4276-af5c-1783ac89d13b
@westonruter

Copy link
Copy Markdown
Contributor Author

Looks like this is not required. See WordPress/wordpress-develop#16049

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants