Debug Magento 2 PHP with Tinkerwell

Laravel developers have had Tinkerwell for years, and it works with Magento just as well. Point it at your project, connect it to the PHP container, and you have a REPL with $om (the ObjectManager) already wired up, so you can run a few lines of Magento code without writing a CLI command or a controller first.

It takes just a few minutes to set up, so let's get right to it.

Set the Tinkerwell working directory

After you install Tinkerwell, you'll see a screen that looks something like this:

The first thing to do is click the "Set the working directory" icon and point it at your Magento installation. The project I'm working with is in the ~/Sites/magento directory.

But that's not the directory you want, since it's the main project directory that holds the Docker configuration and other project files. Step into the src directory instead, which is the actual Magento installation: ~/Sites/magento/src. Afterwards, click Open to set it as the working directory.

Tinkerwell then starts indexing the project, which can take a few minutes. If you're a Magento developer, you're all too familiar with this indexing process, and it pays off once you start typing code.

Configure Tinkerwell for Docker

I use docker-magento for local development (it's the open source Magento environment I've been maintaining since 2017, and its documentation course is open access in the M.academy Library), so Tinkerwell also needs to know which container runs PHP.

The screenshots here are from an older Tinkerwell release. In Tinkerwell 5, click the Runtime Settings icon in the sidebar and choose Docker. Tinkerwell lists the running containers and detects the working directory for you.

Only running containers show up in this list. If it's empty, run bin/start, then click Refresh.

Select the phpfpm container from the list, and let Tinkerwell detect the working directory inside it.

Wait, another working directory? The one you set earlier was the "local" working directory, and this is the "remote" one. Even though Docker runs on your machine, Tinkerwell treats it as sort of a remote environment, since the containers are isolated from everything else running locally.

/var/www/html is the location of the Magento install inside the container, and it's the directory that maps to the local project directory at ~/Sites/magento/src.

Both of these locations need to point at the same Magento root. If they don't, things just won't work.

Close the settings, and you're ready to go.

Test Tinkerwell with the ObjectManager

The indexing process that started earlier works through the hundreds of thousands of files in Magento. When it's done, you'll see a "Done indexing" message in the bottom right of the Tinkerwell app. If you don't see it, double-check that both working directories are set correctly.

Tinkerwell's Magento driver exposes the ObjectManager as the $om variable. Type that variable in and run it, and you'll get back the ObjectManager instance, along with all of the properties set on it:

$om is fine in a REPL. Never use the ObjectManager directly in module code, though: inject the interface in a constructor instead (see the ObjectManager in Magento 2 for why).

Load a product with Tinkerwell

Let's do something a bit more practical and load a product. The proper way to do this in Magento is with a repository (more on that in the Magento 2 model and repository design pattern). Repositories are shared services, so grab the shared instance with get() rather than building a new one with create():

$productRepository = $om->get(ProductRepositoryInterface::class);

As you start typing ProductRepositoryInterface, type the first few letters and press Tab. Tinkerwell's autocompletion figures out which class you mean and adds the use statement at the top for you. That saves a ton of typing with Magento's deeply nested, long class names.

My favorite product in Magento's sample data is the Joust Duffle Bag, so let's use its SKU to grab its data from the repository.

$productRepository->get('24-MB01');

Rather than clicking the Run button, you can also press Cmd+R (Ctrl+R on Windows and Linux) to execute the code. Here's the full code:

use Magento\Catalog\Api\ProductRepositoryInterface;
 
$productRepository = $om->get(ProductRepositoryInterface::class);
 
$product = $productRepository->get('24-MB01');

And now you're looking at the full product object for the Joust Duffle Bag.

When I reach for Tinkerwell

I reach for Tinkerwell any time I'd otherwise write a throwaway CLI command just to run three lines of Magento code. I use it all the time to debug snippets. Rather than creating a class or a controller, I fire up Tinkerwell and type it in, with no boilerplate to set up first. And since I teach Magento, having a place to write some quick Magento code during a lesson is really handy.

For more complex debugging, create a conditional breakpoint in PhpStorm with Xdebug or configure Xdebug modes for different debugging workflows. If you'd rather dump values out of a running request, debugging Magento in Docker with Spatie Ray pairs nicely with Tinkerwell.

What do you use for quick Magento experiments? I'm always curious what other developers keep in their toolbox.