API reference

Everything you do with Peep starts with peep(). This page explains how a card works and lists every method. Each method is documented in full, with its parameters, return value, behavior and examples, on one of these pages:

Page	Covers
Values	Sending values in every format, and how values are shown
Inspecting	The card's look, traces, exceptions, timing, counting, catching, pausing and stopping
Control	Sending less, turning Peep on and off, the viewer, SMS, and macros
Laravel	Query and watcher switches, models, mail, Context, ->peep() on Laravel classes and Blade

The helpers

peep(mixed ...$values): Peep
pd(mixed ...$values): never

peep() creates a new card. With values, it sends them right away, so peep($user) is the same as peep()->send($user). It always returns the card, an instance of ShibbirWeb\Peep\Peep.

pd() sends the values, then stops the script with exit code 1, like Laravel's dd().

Both helpers are defined only when no function of that name exists yet, so they never clash with another package.

How a card works

• One call, one card. Each peep() call makes a new card in the viewer.
• Methods chain. Almost every method returns the same card, so you can keep calling. The exceptions are documented: pass(), catch(), invade(), counterValue(), rateLimiter(), isActive(), enabled(), disabled() and card() return something else.
• Later calls update the card. Methods called on a card change that card, not a new one. Keep the object to update it later:

$card = peep('Importing...')->label('Import')->blue();

foreach ($rows as $row) {
    // ...
}

$card->send("Imported {$count} rows")->green();  // the same card, now green with the new text

• Where it was called. Each card shows the file and line of the call (mapped to your machine in Docker, see Configuration), with a link that opens it in your editor.
• Grouped by request. Cards are grouped by the request, command or job that sent them, and kept apart by project. See The viewer.

When nothing is sent

Peep stays out of the way when it cannot or should not send:

• Off. Plain PHP apps start with Peep off: turn it on with PEEP_ENABLED=true or a peep.php file. Laravel turns it on everywhere except production. The global install is on by default. See Configuration.
• No viewer. When the viewer does not answer, Peep remembers it for 30 seconds (across PHP processes when APCu is installed) and sends nothing in that time, so a closed viewer costs a few milliseconds once.
• Muted. once(), limit() and if() can mute a card: then every later call on it does nothing.

While nothing is sent, methods do no work: values are not serialized and files are not read. They still return what they normally return, so code around them behaves the same. A problem inside Peep never reaches your app: it is swallowed and the call does nothing.

Every method

Values

Method	Does
send	Shows values; on a card that has some, replaces them
pass	Shows a value and returns it
raw	Shows values without casters
text	Text with whitespace kept
html	HTML in a sandboxed frame
json, toJson	A JSON string, or values encoded as JSON
xml	XML, indented
table	An array as a table
image	An image from a URL, file, data URI or base64
file	A file's contents
link, url	A clickable link
date	A date to the microsecond
className	An object's class
invade	Private properties and methods
phpinfo	PHP's configuration
separator	A divider

Inspecting

Method	Does
color, red() ... yellow()	Colors the card
label	A title for the card
small, large	Text size
hide	Shows the card collapsed
expand, expandAll	Opens nested values
caller	Where the current function was called from
trace, backtrace	The call stack
exception	An exception with its trace and source
measure	Time and memory
count, counterValue	How often a line runs
catch	Shows exceptions instead of throwing them
pause	Waits for a click in the viewer
die	Stops the script

Control

Method	Does
once, limit	Sends only the first times a line runs
if, showIf	Sends only when a condition holds
remove, removeIf, removeWhen	Removes the card
rateLimiter	Process-wide limits
enable, disable, enabled, disabled	Turns Peep on or off, or asks
isActive	Whether calls are sent right now
newScreen, clearScreen, clearAll	Screens and clearing
notify	A notification
showApp, hideApp	The desktop app's window
sms	An SMS in the viewer's inbox
Peep::macro, Peep::hasMacro	Your own methods
payload, sendCustom	Payloads for macros and adapters
card	The card's id

Laravel

showQueries() and the other query switches, countQueries(), showEvents(), showJobs(), showCache(), showHttpClientRequests(), showViews(), showRequests(), model(), mailable(), markdown(), context(), hiddenContext(), ->peep() on collections, strings, query builders and test responses, and the Blade directives. See Laravel methods.

Finding leftover calls

vendor/bin/peep-clean lists the peep(), pd(), ->peep() and @peep calls left in your code, and --fix removes the safe ones. A PHPStan rule reports them in CI. See Finding leftover calls.