Skip to main content
Get up and running with PsySH quickly. This guide will walk you through starting the REPL, running basic commands, and debugging your first application.

​
Prerequisites

Before you begin, make sure you have:
  • PHP 7.4 or later installed
  • PsySH installed (see Installation)

​
Starting PsySH

1

Launch the shell

Simply run psysh from your terminal:
psysh
You’ll see the PsySH prompt:
Psy Shell v0.12.20 (PHP 8.2.0 — cli) by Justin Hileman
>>>
2

Try some PHP code

Start typing PHP code at the prompt:
>>> $message = 'Hello, PsySH!'
=> "Hello, PsySH!"

>>> echo $message
Hello, PsySH!
=> null

>>> $numbers = [1, 2, 3, 4, 5]
=> [
     1,
     2,
     3,
     4,
     5,
   ]

>>> array_sum($numbers)
=> 15
PsySH evaluates each expression and shows you the return value.
3

Use built-in commands

PsySH includes powerful built-in commands. Try help to see all available commands:
>>> help
List all available functions:
>>> ls
Get documentation for a function:
>>> doc array_map

​
Essential Commands

Here are the most commonly used PsySH commands:

help

Show all available commands and their usage

ls

List variables, functions, classes, and more

doc

Show documentation for functions, classes, and methods

show

Display the source code for a function or class

​
Exploring Code

PsySH excels at code introspection. Let’s explore a class: 
>>> class User {
...     private $name;
...     private $email;
...     
...     public function __construct($name, $email) {
...         $this->name = $name;
...         $this->email = $email;
...     }
...     
...     public function getName() {
...         return $this->name;
...     }
... }
=> null

>>> $user = new User('Alice', '[email protected]')
=> User {#123}

>>> ls $user
Class Methods:
  __construct   getName

>>> show $user->getName
  public function getName() {
      return $this->name;
  }

​
Debugging with \Psy\debug()

The real power of PsySH comes from debugging your running application. Add a debug breakpoint anywhere in your code: 
<?php

function processOrder($order) {
    $total = 0;
    
    foreach ($order['items'] as $item) {
        // Break into PsySH to inspect variables
        \Psy\debug(get_defined_vars(), $this);
        
        $total += $item['price'] * $item['quantity'];
    }
    
    return $total;
}
When this code runs, PsySH will start at the breakpoint. You can:
  • Inspect $order, $item, and $total
  • Modify variables to test different scenarios
  • Call functions to test behavior
  • Continue execution when ready

​
Two-Way Debugging

Use extract() to modify variables in your running code: 
foreach ($items as $item) {
    extract(\Psy\debug(get_defined_vars()));
    // Changes you make in the shell affect the running code
    var_dump($item); // will be whatever you set $item to in PsySH
}

​
Quick Debugging with eval(\Psy\sh())

For a one-liner debug breakpoint, use: 
eval(\Psy\sh());
This drops you into a PsySH session with all the current context available.

​
Working with APIs

PsySH is perfect for testing APIs and exploring libraries: 
>>> $client = new GuzzleHttp\Client()
=> GuzzleHttp\Client {#456}

>>> $response = $client->get('https://api.example.com/users')
=> GuzzleHttp\Psr7\Response {#789}

>>> $data = json_decode($response->getBody(), true)
=> [
     [
       "id" => 1,
       "name" => "Alice",
     ],
     [
       "id" => 2,
       "name" => "Bob",
     ],
   ]

>>> $data[0]['name']
=> "Alice"

​
Tips for Productivity

Press the Up arrow to cycle through previous commands. Your history is saved between sessions.Search history with:
>>> history --grep array
Press Tab to auto-complete variable names, function names, and class names:
>>> $myLongVariable = 'test'
>>> $myL<Tab>  # completes to $myLongVariable
PsySH provides special variables:
  • $_ - The result of the last expression
  • $_e - The last exception thrown
  • $__out - Captured output from the last command
Learn more in Magic Variables.
When an exception is thrown, use the wtf command to see the stack trace:
>>> throw new Exception('Something went wrong')
Exception: Something went wrong

>>> wtf
# Shows detailed stack trace

​
Next Steps

REPL Basics

Learn more about using the REPL effectively

Commands

Explore all available commands

Configuration

Customize PsySH to your preferences

Debugging Guide

Master debugging techniques

Build docs developers (and LLMs) love

Get started for freeTalk to us