phpro/grumphp

GrumPHP is a PHP-based static analysis and quality assurance tool that integrates directly into Git workflows to enforce coding standards and project conventions. It operates by intercepting pre-commit and commit-msg hooks to run a configurable suite of linters, parsers, and task validators against staged code changes. The system supports parallel execution, automatic code fixing, and structured configuration, allowing developers to maintain code quality through automated checks on syntax, formatting, and commit message rules.

43 changes.

This period focused on the major v2 release of GrumPHP, involving a comprehensive architectural rewrite to support PHP 8.2+ and Symfony 6.4+. The work included refactoring the core task runner, configuration system, and event handling into modern, strictly-typed components, alongside adding new linters and git hook integrations. Extensive PhpSpec test coverage was added to validate the new collection, parser, and locator subsystems.

29 changes.

The project refactored the task runner to use an async-first, middleware-based architecture powered by Amp v3, introducing parallel execution and stop-on-failure capabilities. Concurrently, the configuration system was restructured with dedicated model classes and resolvers to improve type safety and validation. This period also introduced automatic code fixing via FixerUpper and expanded test coverage across the new runner, configuration, and Git integration components.

4 changes.

This period focused on enhancing the configuration system by adding support for .dist files and expanding unit test coverage for configuration handling and IO factory detection. Developers also introduced helper traits to streamline mocking context and task objects, improving the robustness of the test suite.

Users can now lint JSON files using the Seld JsonLint parser. The new JsonLinter component validates JSON syntax and, when the 'detectKeyConflicts' option is enabled, also flags duplicate keys. Lint errors are reported via the new JsonLintError class, which formats output as '\[ERROR\] \<path\>: \<message\>'.

src/Linter/Json · high confidence

Users can now integrate GrumPHP with Symfony's event system via a new bridge component. This change introduces a dedicated \EventDispatcherInterface\ and a \SymfonyEventDispatcher\ adapter that automatically detects whether the installed Symfony version uses the legacy \EventDispatcherInterface\ or the newer \SymfonyContracts\ interface, ensuring compatibility with both Symfony 4 and Symfony 5.

src/Event/Dispatcher · high confidence

Two new event subscribers have been added to the event system. The StashUnstagedChangesSubscriber automatically stashes unstaged and untracked files before running tasks in the pre-commit context and reapplies them afterward, with an option to ignore these changes on errors via the ignoreUnstagedChanges config. The VerboseLoggerSubscriber now logs configuration paths (config file, working dir, project dir, git dirs, bin dir, composer file) to stdout when the console output is set to verbose mode.

src/Event/Subscriber · high confidence

The repository is initialized with essential project files including a README, MIT license, contributing guidelines, and a security policy. Development tooling is configured via \.editorconfig\, \phpunit.xml.dist\, \psalm.xml\, \phpspec.yml\, and \phive.xml\, alongside CI configurations for AppVeyor and a Makefile for release automation. A default \grumphp.yml.dist\ is provided to set up the GrumPHP git hook tasks, and the \UPGRADE-v2.md\ document outlines breaking changes for extension developers regarding the new AMP-based parallel execution and extension interface.

(repo-wide) · high confidence

The \src/Exception\ directory now contains a dedicated set of exception classes for the GrumPHP application, including \ExceptionInterface\, \RuntimeException\, and specific types such as \ExecutableNotFoundException\, \FileNotFoundException\, \FixerException\, \InvalidArgumentException\, \ParallelException\, \PlatformException\, \ProcessException\, and \TaskConfigResolverException\. These classes provide structured, typed error handling for common failure scenarios like missing executables, file access issues, process errors, and task configuration problems, replacing any previous generic exception usage in this area.

src/Exception · high confidence

A new TaskConfigResolver class has been added to the GrumPHP configuration namespace to handle the resolution of task-specific configurations. This component maps task names to their respective configuration options and metadata, allowing the system to validate and resolve task settings against defined interfaces. Users benefit from a more robust configuration resolution process that ensures task configurations are correctly interpreted and validated before execution.

src/Configuration/Resolver · high confidence

