Getting things set up correctly can be tricky. That’s where this tutorial helps.

Xdebug

Xdebug is a powerful tool for debugging PHP applications. It conveniently comes bundled with Local.

We’re using VS Code for our code editor in this tutorial, as well as some other tools I’ve listed below. Everything included here is the current release and version numbers are noted just in case it might be helpful since things change.

Prerequisites

• Local v6.4.2+6012: A local WordPress development environment, formally known as Local by Flywheel
  • • PHP v7.4.1/v7.3.5/v8.0: Selectable via the Local UI. Choose v7.4.1 or v 7.3.5 for now because PHP 8 has a different Xdebug setup we’ll cover at the end of the article.
• VS Code v1.70.2: Code editor
• PHP Debug by Xdebug for VS code v1.27.0: VS Code extension which allows VS Code to talk to Xdebug
• Xdebug Helper browser extension: Used for explicitly enabling or disabling debugging sessions
  • Chrome
  • Firefox

I use Windows because that’s what makes me happy, but this guide applies to other environments as well. I just wanted to note that, since the paths I’ll be referencing are Windows-y.

Create a Site in Local

Once all of the prerequisites have been installed and activated, you’ll need to create a new WP site in Local if you don’t have one already. When PHP Versions 7.3.x or 7.4.x are selected in Local, Xdebug Version 2 is used.

When PHP Version 8 is selected, Xdebug Version 3 is used. We’re going to use PHP Version 7.4.1 to start off with and will cover PHP Version 8 at the end of the article.

I’ve named my site xdebugvscode.test. Here are its settings:

Set Up php.ini.hbs Directives

Now that the site has been created, let’s double-check the Xdebug configuration directives in the site’s php.ini.hbs file. This file is located under your site’s conf/php directory.

For me, the path is D:devlocal-sitesxdebugvscodeconfphpphp.ini.hbs. Scroll to the bottom of the file under the [xdebug] section, and verify that you have the directives below set accordingly. If you need to make any changes, be sure to restart your Local site.

; Enable remote debugging.
xdebug.remote_enable=1

; If enabled, the xdebug.remote_host setting is ignored and
; Xdebug will try to connect to the client that made the HTTP request.
; It checks the $_SERVER['HTTP_X_FORWARDED_FOR'] and $_SERVER['REMOTE_ADDR'] variables to find out remote IP
xdebug.remote_connect_back=Off

; Set the port that Xdebug connects to.
xdebug.remote_port="9000"

; Disable the profiler.
xdebug.profiler_enable=0

; Set the profiler's output directory for when we're profiling.
xdebug.profiler_output_dir = "D:/dev/xdebug-profiler-output"

A Note About the php.ini.hbs File When Switching PHP Versions

If you ever change the PHP version for your Local site, Local will save the settings for the previous install of PHP under the {local-site-dir}/conf/php/php-{version-number}directory.

For example, I started out with PHP Version 7.4.1 installed, then switched to PHP Version 7.3.5. Local made a copy of my PHP Version 7.4.1 settings under D:devlocal-sitesxdebugvscodeconfphp-7.4.1.

If you change PHP versions and made any modifications to Local’s php.ini.hbs file, you’ll need to make the changes again, if this is the first time the PHP version has been activated. After that, if you swap between PHP versions, your setting changes will be preserved.

Ensure Xdebug Is Running

To make sure that Xdebug is running, create a file named pi.php in the root of your site and add the following code to it:

<?php
// Output information about PHP's configuration.
phpinfo();

Activate Xdebug Helper Browser Extension

Once you’ve installed and activated the Xdebug Helper extension for your preferred browser, make sure to enable debugging by clicking on the icon and selecting Debug. The little bug icon will turn green letting you know that the browser extension will set the appropriate flag to turn on debugging.

Open Local Site in VS Code and Save a Workspace

Once the site has been created, go to File > Open Folder in VS Code, then navigate to the site’s directory. Now, save the workspace by going to File > Save Workspace As… and then give the workspace a name.

Install and Activate PHP Debug Extension for VS Code

The PHP Debug extension for VS Code helps to bring everything together. Locate the extension in VS Code’s Extension Browser, and activate it. Make sure to select the one published by the Xdebug team, since there are a few extensions with the same name.

Create a launch.json File for Your Workspace

