PsySH: Debugging Moodle LMS with Magic!

This month, we will delve into the captivating powers of PsySH and transform your Moodle development and debugging experience, saving you from endless var_dump() and die(). Get ready to connect with your inner wizards and wield PsySH to unravel the secrets of Moodle LMS.

What is PsySH?

PsySH is a runtime developer shell console and REPL for PHP that allows you to interactively inspect the plethora of Moodle variables and properties, call functions and interact at any point you desire in your code. You may have toyed at times with “php -a”, PHP’s interactive shell. If you think that was cool, you will love PsySH. It not only gives you the ability to test out PHP commands but lets you examine Moodle LMS variables and try out its functions. If this sounds to you like wizardry to you, you’re not alone.

In this article, I will reveal this wizard’s magic and you too will be able to install and conjure up PsySH for Moodle LMS whether you are in Windows, Linux or MacOS.

On a side note, PsySH works with most PHP code. So you can also use it with WordPress, Drupal and Joomla to name a few. It will even work with your own custom PHP scripts or just simply on its own.

System Requirements

The instructions that follow assume that you already have the following installed in your Linux, MacOS or Windows development environment:

  • Composer
  • A working locally installed instance of a Moodle site (should be compatible with most versions)

Installing PsySH

The instructions for installing PsySH on Linux, MacOS and Windows are all the same thanks to Composer:

composer global require psy/psysh:@stable

Configuring PsySH for Moodle LMS

To get PsySH integrated with Moodle, you will need to create two small files in your Moodle root directory.

First, create a file called .psysh.php and add the following lines of code:

return [
    'commands' => [
        new \Psy\Command\ParseCommand,
    'defaultIncludes' => [
        __DIR__ . '/moodle-psysh.php',
    'forceArrayIndexes' => true,

Then create a file called moodle-psysh.php and add the following lines code:

define('CLI_SCRIPT', true);
require(__DIR__ . '/config.php');
require_once($CFG->libdir . '/adminlib.php');
// You can load other libraries here as needed.
if ($CFG->branch >= 402) {
} else {

If you run Moodle sites locally, you will need to add a copy of these two files to each of the Moodle root directories. See Troubleshooting for a note regarding versions of PHP.

That’s it! You are ready to cast your magic in Moodle LMS.

Using PsySH with Moodle

Note: Unfortunately PsySH doesn’t yet support debugging web-based requests such as from Apache or Nginx.

Technique #1: Interactive Console

Open a command/shell prompt in your Moodle root directory and simply enter the following command:


This will open up the PsySH interactive console with you logged in as the primary site administrator.

Technique #2: Add a breakpoint to your code in order to open a Psy Shell console wherever you need it

Simply add the following line wherever you need a breakpoint in your code and then run your code:


What can you do with PsySH?

Figure 1: Display a list of all variables in PsySH console.

The short answer is LOTS! Here are just a few examples of things you can do in the PsySH console:

  • Type the name of a variable to see its value or object to see its properties. It even has tab completion for variable names, functions, classes, methods, properties and filenames.
  • Need PHP documentation on a function? Just type doc array_map for example.
  • Commands like ls -l list variables and property names instead of filenames (see Figure 1).
  • What if you actually want to see a list of files or run some other CLI command? Just wrap your CLI command in backticks (`). Example: `ls -l`.
  • What to see a backtrace? No need to wait for an error to occur. Try the wtf command.
  • Not sure which is the current breakpoint? Just ask whereami.
  • Need a quick calculation? Just enter the equation.
  • You can call any Moodle or PHP core function too though you may need to add some libraries to the moodle-psysh.php file to make them available. Of course, you could include them during runtime from within PsySH.
  • For more help, you guessed it, try the help command.
  • Done? Just quit or exit to leave the PsySH console and resume the code execution of your PHP script or exit.

You can even create your own PsySH spells (commands). For more information and tips, check out the PsySH home page at

Troubleshooting PsySH

If the Moodle environment is not available, make sure that you are running PsySH from the Moodle root directory. However, access to the Moodle-related environment only works if you start it up from within the Moodle root directory. Be sure to also make sure that the two configuration files were created in that directory.

If you tend to switch versions of PHP regularly for testing purposes, note that your installation of PsySH is PHP version dependent. If you switch to an earlier version of PHP, you will see an error similar to Fatal error: Composer detected issues in your platform: Your Composer dependencies require a PHP version “>= 8.1.0”. You are running 7.4.25. However, it just takes a few seconds to re-install PsySH under a different version of PHP.

With PsySH in your tool chest, Moodle LMS development can be a lot more fun, just like magic.

Hope you found this information helpful. Abracadabra and [Poof!] I’m out of here.

See you next month!

Michael Milette

Follow me

Latest posts by Michael Milette (see all)

Michael Milette

Michael Milette is the owner and an independent consultant with TNG Consulting Inc. in Canada. He works with government, non-profit organizations, businesses and educational institutions on Moodle-related projects. Michael writes about implementing Moodle LMS, developing in Moodle, Moodle administration, using the FilterCodes plugin (his own project), creating multi-language Moodle implementations and courses, and WCAG 2.1 accessibility.

One thought on “PsySH: Debugging Moodle LMS with Magic!

  • 22nd May 2023 at 11:55 am

    Wow – that’s a powerful utility – and I had never heard of it !
    Thanks 🙂


Add a reply or comment...

%d bloggers like this: