PlaywrightPHP

Internals

Understand the runtime architecture, public object model, transport, configuration, and JavaScript mapping.

Use this chapter when you need to understand what happens behind the public PHP API. It is useful for runtime startup problems, contribution work, custom infrastructure, and migration from upstream JavaScript examples.

Most browser tests do not need internals. If the browser launches and the page behaves incorrectly, start with Browser, Testing, or Debugging.

The runtime in one sentence

Your PHP code sends synchronous commands to a Node.js bridge running Playwright core, and that bridge controls real browser processes.

The public PHP objects keep that boundary readable:

  • PlaywrightClient owns the connection;
  • Browser owns contexts;
  • BrowserContext owns isolated session state and pages;
  • Page, Frame, and Locator describe browser work;
  • the transport moves commands, responses, and events between PHP and Node.js.

Choose a page

Need Open
See where PHP, Node.js, and browsers fit Architecture
Understand public objects and ownership Object model
Diagnose bridge startup or connection failures Transport
Configure Node.js, browsers, proxies, and artifacts Configuration
Translate upstream JavaScript examples safely From JavaScript

Read internals when

  • Node.js or the bridge cannot start;
  • the browser process exits unexpectedly;
  • you need explicit runtime ownership in a long-lived PHP process;
  • you are contributing a binding or transport change;
  • a JavaScript example does not map cleanly to PHP.

Avoid

  • Debugging transport before confirming that browsers are installed.
  • Depending on internal JSON payloads from application tests.
  • Treating conceptual upstream classes as shipped PHP classes.
  • Assuming JavaScript async patterns can be copied after removing await.
  • Using internals instead of the API reference for exact public methods.

FAQ

Do I need Node.js to write JavaScript?

No. Node.js runs the Playwright bridge. Your test remains PHP.

Is the PHP API asynchronous?

No. Public calls block until they return, fail, or time out. Browser events are dispatched through the transport while calls are running.

Is the internal protocol public API?

No. Use PHP classes and interfaces from the API reference. Internal transport payloads may change independently.

Where do I check upstream coverage?

Use the public API parity report, then verify exact PHP names in the API reference.