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:@stableConfiguring 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:
<?php
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:
<?php
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) {
\core\cron::setup_user();
} else {
cron_setup_user();
}
chdir(__DIR__);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:
psysh
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:
eval(\Psy\sh());
What can you do with PsySH?
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_mapfor example. - Commands like
ls -llist 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
wtfcommand. - 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
helpcommand. - Done? Just
quitorexitto 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 https://psysh.org
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.
Just run the following command to fix the issue:
composer global updateWith 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
- Debugging SCSS in Moodle LMS – 23rd April 2024
- Moodle LMS Email Deliverability in 2024: Best Practices, Authentication Standards and Troubleshooting – 23rd February 2024
- Terminology for Those New to Moodle LMS – 20th January 2024
Wow – that’s a powerful utility – and I had never heard of it !
Thanks 🙂