Git hooks for PHP projects with Crook
This project started with a search for some tool to help me managing some Git hooks for a simple project. As every sane developer, before trying to write my own solution to the problem I went to the good Packagist and searched for some tools for the job. There are plenty! Really, a lot of tools.
I opened several tabs and started reading about the projects, usage, etc, but I didn’t find anything like what I was looking for. All those tools did way more than just managing Git hooks. Some of them are shipped with several checks, others rely heavily on namespaces. A really complex processes for a simple thing.
What I was looking for?
I wanted the most simple thing: the event happens, then trigger some code wrote by me or by someone else. No matter the language, if I want to plug a pre-commit hook to a Ruby script, that’s OK. If I want to run a Bash script, a binary in Golang, whatever. For me, the tool must just take the event and trigger the hooked action. That’s it. I didn’t find it. And what do we do when we cannot find the right tool? We create one and make it Open Source. : )
First, the requirements
I need something to manage client-side Git hooks. The tool should allow me to run whatever I want when some client-side hook event is triggered, no matter the language. It must be simple, straightforward, easy to install, easy to use, must be a package available on Packagist, have few dependencies, and be written in PHP.
Here comes Crook
Crook is (at least for me) the simplest way to manage Git hooks in your PHP projects. Is my attempt on helping create a nice tool for the job. In the following sections, I’m gonna explain in a little more detail about how everything works and how you can use it to integrate actions and hooks on your projects. I published it on Packagist here and you can find the source code on my GitHub page here.
If you just need the basics to let me explain it shortly. TL;DR: after installation, you create an entry on composer’s script section and give it a name, any name, then run Crook add command (once) to bind that script (action) to a given hook name (event). When the event is triggered, that script will run. That’s it.
How does it work?
First, you run
$ vendor/bin/crook init
This command will create a JSON file called crook.json. This file is responsible for holding the bind between the Git hook names and actions, and other few configuration information. There is no need to change it manually, you do everything using Crook through command line.
After adding an entry on composer.json in the scripts section, you can bind that action to the hook like this
$ vendor/bin/crook add hook-name action-name
The same goes for removing a hook
$ vendor/bin/crook remove hook-name
So, let’s say that you are having a hard time in your team discussing code style and all the code review is based on “put a blank line here”, “send this bracket to the next line” and all that kind of non-important stuff. Choose your code-check/code-beautifier tool and plug it into pre-commit Git hook. Add some entry in composer.json and then run
$ vendor/bin/crook add pre-commit code-check
Next time someone tries to create a new commit, the code check will run and run some fixes according to your company’s code standard. By the way, I discussed a little bit about PHPCS and other interesting tools and concepts for PHP in another article, if you don’t know about it or want to have a nice read, please take a look at This is what modern PHP looks like.
The mechanism
Git hooks are based on actions/files you create inside .git/hooks. So, if you go to your project and list this directory you will find some sample files to help you create your own hooks.
What crook does is simply create a symbolic link from .git/hooks/some-hook to a file called theHook, so, every time you add a new hook, a new symbolic link is created between that hook file and theHook. This way, when it triggers that script, theHook will run and then do whatever action you added. That’s the reason I said at the beginning of this article that you can run everything you want, all commands available in the server can be used, you can create scripts in any language, mix things, do your magic there.
The project
I had a nice time creating this and I hope it can be helpful to your project. You can find more about Crook on its Github page. My last commit was a few months ago, but it seems to be really stable and has some tests. I know of a company using it to manage hooks for a PHP team and I got a few good feedbacks. I would be flattered if someone could use it, find issues, report them, and maybe contribute. Any criticism or questions are welcome.
What do you use for Git hooks management? What do you expect of a tool of this type? Tell me in the comments.
This story is published in The Startup, Medium’s largest entrepreneurship publication followed by + 382,862 people.
Subscribe to receive our top stories here.
