generator-cleanphp
is a Yeoman generator for scaffolding Composer based PHP projects. It supports a variety of 3rd party tools and intergrations and advocates the use of a custom Clean Architecture implementation.
Usage
To install the PHP project generator and its dependencies, please run:
npm install -g yo generator-cleanphp
To scaffold a new PHP project, create a new directory, cd
into it and run the generator:
mkdir vendorname-project
cd vendorname-project
yo cleanphp
Generators
The generator consists of several subgenerators:
The subgenerators partly depend on each other:
Each subgenerator will only run once and automatically pull in the other generators it depends on. You can run them individually at any time, using them as supplementary add-ons to your project.
app
The cleanphp:app
subgenerator is basically a meta generator pulling in all of the other subgenerators.
yo cleanphp
main
The cleanphp:main
generator creates the basic project structure and setup. During installation, you will be asked a couple of questions like the vendor and project name, the minimum PHP version and some information about the project author.
yo cleanphp:main
will scaffold these files and directories for you:
|-- .editorconfig
|-- .yo-rc.json
|-- CHANGELOG.md
|-- CONDUCT.md
|-- LICENSE
|-- README.md
|-- composer.json
|-- composer.lock
|-- doc
|-- phpunit.php
|-- phpunit.xml.dist
`-- src
`-- <Project>
|-- Application
|-- Domain
|-- Infrastructure
|-- Ports
`-- Tests
Files & directories
File | Description |
---|
.editorconfig | Editorconfig definitions file |
.yo-rc.json | Yeoman's configuration file where your answers are stored between generator runs. Don't edit this file manually. However, if you're sure you'll never run any of the generators again, you can safely delete this file. |
CHANGELOG.md | Changelog of your project. Try to stick to Keep a CHANGELOG principles when adding entries. |
CONDUCT.md | Contributor Code of Conduct, adapted from the Contributor covenant version 1.4. |
LICENCE | The license you selected during installation. |
README.md | The main README file of your project. Be aware that it might be amended and overwritten when you run additional subgenerators at a later time. However, you'll always have the chance to review the differences (if any) and skip an update. |
composer.json | The Composer configuration of your project. |
doc | This is the directory where your project documentation should reside. You can add some basic files with the cleanphp:docs generator. |
phpunit.php | Bootstrap file for PHPUnit including the Composer autoloader. |
phpunit.xml.dist | PHPUnit configuration |
src | Base directory for your PHP project source files. See below for some words on the clean architecture principles propagated by the generator. |
Composer dependencies
Scripts
Unit tests
You can run your PHPUnit unit tests by calling the Composer script
composer run phpunit
or
composer run test
Dependency graph
You can create a dependency graph of your project by running
composer run depgraph
This will create an SVG file like this:
stored in the doc
directory:
|-- doc
| `-- dependencies.svg
By default, the dependency graph is embedded into the README.md
. Unless you run the cleanphp:github subgenerator, you'll have to create and update the graph manually each time you change the Composer dependencies of your project.
PHP code style linter
You can use the check-style
script to test your PHP files for PSR-2 compliance:
composer run check-style
You can automatically fix a wide range of coding style violations with the fix-style
script:
composer run fix-style
github
The cleanphp:github
subgenerator is an essential requirement for most of the other subgenerators and will connect your project to a Github repository.
yo cleanphp:github
The generator initializes a local Git repository and adds some files:
|-- .git
| `-- hooks
| |-- post-commit
| `-- pre-commit
|-- .gitattributes
|-- .gitignore
|-- .travis.yml
Please be aware that the generator doesn't create a remote repository on Github. You'll have to do that manually prior to running the generator. The generator will ask you for the Github repository URL. You can provide either the SSH or the HTTPS repository URL here.
Files & directories
codeclimate
The cleanphp:codeclimate
generator integrates the Code Climate 3rd party service (account needed):
yo cleanphp:codeclimate
It adds some configuration resources:
|-- .codeclimate.yml
|-- phpmd.xml
Files & directories
Composer dependencies
Travis configuration
Among other things, the generator adds a Code Climate repository token to your Travis CI configuration file:
after_script:
- bash -c 'if [ "$TRAVIS_PHP_VERSION" != "hhvm" ]; then vendor/bin/test-reporter; fi;'
addons:
code_climate:
repo_token: <CODE-CLIMATE-REPO-TOKEN>
Please obtain this token prior to running the generator by
- adding your Github repository as a project to your Code Climate profile,
- going to
Settings > Test Coverage
, - scrolling down, displaying the Travis CI options and copying the 64-character
repo_token
from there.
coverage
The cleanphp:coverage
generator integrates the Coveralls 3rd party service (account needed):
yo cleanphp:coverage
Composer dependencies
Travis configuration
The generator adds an after_script
entry to your Travis CI configuration file, used for submitting code coverage data to Coveralls:
after_script:
- bash -c 'if [ "$TRAVIS_PHP_VERSION" != "hhvm" ]; then php vendor/bin/coveralls -v; fi;'
Coveralls configuration
You need to manually activate the Github repository in your Coveralls account settings.
scrutinizer
The cleanphp:scrutinizer
generator integrates the Scrutinizer 3rd party service (account needed)
yo cleanphp:scrutinizer
It adds a single configuration resource:
|-- .scrutinizer.yml
Files & directories
File | Description |
---|
.scrutinizer.yml | Scrutinizer configuration file |
Travis configuration
The generator adds two after_script
entries to your Travis CI configuration file, used for submitting code coverage data to Scrutinizer:
after_script:
- bash -c 'if [ "$TRAVIS_PHP_VERSION" != "hhvm" ]; then wget https://scrutinizer-ci.com/ocular.phar; fi;'
- bash -c 'if [ "$TRAVIS_PHP_VERSION" != "hhvm" ]; then php ocular.phar code-coverage:upload --format=php-clover build/logs/clover.xml; fi;'
Scrutinizer configuration
You need to manually add your Github repository to your Scrutinizer account.
docs
The cleanphp:docs
generator enables the Read the Docs 3rd party service to render an online documentation of your project resources (account needed):
yo cleanphp:docs
It adds some configuration and example documentation resources:
|-- doc
| |-- index.md
| `-- todo.md
|-- mkdocs.yml
Files & directories
File | Description |
---|
index.md / todo.md | Basic documentation example files |
mkdocs.yml | MkDocs configuration file (used by Read the Docs) |
Read the Docs / MkDocs configuration
To render an online documentation of your project, you have to
apidocs
The cleanphp:apidocs
generator installs some tools which can automatically create a rich API documentation of your project (requires PHP 5.6+):
yo cleanphp:apidocs
It adds some configuration resources:
|-- build
|-- phpdox.xml.dist
Files & directories
File | Description |
---|
build | Directory for temporary files needed during API documentation creation |
phpdox.xml.dist | phpDox configuration file |
Composer dependencies
Scripts
API documentation
The generator configures a couple of Composer scripts for API documentation creation:
phploc
: Collect project size dataphpmd
: Run PHP Mess Detector on your projectphpdox
: Create the API documentationbuild
: Run the phploc
, phpmd
, phpunit
and phpdox
scripts in a row (complete API documentation creation)
While you can call the scripts individually, you will most likely want to run the build
script to create your API documentation:
composer run build
Your documentation will be rendered into the apidocs
directory (created if necessary). Please be aware that the creation will fail as long as you don't have any PHP files in your project.
To use the scripts on Windows, edit the scripts
section of your composer.json
manually and add a .bat
file extension to all the vendor/bin/*
binary calls.
Clean Architecture
Please see the recommended architecture principles for an inspiration on how to structure your PHP application.
Known problems / To-do
Currently there are no known problems.
Changelog
Please refer to the changelog for a complete release history.
Legal
Copyright © 2017 Joschi Kuphal joschi@kuphal.net / @jkphl. generator-cleanphp is licensed under the terms of the MIT license.