XAMPP + xDebug + PhpStorm

First steps



- DRAFT -


This manual is applicable to:

  • XAMPP 7.0.8 - XAMPP 7.4.5
  • xDebug 2.5.3 - xDebug 2.9.5
  • PhpStorm 2018.1 - PhpStorm 2020.1

but is now updated for the latest versions.

1. XAMPP


First we must have the XAMPP installed.

1.1. Configuring Virtual Hosts


We can't thank the XAMPP Virtual Host HOW-TO.
They offered rather a poor configuration manual.
So we'll have to dive deeper into native Apache configuration directives.


Configuring virtual hosts (all files to be edited as root):
1. To be done once. Before adding any virtual hosts edit file /opt/lampp/etc/httpd.conf. Within the file, find the following line and uncomment it by removing the hash symbol (#) at the beginning of the line:
Include etc/extra/httpd-vhosts.conf


2. To be done once. When you configure youre virtual hosts you should keep in mind that default http://localhost will stop working as before unless you add it to your /opt/lampp/etc/extra/httpd-vhosts.conf as all the other virtual hosts with configuration like this:


 <VirtualHost *:80>
    ServerName localhost
    ServerAdmin hostname@mail.local
    DocumentRoot "/opt/lampp/htdocs"
    DirectoryIndex index.php index.html index.htm
    <Directory "/opt/lampp/htdocs">
 Options Includes Indexes FollowSymLinks
 AllowOverride All
 Require all granted
    </Directory>
</VirtualHost>

3. Now you can configure your virtual hosts. let's have them in /opt/lampp/docs
and give the hosts a structure like:
/opt/lampp/docs/hostname - virtual host folder
/opt/lampp/docs/hostname/www - virtual host server document root
/opt/lampp/docs/hostname/error_log - virtual host error_log
/opt/lampp/docs/hostname/access_log - virtual host access_log


2. to do so let's add to /opt/lampp/etc/extra/httpd-vhosts.conf 


 <VirtualHost *:80>
    ServerName hostname
    ServerAlias www.hostname
    ServerAdmin hostname@mail.local
    DocumentRoot "/opt/lampp/docs/hostname/www"
    DirectoryIndex index.php index.html index.htm
    ErrorLog "/opt/lampp/docs/hostname/error_log"
    CustomLog "/opt/lampp/docs/hostname/access_log" common
    <Directory "/opt/lampp/docs/hostname/www">
 Options Includes Indexes FollowSymLinks
 AllowOverride All
 Require all granted
    </Directory>
</VirtualHost>

3. Now add to /etc/hosts a line:

127.0.0.1 hostname www.hostname

4. Now run/restart Apache to check our changes has made any effect.


5. Then open http://hostname in web browser.


1.2. Installing xDebug


It turned out to be a lie what they say in XDebug HOW-TO for XAMPP 7.4.5.
In fact there is no any xdebug.so extension where it should be (as well as no most of other extensions).
This can't stop us so we step to tailored installation of xDebug. Tailored Installation means you can compile an extension for a pre-installed PHP. So it's compiler time.


Tailored Installation Instructions:
1. Run: /opt/lampp/bin/php-7.4.5 -i
to get textual phpinfo output (with full path cause in XAMPP nothing is installed globally)


2. Copy that output and paste to xDebug dist wizard at https://xdebug.org/wizard and run analysis


3. Wizard detected my php.ini options and gave a summary:

Xdebug installed: no
Server API: Command Line Interface
Windows: no
Zend Server: no
PHP Version: 7.4.5
Zend API nr: 320190902
PHP API nr: 20190902
Debug Build: no
Thread Safe Build: no
OPcache Loaded: no
Configuration File Path: /opt/lampp/etc
Configuration File: /opt/lampp/etc/php.ini
Extensions directory: /opt/lampp/lib/php/extensions/no-debug-non-zts-20190902

and offered to download xdebug-2.9.5.tgz


4. Download the offered http://xdebug.org/files/xdebug-2.9.5.tgz


5. Install the pre-requisites for compiling PHP extensions.
On Ubuntu system, install them with: apt-get install php-dev autoconf automake


6. Unpack the downloaded file with tar -xvzf xdebug-2.9.5.tgz


7. Run: cd xdebug-2.9.5


8. Run: /opt/lampp/bin/phpize-7.4.5
if it's ok, it shows:
Configuring for:

Configuring for:
PHP Api Version:         20190902
Zend Module Api No:      20190902
Zend Extension Api No:   320190902

If it does not, you are using the wrong phpize.


9. Run: ./configure --with-php-config=/opt/lampp/bin/php-config
10. Run: make
11. Run: sudo cp modules/xdebug.so /opt/lampp/lib/php/extensions/no-debug-non-zts-20190902
12. Run: chown root:root /opt/lampp/lib/php/extensions/no-debug-non-zts-20190902/xdebug.so
13. Run: chmod 755 /opt/lampp/lib/php/extensions/no-debug-non-zts-20190902/xdebug.so
14. Edit as root /opt/lampp/etc/php.ini and add the lines:

zend_extension = /opt/lampp/lib/php/extensions/no-debug-non-zts-20190902/xdebug.so

[xdebug]
xdebug.extended_info = 1
xdebug.max_nesting_level = 1000
xdebug.profiler_enable = 1
xdebug.profiler_enable_trigger = 1
xdebug.remote_enable = 1
xdebug.remote_autostart = 1
xdebug.remote_host = "localhost"
xdebug.idekey="PHPSTORM"
xdebug.remote_port = 9000
xdebug.remote_handler = "dbgp"
xdebug.remote_mode = "req"
xdebug.remote_log = "/opt/lampp/logs/php_error_xdebug_log"
xdebug.show_local_vars = 1
xdebug.trace_output_dir = "/opt/lampp/temp"
xdebug.var_display_max_data = 1000
xdebug.var_display_max_depth = 1

15. Now we should run/restart Apache to check our changes has made any effect.
Important! When you run "gksu /opt/lampp/manager-linux-x64.run" - so it runs as root - to control httpd and mysqld Never click "Go To Application" so XAMPP starts a web browser http://localhost -- the web browser is run also as root! Instead of that run web browser manually as normal user and type or make a shortcut for http://localhost.


To avoid this better use command sudo /opt/lampp/xampp [start|stop|restart]


BTW, when you run XAMPP locally you may want to disable ProFTPD from starting automatically with the rest XAMPP. To achieve this just delete the empty file /opt/lampp/etc/xampp/startftp it's root:root 664 and you can re-create it if needed.


16. If it all was done right the phpinfo() page:
http://localhost/dashboard/phpinfo.php
should contain "with Xdebug v2.9.5"


Links for the article:

  1. http://7php.com/install-xdebug-xampp/ - example of xDebug XAMPP installation
  2. http://xdebug.org/ - xDebug web site

2. PhpStorm: Create project from existing files, configure server-side PhpStorm + xDebug, and client-side web browser + xDebug for remote debugging


If you got a folder with files and sub-folders you can convert it to PhpStorm project. It is required for further PhpStorm configuration that is applicable only to projects. It's a good idea do develop each project inside its personal test virtual host of a local server. Further we'll describe how PhpStorm works in this situation.


  1. Run PhpStorm.
  2. On start window choose "Create New Project from Existing Files".
  3. Choose "Web server is installed locally, source files are located under it's document root".
  4. Find in directory tree your project's virtual host root, select it and click "Project Root" button at the top of the list. Then click "Next".
  5. Specify the local server. Choose "Add new local server". Then click "Next".
  6. Specify "Name" - like your project_name, cause we'll have individual servers for each project and "Web server root URL:", which should likely be http://project_name. You can click "Open" button to make sure it's the right URL. Then click "Next".
  7. The IDE will offer you "Web path for project root". According to previous configuration having the same project and server document root, just click "Finish". The server configuration is saved and is available in menu "File" -> "Settings" -> "Build, Execution, Deployment" -> "Deployment" when project is open. But the server is not yet fully configured.
  8. The project window opens now. To continue configuration go to menu "Run" -> "Edit configurations" -> Click "+" -> Choose "PHP Remote Debug" -> "Name:" - hostname , "Servers:" -> click ... -> to open "Servers" -> Click "Import" ("Door sign") -> Choose "Deployment:" - hostname -> Click "OK" -> Click "OK" -> Set "Ide key (session Id):" PHPSTORM -> Click "OK".
  9. Now you've configured serverside. But to start debugging we must configure client-side to let web browser start xDebug session. After we got php.ini configured and confirmed that "with Xdebug v2.5.3" string is now in phpinfo() page, and PhpStorm can work with our web server - it's now time to configure your favourite web browser to start remote debugging sessions. Without this remote debugging won't go.
  10. When configuring xDebug browser extensions keep in mind that your IDE key was set to PhpStorm at php.ini, so you should configure IDE key in your browser extensions' or bookmarklets' options to be PhpStorm also.
  11. When it's all done you can start toggling breakpoints in your_script.php.
  12. When all of them are set select "hostname" fom a drop-down menu at the top right of the main screen, then click "Start Listening for PHP Debug Connections" ("Phone headset sign" ) and then "Debug 'hostname' (Shift + F9)" ("Green bug sign"). there can emerge a warning "PHP Interpreter is not configured: Please configure PHP Interpreter to use built-in web server" - Ignore it. We're using local web server and not a built-in one so it's ok.
  13. Open in web browser the php-file, where you've set up xDebug browser extensions or bookmarklets, click "[Enable/Start] Debug", then go to http://hostname/your_script.php.
  14. The execution of your_script should stop on the first break point, the IDE will become active and you can see the variables and control the step-by-step execution of it.
  15. When you've done click "Stop 'hostname' (Shift + F2)" ("Red Stop sign").

Links for the article:

  1. https://www.jetbrains.com/phps[...]video-tutorials.html - video PhpStorm tutorials

3. Special Notes


  1. Sometimes Firefox (I've tested this on 53.0) does not open localhost or local virtual hosts when internet is offline. But there is a solution:
    https://askubuntu.com/question[...]hen-offline-how-to-f
    For me this issue emerged and fixed itself without any actions.
  2. PhpStorm requires Google Chrome for WYSIWYG web page editing and HTML debugging. It's not a problem if you're on x86_64 but x86 is not supported in Google Chrome now. Last x86 build was: google-chrome-stable_48.0.2564.116-1_i386.deb
    See discussion: https://unix.stackexchange.com[...]scontinued-by-google
    and Google for the old version if needed.
  3. PhpStorm may start to tell you about some problems with your php-code, but you should keep in mind that all those advice are related to certain PHP version and you should manually switch to the one that you use: Go to "File -> Settings -> Languages & Frameworks > PHP" and set "PHP language level" to "7.1" for WackoWiki R6.0.5 and press "OK".
    See for details:
    https://stackoverflow.com/ques[...]-version-in-phpstorm
    https://www.jetbrains.com/help/phpstorm/php.html

4. Video

  1. https://www.youtube.com/channe[...]LkWz6MS2iehzg/videos -- Installing and Configuring Xampp + Xdebug on Ubuntu (Linux) + PhpStorm, 3 parts, about 40 minutes total -- words in Russian, commands and interface in English.

Read comment (1 comment)