Comet Components is an active work in progress. These docs and the code currently available via GitHub and Packagist should be considered an incomplete alpha release.

PHP development setup on Windows

Installing PHP natively in Windows

You can install PHP in Windows a number of ways, including:

  1. Installing Laravel Herd, a GUI which includes PHP and Composer and puts them in your system PATH automatically
  2. Using the Chocolatey package manager through PowerShell
  3. For WordPress development, using Local by Flywheel
  4. Using local web server software such as WampServer
  5. Downloading a zip from php.net and extracting it where you want it to live (quickest and easiest in the short term, but not great for updates).
Install with Laravel Herd

Download and install Laravel Herd. It comes with PHP and Composer built in, and makes it very easy to have multiple PHP versions installed and switch between them - no need to change environment variables or even type a terminal command.

Install via PowerShell with Chocolatey

Standard installation - installs in C:/tools by default:

choco install php

To update:

choco upgrade php

After installing, you can confirm PHP is available in your terminal (and the version) like so:

PowerShell
php -v

If this doesn't show a PHP version, you may just need to manually add PHP to your PATH.

If you have multiple instances of PHP, see which is in use with:

PowerShell
Get-Command php

Optional Use Windows' PHP in WSL

If using WSL for your day-to-day CLI needs, you can install PHP within the Linux environment, but for consistency with other tools it can be easier to use the Windows installation. There are two ways you can do this:

Option 1: Use an alias

You can have WSL use the "Global PHP version" set in Laravel Herd using an alias in .zshrc or .bashrc that routes the command via PowerShell like the below example:

# /home/leesa/.zshrc
alias php='powershell.exe /c C:\\Users\\leesa\\.config\\herd\\bin\\php.bat'

You can also alias it to a specific version or instance of PHP, for example:

# /home/leesa/.zshrc
# Specific Herd instance
alias php='powershell.exe /c C:\\Users\\leesa\\.config\\herd\\bin\\php84\\php.exe'

# /home/leesa/.zshrc
# Chocolatey default location
alias php='powershell.exe /c C:\\tools\\php84\\php.exe'

Restart the WSL terminal and then confirm it works and see the version with:

php -v
Option 2: Use a symlink

You can create a symbolic link to have WSL use a specific PHP executable that is installed anywhere in Windows.

If you already have one set up and are here to change your PHP version, remove the existing symlink first:

sudo rm /usr/local/bin/php

For a symlink to specific PHP version, use one of the following from a WSL terminal as relevant to your setup and PHP version, the command format is sudo ln -s /mnt/c/path/to/php.exe /usr/local/bin/php. For example:

# For PHP 8.4 from Laravel Herd (replace leesa with your Windows username)
sudo ln -s /mnt/c/Users/leesa/.config/herd/bin/php84/php.exe /usr/local/bin/php

Restart the WSL terminal and then confirm it works and see the version with:

php -v
Troubleshooting

To confirm which PHP instance is being used, you can run the following in WSL:

which php

If it is using alias, you will see something like:

php: aliased to powershell.exe /c C:\Users\leesa\.config\herd\bin\php.bat

For a symlink, you will see something like:

/usr/local/bin/php

If you have both, the alias will take precedence.

Composer

Composer is a dependency manager for PHP. You can install it in a number of ways, such as:

  • Downloading and running the Windows installer from the Compser website
  • Via Chocolatey in PowerShell
  • By installing Laravel Herd, which comes with Composer built-in.
Install with Laravel Herd

Download and install Laravel Herd. It comes with PHP and Composer built in.

Install via PowerShell with Chocolatey
choco install composer

To update:

choco upgrade composer
Confirm Composer alias is available

Once installed, confirm that it works in PowerShell:

composer -v

If it doesn't work, you probably just need to manually add the path to composer in your PATH system environment variable.

Optional Use Windows' Composer in WSL

If using Windows' PHP as explained above, Composer can then be used from WSL by adding an alias to your Bash config (
.bashrc or .zshrc) like so:

# /home/leesa/.zshrc
alias composer='powershell.exe /c C:\\Users\\leesa\\.config\\herd\\bin\\composer.bat'

As you can see from it starting with powershell.exe, this effectively makes WSL a wrapper and the command is actually
executed by PowerShell. This makes no real difference in practice, but it's nice to not have to switch terminals.

Restart the WSL terminal and then confirm it works:

WSL (Bash)
composer -v

:::

Checking and changing instances

Which instance is being used?

At any time, you can confirm where the PHP and Composer aliases resolve to with the following commands:

WSL (Bash)
readlink -f $(which php)

which composer
Changing the PHP or Composer instance

To change the global PHP version, if you're using Laravel Herd you can just do it in the GUI - there's a simple dropdown. Otherwise, you can modify the system PATH variables in the Windows GUI.

For WSL, follow the "Use Windows' PHP in WSL" and "Use Windows' Composer in WSL" instructions above to set up or update your alias or symlink to the PHP executable you want to use.

Optional Xdebug

Xdebug is a PHP extension which provides debugging and profiling capabilities. It is required for generating code coverage reports with Pest/PHPUnit, and is useful for other debugging tasks.

Tips

If you are using Laravel Herd or Local by Flywheel to manage PHP, Xdebug is already installed on your system.

If using PhpStorm you can check if Xdebug is available (and find your php.ini file if it isn't) in File > Settings > PHP > CLI Interpreter.

For Local by Flywheel, there is a toggle on your site's main screen to enable Xdebug.

For Laravel Herd Pro with PhpStorm, the Xdebug detection feature should enable it automatically when you try to use it with breakpoints. If it doesn't, or you need to trigger it another way (such as for unit test coverage), you can enable it manually. See the troubleshooting section of the unit testing page for more information.

For other setups including the free version of Herd, enable it by adding the following to the php.ini file (updating the path to the Xdebug DLL as necessary):

zend_extension = C:\Program Files\Herd\resources\app.asar.unpacked\resources\bin\xdebug\xdebug-8.4.dll
xdebug.mode = debug,develop
xdebug.start_with_request = yes
xdebug.start_upon_error = yes
Tips for using XDebug with Local by Flywheel

If you are trying to use XDebug for a WordPress site using Local, make sure to:

  • Turn on XDebug in the Local GUI for the site
  • Set the PhpStorm CLI interpreter to use Local's PHP instance
  • Exit Laravel Herd if it is running, because it is probably using the same port unless you've changed one of them
  • Restart your site in Local after making any changes to php.ini.

Optional PhpStorm Configuration

See the PhpStorm setup notes for more information.