Needlessly Promiscuous, Modularize!

    generator-clearphp

    1.0.0 • Public • Published

    generator-clearphp

    NPM version NPM downloads Dependency Status Development Dependency Status

    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-clearphp

    To scaffold a new PHP project, create a new directory, cd into it and run the generator:

    mkdir vendorname-project
    cd vendorname-project
    yo clearphp

    Generators

    The generator consists of several subgenerators:

    The subgenerators partly depend on each other:

    Subgenerator dependencies

    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 clearphp:app subgenerator is basically a meta generator pulling in all of the other subgenerators.

    yo clearphp

    main

    The clearphp: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 clearphp: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 clearphp: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:

    PHP project dependency graph (example)

    stored in the doc directory:

    |-- doc
    |   `-- dependencies.svg
    

    By default, the dependency graph is embedded into the README.md. Unless you run the clearphp: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 clearphp:github subgenerator is an essential requirement for most of the other subgenerators and will connect your project to a Github repository.

    yo clearphp: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

    File Description
    .git The Git repository of your project
    post-commit / pre-commit Git hooks that automatically recreate the dependency graph of your project whenever you commit an altered composer.json file.
    .gitattributes Configuration file assigning attributes to paths.
    .gitignore Specification which files (not) to track.
    .travis.yml Configuration file for the Travis CI Service. For Travis to build your project on every commit, you have to manually activate the project repository in your Travis profile.

    codeclimate

    The clearphp:codeclimate generator integrates the Code Climate 3rd party service (account needed):

    yo clearphp:codeclimate

    It adds some configuration resources:

    |-- .codeclimate.yml
    |-- phpmd.xml
    

    Files & directories

    File Description
    .codeclimate.yml Code Climate configuration file
    phpmd.xml PHP Mess Detector configuration file (used by Code Climate)

    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 clearphp:coverage generator integrates the Coveralls 3rd party service (account needed):

    yo clearphp: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 clearphp:scrutinizer generator integrates the Scrutinizer 3rd party service (account needed)

    yo clearphp: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 clearphp:docs generator enables the Read the Docs 3rd party service to render an online documentation of your project resources (account needed):

    yo clearphp: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 clearphp:apidocs generator installs some tools which can automatically create a rich API documentation of your project (requires PHP 5.6+):

    yo clearphp: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 data
    • phpmd: Run PHP Mess Detector on your project
    • phpdox: Create the API documentation
    • build: 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.

    Clear Architecture

    Please see the Clear Architecture documentation 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-clearphp is licensed under the terms of the MIT license.

    Install

    npm i generator-clearphp

    DownloadsWeekly Downloads

    5

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    77.9 kB

    Total Files

    55

    Last publish

    Collaborators

    • jkphl