Filesystem

Use the filesystem API to read, change, and search files in a sandbox without constructing shell commands.

Read and write files

Read and update a Laravel view:

const view = await sandbox.files.readText('resources/views/welcome.blade.php');

await sandbox.files.write('resources/views/welcome.blade.php', view.replace('Laravel', 'Inventory'));

Use read() for binary data, readLines() for part of a text file, and readStream() for a large download. write() accepts text, binary, and stream content.

Manage files and directories

await sandbox.files.createDirectory('storage/imports');
await sandbox.files.copy('fixtures/customers.csv', 'storage/imports/customers.csv');
await sandbox.files.move('storage/imports/customers.csv', 'storage/imports/pending.csv');

const entries = await sandbox.files.list('storage/imports');
const tree = await sandbox.files.tree('storage');

console.log(entries, tree);

Use stat() to inspect an entry and exists() when a missing path is an expected outcome. remove() changes the sandbox immediately.

Find names and search content

find() searches paths. search() searches file contents and returns whether its result limit was reached alongside the matches:

const routeFiles = await sandbox.files.find('*.php', {
  includes: ['routes/**'],
});

const [limitHit, matches] = await sandbox.files.search(
  { pattern: 'Route::' },
  {
    includes: ['**/*.php'],
    excludes: ['vendor/**'],
  }
);

console.log({ routeFiles, limitHit, matches });

Watch a path

Filesystem watches require the realtime transport. Creating a watch is asynchronous:

const watcher = await sandbox.files.watch('/app', { recursive: true, excludes: ['vendor/**', 'node_modules/**'] }, (change) =>
  console.log(change.type, change.path)
);

File watches require the realtime client. REST clients can read, write, and search, but cannot receive filesystem events. Use follow() when appended content matters, such as a Laravel log.

Use Commands and processes when the operation belongs to a build tool or framework command rather than direct file manipulation.