Configuration

phpspec can be configured via a config file in the project root. The first file found wins.

Config file priority

phpspec.yaml (highest)
phpspec.yml
phpspec.json
phpspec.php (lowest)

Example: `phpspec.yaml`

spec_path: spec
src_path: src
format: pretty
bootstrap: bootstrap.php
stop_on_failure: false
autoload:
  App\: src/App
  Acme\: lib/Acme

Example: `phpspec.json`

{
    "spec_path": "spec",
    "src_path": "src",
    "format": "pretty",
    "bootstrap": "bootstrap.php",
    "stop_on_failure": false,
    "autoload": {
        "App\\": "src/App"
    }
}

Configuration keys

Key	Default	Description
`spec_path`	`spec`	Directory containing spec files
`src_path`	`src`	Source directory for code generation and coverage
`spec_suffix`	`.spec.php`	File suffix for spec files
`format`	`pretty`	`pretty`, `dot`, `tap`, `junit`
`bootstrap`	—	PHP file to require before running
`stop_on_failure`	`false`	Stop on first failure or error
`stop_on_error`	`false`	Stop on first error
`stop_on_warning`	`false`	Stop on first warning
`stop_on_deprecation`	`false`	Stop on first deprecation
`stop_on_notice`	`false`	Stop on first notice
`stop_on_skipped`	`false`	Stop on first skip
`autoload`	—	PSR-4 namespace-to-directory mappings
`base_url`	—	Base URL for browser testing

PSR-4 autoloading

autoload:
  App\: src/App
  Domain\: src/Domain
  Infrastructure\: src/Infrastructure

Each key is a namespace prefix (with trailing \), each value is a directory path relative to the project root.

Named suites

Group specs into named suites, each with its own paths:

suites:
  unit:
    paths:
      - spec/Unit
    src: src
  integration:
    paths:
      - spec/Integration
    src: src

When no suites key is present, phpspec synthesises a default suite from spec_path and src_path.

CLI overrides

CLI flags take priority over config file values:

Config key	CLI flag
`format`	`--format` / `-f`
`bootstrap`	`--bootstrap` / `-b`
`stop_on_failure`	`--stop-on-failure`
`stop_on_error`	`--stop-on-error`

Auto-detection

phpspec automatically detects and requires vendor/autoload.php if it exists. Composer-managed projects work out of the box.

AI configuration

Enable AI-powered pair, next, and refactor commands:

ai:
  provider: anthropic
  api_key: YOUR_API_KEY

Provider	Default Model
`google`	`gemini-2.5-pro`
`anthropic`	`claude-sonnet-4-20250514`
`openai`	`gpt-4o`

See AI Pair Programming for full documentation.

Extensions

extensions:
  matchers:
    - App\ValidJsonMatcher
  formatters:
    - App\MinimalFormatter
  commands:
    - App\GreetCommand
  listeners:
    - App\SlowTestReporter

See Extensions for details.

← CLI Reference

Browser Testing →