Pahout

A pair programming partner for writing better PHP. Pahout means PHP mahout 🐘

Motivation

PHP has been added various features in the long history. However, due to the length of its history, many old syntax is scattered over the Internet. If a PHPer learned from them, the PHPer cannot know the excellent syntax and functions existing in the latest PHP version. This is a very sad thing.

So, I thought about making a linter like a pair programming partner who tells you a good way. It will help you write better PHP with you.

However, please do not try to fix all existing codes based on the hints of Pahout first. Pahout is a pair programming partner. When pairing programming, you don't check all existing codes, do you? My recommendation is to only check on newly created or modified files. For example, it is a good idea to set pre-commit hook as follows:

#!/bin/sh

git diff --name-only | grep .php | xargs vendor/bin/pahout
if ["$?" -ne 0]; then
    exit 1
fi

Installation

Pahout requires the following environment:

• PHP 7.1 or newer
• php-ast v0.1.7 or newer

Using Composer

You can install with composer.

$ composer require --dev wata727/pahout
$ vendor/bin/pahout -V

Using Docker

By using the Docker image, you can easily try Pahout without affecting the local environment.

$ docker run --rm -t -v $(pwd):/workdir wata727/pahout

Quick Start

You are using PHP 7.1.8 in your project. What do you think of the following code?

<?php

// Do something...

$response = get_awesome_response();
$error = isset($response['error']) ? $response['error'] : null;

// Do something...

Perhaps it is a familiar code. However, if you know the null coalescing operator, you will write something like this:

<?php

// Do something...

$response = get_awesome_response();
$error = $response['error'] ?? null; # Great!

// Do something...

Pahout will support such rewriting. Try to run on the above example.

$ pahout --php-version 7.1.8 test.php
test.php:8
    NullCoalescingOperator: Use the null coalecing operator instead of the ternary operator. [https://github.com/wata727/pahout/blob/master/docs/NullCoalescingOperator.md]

1 files checked, 1 hints detected.

Pahout tells you where the null coalescing operator can be used! For the list of hints provided by Pahout, please see this documentation.

If you want to analyze multiple files, you can specify more than one.

$ pahout --php-version 7.1.8 test.php test2.php ...

If you specify a directory name, all .php files under that directory will be covered.

$ pahout --php-version 7.1.8 src

Configuration

You can change the configuration from the command line.

$ pahout --help
Description:
  A pair programming partner for writing better PHP

Usage:
  check [options] [--] [<files>...]

Arguments:
  files                              List of file names or directory names to be analyzed

Options:
      --php-version[=PHP-VERSION]    Target PHP version [default: runtime version]
      --ignore-tools[=IGNORE-TOOLS]  Ignore tool types [default: Nothing to ignore] (multiple values allowed)
      --ignore-paths[=IGNORE-PATHS]  Ignore files and directories [default: Nothing to ignore] (multiple values allowed)
      --extensions[=EXTENSIONS]      File extensions to be analyzed [default: php] (multiple values allowed)
      --vendor[=VENDOR]              Check vendor directory [default: false]
  -f, --format[=FORMAT]              Output format [default: "pretty", possibles: "pretty", "json"]
  -c, --config[=CONFIG]              Config file path [default: ".pahout.yaml"]
      --only-tools[=ONLY-TOOLS]      Check only the given tool types (multiple values allowed)
  -h, --help                         Display this help message
  -q, --quiet                        Do not output any message
  -V, --version                      Display this application version
      --ansi                         Force ANSI output
      --no-ansi                      Disable ANSI output
  -n, --no-interaction               Do not ask any interactive question
  -v|vv|vvv, --verbose               Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

You can also change the configuration by preparing a configuration file called .pahout.yaml.

php_version: 7.0.0
ignore_tools:
    - ShortArraySyntax
ignore_paths:
    - tests
    - bin
extensions:
    - php
    - module
    - inc
vendor: true

PHP Version

Specify the PHP version of your project. The default is the runtime version. Pahout uses this version to select tools.

Ignore Tools

In Pahout, what generates hints is called "Tool". You can specify the tool name you want to ignore. Please look at the documentation for the list of tool names.

Only Tools

Contrary to ignore_tools, specify tools to check.

Ignore Paths

You can specify the file or directory you want to ignore. If a directory name is specified, all files under that directory are ignored.

Extensions

File extensions to be analyzed. Default is php only.

Vendor

You can set whether to ignore the vendor directory.

Note: The vendor directory is ignored by default. Generally, you don't need to check the vendor directory.

Format

Specify the output format. Currently only pretty and json are supported.

Config

Specify a configuration file name. This is useful when you want to use the file name other than .pahout.yaml in the configuration file.

Annotation

Using annotations, you can ignore hints for specific lines. Specify the tool name you want to ignore with @rebel.

<?php

/** @rebel NullCoalescingOperator */
$error = isset($response['error']) ? $response['error'] : null;

The following comments will work in the same way.

<?php

/**
* @rebel NullCoalescingOperator
*/
$error = isset($response['error']) ? $response['error'] : null;

$error = isset($response['error']) ? $response['error'] : null; # @rebel NullCoalescingOperator

Author

Kazuma Watanabe