---
slug: /developers/apis/javascript-api/playground-api-client
---

<!-- Generated by bin/generate-handbook-api-client.js. Do not edit directly. -->

# Playground API Client

The `PlaygroundClient` object implements the `UniversalPHP` interface. All the methods from that interface are also available in Node.js and same-process PHP instances (Playground runs PHP in a web worker).

Broadly speaking, you can use the client to perform three types of operations:

- Running PHP code
- Customizing `PHP.ini`
- Managing files and directories

## Running PHP code

The two methods you can use to run PHP code are:

- [`run()`](#the-run-method) - runs PHP code and returns the output
- [`request()`](#the-request-method) - makes an HTTP request to the website

In Node.js, you can also use the [`cli()`](#the-cli-method) method to run PHP in a CLI mode.

### The `run()` method

<!-- The handbook imports static/handbook/playground-api-client.md, generated
from this page and TypeDoc by bin/generate-handbook-api-client.js. Keep the
TSDocstring components here so the generated API descriptions stay in sync. -->

Runs PHP code.

This low-level method directly interacts with the WebAssembly
PHP interpreter.

Every time you call run(), it prepares the PHP
environment and:

- Resets the internal PHP state
- Populates superglobals ($\_SERVER, $\_GET, etc.)
- Handles file uploads
- Populates input streams (stdin, argv, etc.)
- Sets the current working directory

You can use run() in two primary modes:

#### Code snippet mode

In this mode, you pass a string containing PHP code to run.

```ts
const result = await client.run({
	code: `<?php echo "Hello world!";`,
});
// result.text === "Hello world!"
```

In this mode, information like `__DIR__` or `__FILE__` isn't very
useful because the code is not associated with any file.

Under the hood, the PHP snippet is passed to the `zend_eval_string`
C function.

#### File mode

In the file mode, you pass a scriptPath and PHP executes a file
found at a that path:

```ts
await client.writeFile('/www/index.php', `<?php echo "Hello world!";`);
const result = await client.run({
	scriptPath: '/www/index.php',
});
// result.text === "Hello world!"
```

In this mode, you can rely on path-related information like `__DIR__`
or `__FILE__`.

Under the hood, the PHP file is executed with the `php_execute_script`
C function.

The `run()` method cannot be used in conjunction with `cli()`.

### The `request()` method

Serves the request – either by serving a static file, or by
dispatching it to the PHP runtime.

The request() method mode behaves like a web server and only works if
the PHP was initialized with a `requestHandler` option (which the online
version of WordPress Playground does by default).

In the request mode, you pass an object containing the request information
(method, headers, body, etc.) and the URL to request:

```ts
await client.writeFile('/index.php', `<?php echo file_get_contents('php://input');`);
const result = await client.request({
	url: '/index.php',
	method: 'POST',
	headers: {
		'Content-Type': 'text/plain',
	},
	body: 'Hello world!',
});
// result.text === 'Hello world!'
```

The `request()` method cannot be used in conjunction with `cli()`.

## Customizing `PHP.ini`

The API client also allows you to change the `php.ini` file:

```ts
await setPhpIniEntries(client, {
	display_errors: 'On',
	error_reporting: 'E_ALL',
});
```

## Managing files and directories

The `client` object provides you with a low-level API for managing files and directories in the PHP filesystem:

```ts
await client.mkdirTree('/wordpress/test');
// Create a new PHP file
await client.writeFile(
	'/wordpress/test/index.php',
	`<?php
     echo "Hello, world!<br/>";
     // List all the files in current directory
     print_r(glob(__DIR__ . '/*'));
  `
);
// Create files named 1, 2, and 3
await client.writeFile('/wordpress/test/1', '');
await client.writeFile('/wordpress/test/2', '');
await client.writeFile('/wordpress/test/3', '');
// Remove the file named 1
await client.unlink('/wordpress/test/1');
// Navigate to our PHP file
await client.goTo('/test/index.php');
```

For a complete list of these methods, refer to the `PlaygroundClient` interface.

## Sending messages to JavaScript

You can pass messages from PHP to JavaScript using the `post_message_to_js()` function. It accepts one argument:

- `$data` (string) – Data to pass to JavaScript.

For example, here's how you would send a message with a JSON-encoded post ID and title:

```TypeScript
import { PHP } from '@php-wasm/universal';
import { loadNodeRuntime } from '@php-wasm/node';

const php = new PHP(await loadNodeRuntime('8.3'));

php.onMessage(
	// The data is always passed as a string
	function (data: string) {
		// Let's decode and log the data:
		console.log(JSON.parse(data));
	}
);

// Now that we have a listener in place, let's
// dispatch a message:
await php.runStream({
	code: `<?php
        post_message_to_js(
            json_encode([
                'post_id' => '15',
                'post_title' => 'This is a blog post!'
            ])
        );
    `,
});

// You will see the following output in the console:
// { post_id: '15', post_title: 'This is a blog post!' }
```

## The `cli()` method

In Node.js, you also have access to the `cli()` method that runs PHP in a CLI mode:

```ts
// Run PHP in a CLI mode
client.cli(['-r', 'echo "Hello, world!";']);
// Outputs "Hello, world!"
```

Once `cli()` method finishes running, the PHP instance is no longer usable and should be discarded. This is because PHP internally cleans up all the resources and calls `exit()`.