Add support to build from local source and document it

shivammathur · shivammathur · commit ccadd4a3335b · 2025-08-16T03:33:53.000+05:30
diff --git a/README.md b/README.md
@@ -260,12 +260,18 @@ Next, make sure you have the required Visual Studio version installed to build t
 If the required Visual Studio version is not installed, for the first time you try to build PHP, the module will try to install the required Visual Studio components automatically.
 
 Then, you can build PHP by using the `Invoke-PhpBuild` command.
-- To build a specific version, you can 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 specific PHP version, you can use the `PhpVersion` 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, you can use the `Arch` input. It supports values `x64` and `x86`.
 - To build a thread-safe or non-thread-safe version, you can use the `Ts` input. It supports values `ts` and `nts`.
 
 ```powershell
-Invoke-PhpBuild -Version '8.4.11' -Arch x64 -Ts nts
+Invoke-PhpBuild -PhpVersion '8.4.11' -Arch x64 -Ts nts
+```
+
+To build PHP from a local source, run `Invoke-PhpBuild` from the source directory and omit `PhpVersion` input.
+
+```powershell
+Invoke-PhpBuild -Arch x64 -Ts nts
 ```
 
 It should produce the PGO optimized builds for the input PHP version and configuration in a directory named `artifacts` in the current directory.
@@ -292,7 +298,7 @@ Next, make sure you have the required Visual Studio version installed to build t
 If the required Visual Studio version is not installed, for the first time you try to build the PHP extension, the module will try to install the required Visual Studio components automatically.
 
 Then, you can build the PHP extension by using the `Invoke-PhpBuildExtension` command.
