php-server

library3.0.0jsnpmunverified

php-server is a utility that simplifies the process of starting PHP's built-in development web server directly from Node.js applications. It's designed for development environments, not production, and provides an API to control the server, including specifying port, hostname, base directory, and custom PHP configurations like INI directives or a router script. The package is currently at version 3.0.0 and maintains an active release cadence, primarily driven by Node.js version updates. Key differentiators include its simple API for programmatic control, automatic process management, and seamless integration with Node.js development workflows, making it easy to spin up a quick PHP backend for testing or local development without managing separate PHP processes manually. It is a pure ESM package.

devops web-framework

npm install php-server

github ↗package ↗

INSTALL

IMPORT

SIG · PHP-SERVER

php-server

devopsjavascriptv3.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

phpServer

✓ import phpServer from 'php-server';

✗ const phpServer = require('php-server');

The package is pure ESM since v1.0.0. CommonJS `require` is not supported.

phpServerOptions

✓ import phpServer, { Options as PhpServerOptions } from 'php-server';

Use `Options` for type hinting in TypeScript. The primary export is the default function.

ServerInstance

✓ import phpServer, { Server as ServerInstance } from 'php-server';

The `Server` interface represents the return type of `phpServer()` for type hinting in TypeScript, providing `url`, `stdout`, `stderr`, and `stop()` method.

Demonstrates how to start a basic PHP server, a customized server with specific port, hostname, base directory, and browser opening, along with type imports.

import phpServer from 'php-server'; async function startServers() { // Basic usage const server1 = await phpServer(); console.log(`PHP server running at ${server1.url}`); // With custom configuration const server2 = await phpServer({ port: 8080, hostname: 'localhost', base: './public', open: true, // Opens browser automatically router: './router.php' // Assuming router.php exists in the project root }); console.log(`Custom PHP server running at ${server2.url}`); // Example of a simple router.php file (create this in your project root) // router.php: // <?php // if (preg_match('/\.(?:png|jpg|jpeg|gif|css|js)$/', $_SERVER["REQUEST_URI"])) { // return false; // Serve the requested resource as-is // } else { // echo "<h1>Hello from PHP!</h1>"; // echo "<p>URI: " . $_SERVER["REQUEST_URI"] . "</p>"; // } // ?> // Clean up when done (e.g., on process exit or after tests) // server1.stop(); // server2.stop(); } startServers().catch(console.error);

Debug

Known issues

breakingVersion 3.0.0 of `php-server` requires Node.js version 20 or higher. Previous versions of Node.js are no longer supported.

fix

Upgrade your Node.js environment to version 20 or later. Use a Node.js version manager like `nvm` or `volta` if you need to manage multiple versions.

affects: >=3.0.0

breakingVersion 2.0.0 of `php-server` required Node.js version 18 or higher. Projects running on older Node.js versions needed to upgrade.

fix

Ensure your Node.js environment is version 18 or later. For current versions, refer to the latest breaking changes.

affects: >=2.0.0 <3.0.0

breakingVersion 1.0.0 transitioned `php-server` to be a pure ES Module (ESM). This means it can no longer be imported using `require()` in CommonJS environments.

fix

Refactor your imports from `const phpServer = require('php-server');` to `import phpServer from 'php-server';`. Ensure your project is configured for ESM, potentially by adding `"type": "module"` to your `package.json` or by using `.mjs` file extensions.

affects: >=1.0.0

gotchaThe `open` option in `phpServer` can now accept an absolute URL, a relative path, or a boolean. Prior to v3.0.0, handling of absolute URLs might have been incorrect, leading to unexpected browser behavior.

fix

Ensure you are on `php-server` v3.0.0 or later to correctly utilize the `open` option with absolute URLs or relative paths. Review its usage if migrating from an older version.

affects: <3.0.0

gotchaIf the `php` binary is not found in the system's PATH, `php-server` will fail to start. This is a common issue in environments where PHP is not globally installed or its path is not configured.

fix

Ensure PHP is installed and accessible via your system's PATH. Alternatively, use the `binary` option to provide the explicit path to your PHP executable, e.g., `phpServer({ binary: '/usr/local/bin/php' })`.

affects: >=0.1.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module .../node_modules/php-server/index.js from ... not supported.

Attempting to use `require()` to import `php-server` in a CommonJS context, but the package is pure ESM since v1.0.0.

fix

Change `const phpServer = require('php-server');` to `import phpServer from 'php-server';`. If your project is CommonJS, you'll need to configure it to support ESM imports, typically by adding `"type": "module"` to your `package.json` or changing the file extension to `.mjs`.

Error: spawn php ENOENT

The `php` executable was not found in the system's PATH, or the specified `binary` option path is incorrect.

fix

Verify that PHP is installed on your system and its executable is added to your system's PATH environment variable. If PHP is installed in a non-standard location, provide the full path to the `php` binary using the `binary` option, e.g., `phpServer({ binary: '/path/to/php/bin/php' })`.

TypeError: phpServer(...).stop is not a function

`phpServer()` is an asynchronous function and returns a Promise. The `.stop()` method is available on the resolved server object.

fix

Ensure you `await` the `phpServer()` call to get the actual server object before attempting to call `.stop()`. Example: `const server = await phpServer(); server.stop();`.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/sindresorhus/php-server ↗

packagehttps://www.npmjs.com/package/php-server ↗