The Formatter module now includes specific formatters for Git Blacklist, PHP CS Fixer, and PHPCS, replacing the previous generic handling. The GitBlacklistFormatter provides colored, line-truncated output for long lines, while the PhpCsFixerFormatter parses JSON output to display applied fixers and code diffs. The PhpcsFormatter extracts fixable file suggestions from JSON reports. All new classes implement the ProcessFormatterInterface and use strict types.

src/Formatter · high confidence

The src/Event directory now contains a new, strictly-typed event hierarchy extending Symfony's EventContract, including base Event, RunnerEvent, TaskEvent, and their specific failure/complete variants. This change introduces a new TASK\_SKIPPED event constant in TaskEvents, allowing subscribers to react when a task is skipped, alongside existing run, complete, and failed events for both tasks and the runner.

src/Event · high confidence

A new FixerUpper component has been added to enable automatic correction of code issues. This feature introduces a FixResult class to handle success or failure states and a FixerUpper orchestrator that iterates through fixable task results. Users will now see an interactive prompt asking if they want to automatically fix issues, with the behavior configurable via FixerConfig (enabled status and default fix behavior). The system provides visual feedback (checkmarks/crosses) and verbose error messages during the fixing process.

src/Fixer · high confidence

Added new local git hook scripts (commit-msg and pre-commit) that are POSIX sh compatible. These hooks fetch the staged git diff using the --raw flag and pipe it to GrumPHP, ensuring predictable behavior and proper argument encoding. The commit-msg hook also passes git user details to GrumPHP, while the pre-commit hook runs with success output skipped.

resources/hooks/local · high confidence

Users can now lint XML files using a new XmlLinter that supports multiple validation strategies: basic parsing, XInclude processing, DTD validation, and XML Schema (XSD) validation. The linter allows configuration of whether to load remote resources (DTDs/schemas) and includes a workaround for remote DTD blocking issues by setting a specific user agent. Validation errors are reported via a new XmlLintError class that exposes the error code and column number for precise feedback.

src/Linter/Xml · high confidence

This change introduces a new \Blacklist\ task for \src/Task/Git\ that checks staged files for forbidden keywords using configurable regex types (G, E, P), word matching, and ignore patterns. It also significantly enhances the existing \BranchName\ task by adding \blacklist\ and \whitelist\ arrays, allowing users to enforce naming conventions via regex rules with additional modifiers and support for detached HEAD states. Additionally, the \CommitMessage\ task now supports enforcing type/scope conventions (e.g., Conventional Commits), skipping validation on merge commits, and includes various fixes for subject line parsing and error reporting.

src/Task/Git · high confidence

This change introduces a set of new collection classes in src/Collection to manage specific types of data with domain-specific filtering and formatting logic. FilesCollection provides fluent methods to filter files by name, path, extension, size, and date. ProcessArgumentsCollection simplifies the construction of CLI command arguments with helpers for optional, required, and array-based arguments. TaskResultCollection aggregates task outcomes, providing methods to determine pass/fail status and retrieve messages. TasksCollection introduces the ability to filter tasks by context, test suite, or specific names, and adds logic to sort and group tasks by priority. Additionally, LintErrorsCollection and ParseErrorsCollection standardize the string representation of error lists, while TestSuiteCollection and the new TestSuite/TestSuiteInterface classes provide a structured way to define and retrieve named groups of tasks.

src/Collection · high confidence

The \src/Console/Command\ area now includes a new \ConfigureCommand\ that interactively generates a \grumphp.yml\ configuration file, allowing users to select specific tasks to enable. The existing \RunCommand\ has been updated to support the \--tasks\ option for filtering which tasks to execute and can now read file lists from standard input (stdin) via the \StdInFiles\ locator, enabling piped usage.

src/Console/Command · high confidence

This change introduces three new classes in the environment configuration module to handle runtime environment setup. DotEnvRegistrar now loads and populates environment variables from .env files and explicit variable lists using Symfony's Dotenv component. DotEnvSerializer provides a utility to export environment variables in shell-compatible format. PathsRegistrar automatically prepends specified directories to the system PATH environment variable, ensuring local dependencies are prioritized during execution.