Next, we will create a launch.json file for our workspace. Click on VS Code’s debugging icon to open the debugging panel, then click on the create a launch.json file link.

Now select the name of your workspace which you created earlier.

{
  // Use IntelliSense to learn about possible attributes.
  // Hover to view descriptions of existing attributes.
  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for Xdebug",
      "type": "php",
      "request": "launch",
      "port": 9000,
      "log": false,
      "maxConnections": 1, // @see  https://github.com/xdebug/vscode-php-debug/issues/604
      "xdebugSettings": {
        "resolved_breakpoints": "0", // @see https://github.com/xdebug/vscode-php-debug/issues/629 and https://stackoverflow.com/a/69925257/3059883
        "max_data": 512,
        "show_hidden": 1,
        "max_children": 128
      }
    }
  ]
}

Add a Breakpoint to Your Code

For the purposes of this debugging WordPress demo, I’m going to add a breakpoint to line 48 of  Twenty Twenty-Two’s functions.php file.

To add a breakpoint, hover over the gutter (just to the left of a line number) and a little orange dot will appear. Click it to add a breakpoint.

Click it again to remove it. You can add multiple breakpoints, and the debugger will stop on each one. To keep things simple here, I’ll just add the one.

Once your breakpoint has been added, you will see it listed in the lower left-hand corner of  VS Code’s debugger panel. It’s also possible to set breakpoints on Notices, Warnings, Errors, etc., but we’ll uncheck all of those for this example.

Start Debugging WordPress

We’re finally ready to start debugging WordPress! Open VS Code’s debugger panel and click the green triangle to start listening for Xdebug. Use the F5 shortcut.

Once VS Code is listening for Xdebug, the Debugger Controls window will be displayed. The bottom of the VS Code window will turn orange.

Now Xdebug is waiting to start the session. To kick things off, just load a page that will hit the breakpoint.

I’m just going to load the homepage of the test site I created. Once I hit refresh on the homepage of the test site, VS Code will be highlighted in the taskbar and the debugger will stop executing code on the breakpoint that I had previously set.

Once a debugging session has started, additional controls will be active on the Debugger Control Panel, and variables will be listed under the VARIABLES section of the Debugging Panel.

We can now use the Debugger Controls to navigate through the codebase:

Debugger Controls

• Pause/Run (F6): Resumes code execution. Debugger will stop on the next breakpoint if set.
• Step Over (F10): Steps over a block of code.
• Step Into (F11): Steps into a block of code.
• Step Out (Shift + F11): Steps out of a block of code that was previously stepped into.
• Restart (Ctrl + Shift + F5): Restarts the debugging session.
• Stop (Shift+F5): Halts execution of the script.

The GIF at the top of this article demonstrates some basic usage of these controls.

Exploring Variables

We can also explore the values of local and global variables using the VS Code’s VARIABLES section within the Debugging Panel.

PHP Version 8 + Xdebug Version 3 Set Up

When a Local site is configured to use PHP Version 8.X, the bundled version of Xdebug will be Version 3, and there are many changes from Versions 2 to 3.

These changes are covered thoroughly in this guide. Notably, Xdebug Version 3 defaults to port 9003 instead of 9000. I’m going to switch my Xdebug Version 3 setup to use port 9000 for consistency, so I don’t have to change anything in my launch.json file.

Here are the Xdebug directives in my PHP Version 8 site’s php.ini.hbs file. Note that I’ve commented out the line xdebug.start_with_request.

xdebug.mode=debug
xdebug.client_port="9000"
; xdebug.start_with_request=yes
xdebug.discover_client_host=yes

<?php
xdebug_info();

Troubleshooting

One common issue that comes up when you’re debugging WordPress is that the debugger does not stop on the breakpoint that you’ve set. This is typically caused by a port conflict—some other process is already using the port that you’ve configured for debugging.

Make sure that no other application is using the port that was configured in the php.ini.hbs and launch.json file. If an application is already using the port you’ve specified, make sure to change your port to something that’s not in use.

To check for a port conflict, end your debugging session in VS Code then run the following command:

Windows CMD: netstat -an | find "9000"

Linux/Mac: sudo netstat -nap | grep ":9000"

