caphsule

Caphsule

NVM-style version control for PHP.

Caphsule (pronounced capsule) is a standalone Go CLI for managing PHP runtimes, activation, configuration, and extensions on macOS and Linux.

It uses Homebrew as the runtime provider and supports extension workflows through Homebrew taps, PECL, and PIE. The goal is an nvm-style workflow for PHP without coupling the tool itself to a package manager install.

By default, Caphsule manages PHP itself, not every PHP-adjacent CLI tool on the machine. Existing Composer or project-local tooling can keep working unchanged unless the user explicitly opts into deeper tool management.

What does it do?

In a nutshell? Imagine you're using NVM. But with PHP.

Caphsule can:

• Install and register PHP runtimes from Homebrew sources
• Switch the active runtime with managed shims
• Set default and project-local runtime selections
• Discover or adopt existing PHP installs
• Install, enable, disable, configure, and remove extensions
• Manage runtime-specific PHP configuration
• Detect drift with doctor, repair it with repair, and refresh provider metadata with refresh
• Generate JSON output for automation
• Self-update from GitHub Releases

When installing from the default third-party PHP sources, Caphsule will automatically prepare the trusted shivammathur/php and shivammathur/extensions taps as needed. These are reputable, well known sources for PHP installations.

Highlights

• AI agents integration for your convenience

• PIE (new php extension manager) integration

• Terminal autocomplete

Install Caphsule

Install the latest release:

curl -fsSL https://raw.githubusercontent.com/phillarmonic/caphsule/master/install.sh | sh

Install a specific version:

curl -fsSL https://raw.githubusercontent.com/phillarmonic/caphsule/master/install.sh | sh -s -- --version 0.1.0

Install into a custom directory:

curl -fsSL https://raw.githubusercontent.com/phillarmonic/caphsule/master/install.sh | sh -s -- --install-dir "$HOME/bin"

The installer downloads the matching release archive from GitHub Releases, verifies its SHA-256 checksum, and installs caphsule into ~/.local/bin by default.

MacOS Gatekeeper specific quirk:

MacOS might complain the software is not trusted. If Caphsule doesn't work for you, for some reason, run this in a terminal (no sudo permission required):

xattr -dr com.apple.quarantine ~/.local/bin/caphsule

That will remove any GateKeeper restrictions from the Caphsule rexecutable.

Shell Setup

Initialize your shell so Caphsule-managed shims come first on PATH. Add this at the end of your .zshrc / .bashrc / whatever you use

eval "$(caphsule init zsh)"

The CLI exposes shell initialization for bash, zsh, and fish. Completion scripts are also available for bash, zsh, fish, and powershell.

For enabling completion, add this to your .bashrc / zshrc / etc:

# Add your preferred shell in this case
source <(caphsule completion zsh) 

Install and activate PHP 8.4:

caphsule install 8.4 --use

Need a specific build flavor? Caphsule can install the usual non-thread-safe runtime, thread-safe builds, and debug builds as separate runtime variants. That includes the kind of PHP you might want for symbol-rich crash analysis, core-dump replay, or a GDB session against a debug build.

caphsule install 8.4 --use
caphsule install 8.4-ts
caphsule install 8.4-debug
caphsule install 8.4-debug-ts

Under Homebrew those typically map to formula names like php@8.4, php@8.4-zts, php@8.4-debug, and php@8.4-debug-zts.

If Homebrew reports that PHP was built but could not be symlinked because an older PHP formula is still linked, Caphsule will automatically unlink the conflicting PHP formula and relink the requested one.

Inspect the current runtime:

caphsule current
caphsule info

Install and manage extensions:

caphsule ext install redis
caphsule ext install xdebug
caphsule ext install zip,intl
caphsule ext install redis xdebug
# If you want a specific version of the extension, provide the maj.min.patch
caphsule ext install xdebug@3.4.2
caphsule ext disable xdebug
caphsule ext list
caphsule ext uninstall redis
# Both uninstall and remove are valid
caphsule ext remove redis

