PlaywrightPHP

Configuration

Configure the runtime explicitly or load supported settings from environment variables.

Use the convenience API for a small script. Use PlaywrightConfig and PlaywrightConfigBuilder when a suite needs shared runtime defaults, custom Node.js discovery, browser channels, proxies, or artifact directories.

Choose the configuration surface

The convenience entry point accepts a small set of launch and context options:

php
$context = Playwright::chromium([
    'headless' => false,
    'slowMo' => 100,
    'args' => ['--disable-dev-shm-usage'],
    'context' => [
        'locale' => 'en-GB',
        'timezoneId' => 'Europe/London',
    ],
]);

For reusable configuration, build a client:

php
use Playwright\Browser\BrowserType;
use Playwright\Configuration\PlaywrightConfigBuilder;
use Playwright\PlaywrightFactory;

$config = PlaywrightConfigBuilder::create()
    ->withBrowser(BrowserType::CHROMIUM)
    ->withHeadless(true)
    ->withTimeoutMs(30_000)
    ->withDownloadsDir(__DIR__.'/var/downloads')
    ->build();

$client = PlaywrightFactory::create($config);

The configuration object describes runtime defaults. Individual browser or context options can still be more specific when the public method exposes them.

Defaults

The builder starts with:

Setting Default
Browser Chromium
Headless true
Timeout 30 seconds
Slow motion 0 ms
Minimum Node.js 20.0.0
Channel Playwright-managed browser
Proxy none
Downloads, video, trace directories unset

Keep defaults boring. A suite should not require a developer to know hidden environment state before the first run.

Load supported environment variables

Environment variables are read only when you call PlaywrightConfigBuilder::fromEnv():

php
$config = PlaywrightConfigBuilder::fromEnv()->build();
$client = PlaywrightFactory::create($config);

Supported variables:

Variable Purpose
PLAYWRIGHT_NODE_PATH Explicit Node.js executable
PLAYWRIGHT_NODE_MIN_VERSION Minimum accepted Node.js version
PLAYWRIGHT_BROWSERS_PATH Browser binary cache passed to the bridge
PW_BROWSER chromium, chrome, firefox, or webkit
PW_CHANNEL Browser channel such as chrome or msedge
PW_HEADLESS Headless boolean
PW_TIMEOUT_MS Default timeout in milliseconds
PW_SLOWMO_MS Delay between browser actions
PW_TRACE Enable or disable tracing
PW_TRACE_DIR Trace output directory
PW_DOWNLOADS_DIR Download output directory
PW_VIDEOS_DIR Video output directory
PW_PROXY_SERVER Proxy server URL
PW_PROXY_USERNAME Proxy username
PW_PROXY_PASSWORD Proxy password
PW_PROXY_BYPASS Hosts that bypass the proxy

Names such as PW_TIMEOUT or PW_SLOWMO are not aliases. Use the exact _MS forms.

Precedence

Treat configuration in three steps:

  1. create() supplies library defaults, or fromEnv() supplies defaults plus supported environment values.
  2. Builder calls made afterward override those values.
  3. More specific browser or context options apply to the object created by that call.
php
$config = PlaywrightConfigBuilder::fromEnv()
    ->withHeadless(false)
    ->withTimeoutMs(45_000)
    ->build();

Here, environment values are loaded first; the two explicit builder calls win.

There is no php.ini configuration layer.

Keep secrets and paths intentional

Proxy credentials and authenticated storage can expose real accounts. Prefer CI secrets for credentials and keep storage-state files outside version control.

Give each parallel worker its own artifact directory. Shared download, video, or trace paths can overwrite evidence and make failures appear nondeterministic.

Use project-relative paths when artifacts should be collected by CI:

php
$artifactRoot = dirname(__DIR__).'/var/playwright';

$config = PlaywrightConfigBuilder::create()
    ->withDownloadsDir($artifactRoot.'/downloads')
    ->withVideosDir($artifactRoot.'/video')
    ->withTracing(true, $artifactRoot.'/traces')
    ->build();

Diagnose configuration before browser behavior

When startup fails:

  1. print the effective Node.js path and version;
  2. confirm browser binaries are installed;
  3. check that artifact directories are writable;
  4. test without a custom channel or proxy;
  5. then reintroduce project-specific settings.

Do not increase action timeouts to hide a missing browser binary or broken proxy.

Go next