在 GitHub Actions 中设置 PHP
在 [GitHub Actions](https://github.com/features/actions "GitHub Actions") 中设置具有所需扩展、php.ini 配置、代码覆盖率支持以及各种工具（如 composer）的 PHP 环境。此 Action 为您提供了一个跨平台接口，用于设置测试应用程序所需的 PHP 环境。请参阅 [用法](#memo-usage "How to use this") 部分和 [示例](#examples "Examples of use") 以了解如何使用。
## 目录
- [操作系统/平台支持](#cloud-osplatform-support)
- [GitHub 托管的 Runner](#github-hosted-runners)
- [自托管 Runner](#self-hosted-runners)
- [PHP 支持](#tada-php-support)
- [PHP 扩展支持](#heavy_plus_sign-php-extension-support)
- [工具支持](#wrench-tools-support)
- [覆盖率支持](#signal_strength-coverage-support)
- [Xdebug](#xdebug)
- [PCOV](#pcov)
- [禁用覆盖率](#disable-coverage)
- [用法](#memo-usage)
- [输入参数](#inputs)
- [输出参数](#outputs)
- [标志](#flags)
- [基本设置](#basic-setup)
- [矩阵设置](#matrix-setup)
- [Nightly 构建设置](#nightly-build-setup)
- [Debug 构建设置](#debug-build-setup)
- [线程安全设置](#thread-safe-setup)
- [强制更新设置](#force-update-setup)
- [详细模式设置](#verbose-setup)
- [多架构设置](#multi-arch-setup)
- [自托管设置](#self-hosted-setup)
- [本地测试设置](#local-testing-setup)
- [JIT 配置](#jit-configuration)
- [缓存扩展](#cache-extensions)
- [缓存 Composer 依赖](#cache-composer-dependencies)
- [GitHub Composer 认证](#github-composer-authentication)
- [Private Packagist 认证](#private-packagist-authentication)
- [手动 Composer 认证](#manual-composer-authentication)
- [内联 PHP 脚本](#inline-php-scripts)
- [问题匹配器](#problem-matchers)
- [示例](#examples)
- [版本控制](#bookmark-versioning)
- [许可证](#scroll-license)
- [贡献](#1-contributions)
- [支持本项目](#sparkling_heart-support-this-project)
- [依赖](#package-dependencies)
- [延伸阅读](#bookmark_tabs-further-reading)
## :cloud: 操作系统/平台支持
`setup-php` 在以下操作系统/平台上支持 `GitHub 托管` 和 `自托管` runner。
### GitHub 托管的 Runner
| 虚拟环境 | 架构 | YAML 工作流标签 | 预装 PHP |
|---------------------|---------|------------------------------------|-------------------|
| Ubuntu 24.04 | x86_64 | `ubuntu-latest` 或 `ubuntu-24.04` | `PHP 8.3` |
| Ubuntu 22.04 | x86_64 | `ubuntu-22.04` | `PHP 8.1` |
| Ubuntu 24.04 | aarch64 | `ubuntu-24.04-arm` | `PHP 8.3` |
| Ubuntu 22.04 | aarch64 | `ubuntu-22.04-arm` | `PHP 8.1` |
| Windows Server 2025 | x64 | `windows-2025` | `PHP 8.5` |
| Windows Server 2022 | x64 | `windows-latest` 或 `windows-2022` | `PHP 8.5` |
| macOS Tahoe 26.x | arm64 | `macos-26` | - |
| macOS Sequoia 15.x | arm64 | `macos-latest` 或 `macos-15` | - |
| macOS Sonoma 14.x | arm64 | `macos-14` | - |
| macOS Tahoe 26.x | x86_64 | `macos-26-intel` | `PHP 8.5` |
| macOS Sequoia 15.x | x86_64 | `macos-15-intel` | `PHP 8.5` |
### 自托管 Runner
| 宿主操作系统/虚拟环境 | YAML 工作流标签 |
|----------------------------------|----------------------------|
| Ubuntu 24.04 | `self-hosted` 或 `Linux` |
| Ubuntu 22.04 | `self-hosted` 或 `Linux` |
| Debian 13 | `self-hosted` 或 `Linux` |
| Debian 12 | `self-hosted` 或 `Linux` |
| Debian 11 | `self-hosted` 或 `Linux` |
| Windows 7 及更高版本 | `self-hosted` 或 `Windows` |
| Windows Server 2012 R2 及更高版本 | `self-hosted` 或 `Windows` |
| macOS Tahoe 26.x x86_64/arm64 | `self-hosted` 或 `macOS` |
| macOS Sequoia 15.x x86_64/arm64 | `self-hosted` 或 `macOS` |
| macOS Sonoma 14.x x86_64/arm64 | `self-hosted` 或 `macOS` |
- 请参阅 [自托管设置](#self-hosted-setup) 以在自托管 runner 上使用此 Action。
- 基于上述 Ubuntu 和 Debian 版本的操作系统也尽最大努力提供支持。
- 如果请求的 PHP 版本已预装，`setup-php` 会切换到该版本，否则将安装该 PHP 版本。
## :tada: PHP 支持
在所有支持的操作系统/平台上，可以根据 runner 设置以下 PHP 版本。
- 在 GitHub 托管的 runner 上支持 PHP 5.3 到 PHP 8.6，macOS ARM64 runner (macos-14) 除外。
- 在 GitHub 托管的 macOS ARM64 runner (macos-14) 上支持 PHP 5.6 到 PHP 8.6。
- 在自托管 runner 上支持 PHP 5.6 到 PHP 8.6。
| PHP 版本 | 稳定性 | 发布支持 | Runner 支持 |
|-------------|-----------|-----------------------|--------------------------------|
| `5.3` | `Stable` | `End of life` | `GitHub-hosted` |
| `5.4` | `Stable` | `End of life` | `GitHub-hosted` |
| `5.5` | `Stable` | `End of life` | `GitHub-hosted` |
| `5.6` | `Stable` | `End of life` | `GitHub-hosted`, `self-hosted` |
| `7.0` | `Stable` | `End of life` | `GitHub-hosted`, `self-hosted` |
| `7.1` | `Stable` | `End of life` | `GitHub-hosted`, `self-hosted` |
| `7.2` | `Stable` | `End of life` | `GitHub-hosted`, `self-hosted` |
| `7.3` | `Stable` | `End of life` | `GitHub-hosted`, `self-hosted` |
| `7.4` | `Stable` | `End of life` | `GitHub-hosted`, `self-hosted` |
| `8.0` | `Stable` | `End of life` | `GitHub-hosted`, `self-hosted` |
| `8.1` | `Stable` | `End of life` | `GitHub-hosted`, `self-hosted` |
| `8.2` | `Stable` | `Security fixes only` | `GitHub-hosted`, `self-hosted` |
| `8.3` | `Stable` | `Security fixes only` | `GitHub-hosted`, `self-hosted` |
| `8.4` | `Stable` | `Active` | `GitHub-hosted`, `self-hosted` |
| `8.5` | `Stable` | `Active` | `GitHub-hosted`, `self-hosted` |
| `8.6` | `Nightly` | `In development` | `GitHub-hosted`, `self-hosted` |
## :heavy_plus_sign: PHP 扩展支持
可以使用 `extensions` 输入参数设置 PHP 扩展。它接受 csv 格式的 `string`。
- 在 `Ubuntu` 上，可以设置以包形式提供、在 `PECL` 上可用或位于 git 仓库中的扩展。
```
- name: Setup PHP with PECL extension
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
extensions: imagick, redis
```
- 在 `Windows` 上，可以设置 `PECL` 上提供 `DLL` 二进制文件的扩展。
- 在 `macOS` 上，可以设置 `PECL` 上可用或位于 git 仓库中的扩展。
- 在 `Ubuntu` 和 `macOS` 上，要从 git 仓库编译和安装扩展，请遵循此[指南](https://github.com/shivammathur/setup-php/wiki/Add-extension-from-source "Guide to compile and install PHP extensions in setup-php")。
- 如果指定了随 PHP 一起安装的扩展，它们将被启用。
- 可以通过在扩展名称后附加版本来设置 `PECL` 上特定版本的扩展。这对于安装支持已停止维护 PHP 版本的旧版扩展很有用。
```
- name: Setup PHP with specific version of PECL extension
uses: shivammathur/setup-php@v2
with:
php-version: '5.4'
extensions: swoole-1.9.3
```
- 可以通过在扩展名称后附加其状态（即 `alpha`、`beta`、`devel` 或 `snapshot`）来设置 `PECL` 上提供的预发布版本扩展。
```
- name: Setup PHP with pre-release PECL extension
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
extensions: xdebug-beta
```
- 在 `Ubuntu` 和 `macOS` 上，要使用库或自定义配置从 PECL 编译和安装扩展，请遵循此[指南](https://github.com/shivammathur/setup-php/wiki/Add-extension-from-PECL-with-libraries-and-custom-configuration "Guide to compile and install PHP extensions using PECL with libraries and custom configuration in setup-php")。
- 可以通过在共享扩展前加上 `:` 来禁用它们。所有依赖于指定扩展的扩展也将被禁用。
```
- name: Setup PHP and disable opcache
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
extensions: :mbstring
```
- 可以通过指定 `none` 来禁用所有共享扩展。当 `none` 与其他扩展一起指定时，它会被提升到输入的开头。因此，所有共享扩展将首先被禁用，然后再处理输入中的其余扩展。
这将禁用所有核心和第三方共享扩展，因此可能会破坏需要它们的某些工具。在设置工具时，会尽最大努力重新启用所需的扩展。因此，建议在 `extensions` 输入中将工具所需的扩展放在 `none` 之后，以避免任何问题。
```
- name: Setup PHP without any shared extensions except mbstring
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
extensions: none, mbstring
```
- 在 `Ubuntu` 工作流中，对于 `PHP 5.6` 及更高版本，可以通过在 `intl` 后附加 `ICU` 版本来设置具有特定 `ICU` 版本的 `intl` 扩展。PHP 8.4 及更低版本支持 `ICU 50.2` 及更新版本，PHP 8.5 及更高版本支持 `ICU 57.2` 及更新版本。有关支持的特定版本，请参阅 [`ICU builds`](https://github.com/shivammathur/icu-intl#icu4c-builds)。
```
- name: Setup PHP with intl
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
extensions: intl-77.1
```
- 在 `setup-php` 运行后默认加载的扩展可以在 [wiki](https://github.com/shivammathur/setup-php/wiki) 上找到。
- 这些扩展具有自定义支持：
- `Ubuntu` 上的 `cubrid` 和 `pdo_cubrid`。
- `Ubuntu` 和 `macOS` 上的 `event`、`gearman`、`geos` 和 `relay`。
- 所有受支持操作系统上的 `blackfire`、`couchbase`、`ibm_db2`、`ioncube`、`oci8`、`pdo_firebird`、`pdo_ibm`、`pdo_oci`、`pecl_http`、`phalcon3`、`phalcon4`、`phalcon5` 和 `zephir_parser`。
- 默认情况下，无法正常添加或禁用的扩展会在日志中留下错误消息，执行不会中断。要更改此行为，您可以将 `fail-fast` 标志设置为 `true`。
```
- name: Setup PHP with fail-fast
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
extensions: oci8
env:
fail-fast: true
```
## :wrench: 工具支持
这些工具可以使用 `tools` 输入参数全局设置。它接受 csv 格式的字符串。
[`backward-compatibility-check`], [`behat`], [`blackfire`], [`blackfire-player`], [`box`], [`castor`], [`churn`], [`codeception`], [`composer`], [`composer-dependency-analyser`], [`composer-normalize`], [`composer-prefetcher`], [`composer-require-checker`], [`composer-unused`], [`cs2pr`], [`deployer`], [`ecs`], [`flex`], [`grpc_php_plugin`], [`infection`], [`mago`], [`name-collision-detector`], [`parallel-lint`], [`pecl`], [`phan`], [`phing`], [`phinx`], [`phive`], [`php-config`], [`php-cs-fixer`], [`php-scoper`], [`phpcbf`], [`phpcpd`], [`phpcs`], [`phpdoc`] 或 [`phpDocumentor`], [`phpize`], [`phplint`], [`phpmd`], [`phpspec`], [`phpstan`], [`phpunit`], [`phpunit-bridge`], [`phpunit-polyfills`], [`pie`], [`pint`], [`prestissimo`], [`protoc`], [`psalm`], [`rector`], [`symfony`] 或 [`symfony-cli`], [`vapor`] 或 [`vapor-cli`], [`wp`] 或 [`wp-cli`]
- 除了上述工具外，还可以通过将任何 composer 工具或包指定为 `vendor/package`（与 Packagist 上的列表匹配）来全局设置。此格式接受与 `composer` 相同的[版本约束](https://getcomposer.org/doc/articles/versions.md#writing-version-constraints "Composer version constraints")。
```
- name: Setup PHP with tools
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
tools: vimeo/psalm
```
- 要设置特定版本的工具，请以 `tool:version` 的格式指定。
版本可以是以下格式：
- Semver（语义版本）。例如 `tool:1.2.3` 或 `tool:1.2.3-beta1`。
- 主版本号。例如 `tool:1` 或 `tool:1.x`。
- 主版本号和次版本号。例如 `tool:1.2` 或 `tool:1.2.x`。
当您仅指定主版本号或 `major.minor` 格式的版本时，将设置与输入匹配的最新补丁版本。
- 默认设置最新稳定版本的 `composer`。您可以通过指定主版本 `v1` 或 `v2`，或者 `major.minor` 或 `semver` 格式的版本来设置所需的 `composer` 版本。此外，对于 composer，还可以指定 `snapshot` 和 `preview` 以设置相应的版本。
```
- name: Setup PHP with composer v2
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
tools: composer:v1
```
- 如果您在工作流中不使用 composer，可以指定 `tools: none` 来跳过它。
```
- name: Setup PHP without composer
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
tools: none
```
- 在 Linux 和 macOS 上，默认为所有支持的 PHP 版本设置工具 `pear`、`pecl`、`phpize` 和 `php-config`。
- 当在 tools 输入中指定 `blackfire` 时，将设置最新版本的 `blackfire` cli。有关在 GitHub Actions 中使用 `blackfire`，请参阅[官方文档](https://blackfire.io/docs/integrations/ci/github-actions "Blackfire.io documentation for GitHub Actions")。
- 除非在 tools 输入中也指定了 `composer:v1`，否则工具 `prestissimo` 和 `composer-prefetcher` 将被跳过。建议弃用 `prestissimo` 并使用 `composer v2`。
- 默认情况下，除 `composer` 外，无法设置的工具会在日志中留下错误消息，执行不会中断。要更改此行为，您可以将 `fail-fast` 标志设置为 `true`。
```
- name: Setup PHP with fail-fast
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
tools: deployer
env:
fail-fast: true
```
- 默认情况下，`composer` 会阻止其所有插件。如果您使用 `tools` 输入安装 composer 插件，它将被添加到允许列表中；或者，如果您的依赖项包含 composer 插件，您可以通过设置 `COMPOSER_ALLOW_PLUGINS`（接受插件名称的 csv 字符串）来允许它们。
```
- name: Setup PHP with fail-fast
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
env:
COMPOSER_ALLOW_PLUGINS: composer/installers, composer/satis
```
```
- name: Setup PHP with composer and custom process timeout
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
env:
COMPOSER_PROCESS_TIMEOUT: 300
```
## :signal_strength: 覆盖率支持
### Xdebug
指定 `coverage: xdebug` 以使用 `Xdebug` 并禁用 `PCOV`。
在所有[支持的 PHP 版本](#tada-php-support "List of PHP versions supported on this GitHub Action")上运行。
```
- name: Setup PHP with Xdebug
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
coverage: xdebug
```
- 当您指定 `coverage: xdebug` 时，默认设置与 PHP 版本兼容的最新版 Xdebug。
- 如果您在 PHP 7.2、7.3 或 7.4 上需要 Xdebug 2.x，可以指定 `coverage: xdebug2`。
```
- name: Setup PHP with Xdebug 2.x
uses: shivammathur/setup-php@v2
with:
php-version: '7.4'
coverage: xdebug2
```
### PCOV
指定 `coverage: pcov` 以使用 `PCOV` 并禁用 `Xdebug`。
在 PHP 7.1 及更新的 PHP 版本上运行。
- 如果您的源代码目录不是 `src`、`lib` 或 `app`，请使用 `ini-values` 输入指定 `pcov.directory`。
```
- name: Setup PHP with PCOV
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
ini-values: pcov.directory=api #optional, see above for usage.
coverage: pcov
```
- PHPUnit 8.x 及更高版本开箱即支持 PCOV。
- 如果您使用的是 PHPUnit 5.x、6.x 或 7.x，则需要在执行测试之前设置 `pcov/clobber`。
```
- name: Setup PCOV
run: |
composer require pcov/clobber
vendor/bin/pcov clobber
```
### 禁用覆盖率
指定 `coverage: none` 以同时禁用 `Xdebug` 和 `PCOV`。
出于以下原因禁用覆盖率：
- 您在测试时不生成覆盖率报告。
- 您使用 `phpdbg` 运行测试。
- 您使用 `blackfire` 分析代码。
- 您在 JIT 模式下使用 PHP。有关更多详细信息，请参阅 [JIT 配置](#jit-configuration) 部分。
```
- name: Setup PHP with no coverage driver
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
coverage: none
```
## :memo: 用法
### 输入参数
#### `php-version` (可选)
- 指定您要设置的 PHP 版本。
- 接受一个 `string`。例如 `'8.5'`。
- 接受 `lowest` 以设置最低支持的 PHP 版本。
- 接受 `highest` 或 `latest` 以设置最新的稳定 PHP 版本。
- 接受 `nightly` 以设置来自 PHP master 分支的 nightly 构建。
- 接受 `pre-installed` 以设置最高版本的预装 PHP。您可以将其与 `update: true` 结合使用以更新预装的 PHP 版本。
- 接受 `d.x` 格式，其中 `d` 是主版本号。例如 `5.x`、`7.x` 和 `8.x`。
- 有关支持的 PHP 版本，请参阅 [PHP 支持](#tada-php-support)。
- 如果未指定，它将按顺序查找以下内容：
- `php-version-file` 输入（如果存在）
- `composer.lock` 文件和 `platform-overrides.php` 值
- `composer.json` 文件和 `config.platform.php` 值
- 如果 `composer.lock` 或 `composer.json` 文件位于您仓库的子目录中，请在 `COMPOSER_PROJECT_DIR` env 中指定子目录路径。
#### `php-version-file` (可选)
- 指定包含您要设置的 PHP 版本的文件。
- 接受一个 `string`。例如 `'.phpenv-version'`。
- 有关支持的 PHP 版本，请参阅 [PHP 支持](#tada-php-support)。
- 默认情况下，使用 `.php-version` 文件。
- 该文件需要包含 PHP 版本作为其内容，或者遵循 asdf `.tool-versions` 格式。
- 如果未指定且未找到默认的 `.php-version` 文件，则设置最新的稳定 PHP 版本。
#### `extensions` (可选)
- 指定您要添加或禁用的扩展。
- 接受 csv 格式的 `string`。例如 `mbstring, :opcache`。
- 接受 `none` 以禁用所有共享扩展。
- 以 `:` 为前缀的共享扩展将被禁用。
- 有关更多信息，请参阅 [PHP 扩展支持](#heavy_plus_sign-php-extension-support)。
#### `ini-file` (可选)
- 指定基础 `php.ini` 文件。
- 接受 `production`、`development` 或 `none`。
- 默认情况下，使用生产环境 `php.ini` 文件。
#### `ini-values` (可选)
- 指定您要添加到 `php.ini` 的值。
- 接受 csv 格式的 `string`。例如 `post_max_size=256M, max_execution_time=180`。
- 接受用引号包裹的包含逗号的 ini 值。例如 `xdebug.mode="develop,coverage"`。
#### `coverage` (可选)
- 指定您要设置的代码覆盖率驱动程序。
- 接受 `xdebug`、`pcov` 或 `none`。
- 有关更多信息，请参阅 [覆盖率支持](#signal_strength-coverage-support)。
#### `tools` (可选)
- 指定您要设置的工具。
- 接受 csv 格式的 `string`。例如：`phpunit, phpcs`
- 有关支持的工具，请参阅 [工具支持](#wrench-tools-support)。
#### `github-token` (可选)
- 指定用于认证的 GitHub token。
- 接受一个 `string`。
- 默认情况下，使用 GitHub Actions 提供的 `GITHUB_TOKEN` secret。
- 对于 GitHub Enterprise 用户，建议使用 Personal Access Token (PAT)。
### 输出参数
#### `php-version`
在 GitHub Actions 中，您可以为 `setup-php` 步骤分配一个 `id`，您可以在后续步骤中使用该 id 获取输出。
- 以 semver 格式提供 PHP 版本。
```
- name: Setup PHP
id: setup-php
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
- name: Print PHP version
run: echo ${{ steps.setup-php.outputs.php-version }}
```
### 标志
#### `fail-fast` (可选)
- 指定如果扩展或工具设置失败，则将工作流标记为失败。
- 这会将默认模式从优雅警告更改为快速失败。
- 默认设置为 `false`。
- 接受 `true` 和 `false`。
#### `phpts` (可选)
- 指定设置 PHP 的线程安全构建。
- 接受 `nts` 表示非线程安全，`zts` 或 `ts` 表示线程安全。
- 默认设置为 `nts`。
- 有关更多信息，请参阅 [线程安全设置](#thread-safe-setup)。
#### `update` (可选)
- 指定将 runner 上的 PHP 更新到最新的补丁版本。
- 接受 `true` 和 `false`。
- 默认设置为 `false`。
- 有关更多信息，请参阅 [强制更新设置](#force-update-setup)。
有关更多信息，请参阅下文。
### 基本设置
```
steps:
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
extensions: mbstring, intl
ini-values: post_max_size=256M, max_execution_time=180
coverage: xdebug
tools: php-cs-fixer, phpunit
```
### 矩阵设置
```
jobs:
run:
runs-on: ${{ matrix.operating-system }}
strategy:
matrix:
operating-system: ['ubuntu-latest', 'windows-latest', 'macos-latest']
php-versions: ['8.2', '8.3', '8.4', '8.5']
phpunit-versions: ['latest']
include:
- operating-system: 'ubuntu-latest'
php-versions: '8.1'
phpunit-versions: 10
steps:
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: ${{ matrix.php-versions }}
extensions: mbstring, intl
ini-values: post_max_size=256M, max_execution_time=180
coverage: xdebug
tools: php-cs-fixer, phpunit:${{ matrix.phpunit-versions }}
```
### Nightly 构建设置
- 这些 PHP 版本目前处于活跃开发中，可能包含错误和重大更改。
- 某些用户空间扩展目前可能不支持这些版本。
```
steps:
- name: Setup nightly PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.6'
extensions: mbstring
ini-values: post_max_size=256M, max_execution_time=180
coverage: xdebug
tools: php-cs-fixer, phpunit
```
### Debug 构建设置
- 默认设置不带调试符号的 PHP 生产发布构建。
- 您可以使用 `debug` 环境变量为 PHP 5.6 及更高版本设置带有调试符号的构建。
```
steps:
- name: Setup PHP with debugging symbols
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
env:
debug: true # specify true or false
```
### 线程安全设置
- 默认设置 `NTS` 版本。
```
jobs:
run:
runs-on: [ubuntu-latest, windows-latest, macos-latest]
name: Setup PHP TS
steps:
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
env:
phpts: ts # specify ts or nts
```
### 强制更新设置
- 预装的 PHP 版本默认不会更新到最新的补丁发布版本。
- 如果 Ubuntu GitHub 环境中缺少 `ppa:ondrej/php`，PHP 版本将更新到最新的补丁发布版本。
- 您可以将 `update` 环境变量指定为 `true` 以更新到最新版本。
```
- name: Setup PHP with latest versions
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
env:
update: true # specify true or false
```
### 详细模式设置
要调试任何问题，您可以使用 `verbose` 标签代替 `v2`。
```
- name: Setup PHP with logs
uses: shivammathur/setup-php@verbose
with:
php-version: '8.5'
```
### 多架构设置
- `setup-php` 在 `Ubuntu` 和 `Debian` 上支持多种架构的 `PHP 5.6` 到 `PHP 8.5`。
- 为此，您可以使用 `shivammathur/node` 镜像作为容器。这些镜像安装了兼容的 `Nodejs` 和 `PHP` 供 `setup-php` 使用。
```
jobs:
run:
runs-on: ${{ matrix.os }}
container: shivammathur/node:php-${{ matrix.php-versions }}-24.04-${{ matrix.arch }}
strategy:
matrix:
arch: ["amd64", "arm64v8"]
php-versions: [8.4, 8.5]
include:
- arch: "amd64"
os: "ubuntu-24.04"
- arch: "arm64v8"
os: "ubuntu-24.04-arm"
steps:
- name: Install PHP
uses: shivammathur/setup-php@v2
with:
php-version: ${{ matrix.php-versions }}
```
### 自托管设置
- 要设置容器化的自托管 runner，请根据您的基础操作系统参考以下指南。
- [Linux](https://github.com/shivammathur/setup-php/wiki/Dockerized-self-hosted-runner-on-Linux)
- [Windows](https://github.com/shivammathur/setup-php/wiki/Dockerized-self-hosted-runner-on-Windows)
- 要直接在宿主操作系统或虚拟机上设置 runner，请在设置自托管 runner 之前遵循此[需求指南](https://github.com/shivammathur/setup-php/wiki/Requirements-for-self-hosted-runners "Requirements guide for self-hosted runner to run setup-php")。
- 如果您的工作流使用[服务容器](https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idservices "GitHub Actions Services")，请在 Linux 主机或 Linux 虚拟机上设置 runner。GitHub Actions 不支持 Linux 上的嵌套虚拟化，因此服务将无法在 Docker 容器中工作。
建议为自托管环境指定值为 `self-hosted` 的环境变量 `runner`。
```
jobs:
run:
runs-on: self-hosted
strategy:
matrix:
php-versions: ['5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3', '8.4', '8.5']
name: PHP ${{ matrix.php-versions }}
steps:
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: ${{ matrix.php-versions }}
env:
runner: self-hosted
```
### 本地测试设置
```
jobs:
run:
runs-on: ubuntu-latest
steps:
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
```
使用 `act` 和 [`shivammathur/node`](https://github.com/shivammathur/node-docker "Docker image to run setup-php") docker 镜像在本地运行工作流。
选择与您工作流中 `runs-on` 属性匹配的镜像标签。例如，如果您在工作流中使用 `ubuntu-22.04`，请运行 `act -P ubuntu-22.04=shivammathur/node:22.04`。
```
# 对于 runs-on: ubuntu-latest
act -P ubuntu-latest=shivammathur/node:latest
# 对于 runs-on: ubuntu-24.04
act -P ubuntu-24.04=shivammathur/node:24.04
# 对于 runs-on: ubuntu-22.04
act -P ubuntu-22.04=shivammathur/node:22.04
```
### JIT 配置
- 要启用 JIT，请通过设置 `opcache.enable_cli=1` 在 cli 模式下启用 `opcache`。
- JIT 与 `Xdebug`、`PCOV` 以及其他覆盖 `zend_execute_ex` 函数的扩展冲突，因此如果添加了此类扩展，请设置 `coverage: none` 并禁用它们。
- 默认情况下，设置 `opcache.jit=1235` 和 `opcache.jit_buffer_size=256M`（在 ARM 环境中为 `opcache.jit_buffer_size=128M`），可以使用 `ini-values` 输入更改这些值。
- 有关 JIT 相关指令的详细信息，请参阅 [`PHP 官方文档`](https://www.php.net/manual/en/opcache.configuration.php#ini.opcache.jit "opcache.jit documentation")。
例如，要在 `tracing` 模式下启用缓冲区大小为 `64 MB` 的 JIT。
```
- name: Setup PHP with JIT in tracing mode
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
coverage: none
ini-values: opcache.enable_cli=1, opcache.jit=tracing, opcache.jit_buffer_size=64M
```
### 缓存扩展
您可以使用 `shivammathur/cache-extensions` 和 `action/cache` GitHub Actions 缓存 PHP 扩展。设置耗时很长的扩展在缓存后，可在下一次工作流运行中直接使用并启用。这减少了工作流执行时间。
有关详细信息，请参阅 [`shivammathur/cache-extensions`](https://github.com/shivammathur/cache-extensions "GitHub Action to cache php extensions")。
### 缓存 Composer 依赖
如果您的项目使用 composer，您可以持久化 composer 的内部缓存目录。缓存的依赖项将直接加载，而不是在安装时下载。缓存的文件可在各次检查运行中使用，并将减少工作流执行时间。
```
- name: Get composer cache directory
id: composer-cache
run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
- name: Cache dependencies
uses: actions/cache@v4
with:
path: ${{ steps.composer-cache.outputs.dir }}
key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
restore-keys: ${{ runner.os }}-composer-
- name: Install dependencies
run: composer install --prefer-dist
```
```
key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
```
- 如果您支持一定范围的 `composer` 依赖项并使用 `-lowest` 和 `prefer-stable` 选项，您可以将它们存储在矩阵中并将它们添加到键中。
```
key: ${{ runner.os }}-composer-${{ matrix.prefer }}-${{ hashFiles('**/composer.lock') }}
restore-keys: ${{ runner.os }}-composer-${{ matrix.prefer }}-
```
### GitHub Composer 认证
默认情况下，setup-php 使用为每次工作流运行生成的 `GITHUB_TOKEN` secret。如果您想改用 Personal Access Token (PAT)，可以设置 `github-token` 输入。
```
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
github-token: ${{ secrets.YOUR_PAT_TOKEN }}
```
`COMPOSER_TOKEN` 和 `GITHUB_TOKEN` 环境变量已被弃用，取而代之的是 `github-token` 输入，并将在下一个主要版本中删除。
对于 GitHub Enterprise 用户，`github-token` 输入不会默认为 `GITHUB_TOKEN` secret。因此，建议将 `github-token` 输入设置为 Personal Access Token (PAT)。
### Private Packagist 认证
如果您使用 Private Packagist 管理私有 composer 依赖项，可以设置 `PACKAGIST_TOKEN` 环境变量进行认证。
```
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
env:
PACKAGIST_TOKEN: ${{ secrets.PACKAGIST_TOKEN }}
```
### 手动 Composer 认证
除了 GitHub 或 Private Packagist 之外，如果您想对托管在其他地方的私有仓库进行认证，可以设置 `COMPOSER_AUTH_JSON` 环境变量，其中包含 json 格式的认证方法和凭据。
有关更多详细信息，请参阅 [`composer 文档`](https://getcomposer.org/doc/articles/authentication-for-private-packages.md "composer documentation") 中的认证部分。
```
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
env:
COMPOSER_AUTH_JSON: |
{
"http-basic": {
"example.org": {
"username": "${{ secrets.EXAMPLE_ORG_USERNAME }}",
"password": "${{ secrets.EXAMPLE_ORG_PASSWORD }}"
}
}
}
```
### 内联 PHP 脚本
如果您必须在工作流中运行多行 PHP 代码，无需将其保存到文件即可轻松完成。
将代码放在步骤的 run 属性中，并将 shell 指定为 `php {0}`。
```
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.5'
- name: Run PHP code
shell: php {0}
run: |
## :sparkling_heart: 支持本项目
这些公司慷慨地向 setup-php 提供产品和服务，以帮助本项目的开发。
许多用户和组织通过 [GitHub Sponsors](https://github.com/sponsors/shivammathur) 支持 setup-php。
- 如果您使用 setup-php，请考虑为项目加星并分享它。
- 如果您写博客，请分享您使用 `setup-php` 的经验。
- 如果您对赞助 setup-php 有任何疑问，请[联系我们](mailto:contact@setup-php.com)。
## :package: 依赖
- [Node.js dependencies](https://github.com/shivammathur/setup-php/network/dependencies "Node.js dependencies")
- [aaronparker/VcRedist](https://github.com/aaronparker/VcRedist "VcRedist PowerShell package")
- [mlocati/powershell-phpmanager](https://github.com/mlocati/powershell-phpmanager "Package to handle PHP on windows")
- [ppa:ondrej/php](https://launchpad.net/~ondrej/+archive/ubuntu/php "Packaging active PHP packages")
- [shivammathur/cache-extensions](https://github.com/shivammathur/cache-extensions "GitHub action to help with caching PHP extensions")
- [shivammathur/composer-cache](https://github.com/shivammathur/composer-cache "Cache composer releases")
- [shivammathur/homebrew-extensions](https://github.com/shivammathur/homebrew-extensions "Tap for PHP extensions on MacOS")
- [shivammathur/homebrew-php](https://github.com/shivammathur/homebrew-php "Tap for PHP builds on MacOS")
- [shivammathur/icu-intl](https://github.com/shivammathur/icu-intl "icu4c and php-intl builds")
- [shivammathur/php-builder](https://github.com/shivammathur/php-builder "Nightly PHP package for Ubuntu")
- [shivammathur/php-builder-windows](https://github.com/shivammathur/php-builder-windows "Nightly PHP package for Windows")
- [shivammathur/php-ubuntu](https://github.com/shivammathur/php-ubuntu "Cache stable PHP Packages for Ubuntu")
- [shivammathur/php5-darwin](https://github.com/shivammathur/php5-darwin "Scripts to set up PHP5 versions on darwin")
- [shivammathur/php5-ubuntu](https://github.com/shivammathur/php5-ubuntu "Scripts to set up PHP5 versions on ubuntu")
## :bookmark_tabs: 延伸阅读
- [关于 GitHub Actions](https://github.com/features/actions "GitHub Actions")
- [GitHub Actions 语法](https://help.github.com/en/articles/workflow-syntax-for-github-actions "GitHub Actions Syntax")
- [其他精选 Actions](https://github.com/sdras/awesome-actions "List of Awesome GitHub Actions")