Set a project-local runtime:

caphsule local 8.4

Check the environment and managed state:

caphsule doctor
caphsule repair --dry-run

Use JSON output in scripts for a more programmatic behavior:

caphsule --json current

Project Files

Caphsule uses a home directory at ~/.caphsule by default. You can override it with CAPHSULE_HOME.

Useful environment variables:

• CAPHSULE_HOME sets the state/config directory
• CAPHSULE_CONFIG points to an alternate config file
• CAPHSULE_PROVIDER overrides the selected provider
• CAPHSULE_PHP pins the runtime for the current command/session
• CAPHSULE_NO_COLOR=1 disables color output

Tooling Model

The default model is conservative:

• Caphsule manages the selected php runtime and companion binaries such as phpize and php-config
• Existing global tools like composer remain untouched
• Project tools in vendor/bin remain the preferred path for project-specific utilities like phpactor

This avoids coupling tool installation to Homebrew formulas that may pull a different PHP version than the one you selected in Caphsule.

Future opt-in tooling support can add pinned versions of tools like Composer or Phpactor, but that is intentionally not the default behavior.

When you do want Caphsule-managed tooling, declare it explicitly in caphsule.yaml and let sync or tool install fetch the payload into ~/.caphsule/tools:

php: 8.4
tools:
  composer:
    mode: inherit-runtime
    source: phar
    version: "2.8.10"
    url: https://example.invalid/composer.phar
  phpactor:
    mode: project

Install and run those opt-in tools with:

caphsule sync
caphsule tool install composer
caphsule tool run composer -- --version
caphsule tool run phpactor

Per-project runtime selection is stored in:

.caphsule-version

Project sync state is declared in:

# caphsule.yaml
php: 8.4
extensions:
  redis:
    enabled: true
  xdebug:
    enabled: false
ini:
  memory_limit: 512M
profiles:
  dev:
    extensions:
      xdebug:
        enabled: true

Apply that desired state with:

caphsule sync

Reusable profiles can also be managed with:

caphsule profile list
caphsule profile capture dev
caphsule profile apply dev

Command Areas

Top-level command groups:

• source manages runtime and extension sources
• list, install, adopt, discover, use, default, current, info, uninstall manage PHP runtimes
• ext manages PHP extensions
• config manages runtime INI values and config file paths
• local, sync, profile cover project-specific state
• tool manages opt-in PHP CLI tool installs and execution
• doctor, refresh, repair handle diagnostics and drift
• self-update updates the Caphsule binary
• completion generates shell completion scripts

Run caphsule --help or caphsule <command> --help for the full surface.

Development

We use the Drun task automation language and CLI for our development pipeline. Install it from the Official Repository

Build and verify with the repository automation:

xdrun build
xdrun test
xdrun ci

Useful tasks:

• xdrun install installs the local binary with dev build metadata
• xdrun dist builds cross-platform release binaries
• xdrun release-artifacts version=v0.0.0-dev produces archives, checksums, SBOMs, and release metadata

AI Agents

In the cases you want to use AI agent loops for testing software with different PHP versions, configurations, etc, you can install the skills/instructions for your preferred agent of choice.

caphsule agent list
caphsule agent install /path/to/project
caphsule agent install /path/to/project --agent claude --agent cursor --agent copilot

Defaults:

• no --agent flags installs the generic AGENTS.md plus skills/caphsule/SKILL.md
• agent-specific installs automatically include the generic base
• use --dry-run to preview writes
• rerunning the installer updates previously generated managed sections and managed files
• existing shared files like AGENTS.md, CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md receive a Caphsule-managed block instead of being blindly replaced
• use --force to overwrite conflicting dedicated generated files such as skills/caphsule/SKILL.md or .cursor/rules/caphsule.mdc

License

This project uses the GNU Affero General Public License Version 3. You can check it in the LICENSE file contained in the project.