Global Install

The global install makes peep() available to every script a PHP install runs, with no Composer and no code changes: legacy apps, WordPress, one-off scripts.

It is a PHAR loaded through PHP's auto_prepend_file. Install it for each PHP version you use (Peep supports 7.1 to 8.5).

Install

Download peep.phar from the releases page, then:

php peep.phar install

This copies the PHAR to ~/.peep/peep.phar and writes 99-peep.ini into PHP's ini scan directory. Check the result with:

php ~/.peep/peep.phar status

Restart PHP-FPM (or Herd, Valet, Apache) so web requests pick up the change.

Options:

Option	Does
--dry-run	Shows what would change, changes nothing
--ini-dir=DIR	Writes the ini file into DIR instead of the scan directory
--force	Replaces an auto_prepend_file that something else set

Writing into a system directory such as /etc/php/8.3/cli/conf.d may need sudo. If the PHP has no scan directory, install prints the line to add to php.ini yourself.

PHP allows one auto_prepend_file. Laravel Herd, for example, uses it for its own dump capture, so install stops instead of replacing it. Use --force only if you no longer need the other one, or install Peep with Composer for those projects.

On by default

A script loaded through the global install has Peep on unless something says otherwise, because installing it globally is already the opt-in. Turn it off:

• for one project, with a peep.php file returning ['enabled' => false];
• for one run, with PEEP_ENABLED=false.

When the viewer is not running, each script pays a few milliseconds once and then skips Peep.

Projects that use Composer

A project that requires shibbirweb/peep uses its own version, not the PHAR. The PHAR registers its autoloader last, so Composer's autoloader loads Peep's classes first.

flowchart LR
    Script["Any PHP script"] --> Prepend["auto_prepend_file:<br/>peep.phar"]
    Prepend --> Fn["peep() is defined"]
    Script --> Composer{"Does the project<br/>require shibbirweb/peep?"}
    Composer -- yes --> Own["Composer's autoloader<br/>(registered first) loads its version"]
    Composer -- no --> Phar["The PHAR's autoloader<br/>loads Peep from the PHAR"]

Loading

Docker

Mount the PHAR into the container and load it there:

docker run --rm \
    --add-host=host.docker.internal:host-gateway \
    -e PEEP_HOST=host.docker.internal \
    -v ~/.peep:/peep \
    php:8.3-cli php -d auto_prepend_file=/peep/peep.phar script.php

Uninstall

php ~/.peep/peep.phar uninstall

It removes the ini file only if Peep wrote it, and deletes ~/.peep/peep.phar.