README

A PHP wrapper around the Bun binary. It manages a hidden Bun binary — downloaded on first use into .phpdot/runtime/, integrity-verified, and pinned to a reproducible version — and exposes Bun's CLI as console commands and as an injectable service.

This package is a thin wrapper. It does not reimplement a bundler, a package manager, or a runtime; it delegates to the Bun binary.

phpdot/bun is a PHP wrapper around Bun (oven-sh/bun), which is MIT licensed.

Requirements

• PHP 8.4+
• ext-curl (registry access and binary download)
• A PSR-18 client + PSR-17 factories — bundled by default via symfony/http-client + nyholm/psr7
• ext-pcntl (suggested) — forwards SIGINT/SIGTERM to long-lived processes (run dev server, build --watch) for clean shutdown
• On Alpine/musl, install libstdc++ (apk add libstdc++) — the downloaded Bun binary links against it at runtime. Glibc distros and macOS/Windows already provide it.

Installation

composer require phpdot/bun

Add the runtime directory to your .gitignore — the binary is downloaded per machine, never committed:

/.phpdot/

Configuration

BunConfig is an immutable value object resolved from the container (#[Config('bun')]):

Console commands

Registered into your phpdot console application (discovered via #[AsCommand]):

# Discovery (uses the npm registry; never needs the binary)
bun:search chart --limit=20

# Packages
bun:install lodash axios          # bun add
bun:install --dev typescript      # bun add --dev
bun:remove lodash                 # bun remove
bun:view react                    # bun pm view

# Run scripts and tools (output streams live; Ctrl-C is forwarded)
bun:run dev                       # bun run dev
bun:run dev -- --port 3000        # flags for the script go after --
bun:x prettier src -- --write     # bun x — run any installed CLI tool

# Bundle
bun:build src/index.ts --out-dir=dist --minify --splitting --hashed-names
bun:build src/index.ts --watch    # long-lived: rebuilds on change, exits cleanly on signal

Passthrough commands (bun:run, bun:x) forward arguments verbatim. Put flags meant for the script/tool after a -- separator so the console does not parse them.

Build-step tools

There is no special-casing for any tool. Install it and run it with bun:x:

bun:install javascript-obfuscator
bun:x javascript-obfuscator app.js -- --output app.obf.js

Programmatic use

Inject the Bun service — there is no static entry point or facade:

use PHPdot\Bun\Build\BuildSpec;
use PHPdot\Bun\Bun;

final class Deploy
{
    public function __construct(private readonly Bun $bun) {}

    public function bundle(): void
    {
        $this->bun->install(['lodash']);

        // Zero-config production build: minify, code splitting, hashed names, metafile.
        $this->bun->build('resources/js/app.ts');

        // Adjust via a BuildSpec closure when needed:
        $this->bun->build('resources/js/app.ts', fn (BuildSpec $b) => $b->outDir('public/dist')->sourcemap());
    }
}

watch() is the dev counterpart (no minify, sourcemaps, rebuilds on change). Each call resolves the binary (downloading it on first use) and streams Bun's output through, returning Bun's exit code.

Resolving hashed assets — Manifest

Both build() and the bun:build command write the hashed assets plus a trimmed, deploy-safe manifest (manifest.json) into the output dir (the verbose metafile is distilled, then removed). Manifest maps a source entry to its content-hashed URL — and a single entry that also imports CSS resolves to different files per extension via js()/css():

use PHPdot\Bun\Manifest\Manifest;

$assets = new Manifest('public/build/manifest.json', '/build');
echo '<script type="module" src="' . $assets->js('resources/js/app.ts') . '"></script>';

Security: the manifest holds relative output paths only, so it is safe to commit, deploy, and serve. Bun's verbose metafile — which carries absolute build-machine paths and the full module graph — is used only as a throwaway intermediate (written privately, then deleted); it is never kept or web-served. So there is one file to deploy: public/build/manifest.json.

How it works

1. PlatformDetector resolves the host OS, architecture, and (on Linux) libc flavour.
2. BinaryResolver checks the cached binary; if missing or version-mismatched it acquires a lock and downloads the matching @oven/bun-* npm package, verifies its sha512 integrity, and extracts it.
3. If the standard x64 binary fails to execute (e.g. no AVX2 / illegal instruction), it falls back to the -baseline variant automatically.
4. Concurrent first-use downloads are guarded by a file lock.

License

MIT. Bun itself is MIT licensed; redistribution via download preserves that notice.