As any developer can attest, code isn’t able for manufacturing after the primary draft. One key a part of the improvement activity is debugging — taking away or converting all portions of your code that don’t paintings.

The Xdebug extension for PHP is a well-liked method to root out and spoil the entire insects to your code.

One of the most nice sides of Xdebug is how versatile it’s. Without reference to your most well-liked framework or construction surroundings, you’ll be capable of discover a edition of Xdebug that slots into your workflow. From there, getting a maintain at the software gained’t take lengthy.

This educational will take a look at Xdebug intensive, together with the set up activity, integrating it into your setup, and basic utilization.

First, let’s come up with extra context on what Xdebug is and what it does.

Introducing Xdebug

Xdebug is likely one of the hottest extensions to debug your PHP code. You’ll set up it from inside your preferred surroundings, and it acts as a “step debugger.”

A green layered background showing the Xdebug logo, complete with a green 'X'.
The Xdebug emblem.

In brief, this allows you to paintings to your code line by way of line so you’ll be able to step thru and take a look at how the code acts and interacts inside your program, in addition to examine its output. From there, you’ll be able to make adjustments as you spot are compatible.

Xdebug can do a lot more, even though:

  • You’ll analyze the efficiency of your code the use of a suite of metrics and visualizations.
  • While you run PHP unit checks, you’ll be able to see which suites of code you run and execute.
  • Xdebug comprises “tracing” functions, which can write each serve as name to disk. This will likely come with arguments, variable assignments, and go back values.
  • Xdebug additionally makes enhancements to the usual PHP error reporting. We’ll quilt extra in this later.

Given the function set, there are many tactics to make use of Xdebug (and any equivalent debugger) inside your workflow. We’ll quilt those within the subsequent segment.

Debugging is a key a part of the improvement process- and Xebug is right here to make that activity more uncomplicated 💪Click on to Tweet

Why You’d Need To Use Xdebug

Many builders gained’t have a devoted debugging workflow that makes use of third-party equipment and extensions. It’s because PHP comprises its personal rudimentary error logging. You’ll use instructions similar to error_log, var_dump, and print to peer the result of variables and serve as calls.

For instance, there are many snippets you’ll be able to repurpose for WordPress construction — Stack Overflow is rife with them:

