php-composter/php-composter

Git Hooks Management through Composer.

v0.3.3 2018-08-04 07:37 UTC

Requires

• php: ^5.4 || ^7.0
• composer-plugin-api: ^1
• composer/composer: ^1
• composer/installers: ^1

Requires (Dev)

• phpunit/phpunit: 5.3.*

MIT

• Alain Schlesser

README

Git Hooks Management through Composer.

This is a Composer plugin that manages Git pre- & post-hooks through Composer dependencies. Actions you want to be executed on Git hooks can simply be required as --dev dependencies, and will immediately become active on composer install.

Introductory post: Adding Git Hooks Through Composer Dev-Dependencies

Table Of Contents

• Installation
• Existing PHP Composter Actions
• Creating a New PHP Composter Action
• Using Existing PHP Composter Actions in Your Projects
• Skipping Installation of PHP Composter Actions
• Contributing

Installation

You should not need to install this package directly. It should come as a dependency of a package that is of type php-composter-action.

Existing PHP Composter Actions

• PHP Composter PHPCS PSR2

  Check your PHP source code for PSR-2 compliance before committing.

• PHP Composter Regular Expression

  Check your commit messages against a regular expression pattern, to enforce a commit message standard.

• PHP Composter PHPCS WordPress

  Check your PHP source code for WordPress Coding Standards compliance before committing.

  Thanks to Gabor Javorszky for contributing this action.

• PHP Composter PHPCS Drupal

  Check your source code for Drupal Coding Standards compliance before committing.

  Action by Nick Wilde.

• PHP Composter PHPUnit (coming soon)

  Run a PHPUnit test suite before committing.

• PHP Composter PHP Syntax Checker (coming soon)

  Validate the PHP syntax before committing.

Creating a New PHP Composter Action

To build a new PHP Composter action, you need to proceed as follows:

1. Create a Composer Package with a Valid Name
2. Extend BaseAction class
3. Add Public Methods
4. Add the Class to Composer Autoloader
5. Set the Composer Package Type to php-composter-action
6. Add php-composter/php-composter as a dependency
7. Configure Git Hooks through Composer Extra key

Create a Composer Package with a Valid Name

Create a new Composer package with the following naming pattern: <vendor>/php-composter-<action intent>

Example:

composer init --name php-composter/php-composter-example

Extend BaseAction class

Create a new class that extends PHPComposter\PHPComposter\BaseAction.

Example:

<?php namespace PHPComposter\PHPComposterExample;

use PHPComposter\PHPComposter\BaseAction;

class Example extends BaseAction
{
    // [...]
}

Add Public Methods

PHP Composter allows you to attach PHP methods to Git hooks. These methods need to be publicly accessible, so that they can be called by the PHP-Composter bootstrapping script.

Example:

<?php
// [...]

class Example extends BaseAction
{

    /**
     * Example pre-commit action method.
     *
     * @var string $hook Name of the hook that was triggered.
     * @var string $root Root folder in which the hook was triggered.
     */
    public function preCommit()
    {
        echo 'Example Pre-Commit Hook ' . $this->hook . ' @ ' . $this->root . PHP_EOL;
    }
}

Set the Composer Package Type to php-composter-action

You need to set the type of your Composer package in your composer.json file to php-composter-action.

Example:

{
  "name": "php-composter/php-composter-example",
  "description": "PHP Composter Example.",
  "type": "php-composter-action",
  "[...]": ""
}

Add the Class to Composer Autoloader

Composer's Autoloader will be initialized for each Git hook, so make sure you've registered your newly created class correctly.

Example:

{
  "[...]": "",
  "autoload": {
    "psr-4": {
      "PHPComposter\\PHPComposterExample\\": "src/"
    }
  },
  "[...]": ""
}

Add php-composter/php-composter as a dependency

You need to set the type of your Composer package in your composer.json file to php-composter-action.

Example:

{
  "[...]": "",
  "require": {
    "php-composter/php-composter": "^0.1",
  },
  "[...]": ""
}

Configure Git Hooks through Composer Extra key

Finally, add a new entry "php-composter-hooks" to the extra key in the package's composer.json to attach each of your methods to a specific Git hook.

Example:

{
  "[...]": "",
  "extra": {
    "php-composter-hooks": {
      "20.pre-commit": "PHPComposter\\PHPComposterExample\\Example::preCommit"
    }
  }
}

Hooks can either be "<priority>.<git-hook-name>", or just "<git-hook-name>".

In the above example, the priority is 20. It defaults to 10 if omitted. Lower priority numbers get executed before higher ones.

Supported Git Hooks:

• applypatch-msg
• pre-applypatch
• post-applypatch
• pre-commit
• prepare-commit-msg
• commit-msg
• post-commit
• pre-rebase
• post-checkout
• post-merge
• post-update
• pre-auto-gc
• post-rewrite
• pre-push

Using Existing PHP Composter Actions in Your Projects

To use an existing PHP Composter Action in your projects, simply require them as --dev dependencies:

composer require --dev php-composter/php-composter-example

Anyone using Composer to pull in the development dependencies will automatically have your PHP Composter Actions installed into their .git.

Skipping Installation of PHP Composter Actions

In case you want to install your the Composer dependencies of a project without activating the PHP Composter system, you can run Composer with the --no-plugins option:

composer install --no-plugins

Contributing

All feedback / bug reports / pull requests are welcome.