How to Build Windows PHP Extensions with AppVeyor: A Complete Step‑by‑Step Guide

Introduction

AppVeyor is a hosted continuous‑integration platform that supports Windows, Linux, and macOS. It can be used for free with public GitHub projects and, with a self‑hosted setup, for private repositories. The guide explains how to use AppVeyor to build Windows‑specific PHP extensions.

Forking the Repository and Preparing Tokens

The author forked the official repository under the yangweijie account. Because the build process needs a GitHub token to publish a zip release, the token was encrypted and stored in the deplo project's auth_token field. Environment variables were attempted first but proved unreliable.

AppVeyor Configuration

The original .appveyor.yml defines a matrix of PHP versions, architectures, and ZTS states, and selects appropriate Visual Studio images. Below is the core configuration (trimmed for brevity):

image: Visual Studio 2015
version: '{branch}.{build}'

cache:
  - c:\build-cache -> .appveyor.yml, .appveyor/*.cmd

environment:
  PHP_BUILD_CACHE_BASE_DIR: c:\build-cache
  PHP_BUILD_OBJ_DIR: c:\obj
  PHP_BUILD_CACHE_SDK_DIR: c:\build-cache\sdk
  PHP_BUILD_SDK_BRANCH: php-sdk-2.2.0
  SDK_REMOTE: https://github.com/OSTC/php-sdk-binary-tools.git
  SDK_BRANCH: php-sdk-2.2.0

matrix:
  - PHP_REL: 8.0
    ARCHITECTURE: x64
    ZTS_STATE: enable
    APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2019
    PHP_BUILD_CRT: vs16
  - PHP_REL: 7.4
    ARCHITECTURE: x64
    ZTS_STATE: enable
    APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017
    PHP_BUILD_CRT: vc15
  # ... other matrix entries omitted ...

install:
  - .appveyor\install.cmd

build_script:
  - .appveyor\build.cmd

This matrix mirrors a typical GitHub Actions workflow for building PHP extensions, but adds a step to deploy the built artifacts to GitHub.

Packaging and Deploying Artifacts

The build script creates a zip package containing the compiled DLLs. The following commands compress the build directory and push the artifact to AppVeyor, which then uploads it as a GitHub release attachment:

7z a php_tideways_xhprof-%APPVEYOR_REPO_TAG_NAME%-%PHP_REL%-%PHP_BUILD_CRT%!ZTS_IN_FILENAME!!ARCH_IN_FILENAME%.zip %APPVEYOR_BUILD_FOLDER%\php_tideways_xhprof-%PHP_REL%-!ZTS_SHORT!-%PHP_BUILD_CRT%-%PHP_SDK_ARCH%\*
appveyor PushArtifact php_tideways_xhprof-%APPVEYOR_REPO_TAG_NAME%-%PHP_REL%-%PHP_BUILD_CRT%!ZTS_IN_FILENAME!!ARCH_IN_FILENAME%.zip -FileName php_tideways_xhprof-%APPVEYOR_REPO_TAG_NAME%-%PHP_REL%-%PHP_BUILD_CRT%!ZTS_IN_FILENAME!!ARCH_IN_FILENAME%.zip

By adding a custom tag name environment variable that combines the PHP version and architecture, the resulting release files have predictable names.

Remote Build Observation

During a successful run, AppVeyor connects via RDP to a Windows VM, clones the PHP source, places the extension code under ext, builds the DLL in a build folder, and then creates a delete ‑prefixed file on the desktop to signal completion. Removing this file allows the job to finish.

Running the Build Locally

The same configuration can be executed on a personal Windows machine by adding it as a new build agent in the AppVeyor dashboard. After installing the required tools (Visual Studio, 7‑Zip, etc.), the build proceeds identically.

Lessons Learned and Pitfalls

Token handling must be encrypted; plain environment variables may not be read correctly.

Only the selected matrix jobs should be kept; unfinished jobs block subsequent builds.

Remote scripts can modify local firewall rules and create unwanted accounts, so clean up after testing.

Artifact packaging must explicitly include the compiled DLLs; otherwise only the source zip is uploaded.

With these adjustments, building Windows DLLs for PHP extensions via AppVeyor becomes reliable and reproducible.