You should not see any output after entering these commands. If you do, that means that a process is already using the port you’ve configured for Xdebug (9000) in our example. So you should either configure a different port in your php.ini.hbs and launch.json files, or locate the process that is tying up the port, and stop it/configure it to use a different port.

Bonus: Quick and Dirty Debugging

Sometimes, instead of using Xdebug, I prefer to simply log variables to WP’s error.log file using PHP’s error_log().

I find this handy for real quick stuff, though it’s really not the best way to debug WordPress when things get serious. For this setup, first, add the following statements to your site’s wp-config.php file:

define( 'WP_DEBUG', true ); // Debugging mode activated.
define( 'WP_DEBUG_LOG', true ); // Logs to wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false ); // Don't add errors to the output.
define( 'SCRIPT_DEBUG', true ); // Load un-minified scripts.

Now, errors will be logged to your site’s wp-content/debug.log file. I typically keep this file open in a side panel of VS Code.

I usually use this one-liner to output values to the debug.log file:  error_log( '$variable_name ' . var_export( $variable_name, true ) );

To make things easier, I trigger this one-liner using a VS Code User Snippet with the trigger logv. Here’s a copy of the debugging-related snippets I use. These are configured in VS Code under File > Preferences >  Configure User Snippets > PHP.

{
// Place your snippets for php here. Each snippet is defined under a snippet name and has a prefix, body and
// description. The prefix is what is used to trigger the snippet and the body will be expanded and inserted. Possible variables are:
// $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. Placeholders with the
// same ids are connected.
// Example:
// "Print to console": {
// "prefix": "log",
// "body": [
// "console.log('$1');",
// "$2"
// ],
// "description": "Log output to console"
// }
"Log var_export()": {
"prefix": "logv",
"body": ["error_log( '$1 ' . var_export( $2, true ) );"],
"description": "Do a var_export( $variable ) to PHP error log."
},
"Log print_r()": {
"prefix": "logp",
"body": ["error_log( print_r( $0, true ) );"],
"description": "Do a print_r( $variable ) to PHP error log."
},
"Exit with var_dump()": {
"prefix": "xvd",
"body": ["exit( var_dump( $0 ) );"],
"description": "Exit with var_dump()"
},
"Exit with print_r()": {
"prefix": "xpr",
"body": ["exit( print_r( $0 ) );"],
"description": "Exit with print_r()"
},
"Detailed Error Log": {
"prefix": "logd",
"body": [
"error_log( print_r( (object)",
"t[",
"tt'line' => __LINE__,",
"tt'file' => __FILE__,",
"tt'dump' => [",
"ttt$0,",
"tt],",
"t], true ) );"
],
"description": "Detailed error logging"
},
"Log gettype()": {
"prefix": "logt",
"body": ["error_log( gettype( $0 ) );"],
"description": "Do a gettype( $variable ) to PHP error log."
},
"Debug Filters": {
"prefix": "logf",
"body": ["add_action( 'all', function() { error_log( var_export( current_filter(), true ) ); } );"],
"description": "Logs current filter."
}
}

Conclusion

That’s about it for this post on debugging WordPress using Xdebug, Local, and VS Code. Using Xdebug, you’ll be able to more efficiently and effectively debug code. If you’ve never used it before, I’m sure you will find that Xdebug is a helpful tool in your development arsenal.

The post Debugging WordPress Using Xdebug, Local, and VS Code appeared first on WebDevStudios.

The solution to combat this “cowboy coding” is to not work directly on a server, but rather on a server that is on your local machine. There are a ton of ways to do this, and I’ll walk you through what I do.

• Faster. No waiting for files to upload via FTP before you can refresh your browser and see your changes.
• Easier debugging. Because everything is running on your system, setting up and using xDebug or other debugging tools is quite a bit easier.
• Don’t need an internet connection work on things.
• Less fear of screwing up. When working locally, you’re free to experiment and play around, as your work is not affecting current users.

I use Vagrant and a nifty tool called Varying Vagrant Vagrants (VVV) to power my local development. This, coupled with some tools I’ve written to make my life easier, is a very enjoyable way to work locally. I’ll walk through setting up VVV, as well as a helper tool VV, and how to use both.

So what’s Vagrant?

Vagrant is a toolkit that runs on top of VirtualBox, VMWare, or another virtual machine provider on your local machine. Vagrant will allow you to work with these virtual machines to run your code, while you keep your entire workflow on your local computer.

