Configuration

Unless overridden with the --config option, PHPBench will try to load its configuration from the current working directory. It will check for the existence each of the files phpbench.json and phpbench.json.dist in that order and use one if it exists.

{
    "bootstrap": "vendor/autoload.php",
    "path": "path/to/benchmarks",
    "outputs": {
         "my_output": {
             "extends": "html",
             "file": "my_report.html",
             "title": "Hello World"
         }
    },
    "reports": {
        "my_report": {
            "extends": "aggregate",
            "exclude": ["benchmark"]
        }
    }
}

Note

Typically you should use phpbench.json.dist in your projects. This allows the end-user of your library to override your configuration by creating phpbench.json.

Bootstrap

You can include a single file, the bootstrap file, before the benchmarks are executed. Typically this will be the class autoloader (e.g. vendor/autoload.php).

It is specified with the bootstrap key:

{
    "bootstrap": "vendor/autoload.php",
}

Note

You can override (or initially set) the bootstrap using the --bootstrap CLI option.

Path

Specify the default path to the benchmarks:

{
    "path": "tests/benchmarks"
}

Progress Logger

Specify which progress logger to use:

{
    "progress": "dots"
}

Retry Threshold

Set the Retry Threshold:

{
    "retry_threshold": 5
}

Reports

List of report definitions:

{
    "reports": {
        "my_report": {
            "extends": "aggregate",
            "exclude": ["benchmark"]
        }
    }
}

The key is the name of the report that you are defining, and the object properties are the options for the report. Each report must specify either the generator or extends key, specifying the generator or report to extend respectively.

See the Report Generators chapter for more information on report configuration.

Outputs

Custom output definitions:

"outputs": {
     "my_output": {
         "extends": "html",
         "file": "my_report.html",
         "title": "Hello World"
     }
}

Note that:

  • The key of each definition is the output name.
  • As with reports, each definition MUST include either the renderer or extends key.
  • All other options are passed to the renderer as options.

See the Report Renderers chapter for more information.

Time Unit and Mode

Specify the default time unit. Note that this will be overridden by individual benchmark/subjects and when the time-unit option is passed to the CLI.

{
    "time_unit": "milliseconds"
}

Similarly the Mode: Throughput Representation can be set using the output_mode key:

{
    "output_mode": "throughput"
}

PHP Binary and INI settings

You can change the PHP binary and INI settings used to execute the benchmarks:

{
    "php_binary": "hhvm",
    "php_config": {
        "memory_limit": "10M"
    }
}

Prefixing the Benchmarking Process

You can prefix the benchmarking command line using the php_wrapper option:

{
    "php_wrapper": "blackfire run"
}

Note

This can also be set using the --php-wrapper CLI option.

Customizing the subject matching pattern

By default PHPBench will identify subject methods when they have a bench prefix. It is possible to change the regex pattern used to identify subjects as follows:

{
    "subject_pattern": "^spin_"
}

The above will allow you to have benchmark class such as:

<?php

class Foobar
{
    public function spin_kde()
    {
        // ...
    }

    public function spin_lcd()
    {
        // ...
    }
}

Note

You can also explicitly declare that methods are benchmark subjects by using the @Subject annotation.