bound1ess/adviser

A CLI application that checks your project for various possible improvements.

Adviser

Adviser is a CLI application that checks your PHP project for various possible improvements., _(*1)

Heavily inspired by phppackagechecklist.com., _(*2)

Motivation

• Do I have some sort of a license file?
• Is my composer.json valid?
• Is my code PSR-2 compatible?
• Are the repository tags and settings OK?

I often ask myself such questions. And I got tired of checking it all manually every time. Here comes Adviser to make things a lot easier., _(*3)

Navigation

• Installing
• Using
• Configuring
• Extending
• Contributing
• Additional information

Installing

Composer way

Just run in your terminal (you should be in your project's root directory):, _(*4)

composer require --dev bound1ess/adviser

Or, if you don't have Composer installed globally:, _(*5)

curl -sS https://getcomposer.org/installer | php
./composer.phar require --dev bound1ess/adviser

Now you should be able to run vendor/bin/adviser and see Adviser's CLI., _(*6)

Building a PHAR (Box is required)

This is not very difficult to do either, just run:, _(*7)

box --version
git clone https://github.com/bound1ess/adviser.git
cd adviser
composer update # Assuming that it's installed globally.
make build-phar

, _(*8)

Now you can use builds/adviser.phar, or (only if you want to!) you can also do this:, _(*9)

sudo mv builds/adviser.phar /usr/local/bin/adviser

Now you can use adviser (everywhere!) instead of builds/adviser.phar., _(*10)

Using

analyse

This command will analyse (suggest possible improvements) the current working directory., _(*11)

, _(*12)

analyse --formatter="formattername"

Same, but the output will be formatted depending on the formatter you choose., _(*13)

, _(*14)

Available formatters:, _(*15)

• plaintext (Adviser\Output\Formatters\PlainTextFormatter).

analyse-repository name [--formatter="..."]

The name argument here is a Github repository name (e.g. bound1ess/adviser). This command will make a local clone of it, run the analyse command, then remove it (directory)., _(*16)

, _(*17)

Configuring

Adviser can be configured via an adviser.yml file placed in the working directory., _(*18)

Adding a Formatter

# Add a new formatter.
formatters:
    - "Your\Custom\Formatter\ClassName"
    # ...

Adding a Validator

# Add a new validator.
validators:
    - "Your\Custom\Validator\ClassName"
    # ...

Configuring a Validator

ChangelogValidator

Adviser\Validators\ChangelogValidator:
    files:
        - "CHANGELOG.md"
        # ...

CIValidator

Adviser\Validators\CIValidator:
    allowedVersions:
        - "5.6"
        - "5.5"
        - "5.4"
        - "hhvm"
        # ...

ComposerValidator

Adviser\Validators\ComposerValidator:
    autoloader: "psr-4"
    source_directory: "src"

ContributingValidator

Adviser\Validators\ContributingValidator:
    files:
        - "CONTRIBUTING.md"
        # ...

FrameworkValidator

Adviser\Validators\FrameworkValidator:
    frameworks:
        - "laravel/framework"
        # ...

LicenseValidator

Adviser\Validators\LicenseValidator:
    files:
        - "LICENSE.md"
        # ...

ReadmeValidator

Adviser\Validators\ReadmeValidator:
    files:
        - "README.md"
        # ...

TestValidator

Adviser\Validators\TestValidator:
    frameworks:
        - "phpunit/phpunit"
        # ...
    frameworkToFiles:
        phpunit/phpunit:
            - "phpunit.xml"
            - "phpunit.xml.dist"
            # ...
        # ...

Extending

1. Write the code.
2. Don't forget to test it!
3. Add it to the adviser.yml configuration file (see Configuring section).
4. Done! Share your work with others if you want to.

Creating a Validator

class YourValidator extends \Adviser\Validators\AbstractValidator
{

    /**
     * @return \Adviser\Output\MessageBag
     */
    public function handle()
    {
        // @todo
    }
}

Creating a Formatter

use Adviser\Output\MessageBag;

class YourFormatter extends \Adviser\Output\Formatters\AbstractFormatter
{

    /**
     * @param MessageBag $bag
     * @return string
     */
    public function format(MessageBag $bag)
    {
        // @todo
    }
}

Contributing

1. Fork the project and create a local clone of it.
2. Install the dependencies: composer update or composer install --dev.
3. Make a fix.
4. Run the tests: make tests.

, _(*19)

1. Build the coverage report:

make code-coverage
make boot-server

Now open localhost:8000 in your browser. , _(*20)

1. Commit and pull!

Extra: building the documentation (ApiGen is required)

apigen --version
make build-docs boot-docs-server

Additional information

License and support information, as well as my thanks to everyone who made Adviser possible., _(*21)

License

This project is licensed under the MIT license., _(*22)

Support

Stuck? Found a bug? Feel free to create a new issue here on Github, or find me on Twitter., _(*23)

Thanks!

To the creators of PHPUnit, Symfony, Guzzle, Mockery and Box projects., _(*24)