src/Configuration/Environment · high confidence

Added InputWritingProcessRunner and TmpFileUsingProcessRunner to src/Process, enabling commands to receive input via STDIN streams or temporary files respectively. These new utilities complement the existing ProcessBuilder and ProcessFactory, providing specialized ways to feed data into external processes without manual file or stream management.

src/Process · high confidence

The src/Util directory now includes several new helper classes to standardize internal operations. ComposerFile parses composer.json to resolve bin and config paths. Filesystem extends Symfony's component with methods for path guessing, backup creation, and cross-platform slash normalization. Paths provides a centralized API for resolving project, git, and worktree directories, supporting git submodules and worktrees. PhpVersion checks PHP version support against end-of-life dates. Platform defines Windows command-line limits. Regex handles glob-to-regex conversion and modifier management. Str adds string utility methods like containsOneOf and explodeWithCleanup.

src/Util · high confidence

The configuration loader now supports loading files with the .dist extension. A new DistFileLoader decorator has been introduced to handle these files, allowing users to provide default or example configuration files that can be loaded alongside or instead of standard configuration files without manual renaming.

src/Configuration/Loader · high confidence

The empty \QualityCheckerPlugin\ class, which previously implemented Composer's \PluginInterface\ and \EventSubscriberInterface\ but contained no logic in its \activate\ and \getSubscribedEvents\ methods, has been removed from the codebase.

src/GrumPHP · high confidence

A change to existing behaviour in tools — 4 commits (1 fix), 8 files.

tools · medium confidence · unverified

Task execution in the runner has been refactored to be async-first, utilizing the Amp library to return Futures for non-blocking operation. The previous monolithic handler is replaced by a middleware pipeline (TaskHandler) that chains specific concerns: parallel processing via worker pools, error handling, event dispatching, result memoization, reporting, and stop-on-failure logic. This change enables tasks to run concurrently and improves resource management by swapping serialized contexts back to original objects to aid garbage collection.

src/Runner/TaskHandler · high confidence

Users can now specify which exit codes are considered successful when running fixer commands, rather than relying solely on exit code 0. The new \FixableProcessProvider\ and \FixableProcessResultProvider\ classes allow passing a \successExitCodes\ array to define acceptable outcomes, enabling fixers that return non-zero codes for success to be handled correctly.

src/Fixer/Provider · high confidence

The git hook commands (git:commit-msg, git:pre-commit, git:init, git:deinit) have been refactored to use the Symfony Console \\#\[AsCommand\]\ attribute instead of legacy command declarations, and now require PHP 7.1+ and Symfony 5. This change updates the internal implementation to use modern dependency injection and strict typing, ensuring the hooks function correctly in newer environments while maintaining the same user-facing behavior for running and managing git hooks.

src/Console/Command/Git · high confidence

The Composer plugin now includes a new DevelopmentIntegrator class that automatically copies the GrumPHP executable to the Composer bin directory and initializes git hooks during development, ensuring the tool is ready to sniff commits immediately after installation. The plugin's core logic has been refined to better detect GrumPHP package operations (install, update, uninstall) and schedule configuration and initialization tasks appropriately, preventing redundant executions. Additionally, the codebase addresses compatibility issues with older Composer versions by fixing internal Symfony Process version conflicts, ensuring the plugin functions correctly across different Composer environments.

src/Composer · high confidence

A new ApplicationConfigurator class has been added to src/Console to centralize the configuration of the GrumPHP console application. This component explicitly sets the application name and version (2.23.0) and registers the --config/-c input option, allowing users to specify a custom configuration file path via the command line.

src/Console · high confidence

The IO subsystem has been refactored into a dedicated namespace with a new \IOInterface\ and factory pattern (\IOFactory\) that automatically selects the appropriate implementation based on the environment. A new \ConsoleIO\ class handles standard console output, input, and serialization for parallel execution, while a new \GitHubActionsIO\ class extends this to wrap output in GitHub Actions workflow commands (\::group::\ / \::endgroup::\) for better visibility in CI logs. The system also improves stdin handling by detecting piped input and reading it non-blockingly when appropriate.