-- To build a php extension, you can use the `ExtensionUrl` input. It supports a git repository URL as value.
+- To build a php extension from a git repository, 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`.
@@ -310,6 +316,13 @@ Invoke-PhpBuildExtension -ExtensionUrl https://github.com/xdebug/xdebug `
                          -Args "--with-xdebug"
 ```
 
+To build an extension from a local source, run `Invoke-PhpBuildExtension` from the extension’s source directory and omit `ExtensionUrl` and `ExtensionRef` inputs.
+
+```powershell
+# cd to xdebug source directory, and then run
+Invoke-PhpBuildExtension -PhpVersion 8.4 -Arch x64 -Ts nts -Libraries "zlib" -Args "--with-xdebug"
+```
+
 It should produce the extension builds in a directory named `artifacts` in the current directory.
 
 ## License
diff --git a/extension/BuildPhpExtension/private/Get-Extension.ps1 b/extension/BuildPhpExtension/private/Get-Extension.ps1
@@ -6,91 +6,109 @@ function Get-Extension {
         Extension URL
     .PARAMETER ExtensionRef
         Extension Reference
+    .PARAMETER BuildDirectory
+        Build directory
+    .PARAMETER LocalSrc
+        Is source local
     #>
     [OutputType()]
     param (
-        [Parameter(Mandatory = $true, Position=0, HelpMessage='Extension URL')]
-        [string] $ExtensionUrl,
-        [Parameter(Mandatory = $true, Position=1, HelpMessage='Extension Reference')]
-        [string] $ExtensionRef
+        [Parameter(Mandatory = $false, Position=0, HelpMessage='Extension URL')]
+        [string] $ExtensionUrl = '',
+        [Parameter(Mandatory = $false, Position=1, HelpMessage='Extension Reference')]
+        [string] $ExtensionRef = '',
+        [Parameter(Mandatory = $true, Position=2, HelpMessage='Build directory')]
+        [ValidateNotNull()]
+        [ValidateLength(1, [int]::MaxValue)]
+        [string] $BuildDirectory,
+        [Parameter(Mandatory = $true, Position=3, HelpMessage='Is source local')]
+        [ValidateNotNull()]
+        [bool] $LocalSrc = $false
     )
     begin {
     }
     process {
-        Add-StepLog "Fetching extension from $ExtensionUrl"
-        try {
-            if(
-            ($null -eq $ExtensionUrl -or $null -eq $ExtensionRef) -or
-                    ($ExtensionUrl -eq '' -or $ExtensionRef -eq '')
-            ) {
-                throw "Both Extension URL and Extension Reference are required."
-            }
+        if($LocalSrc) {
             $currentDirectory = (Get-Location).Path
-            if($null -ne $ExtensionUrl -and $null -ne $ExtensionRef) {
-                if ($ExtensionUrl -like "*pecl.php.net*") {
-                    $extension = Split-Path -Path $ExtensionUrl -Leaf
-                    try {
-                        Get-File -Url "https://pecl.php.net/get/$extension-$ExtensionRef.tgz" -OutFile "$extension-$ExtensionRef.tgz"
-                    } catch {}
-                    if(-not(Test-Path "$extension-$ExtensionRef.tgz")) {
+            Copy-Item -Path "$currentDirectory\*" -Destination $BuildDirectory -Recurse -Force
+        } else {
+            Add-StepLog "Fetching extension from $ExtensionUrl"
+            try {
+                if (($null -ne $ExtensionUrl -and $null -ne $ExtensionRef) -and ($ExtensionUrl -ne '' -and $ExtensionRef -ne '')) {
+                    Set-Location $BuildDirectory
+                    if ($ExtensionUrl -like "*pecl.php.net*") {
+                        $extension = Split-Path -Path $ExtensionUrl -Leaf
                         try {
-                            Get-File -Url "https://pecl.php.net/get/$($extension.ToUpper())-$ExtensionRef.tgz" -OutFile "$extension-$ExtensionRef.tgz"
+                            Get-File -Url "https://pecl.php.net/get/$extension-$ExtensionRef.tgz" -OutFile "$extension-$ExtensionRef.tgz"
                         } catch {}
+                        if(-not(Test-Path "$extension-$ExtensionRef.tgz")) {
+                            try {
+                                Get-File -Url "https://pecl.php.net/get/$($extension.ToUpper())-$ExtensionRef.tgz" -OutFile "$extension-$ExtensionRef.tgz"
+                            } catch {}
+                        }
+                        & tar -xzf "$extension-$ExtensionRef.tgz" -C $BuildDirectory
+                        Copy-Item -Path "$extension-$ExtensionRef\*" -Destination $BuildDirectory -Recurse -Force
+                        Remove-Item -Path "$extension-$ExtensionRef" -Recurse -Force
+                    } else {
+                        if($null -ne $env:AUTH_TOKEN) {
+                            $ExtensionUrl = $ExtensionUrl -replace '^https://', "https://${Env:AUTH_TOKEN}@"
+                        }
+                        git init > $null 2>&1
+                        git remote add origin $ExtensionUrl > $null 2>&1
+                        git fetch --depth=1 origin $ExtensionRef > $null 2>&1
+                        git checkout FETCH_HEAD > $null 2>&1
                     }
-                    & tar -xzf "$extension-$ExtensionRef.tgz" -C $currentDirectory
-                    Copy-Item -Path "$extension-$ExtensionRef\*" -Destination $currentDirectory -Recurse -Force
-                    Remove-Item -Path "$extension-$ExtensionRef" -Recurse -Force
-                } else {
-                    if($null -ne $env:AUTH_TOKEN) {
-                        $ExtensionUrl = $ExtensionUrl -replace '^https://', "https://${Env:AUTH_TOKEN}@"
-                    }
-                    git init > $null 2>&1
-                    git remote add origin $ExtensionUrl > $null 2>&1
-                    git fetch --depth=1 origin $ExtensionRef > $null 2>&1
-                    git checkout FETCH_HEAD > $null 2>&1
                 }
+            } catch {
+                Add-BuildLog cross extension "Failed to fetch extension from $ExtensionUrl"
+                throw
             }
+        }
 
-            $patches = $False
+        $patches = $False
+        if($null -ne $extension) {
             if(Test-Path -PATH $PSScriptRoot\..\patches\$extension.ps1) {
                 if((Get-Content $PSScriptRoot\..\patches\$extension.ps1).Contains('config.w32')) {
-                     Add-Patches $extension
-                     $patches = $True
+                    Add-Patches $extension
+                    $patches = $True
                 }
             }
+        }
 
-            $configW32 = Get-ChildItem (Get-Location).Path -Recurse -Filter "config.w32" -ErrorAction SilentlyContinue
-            if($null -eq $configW32) {
-                throw "No config.w32 found"
+        $configW32 = Get-ChildItem (Get-Location).Path -Recurse -Filter "config.w32" -ErrorAction SilentlyContinue
+        if($null -eq $configW32) {
+            if($LocalSrc) {
+                throw "No config.w32 found, please make sure you are in the extension source directory and it supports Windows."
+            } else {
+                throw "No config.w32 found, please check if the extension supports Windows."
             }
-            $subDirectory = $configW32.DirectoryName
-            if((Get-Location).Path -ne $subDirectory) {
-                Copy-Item -Path "${subDirectory}\*" -Destination $currentDirectory -Recurse -Force
-                Remove-Item -Path $subDirectory -Recurse -Force
-            }
-            $configW32Content = Get-Content -Path "config.w32"
-            $extensionLine =  $configW32Content | Select-String -Pattern '\s+(ZEND_)?EXTENSION\(' | Select-Object -Last 1
-            if($null -eq $extensionLine) {
-                throw "No extension found in config.w32"
-            }
-            $name = ($extensionLine -replace '.*EXTENSION\(([^,]+),.*', '$1') -replace '["'']', ''
-            if($name.Contains('oci8')) {
-                $name = 'oci8_19'
-            } elseif ([string]$configW32Content -match ($([regex]::Escape($name)) + '\s*=\s*["''](.+?)["'']')) {
-                if($matches[1] -ne 'no') {
-                    $name = $matches[1]
-                }
+        }
+        $subDirectory = $configW32.DirectoryName
+        if((Get-Location).Path -ne $subDirectory) {
+            Copy-Item -Path "${subDirectory}\*" -Destination $currentDirectory -Recurse -Force
+            Remove-Item -Path $subDirectory -Recurse -Force
+        }
+        $configW32Content = Get-Content -Path "config.w32"
+        $extensionLine =  $configW32Content | Select-String -Pattern '\s+(ZEND_)?EXTENSION\(' | Select-Object -Last 1
+        if($null -eq $extensionLine) {
+            throw "No extension found in config.w32"
+        }
+        $name = ($extensionLine -replace '.*EXTENSION\(([^,]+),.*', '$1') -replace '["'']', ''
+        if($name.Contains('oci8')) {
+            $name = 'oci8_19'
+        } elseif ([string]$configW32Content -match ($([regex]::Escape($name)) + '\s*=\s*["''](.+?)["'']')) {
+            if($matches[1] -ne 'no') {
+                $name = $matches[1]
             }
+        }
 
-            if(!$patches) {
-                Add-Patches $name
-            }
+        if(!$patches) {
+            Add-Patches $name
+        }
+        if(-not($LocalSrc)) {
             Add-BuildLog tick $name "Fetched $name extension"
-            return $name
-        } catch {
-            Add-BuildLog cross extension "Failed to fetch extension from $ExtensionUrl"
-            throw
         }
+        return $name
     }
     end {
     }
diff --git a/extension/BuildPhpExtension/private/Get-ExtensionSource.ps1 b/extension/BuildPhpExtension/private/Get-ExtensionSource.ps1
@@ -30,10 +30,31 @@ function Get-ExtensionSource {
                     $ExtensionRef = $env:GITHUB_SHA
                 }
             }
+        } else {
+            if($null -eq $ExtensionRef -or $ExtensionRef -eq '') {
+                try {
+                    if(Test-Path package.xml) {
+                        $xml = [xml](Get-Content package.xml)
+                        $ExtensionRef = $xml.package.version.release
+                    } elseif(Test-Path .git) {
+                        $tag = git tag --points-at HEAD | Where-Object { $_ -match '^v?(\d+(\.\d+){0,2})$' } | Select-Object -First 1
+                        if($tag) {
+                            $ExtensionRef = $tag
+                        } else {
+                            $ExtensionRef = (git rev-parse --abbrev-ref HEAD) -replace 'origin/', ''
+                        }
+                    } else {
+                        $ExtensionRef = 'local'
+                    }
+                } catch {
+                    $ExtensionRef = 'local'
+                }
+            }
         }
         return [PSCustomObject]@{
             url = $ExtensionUrl;
             ref = $ExtensionRef
+            local = ($null -eq $ExtensionUrl -or $ExtensionUrl -eq '')
         }
     }
     end {
diff --git a/extension/BuildPhpExtension/public/Invoke-PhpBuildExtension.ps1 b/extension/BuildPhpExtension/public/Invoke-PhpBuildExtension.ps1
@@ -62,11 +62,11 @@ function Invoke-PhpBuildExtension {
 
         $buildDirectory = Get-BuildDirectory
 
-        Set-Location "$buildDirectory"
-
         $source = Get-ExtensionSource -ExtensionUrl $ExtensionUrl -ExtensionRef $ExtensionRef
 
-        $extension = Get-Extension -ExtensionUrl $source.url -ExtensionRef $source.ref
+        $extension = Get-Extension -ExtensionUrl $source.url -ExtensionRef $source.ref -BuildDirectory $buildDirectory -LocalSrc $source.local
+
+        Set-Location "$buildDirectory"
 
         $config = Add-BuildRequirements -Extension $extension `
                                         -ExtensionRef $source.ref `
diff --git a/php/BuildPhp/BuildPhp.psd1 b/php/BuildPhp/BuildPhp.psd1
@@ -72,6 +72,7 @@
         'Get-PhpSdk',
         'Get-PhpSrc',
         'Get-PhpTestPack',
+        'Get-SourcePhpVersion',
         'Get-TestSettings',
         'Get-TestsList'
         'Get-VsVersionHelper',
diff --git a/php/BuildPhp/private/Add-BuildRequirements.ps1 b/php/BuildPhp/private/Add-BuildRequirements.ps1
@@ -6,6 +6,8 @@ function Add-BuildRequirements {
         PHP Version
     .PARAMETER Arch
         PHP Architecture
+    .PARAMETER FetchSrc
+        Fetch PHP source code
     #>
     [OutputType()]
     param (
@@ -16,14 +18,19 @@ function Add-BuildRequirements {
         [Parameter(Mandatory = $true, Position=1, HelpMessage='PHP Architecture')]
         [ValidateNotNull()]
         [ValidateSet('x86', 'x64')]
-        [string] $Arch
+        [string] $Arch,
+        [Parameter(Mandatory = $false, Position=2, HelpMessage='Fetch PHP source code')]
+        [ValidateNotNull()]
+        [bool] $FetchSrc = $True
     )
     begin {
     }
     process {
         Get-OciSdk -Arch $Arch
         Get-PhpSdk
-        Get-PhpSrc -PhpVersion $PhpVersion
+        if($FetchSrc) {
+            Get-PhpSrc -PhpVersion $PhpVersion
+        }
     }
     end {
     }
diff --git a/php/BuildPhp/private/Get-PhpSrc.ps1 b/php/BuildPhp/private/Get-PhpSrc.ps1
@@ -8,8 +8,6 @@ function Get-PhpSrc {
     [OutputType()]
     param (
         [Parameter(Mandatory = $true, Position=0, HelpMessage='PHP Version')]
-        [ValidateNotNull()]
-        [ValidateLength(1, [int]::MaxValue)]
         [string] $PhpVersion
     )
     begin {
@@ -21,10 +19,13 @@ function Get-PhpSrc {
         $zipFile = "php-$PhpVersion.zip"
         $directory = "php-$PhpVersion-src"
 
-        if ($PhpVersion.Contains(".")) {
+        if ( $PhpVersion.Contains("."))
+        {
             $ref = "php-$PhpVersion"
             $url = "$baseUrl/refs/tags/php-$PhpVersion.zip"
-        } else {
+        }
+        else
+        {
             $ref = $PhpVersion
             $url = "$baseUrl/$PhpVersion.zip"
         }
@@ -37,7 +38,7 @@ function Get-PhpSrc {
         Get-File -Url $url -Outfile $zipFile
         [System.IO.Compression.ZipFile]::ExtractToDirectory($zipFilePath, $currentDirectory)
         Rename-Item -Path "php-src-$ref" -NewName $directory
-        [System.IO.Compression.ZipFile]::CreateFromDirectory($directoryPath,  $srcZipFilePath)
+        [System.IO.Compression.ZipFile]::CreateFromDirectory($directoryPath, $srcZipFilePath)
     }
     end {
     }
diff --git a/php/BuildPhp/private/Get-SourcePhpVersion.ps1 b/php/BuildPhp/private/Get-SourcePhpVersion.ps1
@@ -0,0 +1,27 @@
+function Get-SourcePhpVersion {
+    <#
+    .SYNOPSIS
+        Get the PHP version from the source code.
+    #>
+    [OutputType([string])]
+    param (
+    )
+    begin {
+    }
+    process {
+        $versionFile = "main/php_version.h"
+        if (-not (Test-Path -Path $versionFile)) {
+            throw "PHP source not found. Please either specify PhpVersion or ensure you are in the PHP source directory."
+        }
+
+        $content = Get-Content -Path $versionFile -Raw
+
+        $major = [regex]::Match($content, 'PHP_MAJOR_VERSION\s+(\d+)').Groups[1].Value
+        $minor = [regex]::Match($content, 'PHP_MINOR_VERSION\s+(\d+)').Groups[1].Value
+        $patch = [regex]::Match($content, 'PHP_RELEASE_VERSION\s+(\d+)').Groups[1].Value
+
+        "$major.$minor.$patch"
+    }
+    end {
+    }
+}
diff --git a/php/BuildPhp/public/Invoke-PhpBuild.ps1 b/php/BuildPhp/public/Invoke-PhpBuild.ps1
