Filesystem Operations

Filesystem Methods

The following EmscriptenFS methods are exposed via the php object:

php.analyzePath

Get information about a file or directory.

await php.analyzePath(path);

php.readdir

Get entry names as string[]:

await php.readdir(path);

Pass {withFileTypes: true} to return serializable entry types:

const entries = await php.readdir(path, {withFileTypes: true});
// Each entry is {name: string, isFolder: boolean}.

Both forms preserve filesystem order and include . and ... Types follow symbolic links, as analyzePath does. Listing and metadata errors, including dangling links, reject the operation. Omitted options or withFileTypes: false keep the name-only result. Embedded, CLI, CGI, debugger, and Cloudflare wrappers support this option, with matching TypeScript overloads.

Browser CGI resolves the whole typed listing inside one read-only transaction, with one storage refresh and no flush. This avoids a separate analyzePath request for every entry. See Transactions.

php.readFile

Get the contents of a file as a Uint8Array by default, or optionally as utf-8.

await php.readFile(path);
await php.readFile(path, {encoding: 'utf8'});

php.stat

Get information about a file or directory.

await php.stat(path);

php.mkdir

Create a directory.

await php.mkdir(path);

php.rmdir

Delete a directory (must be empty).

await php.rmdir(path);

Delete a file.

await php.unlink(path);

php.rename

Rename a file or directory.

await php.rename(path, newPath);

php.writeFile

Create a new file. Content should be supplied as a Uint8Array, or optionally as a string of text.

await php.writeFile(path, data);
await php.writeFile(path, data, {encoding: 'utf8'});

Accessing the FileSystem of a Service Worker

Use the quickbus client from the Service Worker guide. Browser CGI filesystem methods refresh persisted storage automatically with autoTransaction enabled. Await the writer’s persistence before reading from another runtime.

// Write a file
await bus.writeFile('/path/to/your/file', 'contents', {encoding: 'utf8'});

// Check the path
const result = await bus.analyzePath('/path/to/your/file');

// Get names and types in one request.
const entries = await bus.readdir('/path/to/your', {withFileTypes: true});

refresh() recreates the PHP runtime, discarding temporary files and in-memory PHP state. Use it when you need a fresh runtime, rather than before each read.

// Recreate the runtime; only persisted files survive.
await bus.refresh();