|
1 | | -# gulp-dev-toolbox |
2 | | -Gulp development toolbox |
| 1 | +gulp-php-dev-toolbox |
| 2 | +-- |
| 3 | +There are a lot of tools available all with different settings and command line arguments. It makes live a lot easier if all these tasks can be done automatically when the code changes, before a commit. This toolbox contains automated tasks to install dependencies, checking code styling and structure and running unit tests with or without code coverage. |
| 4 | + |
| 5 | +The toolbox uses [gulp](http://gulpjs.com/) as the task runner. Gulp is using [nodejs](https://nodejs.org/en/) as a engine. This way gulp has the ability to run tasks async which will increase the speed off your tasks. If you really need to run the task in sync it's still possible. See the [gulp api documentation](https://github.com/gulpjs/gulp/blob/master/docs/API.md) for more information. Tasks in gulp are created by code and not by configuration. This makes it a lot easier to read and all the tools that are available for [nodejs](https://nodejs.org/en/) are at your disposal for creating tasks. |
| 6 | + |
| 7 | +# Requirements |
| 8 | +To make use of this toolbox [nodejs](https://nodejs.org/en/) and gulp are required. Gulp will be installed by the toolbox itself. Nodejs can be [downloaded](https://nodejs.org/en/download/) or installed using a [package manager](https://nodejs.org/en/download/package-manager/). |
| 9 | + |
| 10 | +# Setup |
| 11 | +There are multiple ways to setup and use the toolbox. The php tools can be added as a dev dependency in your composer.json of your project or your can use the toolbox in a separate repository. |
| 12 | + |
| 13 | +## Install as composer dev dependency |
| 14 | +The most easy one is using composer. Add this repository as a dependency to the composer.json file. |
| 15 | +```bash |
| 16 | +composer require --dev rregeer/gulp-php-dev-toolbox |
| 17 | +composer install |
| 18 | +``` |
| 19 | +Run composer install in your project and the magic happens. The toolbox will copy itself to your project and is now a part of it. You are free the commit the tasks and other toolbox files. |
| 20 | + |
| 21 | +## Install it manually by using git |
| 22 | +Just clone the git repository and start the setup script. The setup script will copy the toolbox to the given destination directory. If you want it to be a part of your project use your project root. If no destination or source directory is given the current working directory will be used. |
| 23 | +```bash |
| 24 | +git clone git://github.com/richardregeer/gulp-php-dev-toolbox.git |
| 25 | +cd gulp-php-dev-toolbox |
| 26 | +./scripts/setup.sh <path/to/destination> <source/toolbox> |
| 27 | +cd <path/to/destination> |
| 28 | +gulp composer:install |
| 29 | +``` |
| 30 | + |
| 31 | +If you just want to install it in the dev-toolbox directory itself, you can also directly call npm install. |
| 32 | +```bash |
| 33 | +git clone git://github.com/richardregeer/gulp-php-dev-toolbox.git |
| 34 | +cd gulp-php-dev-toolbox |
| 35 | +npm install |
| 36 | +gulp composer:install |
| 37 | +``` |
| 38 | + |
| 39 | +# Available tasks |
| 40 | +To see all the available tasks |
| 41 | +```bash |
| 42 | +gulp help |
| 43 | +``` |
| 44 | +The task are using gulp plugins to call various php tools like [phpunit](https://phpunit.de/), [php code sniffer](https://github.com/squizlabs/PHP_CodeSniffer), [php mess detector](http://phpmd.org/), [php copy / paste detector](https://github.com/sebastianbergmann/phpcpd), [composer](https://getcomposer.org/), [phplint](http://www.icosaedro.it/phplint/), [php code beautifier](https://github.com/squizlabs/PHP_CodeSniffer/wiki/Fixing-Errors-Automatically) |
| 45 | +The available tasks will be listed with a description and available arguments or aliases. |
| 46 | + |
| 47 | +If no task name is given the **default task** will be executed. This will start all the most used tasks. Currently this is composer, tests and check code styling. |
| 48 | + |
| 49 | +# Configuration |
| 50 | +For the most php tools there's a configuration file is available to setup the tool (like phpunit.dist.xml). If the tool has a configuration file available it will be mandatory to use and **should be available in your project root**. The task will fail if the configuration file is not found. |
| 51 | + |
| 52 | +Tasks that don't have a configuration file available have a default configuration and can be overridden by using command line arguments or the **dev-toolbox.config.json**. The tasks always use the tools that are installed locally by your composers dependencies. If composer has not installed the required tool, it will always be installed before the task will run. The tools can be found in **vendor/bin** in your project root. |
| 53 | + |
| 54 | +## dev-toolbox.config.json |
| 55 | +The toolbox has a configuration file that can be used to configure the toolbox and the tasks. |
| 56 | + |
| 57 | +### tasks |
| 58 | +Instead of setting the source of the task as a command line argument using *--source=<path/ **/ *.php> * for example. You can set it directly in the configuration. This why you can start multiple task with different sources and also don't have to pass the source argument every time you want to execute the task. |
| 59 | + |
| 60 | +**Example:** |
| 61 | +```json |
| 62 | +{ |
| 63 | + "tasks": { |
| 64 | + "style:syntax": { |
| 65 | + "source": ["Library/**/*.php", "UnitTests/**/*.php"] |
| 66 | + }, |
| 67 | + "structure:duplication": { |
| 68 | + "source": ["Library/**/*.php"] |
| 69 | + }, |
| 70 | + "structure:complexity": { |
| 71 | + "source": ["Library/"] |
| 72 | + } |
| 73 | + } |
| 74 | +} |
| 75 | +``` |
| 76 | + |
| 77 | +### projectRoot |
| 78 | +The project root can also be changed. This can be used if you don't want that the toolbox is a part of your project for example. |
| 79 | +The working directory must be the toolbox else the gulp task runner can't find the main gulp file. |
| 80 | + |
| 81 | +**Example:** |
| 82 | +```json |
| 83 | +{ |
| 84 | + "projectRoot": "/development/php/hello-world-project" |
| 85 | +} |
| 86 | +``` |
0 commit comments