Vagrant is configured all within one file–the Vagrantfile. This allows you to just do a “vagrant up” on the command line, and Vagrant will set up a virtual machine configured exactly how it should be.

Vagrant allows you to create Vagrant boxes, which are basically an image of a machine that you can pull down. This, coupled with some nifty provisioning code, is what gives VVV its magic.

What is VVV?

Varying Vagrant Vagrants is a Vagrant setup that provides a great start for local WordPress development. Whether you’re building plugins, themes, or full site, a local VVV installation is the best place to do your development.

Setting up VVV

Getting VVV set up is pretty simple. You can follow along with the guide here.

• First you’ll want to install VirtualBox. You can probably switch this out for VMWare or something else, but Virtualbox is free and works perfectly for our needs.
• You’ll also want to install Vagrant. VVV’s README recommends Vagrant 1.6.x, but I’m running 1.7 with absolutely no problems, so you’ll probably be fine with the latest version.
• You’ll also want the vagrant-hostsupdater plugin. This is optional, but highly recommended. This lets you easily set up custom domains to use.
• VVV recommends installing the vagrant-triggers plugin, but I’ve actually run into some issues with this installed. If you choose to use this, disabling it should be your first step if you have issues.

After installing all the above requirements, just run git clone git@github.com:Varying-Vagrant-Vagrants/VVV.git on the command line where you’d like your local installation  and then a vagrant up. Boom! You’re using VVV.

This creates some local sites for you to use (keep in mind, these links will not work unless you have the software up and running):

• The latest stable, released version of WordPress
• The current development version of WordPress
• The current development version of WordPress, with all files
• The version of those development files built with Grunt
• A default dashboard containing several useful tools

Using VVV

Once you’ve set up VVV, you’ll be able to access above sites in your browser and the files inside the folder where you installed VVV. This is a perfect set up to start developing themes and plugins while testing on both the current version of WordPress, as well as the currently in-development version.

There are a few command line commands you’ll want to know when using VVV:

vagrant up – When in the VVV root directory, this will start the virtual machine that powers VVV. It will set up your hosts file with the correct local domain names, update your local versions of WordPress, and run any custom init scripts you have set up. (More on this later!)

vagrant halt – This pauses Vagrant. This is useful when you’re on battery power, aren’t using VVV, and you don’t want to run a virtual machine in the background.

vagrant provision – This runs provisioning scripts. These are the things that VVV uses to make sure it is set up correctly. You generally don’t need to do this all the time, but I recommend running this command if you start having issues and want to start troubleshooting.

vagrant ssh – And this connects you to VVV via ssh. This is probably my favorite command, as it allows you to run commands inside of the virtual machine. I use this mostly to run WP-CLI and PHPUnit things inside of VVV.

Vagrant also has more commands, but these are the ones you’ll mostly need and use when working with it for VVV on a daily basis.

Setting up more local sites

VVV has a nifty feature that allows you to create new sites. If you’re working on a project, it is useful to have a separate local installation for it, rather than squeezing it into one of the other ones. I’ve built a small command line tool to help automate the setup and management of this called Variable VVV.

Setting up VV

If you have Homebrew installed, you simply run brew install bradp/vv/vv in your terminal application. That’s it!

If you don’t have Homebrew installed, it’s very quick and really useful.

Using VV

Once installed, you can run vv anywhere you’d like. If vv can’t automatically find your VVV installation, you will be prompted for the path. It will also save this into a configuration file in ~/.vv-config so you won’t be prompted again.

You can read the documentation on Github. It is constantly getting new features and fixes, but for the most part, you’ll want to run the following commands:

vv list – Lists all local sites.

vv create – Walks you through a wizard to create a new site.

vv delete – Walks you through removing a site.

The wizard that VV walks you through can also all be done with flags on the original command, so creating the same site as in our screenshot could be done like so: vv create --domain testing_site.dev --nametesting_site --debug --sample-content.

VV has a lot more features and information covered in the README on Github, and should be read through. It has support for site blueprints which will install a set of plugins and themes you choose, deployments, and a lot more.

Hopefully, now you’ll be a bit more comfortable installing and using VVV and VV to power your local development. Both projects have active Github repositories, and everyone working on the projects is always happy to help.

The post Getting started with Vagrant & VVV for local development appeared first on WebDevStudios.

