PHP debug with IIS Express on Windows

This post describes how you can debug a PHP website with Visual Studio Code and IIS Express on Windows. Visual Studio Code is a lightweight source code editor with built-in support for JavaScript, TypeScript and Node.js, it has extensions for other languages (such as C++, C#, Java, Python, PHP, Go).

You will need to install PHP for IIS and/or PHP for IIS Express in order to be able to run PHP applications on your Windows computer. You can use Web Platform Installer in IIS Manager to install many different versions of PHP, you find them under Products and Frameworks.

IIS and IIS Express will use the latest installed version of PHP by default, you can change the order of handlers “Handler Mappings” in IIS Manager on the server level or the application level. Click on “View Ordered List” in IIS Manager to see the order för handlers. You can also open the applicationHost.config file to see the order of handlers (C:\Windows\System32\inetsrv\Config\).

<handlers accessPolicy="Read, Script">
	<add name="PHP72_via_FastCGI" path="*.php" verb="GET,HEAD,POST" modules="FastCgiModule" scriptProcessor="C:\Program Files (x86)\PHP\v7.2\php-cgi.exe" resourceType="Either" />
	<add name="PHP54_via_FastCGI" path="*.php" verb="GET,HEAD,POST" modules="FastCgiModule" scriptProcessor="C:\Program Files (x86)\PHP\v5.4\php-cgi.exe" resourceType="Either" />
	<add name="AXD-ISAPI-4.0_64bit" path="*.axd" verb="GET,HEAD,POST,DEBUG" modules="IsapiModule" scriptProcessor="%windir%\Microsoft.NET\Framework64\v4.0.30319\aspnet_isapi.dll" preCondition="classicMode,runtimeVersionv4.0,bitness64" responseBufferLimit="0" />
...
</handlers>

There is one applicationHost.config file for IIS Server and one for IIS Express, the configuration file for IIS Express is usually found in C:\Users\%Username%\Documents\IISExpress\config\.

Install Visual Studio Code and extensions

You need to download Visual Studio Code, you can choose a user installer, a system installer or a zip-file. When you have installed the editor, you also need to install the following extensions:

  • IIS Express (warren-buckley.iis-express)
  • PHP Debug (felixfbecker.php-debug)
  • PHP Extension Pack (felixfbecker.php-pack)
  • PHP IntelliSense (felixfbecker.php-intellisense)

Create a new project

To create a new project you just need to create a folder on your computer (D:\PHP-websites\php-test\) and open it in Visual Studio Code. Create a new file called “phpinfo.php” and add the following contents to it.

<html>
 <head>
  <title>PHP Information</title>
 </head>
 <body>
 <?php phpinfo(); ?> 
 </body>
</html>

Open a Command Pallete (Ctrl+Shift+P) from View in the menu or use the shortcut and type “IIS Express: Start Website”. This will add a iisexpress.json file to the .vscode folder in your project and add an localhost address for your website in applicationHost.config. Browse to the phpinfo.php file and check information about the php version used. If this does not work or if the php version used is the wrong one, open the applicationHost.config file for IIS Express (C:\Users\%Username%\Documents\IISExpress\config\). Make sure that you find fastCgi inside system.webServer and that you find the correct PHP-version as an application.

<fastCgi>
	<application fullPath="C:\Program Files (x86)\iis express\PHP\v5.4\php-cgi.exe" monitorChangesTo="php.ini" activityTimeout="600" requestTimeout="600" instanceMaxRequests="10000">
		<environmentVariables>
			<environmentVariable name="PHP_FCGI_MAX_REQUESTS" value="10000" />
			<environmentVariable name="PHPRC" value="C:\Program Files (x86)\iis express\PHP\v5.4" />
		</environmentVariables>
	</application>
	<application fullPath="C:\Program Files (x86)\iis express\PHP\v7.2\php-cgi.exe" monitorChangesTo="php.ini" activityTimeout="600" requestTimeout="600" instanceMaxRequests="10000">
		<environmentVariables>
			<environmentVariable name="PHP_FCGI_MAX_REQUESTS" value="10000" />
			<environmentVariable name="PHPRC" value="C:\Program Files (x86)\iis express\PHP\v7.2" />
		</environmentVariables>
	</application>
</fastCgi>

Next, locate handlers inside system.Webserver in the applicationHost.config file and make sure that a handler exists for the correct PHP-version, the order of handlers is essential (the first one found is used).

<handlers accessPolicy="Read, Script">
	<add name="PHP72_via_FastCGI" path="*.php" verb="GET,HEAD,POST" modules="FastCgiModule" scriptProcessor="C:\Program Files (x86)\iis express\PHP\v7.2\php-cgi.exe" resourceType="Either" />
	<add name="PHP54_via_FastCGI" path="*.php" verb="GET,HEAD,POST" modules="FastCgiModule" scriptProcessor="C:\Program Files (x86)\iis express\PHP\v5.4\php-cgi.exe" resourceType="Either" />
</handlers>

If you want to use a specific PHP-version for this website, create a web.config file in your project and add this (make sure that the name for the handler is unique).

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
	<handlers accessPolicy="Read, Script"> 
      <add name="PHP_localhost_8085" path="*.php" verb="GET,HEAD,POST" modules="FastCgiModule" scriptProcessor="C:\Program Files (x86)\iis express\PHP\v7.2\php-cgi.exe" resourceType="Either" />
	</handlers>
  </system.webServer>
</configuration>

Add Xdebug to PHP version

Browse to the phpinfo.php file of your website an copy the HTML version or the html source of the output. Browse to Xdebug Installation Wizard and paste the content in the textbox to get detailed installation instructions. Download the suggested file and follow the instructions.

My PHP version is 7.2, i added the downloaded file to “C:\Program Files (x86)\iis express\PHP\v7.2\ext” and opened the php.ini file (C:\Program Files (x86)\iis express\PHP\v7.2\php.ini) and added the following contents according to Xdebug and the PHP debug extension.

[XDebug]
zend_extension = "C:\Program Files (x86)\iis express\PHP\v7.2\ext\php_xdebug-2.6.1-7.2-vc15-nts.dll"
xdebug.remote_enable = 1
xdebug.remote_autostart = 1

Start to debug

Restart IIS Express if it is running, type “IIS Express: Restart Website” in the Command Pallete. Go to Debug and Open Configurations in the menu of Visual Studio Code and select PHP, this will add a launch.json file to the .vscode folder that looks like this.

{
    // 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
        },
        {
            "name": "Launch currently open script",
            "type": "php",
            "request": "launch",
            "program": "${file}",
            "cwd": "${fileDirname}",
            "port": 9000
        }
    ]
}

Add a breakpoint in the phpinfo.php file and go to Debug and Start Debugging in the menu, reload the browser and you can start to debug.

Leave a Reply

Your email address will not be published. Required fields are marked *