====== Build your own PHP on Windows ======

**This tutorial concerns building PHP with the new php-windows-builder tooling, it also uses the PHP SDK 2.0 under the hood, so can be used to build PHP 7.0 and above. To build PHP prior to 7.0, or if you experience issues building PHP lower than 7.2 with this, please refer to [[internals:windows:stepbystepbuild|older documentation]].**

===== Before you Begin =====

Building PHP on Windows will require three things.
  - A properly set up build environment, including the compiler, git and the PHP SDK
  - Prebuilt libraries and headers for third party libraries that PHP uses in the correct location
  - The PHP source

The advantage of using php-windows-builder tooling is that it can set up all of it under the hood.

===== Requirements =====

PHP officially supports building with Microsoft's Visual C++ compilers. The following VC++ versions are supported and can be set up before you build, or it will be installed on the first run:

  * 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.

===== Setup =====
 
  * Install the required Visual Studio Version as per the PHP Version as mentioned in the [[#requirements|Requirements]] section.

  * BuildPhp and BuildPhpExtension PowerShell modules.

  * Optional tools 
    * Git

===== Building PHP =====

To build PHP locally, you can install the BuildPhp powershell module from the PowerShell Gallery:

You'll need at least PowerShell version 5, which is available by default on Windows 10 and later. It is recommended to use PowerShell 7 or later. If you have an older version, you can install the latest version [[https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows|following these instructions]].

All commands in the rest of this document should be run in an elevated PowerShell session (Run as Administrator).

==== Install the BuildPhp Package ====

  * Install the BuildPhp PowerShell package: <code powershell>Install-Module -Name BuildPhp -Repository PSGallery -Force</code>

  * To install this module for the current user only: <code powershell>Install-Module -Name BuildPhp -Repository PSGallery -Force -Scope CurrentUser</code>

==== Compile ====

  * To build a specific version, use the Version input. It supports values in major.minor.patch format, e.g., ''%%7.4.25%%'', ''%%8.0.12%%'', etc., or ''%%master%%'' for the master branch of ''%%php-src%%''.
  * To build a 32-bit or a 64-bit version, use the Arch input. It supports values ''%%x64%%'' and ''%%x86%%''.
  * To build a thread-safe or non-thread-safe version, use the Ts input. It supports values ''%%ts%%'' and ''%%nts%%''.
  
  * Run the build: <code powershell>Invoke-PhpBuild -Version 8.4.11 -Arch x64 -Ts nts</code>

  * It should produce the PGO optimized builds for the input PHP version and configuration in a directory named artifacts in the current directory.

===== Building PHP extensions =====

To build the PHP extensions locally, you can install the BuildPhpExtension PowerShell module from the PowerShell Gallery:

==== Install the BuildPhpExtension Package ====

  * Install the BuildPhpExtension PowerShell package: <code powershell>Install-Module -Name BuildPhpExtension -Repository PSGallery -Force</code>

  * To install this module for the current user only: <code powershell>Install-Module -Name BuildPhpExtension -Repository PSGallery -Force -Scope CurrentUser</code>

==== Compile ====

  * To build a PHP extension, you can use the ''%%ExtensionUrl%%'' input. It supports a git repository URL as value.
  * To build a specific version of the extension, you can use the ''%%ExtensionRef%%'' input. It supports a git reference, e.g., a tag or a branch as value.
  * To build the extension for a specific PHP version, you can use the ''%%PhpVersion%%'' input. It supports values in major.minor format, e.g., 7.4, 8.0, etc.
  * To build the extension for a 32-bit or a 64-bit PHP version, you can use the ''%%Arch%%'' input. It supports values ''%%x64%%'' and ''%%x86%%''.
  * To build the extension for a thread-safe or non-thread-safe PHP version, you can use the ''%%Ts%%'' input. It supports values ''%%ts%%'' and ''%%nts%%''.
  * To specify the libraries required for the extension, you can use the ''%%Libraries%%'' input. It supports a comma-separated list of library names.
  * To specify additional arguments to pass to the ''%%configure%%'' script, you can use the ''%%Args%%'' input. It supports a string value.
    <code powershell>Invoke-PhpBuildExtension -ExtensionUrl https://github.com/xdebug/xdebug `
                         -ExtensionRef 3.4.5 `
                         -PhpVersion 8.4 `
                         -Arch x64 `
                         -Ts nts `
                         -Libraries "zlib" `
                         -Args "--with-xdebug"</code>

  * It should produce the extension builds in a directory named artifacts in the current directory.