This will be very thorough, and (I hope) won’t take any knowledge for granted.

References:

• Using SSL for your local development
• Apache SSL on Mac OSX Lion 10.7
• How to create a self-signed SSL Certificate

Steps:

1. Finder App -> Go -> Go to Folder (cmd-shift-g) -> type:

   /private/etc/apache2

   -> hit enter.

2. New folder (cmd-shift-n) (OSX may ask for your admin password) -> name the folder ‘ssl‘ -> hit enter
3. Create a backup of the ‘httpd.conf‘ file in that folder.
4. Open the ‘httpd.conf‘ file (in the apache2 folder that you’re in) in a text editor. (next several steps taken from here)
   1. Make sure the SSL module is enabled if it’s not. Do this by uncommenting (aka, remove the ‘#’ symbol in front) the line that looks like:

      LoadModule ssl_module libexec/apache2/mod_ssl.so

   2. In the same file search for and uncomment (remove the #) this line:

      Include /private/etc/apache2/extra/httpd-ssl.conf

   3. Save the file. (OSX may ask for your admin password)
5. Create a backup of the ‘httpd-ssl.conf‘ file (in the ‘apache2/extra‘ folder).
6. Now open the ‘httpd-ssl.conf‘ file in your text editor.
   1. Update the ‘DocumentRoot‘ line with where your site’s root folder. In my case I put the path to my WordPress installation I needed to test. Something like:

      DocumentRoot /Users/YOURUSERNAME/Sites/WordPress

   2. Make sure ‘ServerName‘ line looks like:

      ServerName localhost

   3. modify ‘ServerAdmin‘ line to use one of your email addresses. (I doubt this is necessary)
   4. Take note of the line ‘ErrorLog‘. You can use the location listed there to “Go to folder” in finder and view the log if things don’t work. Or worse-case scenario, you can provide it’s output to someone smart who might be able to help.
   5. Edit ‘SSLCertificateFile‘ line to point to your new ssl folder and the ssl certificate file (don’t worry, we’ll be creating that shortly). That line should look like:

      SSLCertificateFile "/private/etc/apache2/ssl/ssl.crt"

   6. Do the same with the ‘SSLCertificateKeyFile‘ line:

      SSLCertificateKeyFile "/private/etc/apache2/ssl/ssl.key"

   7. In the same file comment out (add a # to the beginning of the line) the ‘SSLCACertificatePath‘ and ‘SSLCARevocationPath‘ lines if they’re not already.
   8. Save the file. (OSX may ask for your admin password)
7. Open Terminal app -> Read below caveats, then follow instructions here
   1. Each step has a singular line of dark bold text.. that is text you will paste into terminal and hit enter (copy the text exactly, not including white space or line breaks). The blue text below is an example of what terminal will output. (After pasting the line from step 2, terminal will walk you through the certificate’s necessary info. Whatever you put should be fine.. just hit enter after answering)
   2. On step 5, replace ‘/usr/local/apache/conf/ssl.crt‘ with the path to the location of the new ‘ssl’ folder you created in finder: /private/etc/apache2. So this will look like:

      /private/etc/apache2/ssl/ssl.crt

      Do the same with the ssl.key line. Replace:

      /usr/local/apache/conf/ssl.key

      with:

      /private/etc/apache2/ssl/ssl.key

      If you haven’t noticed, these values need to line up exactly with the paths you put in the ‘httpd-ssl.conf‘ file.

   3. Skip step 6 (it’s already done), and step 7.
8. At this point, you should be able to go to https://localhost and see it working. If you’re using a good browser, you’ll probably be warned about the authenticity of the certificate, but unless you have trust issues with yourself, you can ignore the errors. You’ll probably also notice other indications that you’re not using a known certificate, but again, you don’t need to worry about them.

   

*Note: from Using SSL for your local development, Beware that Apache only supports one SSL domain per IP. So you need to add further IP’s to your system, or use a module that allows multiple SSL VirtualHosts per IP. There is some further reading on this topic here.

*Another Note: According to Steph in the comments, “for the new OSX we have to uncomment LoadModule socache_shmcb_module modules/mod_socache_shmcb.so in file httpd.conf”.

The post How to Set Up SSL with OSX Mountain Lion’s Built-In Apache appeared first on WebDevStudios.