How to Use the Command 'grumphp' (with examples)

GrumPHP is a PHP Composer plugin that empowers developers by executing a series of quality checks on their source code. This not only helps maintain high code quality but also enforces certain programming standards and best practices across a team’s codebase. By integrating seamlessly with Git, GrumPHP ensures that these checks happen automatically with each code commit, thus preventing issues from creeping into the master branch.

Registering Git Hooks

Code:

grumphp git:init

Motivation:

The use of the grumphp git:init command is pivotal for teams dedicated to maintaining a high standard of code quality. By initializing GrumPHP’s Git hooks, you’re essentially setting up an automated guardian for your codebase. These hooks serve as checkpoints that intercept commits and ensure that only code meeting predefined quality standards gets integrated. This proactive measure saves time in the long run, prevents bugs, and minimizes refactoring costs by catching issues early in the development cycle.

Explanation:

• grumphp: This is the command-line executable for interacting with GrumPHP. It is used to access various functionalities of the tool.
• git:init: This argument instructs GrumPHP to register its Git hooks. Specifically, this operation configures GrumPHP to automatically run checks when certain Git actions are executed, such as pre-commit.

Example Output:

GrumPHP detected a git repository at /path/to/your/repo
GrumPHP Git hooks successfully installed!

Triggering the Pre-Commit Hook Manually

Code:

grumphp git:pre-commit

Motivation:

There are instances when developers need to test their changes against the formatted criteria without actually committing the code. By using grumphp git:pre-commit, you can trigger the pre-commit hook manually. This ensures that your changes pass all checks before making the actual commit. This is particularly useful for those who want to integrate feedback cycles early in their process, allowing them to correct potential issues immediately after they make changes instead of waiting until a later stage.

Explanation:

• grumphp: This remains the command-line executable for GrumPHP.
• git:pre-commit: This argument calls the pre-commit hook, simulating what would happen if a commit was made. It’s a way to preview the checks without executing a full commit process.

Example Output:

Running tasks...
✔ CodeSniffer: No errors found
✔ PHPStan: No issues detected
All checks passed. You can commit your code!

Checking Every Versioned File

Code:

grumphp run

Motivation:

Executing grumphp run performs a comprehensive quality check across all versioned files in the repository. This is exceptionally useful for maintaining a clean codebase, particularly after significant merges or bulk changes. Developers can use this command to ensure that larger updates haven’t inadvertently introduced new compliance issues or errors into any files, promoting a uniform adherence to standards.

Explanation:

• grumphp: Again, the command needed to run GrumPHP.
• run: This argument directs GrumPHP to perform a full sweep, conducting all preset checks on every file within the repository that is currently versioned. This is a broader, more exhaustive examination compared to the default pre-commit checks.

Example Output:

Running tasks...
✔ CodeSniffer: No errors found in all checked files
✔ PHPStan: All files passed the analysis
All tasks completed successfully!

Conclusion

GrumPHP is an essential tool for maintaining high code quality standards in a PHP project. By automatically running code checks at key stages in the development process, it helps teams catch potential issues early, reducing the time and cost associated with fixing bugs later in the development cycle. Whether you’re setting up hooks, manually triggering checks, or ensuring the consistency of your entire codebase, GrumPHP provides a robust solution for enforcing code quality.