Build your own PHP on Windows

This tutorial concerns the new PHP SDK and PHP 7.2 and later, while the described PHP SDK is compatible with at least PHP 7.0. To build PHP prior to 7.0, or if you experience issues building PHP lower than 7.2 with the new PHP SDK, please refer to older documentation.

Building PHP on Windows will require three things

1. A properly set up build environment, including the compiler and the PHP SDK
2. Prebuilt libraries and headers for third party libraries that PHP uses in the correct location
3. The PHP source

PHP officially supports building with Microsoft's Visual C++ compilers. MinGW and Cygwin are NOT supported. ICC and clang can be used for experimental purposes. Though, be aware, the production quality binaries are guaranteed only by using Visual C++. The freely available Community VC++ editions are fully supported and can be used. For more information and how to get the compiler see the supported versions. The following VC++ versions are supported:

• Visual C++ 14.0 (Visual Studio 2015) for PHP 7.0 or PHP 7.1.
• Visual C++ 15.0 (Visual Studio 2017) for PHP 7.2, PHP 7.3 or PHP 7.4.
• Visual C++ 16.0 (Visual Studio 2019) for PHP 8.0, PHP 8.1, PHP 8.2 or PHP 8.3.
• Visual C++ 17.0 (Visual Studio 2022) for PHP 8.4.

Always keep your installed Visual C++ up to date. Otherwise build errors may occur due to dependencies built with newer versions.

Support for a certain Visual Studio version means only support for its default platform toolset; building PHP with a non-default platform toolset (such as 14.16 with Visual Studio 2019) may work, but is not recommended.

In filenames (and the PHP_SDK_VS environment variable; see below) the Visual Studio version is usually abbreviated. Before Visual Studio 2019, the abbreviation used the scheme “vc#” (for instance, “vc14”). This number (“#”) has tradionally been the major number of the respective platform toolset. The preview releases of Visual Studio 2017 shipped with platform toolset 15.00, so “vc15” was used. The first GA release of Visual Studio 2017, however, shipped with platform toolset 14.10 (to signal the backward compatibility), but the internal Visual Studio version number stayed 15.00. To avoid confusion “vc15” has been kept. For the Visual Studio 2019 builds (master), the “vc#” has finally been changed to “vs#” (note the “s”), where the number now designates the major internal Visual Studio version number.

• Fetch the latest stable SDK tag or HEAD from https://github.com/php/php-sdk-binary-tools
  • The new PHP SDK is required, when building PHP 7.2+
  • Read the PHP SDK specific notes on the Github repository page
• If compiling PHP 7.0+:
  • Install Visual Studio 2015
• If compiling PHP 7.2+:
  • Install Visual Studio 2017
• If compiling master:
  • Install Visual Studio 2019

• Optional tools
  • Git
  • Cppcheck
  • Clang

The PHP SDK 2.0.0+ provides starter scripts, that automatically setup the compiler environment. The starter scripts also provide functionality to inject custom setup pieces. To create a customized setup script, put your code into the file phpsdk-local.bat into the PHP SDK root dir. The following variables are automatically available within the PHP SDK shell

• PHP_SDK_ARCH - the target build architecture used for environment setup
• PHP_SDK_OS_ARCH - the operating system architecture
• PHP_SDK_PHP_CMD - integrated PHP binary wrapper script
• PHP_SDK_ROOT_PATH - the path to the PHP SDK root directory
• PHP_SDK_VS - Visual C++ version used for the environment (before PHP SDK 2.2.0beta4, this variable was named PHP_SDK_VC)
• several other less relevant vars are available, that can be viewed by the set command

The full list of the tools included with the PHP SDK can be found on the repository readme page.

Each version of Visual Studio (or Windows SDK) provides a command prompt environment for compiling (available from the Start Menu group). It is usable, for example, if you want to omit the starter scripts usage or want to test a pre release Visual Studio version.

• If compiling PHP 7.0+ open either the “VS2015 x64 Native Tools Command Prompt” or the “VS2015 x86 Native Tools Command Prompt”.

All commands in the rest of this document should be run in the appropriate command prompt.

1. Get the PHP source, there are two alternatives:
   • download a source archive (Stable releases, QA releases)
   • clone the PHP Git repository (GitHub mirror)
2. Get the binary tools:
   • available from https://github.com/php/php-sdk-binary-tools
   • either fetch a tag as zip, or clone the git repository and checkout the tag
3. Get the libraries on which PHP depends:
   • use the PHP SDK tools to fetch the suitable dependencies automatically by calling phpsdk_deps -u
   • alternatively, download the packaged deps from http://windows.php.net/downloads/php-sdk/deps/ choosing the matching VC++ version and architecture directory. Note the .7z packages are not provided anymore for PHP 7.2 and up.
   • Note: This should include the libraries needed to build most the core extensions. However, some other extensions may need additional libraries, header files and helper apps. See libs, fetch the version you need and extract the archive into the deps directory (see below). Another set of libraries used for the PECL extension builds is available under PECL deps directory. If required, they need to be fetched manually.

This should be done only once before building PHP. The reference binary SDK directory used here is c:\php-sdk, an arbitrary location can be used depending on concrete circumstances. Consequently, we use the path C:\php-sdk\phpdev\vc14\x64\php-7.1.0-src as a reference path for the Visual C++ 64-bit build of PHP 7.1.0.

1. Setup the PHP SDK
   1. Create the build directory c:\php-sdk
   2. Unpack the binary tools archive into this directory, it should contain three sub-directories: bin, lib and msys2
2. Open the command prompt and enter the build directory:

   cd c:\php-sdk\