src/IO · high confidence

The configuration system in src/Configuration/Model now uses dedicated model classes (AsciiConfig, EnvConfig, FixerConfig, GitStashConfig, HooksConfig, ParallelConfig, ProcessConfig, and RunnerConfig) to manage specific settings. This replaces the previous approach of injecting raw parameters, providing a more structured and type-safe way to access configuration values such as parallel worker limits, fixer options, and environment variables.

src/Configuration/Model · high confidence

The task system now uses a dedicated configuration layer in the \GrumPHP\\Task\\Config\ namespace, introducing \TaskConfig\, \EmptyTaskConfig\, and \Metadata\ classes to manage task settings. This change centralizes configurable options such as priority, blocking behavior, and enabled status within the \Metadata\ class, which leverages a new \ConfigOptionsResolver\ for validation. Users benefit from a more robust and structured way to define and resolve task configurations, ensuring that options are consistently handled and validated before being applied to tasks.

src/Task/Config · high confidence

The Linter and Parser components now enforce strict type checking via \declare(strict\_types=1)\ and utilize new, explicitly typed interfaces (\LinterInterface\, \ParserInterface\) along with dedicated error value objects (\LintError\, \ParseError\). This change standardizes how linting and parsing errors are represented and processed, ensuring that method signatures for \lint()\ and \parse()\ strictly return their respective error collections and that error details are encapsulated in strongly-typed classes rather than loose structures.

src/Linter, src/Parser · high confidence

The task runner execution flow has been refactored into a chain of dedicated middleware components, replacing the previous monolithic implementation. This change introduces structured task execution where tasks are now grouped and executed by priority level, allowing for more predictable output ordering. It also adds support for a 'stop on failure' configuration, which halts the execution of subsequent tasks immediately when a blocking failure occurs, rather than continuing to run the entire suite. Additionally, the runner now leverages asynchronous task handling via Amp futures for parallel execution capabilities, and integrates event dispatching and reporting hooks at specific stages of the run lifecycle.

src/Runner/Middleware · high confidence

A new GitRepository wrapper class has been introduced to manage Git operations more robustly. It implements lazy loading for the underlying Gitonomy repository, preventing exceptions when Git is unavailable during non-interactive commands like help or list. Additionally, it provides a tryToRunWithFallback method that allows git commands (such as fetching configuration values) to return a default string instead of throwing an exception if they fail, improving resilience in environments where Git might be partially configured or missing.

src/Git · high confidence

The configuration layer has been rewritten to introduce a new Symfony-based configuration tree (Configuration.php) that defines settings for hooks, tasks, test suites, parallel execution, and fixers. A key behavioral change is the addition of an 'environment' configuration node that allows users to specify .env files, variables, and paths, which are now resolved and enriched into the application context during bootstrapping via ContainerFactory. Additionally, the system now automatically guesses project paths (working dir, repository dir, config file) using locators before loading the container, improving out-of-the-box usability for users who do not explicitly configure paths.

src/Configuration · high confidence

The src/Locator directory now includes a suite of new classes that refine how GrumPHP discovers files and resolves paths. GitRepositoryDirLocator and GitRepositoryLocator now explicitly support Git worktrees and submodules, ensuring diffs and repository operations target the correct worktree-specific git directory rather than collapsing to the shared root. GuessedPathsLocator and EnrichedGuessedPathsFromDotEnvLocator allow configuration of project, bin, and git directories via environment variables (e.g., GRUMPHP\_PROJECT\_DIR) and improve fallback logic when no git repository is present. Additionally, new locators like ChangedFiles, ListedFiles, RegisteredFiles, and StdInFiles provide more robust mechanisms for identifying which files to process, including support for raw diff input and stdin.

src/Locator · high confidence