serve as log_me($message) {
  if ( WP_DEBUG === true ) {
      if ( is_array($message) || is_object($message) ) {
          error_log( print_r($message, true) );
      } else {
           error_log( $message );

On the other hand, there are some necessary drawbacks to this manner:

  • You first should be sure to allow error logs for the platform you might be operating with. On this case, you’ll need to allow WP_DEBUG (extra in this in a while).
  • This case of “unload” debugging provides much less scope for investigation than step debugging. Right here, you’ll be able to most effective output no matter you outline.

The latter level calls for a lot handbook effort, particularly in case your day task isn’t as a sysadmin. For instance, if you wish to debug a code block, it’s possible you’ll upload your snippet in keeping with a variable you outline. On the other hand, it will not be the supply of the issue and even point out what’s going down.

As a substitute, a device similar to Xdebug can paintings its magic to supply larger scope:

  • You’ll “damage” your code at quite a lot of issues all the way through the execution to peer what is going on in real-time.
  • There are myriad metrics, visualizations, branches, and extra that can assist you verify what your code is doing and the way it responds.
  • Now and again, you’ll be able to even alternate values at the fly all the way through the debugging activity. This gives immense price, even for suites of code that paintings smartly. You’ll necessarily perform handbook unit checks at any level.
  • Since you use breakpoints to mark up spaces to debug, you don’t want to paintings with snippets inside your code. This assists in keeping your code cleaner and decreases the collection of long run problems.

Total, the use of a device similar to Xdebug is a proactive choice slightly than a reactive one. You’ll use step debugging as a part of the core construction activity, similar to enforcing unit checks as a part of test-driven construction (TDD).

How To Flip On PHP Error Logging

Whilst it’s worthwhile to debug your code with no particular error, it’s frequently excellent to understand if a subject matter happens with no need Xdebug open. This will provide you with a start line for exploration. It’s no longer strictly vital, however is usually a useful a part of your chain.

To file each error that arises, you’ll want to upload a line to the highest of the related PHP document:


It is a catch-all command, and you’ll be able to reach the similar the use of the ini_set serve as:

ini_set('error_reporting', E_ALL);

This allows you to alternate settings inside your php.ini document on a project-by-project foundation. Whilst it’s worthwhile to move into this document and make a handbook alternate, it’s frequently a greater concept to paintings with ini_set to switch the precise parameter:

ini_set('display_errors', '1');

Upon getting lively error reporting set for your liking, you’ll be able to start operating with Xdebug.

How To Use Xdebug

Over the following few sections, we’ll display you learn how to use Xdebug, together with the stairs you’ll want to set issues up. Whilst we will’t quilt each software side, this quick-start information gets you going speedy.

First, even though, you wish to have to put in Xdebug. Let’s learn the way to do it.

1. Set up Xdebug for Your Working Device (OS)

As a result of Xdebug is adaptable to any collection of setups, the precise activity for every one shall be quite other. On the OS point, there are a couple of variations:

  • Home windows: It is a relatively difficult setup activity that comes to the use of an present PHP document and an set up wizard, then downloading the proper edition on your components.
  • Linux: The process this is arguably the simplest: You’ll use a package deal supervisor to put in Xdebug, or the PHP Extension Neighborhood Library (PECL).
  • Mac: This system could also be easy: While you set up PECL, you’ll be able to run pecl set up xdebug from a Terminal example. You’ll additionally want to have XCode command line equipment and PHP put in to your components.

On the other hand, maximum customers gained’t need to persist with a system-level example of Xdebug. As a substitute, you’ll need to combine it into your individual construction surroundings.

2. Combine Xdebug Into Your Construction Surroundings

While you set up Xdebug on your OS, you must attach it for your surroundings.

There are such a lot of supported programs and equipment right here that we will’t move into they all. Afterward, we’ll give you directions for each DevKinsta and PhpStorm. Even so, there are many different standard environments to choose between. Under are a few of our best suggestions.

Various Vagrant Vagrants (VVV)

VVV is likely one of the named environments at the Make WordPress web site:

A blue background containing 8-bit ASCII art of the Varying Vagrant Vagrants logo (
The Various Vagrant Vagrants emblem.

The excellent news is that VVV already features a edition of Xdebug, however you wish to have to turn on it. You’ll do that the use of Protected Shell (SSH) inside a Terminal window:

vagrant ssh -c "switch_php_debugmod xdebug"

There’s a little bit little bit of a efficiency hit, even though, and also you’ll want to flip this selection again on in case you provision your websites.

Laravel Valet

For some customers, Laravel’s Valet represents a near-perfect internet construction surroundings. Even higher, you’ll be able to combine Xdebug with it.

To do that, you’ll want to create a configuration document for the debugger. You’ll in finding your individual trail the use of php --ini on the command line, which can go back a couple of other document paths:

A Terminal window showing a list of paths of .ini PHP configuration files, and an empty command prompt cursor.
The Terminal appearing a listing of configuration document paths.

Subsequent, create a brand new xdebug.ini document on the trail for extra .ini information. In our instance, it’s at /decide/homebrew/and so on/php/7.4/conf.d.

While you open this new document, additionally open the trail to the Loaded Configuration Record (your major php.ini document). With each open, upload the next to the ground:

  • php.ini: zend_extension=""
  • xdebug.ini: xdebug.mode=debug

While you’ve stored your adjustments, run valet restart from the Terminal, then upload phpinfo(); go out; to one among your website’s information. You’ll need to take a look at whether or not this works thru a handy guide a rough web page load throughout the browser.

A PHP information file within the browser, showing the Xdebug logo and the
The PHP knowledge display screen.

Be aware which you could want to restart PHP the use of sudo brew services and products restart php in addition to take a look at that your components set up of Xdebug is right kind the use of php --info | grep xdebug. You’ll realize the Xdebug-specific traces throughout the output:

A Terminal window showing a number of different Xdebug configuration settings (such as output names and display variables). The prompt shows the

From right here, you’ll be able to glance to include Xdebug into your coding editor of selection.


Just like Valet, there are a couple of portions to the method for XAMPP. On the other hand, Home windows and macOS variations have two other processes.

Start by way of putting in XAMPP, then run a handy guide a rough take a look at to peer if the php_xdebug.dll document (Home windows) or document (macOS) exists to your components:

A Terminal window showing a snippet to test whether a while exists. If it does, the Terminal will output
A Terminal window appearing a examine for a XAMPP document.

If the document exists, you’ll be able to transfer directly to the configuration. Another way, you’ll first want to obtain both the proper binary for Home windows — a 64-bit document on your most well-liked PHP edition — or set up a couple of extra dependencies in case you’re on a Mac.

For Home windows, rename the DLL document php_xdebug.dll, then transfer it to the xamppphpext document trail. Subsequent, open the xamppphpphp.ini document to your most well-liked code editor and upload the next:

output_buffering = Off

On the [XDebug] segment, upload the following 3 traces:


While you save your adjustments, restart Apache and examine for Xdebug.

For Mac, you’ll need to be sure to set up the Xcode command line equipment the use of xcode-select --install at a Terminal example. After that, there are 3 applications you’ll need to set up the use of Homebrew:

brew set up autoconf automake libtool

In some instances, you’ll additionally want to reinstall XAMPP to get each the core program and the “Developer Information.” You must be capable of re-install most effective those information, however you’ll need to perform a backup of your present setup first.

Subsequent, navigate to the obtain for the Xdebug supply folder to your components and unpack the TGZ document. Inside of a Terminal window, navigate to that listing and run the next:

pecl set up xdebug

Be aware which you could want to use sudo right here too. From right here, you’ll be able to edit the XAMPP php.ini document. For many macOS installations, you’ll in finding it at /Packages/XAMPP/xamppfiles/and so on/php.ini. Inside of this listing, you’ll additionally in finding the trail for your document — observe this down and use it rather than the document trail placeholder for this snippet:


To check whether or not this works, create a brand new xdebug_info.php document inside the primary htdocs XAMPP listing. Inside of, upload the next:

…then refresh Apache and examine Xdebug within the browser.

The use of PhpStorm With Xdebug

While you set up Xdebug in the course of the OS and your construction surroundings, you’ll additionally want to view the debugger itself. You’ll do that thru your preferred code editor or built-in construction surroundings (IDE). As together with your surroundings, there are such a large amount of to choose between, and every one would possibly have a special manner.

That mentioned, many builders decide to make use of JetBrains’ PhpStorm. If truth be told, PhpStorm provides “WordPress-aware help” — and it’s a well-liked selection for plenty of different causes, too.

The PhpStorm interface, with a tree directory for the project on the left that uses white, blue, and yellow text. The right-hand side contains PHP code for a WordPress plugin, using orange, purple, green, and white text.
The PhpStorm interface.

The JetBrains web site comprises complete directions on connecting Xdebug and PhpStorm, however we’ll evaluate them right here.

First, navigate to the Languages & Frameworks > PHP web page throughout the Personal tastes pane. Right here, open up the Extra Pieces kebab menu subsequent to the CLI Interpreter dropdown box:

A partial PhpStorm Preferences screen, showing the page link (
Settling on a CLI interpreter in PhpStorm.

This will likely display some additional information about your PHP edition and interpreter. In the event you click on the Extra pieces ellipsis subsequent to the Configuration document choice, you’ll see complete paths on your php.ini document:

A partial PhpStorm More Items screen showing the name of the configuration, a path to the PHP executable file, the current PHP and debugger version numbers, and a list of configuration files for various aspects of the PHP installation.
Amending the PHP configuration inside PhpStorm.

You’ll be operating with this PHP document subsequent to proceed the setup activity.

Operating Inside the php.ini Record

The primary activity this is to edit out any traces that have an effect on how Xdebug will paintings with PhpStorm.

Inside the php.ini document, search for the next traces and both take away them or remark them out:


Those traces gained’t be found in all instances, so don’t be alarmed in case you aren’t seeing them.

Subsequent, upload the next to the document:


There are some things to notice about this suite of code:

  • You might have already got an [xdebug] segment, wherein case you'll be able to put out of your mind the primary designation.
  • The zend_extension access would possibly want you so as to add the total trail of to attach.
  • Whilst it could appear to be a placeholder, the xdebug.client_port parameter is the way you’ll set it inside your code.

While you upload those, save and shut the document, then examine the PHP edition from the command line (the use of php --version):

The Big Sur blue, red, and purple gradient desktop background, showing a macOS Terminal window. It shows the "php -version" command, along with the PHP version number, a copyright notice, and installed versions (complete with version numbers) for Zend Engine, Xdebug, and Zend OPcache.
Checking out for the present installations for PHP and Xdebug the use of the macOS Terminal.

When you have a operating edition of Xdebug, it'll display as probably the most PHP extensions. You'll additionally upload phpinfo(); to a brand new document and examine this within the browser.

Suffering with downtime and WordPress issues? Kinsta is the internet hosting resolution designed to avoid wasting you time! Take a look at our options

That is on the subject of all you wish to have to do to have Xdebug paintings as your default debugger with PhpStorm. The overall step sooner than the use of it's putting in a browser helper extension.

Putting in a Browser Helper Extension

The overall key connection you’ll want to make is between your browser and PhpStorm, completed by way of activating step debugging at the server. Whilst it's worthwhile to do that from the command line the use of particular GET or POST values, it’s easier to make use of an extension.

We advise using the devoted Xdebug Helper extension. You'll set up it to your browser of selection:

If you wish to discover different extensions, the JetBrains web site provides a couple of further choices for the most well liked browsers.

While you’ve put in your preferred browser extension, you shouldn’t have to regulate any more configuration settings. From right here, you'll be able to start to use Xdebug with PhpStorm.

The use of Xdebug

Whilst we’ll use PhpStorm right here, you’ll see a equivalent format and interface between other IDEs — even though there can be some evident variations.

There are a couple of ideas that mix to shape the entire debugging enjoy:

  • Breakpoints: Those are the issues the place Xdebug will prevent to permit you to investigate cross-check the output. You’re in a position to set as many of those as you’d like.
  • Listening for connections: You'll toggle this off and on, even though maximum builders will at all times go away it on.
  • The debugging display screen: Nearly all of your time shall be spent throughout the debugging interface — it’s the place you’ll paintings with the quite a lot of traces of code, variables, and parameters.

Step one is to turn on listening — you gained’t be capable of debug anything else with out it. To do that, click on at the Run > Get started Listening for PHP Debug Connections choice within the toolbar:

A partial PhpStorm interface screen, showing a tree directory on the left, and the application toolbar. The Run menu is open, and the
The open Run menu inside PhpStorm.

Instead, you'll be able to click on at the “phone” icon inside PhpStorm’s toolbar:

A close-up of the PhpStorm toolbar, which displays options for the current run configuration, various Git options, and the Start Listening for PHP Debug Connections telephone icon (complete with tooltip).
Listening for PHP debug connections the use of the phone icon throughout the PhpStorm toolbar.

Both of those choices will delivery the listening for connections.

From right here, you'll be able to start to set breakpoints throughout the code editor’s gutters. A purple dot signifies a breakpoint, which you'll be able to click on to turn on:

A close-up of the PhpStorm interface, showing a tree directory on the left, and the coding panel on the right. Within the gutters of the editor, there are red dots with white ticks at lines 45, 50, and 55. These are breakpoints for debugging.
Breakpoints throughout the gutter of a PhpStorm modifying web page.

When you need to debug your code, the simplest approach is to start out listening, set breakpoints, then head to the precise web page to your browser. Find the icon on your extension throughout the browser, then click on on it and choose the “Debug” choice:

The Mozilla Firefox browser, showing the green background (and
Settling on the Debug choice throughout the browser toolbar the use of a devoted extension.

This will likely open the debugger in PhpStorm and ship both the nice or unhealthy information:

A partial PhpStorm screen, showing an open debugger panel. The left shows various breakpoints, complete with filenames, line numbers, and function references. The right shows the values of the variables throughout the code, along with the value types.
The use of the PhpStorm debugger with Xdebug.

In the event you right-click at the quite a lot of values, attributes, parameters, and variables, you’ll be capable of get right of entry to an additional context menu. This will provide you with a variety of additional scope to check and debug your code:

A portion of the PhpStorm Debugger interface with a list of breakpoints, filenames, line numbers, and function references on the left. The right shows a highlighted value within the code, with a context menu open. Among the options is "Set Value…" — the way to assign new values to variables and debug the code.
The use of the right-click context menu throughout the PhpStorm Debugger to set new values.

For instance, it's worthwhile to set other values for variables alongside the trail. This could be a planned try to damage your code and notice what occurs, or it can be a method to examine out code that already wishes a repair. Both approach, this will provide you with an improbable approach for debugging your code with no need to vary it first.

How Kinsta Is helping You to Debug Your WordPress Website online

WordPress comes with its personal set of debugging choices thru WP_DEBUG and different equipment, similar to Question Track. Those allow a method wherein you’ll begin to see in the past hidden error messages far and wide your website and dashboard. From there, you'll be able to start to determine what the issue is.

You'll additionally save the ones error messages the use of WP_DEBUG_LOG, which will provide you with a method to record the problems together with your website. We quilt learn how to set this up in any other article at the weblog. It is a breeze to arrange thru your MyKinsta dashboard (and the Websites > Gear display screen):

The MyKinsta dashboard, showing the left-hand purple sidebar, and a further gray submenu. There are two options to toggle here — a search and replace tool on the right, and the WordPress debugging tool on the left.
The WordPress debugging choice throughout the MyKinsta dashboard.

In the event you pair this with the unfastened DevKinsta native surroundings software, you’ll actually have a one-click method to allow and disable WP_DEBUG for every website you spin up:

The DevKinsta dashboard for a single site. It shows the database settings, including host, port, name, and user credentials. There is also a
Enabling WP_DEBUG inside DevKinsta’s regulate panel.

This implies you'll be able to catch mistakes to your website all the way through construction, and ensure they don’t make it thru for your are living website. Those modes also are simple to show off — essential for each website and person safety.

All Kinsta plans additionally include the integrated Kinsta APM software, which is our custom-designed efficiency tracking software for WordPress websites.

Command Cheat Sheet

Ahead of we wrap up this publish, we must point out shortcuts.

Like many different device items, there are quite a lot of tactics to navigate round Xdebug (and PhpStorm) the use of the keyboard on my own. If truth be told, it's worthwhile to even use the command line to debug PHP scripts.

As soon as Xdebug is up and working, you'll be able to use the next instructions to get round:

Command Shortcut
Particular the port to concentrate on (similar to [9003]) -p [value]
Units a breakpoint at the specified line for the document trail given. breakpoint_set -t line document:/// -n
Runs your script till the tip, or the following breakpoint run
Steps into the following executable line step_into
Lists variables and values within the present scope context_get
Presentations the price of the desired belongings property_get -n

Whilst your particular code editor can have its personal devoted shortcuts, the point of interest this is on PhpStorm. Check out this desk of keyboard shortcuts for the use of Xdebug with PhpStorm:

Command Home windows macOS
In finding Motion Ctrl + Shift + A Shift + Cmd + A
Open the Debugger Shift + F9 Ctrl + D
Toggle Breakpoint Keep an eye on + F8 Cmd + F8
Step Into F7 F7
Step Over F8 F8
View Breakpoints Ctrl + Shift + F8 Shift + Cmd + F8
Resume the Program F9 F9
Assessment the Present Expression Alt + F8 Possibility + F8

Fortunately, there isn’t so much to memorize right here. You should open the debugger, set breakpoints in keeping with line, concentrate for connections, and run your scripts.

On the other hand, if you wish to have a shortcut for a selected activity, you'll be able to use the PhpStorm In finding Motion command:

The PhpStorm interface, showing the Find Action display. There are various search filters for All, Classes, Files, Symbols, Actions, and Git. The search term is
The use of the In finding Motion menu inside PhpStorm.

While you start to kind on this area, you’ll be proven a dynamic record of instructions and similar shortcuts. You'll additionally discover a PDF edition of all keyboard shortcuts in the course of the Assist > Keyboard Shortcuts PDF menu.

If you need extra of a real-time take a look at shortcuts as you're employed with the mouse, JetBrains supplies the Key Promoter X plugin:

A PhpStorm interface window, showing a number of options to find files and projects alongside the corresponding shortcuts. There are two notifications in the bottom right-hand corner with the format of
The PhpStorm interface appearing Key Promoter X notifications.

This to hand software will show notifications of your newest carried out motion, at the side of its similar keyboard shortcut. While you be informed and use the shortcuts, you'll be able to segment this plugin out and repair that precious genuine property for your display screen.

As any developer can attest, code isn't able for manufacturing after the primary draft. Debugging is key- which is the place Xdebug is available in 🐛Click on to Tweet


The observe of debugging has come far from its humble beginnings; it now encompasses a wider scope than its progenitors may have in all probability imagined. To hold out an intensive task in the case of solving your PHP code, you’ll want to use a reliable software. There are lots of very good extensions and equipment to choose between, however Xdebug is an controversial frontrunner.

As we’ve observed, Xdebug can adapt to even probably the most eclectic of tastes in code editors, and it’s particularly nice when paired with PhpStorm. On the other hand, without reference to your setup, there'll frequently be a edition of Xdebug to fit your wishes. At the complete, it’s an impressive, versatile, and intuitive software to make use of.

Do you assume Xdebug merits its top reward, or is there any other debugging software that you simply desire? Tell us within the feedback segment underneath!

The publish How Xdebug Can Assist You Develop into a Higher WordPress Developer seemed first on Kinsta®.

WP Hosting

[ continue ]