3. Invoke the starter script, for example for Visual Studio 2015 64-bit build, invoke phpsdk-vc14-x64.bat
4. Run the phpsdk_buildtree batch script which will create the desired directory structure:

   phpsdk_buildtree phpdev

5. The phpsdk_buildtree script will create the path according to the currently VC++ version used and switch into the newly created directory
6. Extract the PHP source code to C:\php-sdk\phpdev\vX##\x##, where:
   • vX## is the compiler version you are using (eq vc14 or vs16)
   • x## is your architecture (x86 or x64)
   • For example: C:\php-sdk\phpdev\vc14\x64\php-7.1.0-src
7. In the same directory where you extracted the PHP source there is a deps directory. Do one of the following
   • switch into the php source directory and run phpsdk_deps -u
   • If you downloaded the dependencies manually in the previous step, extract them into deps

Note, that no cross builds are currently supported by the PHP SDK starter scripts.

1. Invoke the starter script to automatically setup the environment for the desired build config, fe

   c:\php-sdk\phpsdk-vc14-x64.bat

2. Change directory to the location of your PHP source code, e.g.

   cd C:\php-sdk\phpdev\vc14\x64\php-7.1.0-src

3. Run:

   buildconf

4. To get an overview of the compiling flags:

   configure --help

5. Create your configure command:

   configure --disable-all --enable-cli --enable-$remains

6. To build PHP, run:

   nmake

7. If you want the resulting PHP builds and extensions to be zipped, after 'nmake' also run:

   nmake snap

8. The compiled PHP is now under “C:\php-sdk\phpdev\vX##\x##\php-source-directory\Release_TS”. If you ran 'nmake snap' the zip file will also be here.
   • If you compiled with “--disable-zts” the compiled PHP will be under “C:\php-sdk\phpdev\vX##\x##\php-source-directory\Release”

1. Clean up old compiled binaries

   nmake clean

2. If you need to update the 'configure' script

   buildconf --force

3. Create your makefile: see release

   configure --disable-all --enable-cli --enable-$remains

4. Compile

   nmake

Many PECL extensions already have prebuilt DLLs which can be downloaded from the extension page on the PECL web site. For example, on the APCu extension page, there are *DLL* links next to the release archive link. They lead you to a page where you can download the compiled extension for your desired PHP version and architecture.

To build a PECL extension (for example APCu):

1. Open the extension's page on PECL ( APCu)
2. Download the extension source either by:
   • downloading a source archive
   • fetching the source from the extension's repository (link can be found under *Browse Source*)
3. Create a directory named pecl on the same level as your PHP source directory, e.g. C:\php-sdk\phpdev\vc14\x64\pecl
4. Extract or clone the extension source code to the pecl directory
   • if cloning, clone to a subdirectory, e.g. C:\php-sdk\phpdev\vc14\x64\pecl\apcu
   • source code archive should already contain a subdirectory named e.g. apcu-4.0.7
5. Invoke the starter script to automatically setup the environment for the desired build config, fe

   c:\php-sdk\phpsdk-vc14-x64.bat

6. Enter your PHP source directory
7. Rebuild the configure script by running:

   buildconf

8. Executing configure --help should now contain an option to enable APCu

   --enable-apcu    Whether to enable APCu support

9. Configure and build:

   configure --disable-all --enable-cli --enable-apcu

   nmake

10. Test the binary with a php -m command, to make sure APCu is loaded

At this point, your compiled extension will be located in the release directory.

Alternatively to the “in-tree” build described above, you can do a “phpize” build, what is mostly useful if you don't need to build PHP from source, but rather use a pre-built PHP binary package.

1. Download and unpack the development package which corresponds to your pre-built PHP version and variant from https://windows.php.net/
2. Download and unpack the source of the PECL extension
3. Invoke the starter script to automatically setup the environment for the desired build config, e.g. c:\php-sdk\phpsdk-vs16-x64.bat
4. Add the development package folder and the PHP folder to the PATH
5. Enter the source folder of the PECL extension
6. Run phpize
7. Run configure --help to see the list of configuration options
   • the most important option is the one which enables the extension to be built (e.g. --enable-apcu)
   • another important options is --with-prefix which expects the PHP folder to be passed
   • if the extension depends on C libraries, you need to download these and put them either in the --with-php-build folder, or use the --with-extra-includes and --with-extra-libs options; suitable pre-built libraries can be found on https://windows.php.net/downloads/php-sdk/deps/ and https://windows.php.net/downloads/pecl/deps/
   • there may be further interesting configuration options, e.g. those which allows to configure details of the extension to be built
8. Run configure with the desired options
9. Run nmake
10. After successful compilation, the build artifacts are located in the release folder
11. If the extension has a PHPT test suite, run nmake test

If you want to build your extension via Github Actions, consider to use https://github.com/php/php-windows-builder or https://github.com/php/setup-php-sdk.

When you have successfully compiled PHP, the release directory can be one of multiple, depending on the build configuration:

1. `Release`: Release NTS build
2. `Release_TS`: Release ZTS build
3. `Debug`: Debug NTS build
4. `Debug_TS`: Debug ZTS build

If you are compiling using a 64-bit compiler, then these directories will be located in a directory called `x64`.

1. For possible PHP SDK issues, please consult the PHP SDK readme
2. As of PHP 7.3 the switch --enable-native-intrinsics is available. The resulting binary will then require a processor with the corresponding feature set available. For example, if you set --enable-native-intrinsics=avx2, be sure the target machine has processor with AVX2 support.
3. In some circumstances, you may hit the linker error C1047; you may be able to work around that with set LDFLAGS=/d2:-AllowCompatibleILVersions and re-configuring the build.