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() - runs PHP code and returns the output
• request() - makes an HTTP request to the website

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

The run() method

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 path to the PHP file to run:

const php = PHP.load('7.4', {
	requestHandler: {
		documentRoot: "/www"
	}
})
php.writeFile("/www/index.php", `<?php echo file_get_contents("php://input");`);
const result = await php.request({
	method: "GET",
	headers: {
		"Content-Type": "text/plain"
	},
	body: "Hello world!",
	path: "/www/index.php"
});
// 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:

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:

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 full list of these methods, consult 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:

const php = await PHP.load('8.0');

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.run({
    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:

// 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().