Stop "Forgetting About" Your Coding Standards with Captain Hook

Slide deck from the Magento Minds of Manchester "Magento Smack-Down" event at Northern Monk Refectory on Thurs 2nd October 2025

Transcript

1. Stop “Forgetting About” Your Coding Standards with Captain Hook www.athoscommerce.com
2. 2 “You are responsible for the quality of your code. Not your client. Not your boss. You donʼt go to the doctor and say: You know what doc? Iʼm in a hurry, why wonʼt you skip washing your hands?ˮ - Michael Toppa
3. 3 A Helping Hand • Code Sniffer (phpcs) • Code Beautifier (phpcbf) • Mess Detector (phpmd) • Static Analysis (phpstan, Psalm) • Architecture Deptrac, Magetrac) Quality • PHPUnit • Infection • MFTF Reliability • SAST • Composer Audit • Malware Finder (pmf) • Exakat • Psalm Security Analysis • Sonarqube Security
4. 4 Enforcing Checks via VCS Hooks Client Side • Pre Commit • Commit Message • Pre Push • Post Checkout Server Side • Pre Receive • Update • Post Receive
5. 5 Introducing Captain Hook • Flexible Git hook library for PHP (and Go) • Developed by Sebastian Feldmann in 2016 • Installed with Composer • Configured using JSON • Ensures everyone is running the same hooks at a project level • Extensible via bash scripts and custom PHP classes
6. 6 Install Captain Hook Install the Composer Plugin Installation and Configuration $ composer require captainhook/captainhook $ composer require captainhook/plugin-composer ... captainhook/plugin-composer contains a Composer plugin which is currently not in your allow-plugins config. Do you trust "captainhook/plugin-composer" to execute code and wish to enable it now? (writes "allow-plugins" to composer.json) [ y,n,d,?]
7. 7 Installation and Configuration
8. 8 Actions Performed • Creates scripts for each selected hook • Generates captainhook.json based on entered configuration Installation and Configuration
9. 9 Some Common Actions • Ensure branch naming conventions • Enforce ticket reference in branch and/or commit message • Check commit message length • Validate against Beams Commit Message and Branch
10. 10 Some Common Actions • Linting • Coding Standards • Static Analysis • Unit Tests Quality and Security Checks
11. 11 Some Common Actions • Captain Hook install • Composer update • Custom scripts Application Compilation
12. 12 Pre-Commit or Pre-Push? • Fast quality checks • Code beautification • Test staged files only Pre-Commit Pre-Push • Execute longer quality checks • Test entire codebase • Run test suites • Security checks • Check for todo / fixme
13. 13 Ensured or Non-Ensured? • “failOnErrorˮ: true • Must be successful for hook to complete and Git action to execute • Used for critical actions, such as running quality and security checks Ensured • “failOnErrorˮ: false • Optional actions which do not prevent a hook completing - and will report successful regardless • Used for non-critical actions, such as notifications, updates to changelogs, etc Non-Ensured
14. 14 Submodules? No Problem • Checks for parent and submodules differ • Can run actions to checkout submodules to applicable commit, including creating matching branches • Pick one option - donʼt mix and match! Considerations • Install only in parent project and checks on submodules using single source of truth • Default configuration for parent; additional configuration to run against each submodule • Checks will not run where submodules are maintained externally Option 1 Single Source of Truth • Installed per module • Each module maintains its own hooks individually and configuration • Requires additional setup and configuration to ensure checks are run consistently and without duplication Option 2 Independent Modules
15. 15 Limitations • Relies on developers installing before starting work • Static Analysis without Magento codebase • Unit tests requiring Magento installation • Developers can skip checks (--no-verify or just disabling in captainhook.json) • Increased commit and push time, especially with long-running actions • “Quick and dirtyˮ POCs can become tedious
16. 16 GrumPHP vs Captain Hook • Designed to ensure code quality with opinionated, pre-configured checks • Declarative configuration in YAML • Quick and simple setup GrumPHP • Flexible hook manager supporting range of actions • Granular configuration in JSON • More complex setup - especially for custom actions Captain Hook
17. 17 In Summary • Define your standards and processes first • Powerful tool to improve code quality and management of a project – with limitations • Balancing act between features and day-to-day usability • Not a replacement for CI/CD and reviews
18. Thank You! Any Questions? www.athoscommerce.com Abi Green Lead Software Engineer @abiverde @abi-klevu