Awesome
Git PHP Hooks
Write your git hooks in PHP, organize them on a per project base and attach them automatically.
Git Hooks
Hooks are little scripts you can place in
$GIT_DIR/hooks
directory to trigger action at certain points.
There're two types of git hooks:
- pre-push (runs client side)
- post-push (runs server side)
For more info on Git Hooks, please take a look at the official docs - they are quite good.
How to
It's really easy:
- Add a folder to your project/repository. The name doesn't matter, as you have to specify
it when triggering
GitPHPHooks
. The name in the following example is'project-hooks'
. (Hint: Not having a name allows you to customize and organize it as you like. It also allowsgit clone
ing into a project specific directory.) - Open your
.git/hooks
directory and add a new Git hook file. For example:pre-commit
(without file extension). - Add a new PHP file to the newly created custom Git hooks folder (again,
'project-hooks'
in the example) that performs the task you want.
That's it.
All your Git hooks (inside .git/hooks
) will have the same contents - only the target folder ('project-hooks'
) name will (maybe) differ.
#!/usr/bin/env php
<?php
include 'vendor/wcm/git-php-hooks/GitHooksLoader.php';
new \GitHooksLoader( __FILE__, 'project-hooks' );
Explanation:
- The first line is a hashbang to specify that we actually have a PHP file on the Command Line.
- The 1st argument for
\GitHooksLoader()
is the name of the current file to make the current hook identifyable for GitPHPHooks. - The 2nd argument is the target location where your custom, pre-project Git PHP hook files for the current task are located.
Naming convention
There's a naming convention that you must follow to properly attach PHP files to Git hooks. Sorting files is also done by file name.
- If a Git hook name is found in the file name, it will get attached to this specific hook
and executed automatically. Example:
pre-commit_
- If one of your hooking PHP files has a number attached, it will get added with this priority. Example:
_10
If it ain't got anyint
in the file name, it will get skipped. This is useful to temporarily disable files if you are testing the order or a new hook. - The name in between the Git hook name and the priority is just an identifiyer for yourself. Example:
PHPUnit
Examples (and ready-to-use tasks)
Before jumping on examples, I suggest that you simply take a look at the GitPHPHooks Library repo. You will find a PHPLint and a PHP Mess Detector task and some others (hint: I happily accept pull requests!).
A real world scenario (simplified version of the task that is available in the linked library)
We want to run PHPLint before we commit
Add a new file named pre-commit
in your .git/hooks
directory. Then add a new directory in the
root folder of your project/repository, named i.e. project-hooks
. In there, add a new PHP file
named pre-commit_lint_10.php
. This file will automatically get added to your pre-commit
hook
where you called the \GitHooksLoader()
like shown above. It will get added with a priority
of 10. Then just put the following contents in your new file:
#!/usr/bin/env php
<?php
$output = shell_exec( 'php -l' );
echo $output;
if ( $output === 1 )
exit 1;
Of course, above code is a very poor example. For a more detailed one, please refer to the library linked above. The GitPHPHooks Library runs two real world examples. To use PHP Mess Detector and PHPLint, I can just suggest using the library as those are currently built in. Again: If you have a custom one and want to share, just send a Pull Request.
Grunt integration
It can easily be integrated with grunt via grunt-githooks
,
originally written by @rhumaric.
Setup your grunt-githooks
task like this:
php : {
options : {
hashbang : '#!/usr/bin/env php',
startMarker : '\n<?php',
template : './templates/git-php-hooks.tmpl.hb'
},
'pre-push' : 'none'
}
Then just add your hooked tasks to your project and use the following template:
include 'vendor/wcm/git-php-hooks/GitHooksLoader.php';
new \GitHooksLoader( __FILE__, 'vendor/wcm/git-php-hooks-library/src' );
This example is assuming that you are using the
GitPHPHooksLibrary.
The template in this case would be located inside a templates
directory in the root folder
of your project and be named git-php-hooks.tmpl.hb
. It's important to set the hooks names
value to none
as GitPHPHooks doesn't need a task name as it identifies tasks by the filename
by itself.
Install
Add the repo to your stack. You can use Composer (w/o Satis as it's added to Packagist). Simply add
"wcm/git-php-hooks": "^1.0"
to your composer.json
file. GitHub has a service hook added to this repo to auto-update whenever
this repo is updated. The ^1.0
version number will bring you all patches without breaking anything.
To add the repository to the dev-part of the stack in composer.json
, the following command can be typed in the prompt (assuming composer is in your PATH or aliased ).
composer require --dev --prefer-dist -- wcm/git-php-hooks
wcm/git-php-hooks suggests installing a library of pre made hooks and tasks, wcm/git-php-hooks-library . To add this with composer the following can be used:
composer require --dev --prefer-dist -- wcm/git-php-hooks-library