The configuration layer has been reworked to support a new v2 extension system and a more robust task compilation process. New compiler passes now handle the registration of extensions, PHP parser visitors, and event listeners (including a workaround for Symfony's removal of custom tag support). The task system has been updated to resolve configurations lazily via a new TaskConfigResolver, allowing for environment variable resolution and conditional task enabling. Additionally, a new TestSuiteCompilerPass validates that test suites only reference registered tasks, and a TaskConfigurator applies resolved configurations to task instances.

src/Configuration/Compiler · high confidence

The parallel execution engine has been updated to support Amp v3, replacing the previous implementation with a new PoolFactory that creates a ContextWorkerPool based on the configured max\_workers setting. This change introduces SerializedClosureTask to handle task serialization and execution within the new Amp-based worker context, enabling the runner to leverage Amp v3's concurrency model for parallel task processing.

src/Runner/Parallel · high confidence

The PHP parser implementation has been rewritten to use a modular visitor pattern, introducing new classes for configuration (TraverserConfigurator), context management (ParserContext), and factory creation (ParserFactory, TraverserFactory). This change enforces strict types across the parser and provides specific visitors to detect issues such as missing strict type declarations, forbidden function or method calls, and the use of 'else' or 'exit' statements. Additionally, a custom VisitorContainer is used to ensure visitor instances are cloned between runs to prevent state leakage.

src/Parser/Php · high confidence

The bin/grumphp script has been rewritten to bootstrap the application via a ContainerFactory instead of direct instantiation. It now loads the project's autoloader from the current working directory first, followed by GrumPHP's autoloader from various possible locations, and finally resolves the Console Application from the built dependency injection container.

bin · high confidence

The reporting logic has been moved from inline task helpers into dedicated middleware classes: \RunnerReporter\ now handles high-level start/finish messages (including the new 'Aborted' message when \stopOnFailure\ triggers) and \TaskResultsReporter\ manages per-task progress updates. A new \CiDetector\ wrapper was added to detect CI environments, which disables interactive output overwrites in CI to prevent broken console sections. Additionally, the \TaskResultsReporter\ now uses \write\ instead of \overwrite\ for CI outputs and improves no-ansi reporting by only rendering at start and completion.

src/Runner/Reporting · high confidence

The task execution engine in src/Runner has been restructured to use a middleware-based architecture. A new MiddlewareStack allows processing task results through a chain of handlers, while the TaskRunner now delegates execution to this stack. A new StopOnFailure mechanism enables the runner to cancel ongoing tasks immediately when a blocking failure occurs. Additionally, new result types like FixableTaskResult and MemoizedTaskResultMap have been introduced to support fixer logic and result caching, and the TaskResult model now explicitly distinguishes between blocking and non-blocking failures.

src/Runner · high confidence

The task execution model has been restructured to support a more modular and configurable architecture. New abstract base classes (AbstractExternalTask, AbstractLinterTask, AbstractParserTask) standardize how tasks interact with external tools, linters, and parsers, introducing shared options like ignore\_patterns and triggered\_by. A new Context system (GitPreCommitContext, RunContext, GitCommitMsgContext) allows tasks to adapt their behavior based on the execution environment. Existing tasks like Behat, ESLint, and ECS have been updated to use these new patterns, enabling features such as stop\_on\_failure for Behat, fixable results for ESLint and ECS, and more granular file filtering.

src/Task · high confidence

The .phpspec/specification.tpl file has been updated to reflect modern PHP practices. The template now uses the fully qualified class name syntax (%subject\_class%::class) instead of string literals for type checking, aligning with PHP 5.5+ standards. This change supports the project's decision to drop PHP 5.4 support, ensuring that generated spec files are compatible with current PHP versions and utilize modern language features for better static analysis and readability.

.phpspec · high confidence

The Vagrant integration for GrumPHP has been updated to include a new \commit-msg\ hook alongside the existing \pre-commit\ hook, enabling commit message validation within the Vagrant environment. Both hooks have been rewritten to use POSIX-compliant \sh\ instead of \bash\, ensuring broader shell compatibility. The implementation now explicitly transfers the commit message and the raw git diff (using \--raw\ format) to the Vagrant guest via heredocs, allowing GrumPHP to analyze both staged changes and commit messages directly from the virtual machine.

resources/hooks/vagrant · high confidence

The YAML linter has been updated to allow configuration of parsing behaviors for advanced YAML features. Users can now enable the parsing of custom YAML tags and PHP constants via new options, which control how the underlying Symfony YAML parser handles these elements during linting.

src/Linter/Yaml · high confidence

Added FilesystemTestCase for Symfony integration tests; Added PhpSpec test coverage for Event classes and StashUnstagedChangesSubscriber; Added PhpSpec test coverage for Util classes; Added PhpSpec test coverage for the Locator components; Added PhpSpec test suites for Collection classes; Added PhpSpec tests for GrumPHP exception classes; Added PhpSpec tests for ProcessBuilder and ProcessFactory; Added PhpSpec tests for Runner components; Added PhpSpec tests for configuration models and resolvers; Added PhpSpec tests for linter and composer plugin components; Added PhpSpec tests for task configuration and context classes; Added PhpSpec unit tests for the PHP parser subsystem; Added XML linter test fixtures for DTD, XSD, and XInclude validation; Added e2e test fixtures for task and extension validation; Added end-to-end test suite for GrumPHP integration scenarios; Added test bootstrap configuration; Added test coverage for Formatter components; Added test helper traits for mocking context and task objects; Added test infrastructure for runner middleware; Added tests for ConsoleIO; Added tests for GitRepository lazy loading and diff parsing; Added unit tests for ASCII configuration handling; Added unit tests for Fixer components; Added unit tests for Git blacklist, branch name, and commit message tasks; Added unit tests for Git worktree and path locator components; Added unit tests for GrumPHP utility classes; Added unit tests for IOFactory CI environment detection; Added unit tests for JSON, XML, and YAML linters; Added unit tests for PHP parser visitors and task integrations; Added unit tests for the CI detector runner; Added unit tests for the task runner middleware stack; New base test classes for task testing.

GrumPHP has been upgraded to version 2, which drops support for PHP versions prior to 8.2 and requires Composer 2. The dependency tree has been modernized to support Symfony components versions 6.4, 7.0, and 8.0, and the package name has changed from 'grumphp/grumphp' to 'phpro/grumphp'. The license is now MIT, and the plugin class has moved to 'GrumPHP\\Composer\\GrumPHPPlugin'.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 71.

• Code Health 96
• Architecture 93
• Maturity 57
• Readiness 72
• Security 96

• 300 commits — 269 feature/other, 31 fixes

• (repo) — 85 commits
• (root) — 40 commits
• doc/tasks — 39 commits
• src/Task — 34 commits
• src/Console — 29 commits
• test/Unit — 18 commits
• .github/workflows — 11 commits
• src/Runner — 6 commits
• resources/config — 5 commits
• src/Locator — 4 commits
• src/Parser — 4 commits
• doc/tasks.md — 3 commits
• src/Configuration — 3 commits
• src/IO — 3 commits
• src/Util — 3 commits
• test/E2E — 3 commits
• doc/faq.md — 2 commits
• src/Test — 2 commits
• resources/hooks — 1 commit
• spec/Exception — 1 commit

• fix: Add bug bounty information
• fix: Fix CI
• fix: Fix E2E
• fix: Fix ESLint cache test expected binary name
• fix: Fix Security Checker Enlightn Allow List
• fix: Fix a couple of PSR violations.
• fix: Fix abstract test case methods to be static for PHPUnit 12
• fix: Fix installation link for deptrac
• fix: Fix invalid Rector install command
• fix: Fix phpcs on Mago task
• fix: Fix psalm
• fix: Fix psalm DeprecatedProperty error
• fix: Fix psalm PossiblyUndefinedMethod error
• fix: Fix psalm UndefinedMethod for nikic/php-parser version < 4.16
• fix: Fix raw Console markup rendered by ConsoleSectionOutput::overwrite()
• fix: Fix test failing in Windows environment
• fix: Fix tests
• fix: Fix tests
• fix: Fix workflow deprecations
• fix: Fixes #815
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

phpro/grumphp was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.