Advanced Usage

Composer authentication, inline PHP scripts, JIT configuration, debug builds, and versioning best practices for setup-php.

Composer authentication

GitHub Composer authentication

By default, setup-php uses the GITHUB_TOKEN secret automatically provided by GitHub Actions to authenticate Composer requests to GitHub package sources. To use a Personal Access Token (PAT) instead, pass it via the github-token input:

- name: Setup PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    github-token: ${{ secrets.YOUR_PAT_TOKEN }}

The COMPOSER_TOKEN and GITHUB_TOKEN environment variables have been deprecated in favour of the github-token input and will be removed in the next major version.

GitHub Enterprise

For GitHub Enterprise users, github-token does not default to GITHUB_TOKEN. Use a PAT explicitly:

- name: Setup PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
    github-token: ${{ secrets.GHE_PAT_TOKEN }}

Private Packagist authentication

If your project uses Private Packagist for private Composer dependencies, set the PACKAGIST_TOKEN environment variable:

- name: Setup PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
  env:
    PACKAGIST_TOKEN: ${{ secrets.PACKAGIST_TOKEN }}

Manual Composer authentication

For private repositories hosted outside GitHub or Private Packagist, set COMPOSER_AUTH_JSON with the authentication credentials in JSON format. The structure follows the Composer authentication 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 }}"
          }
        }
      }

Inline PHP scripts

You can run PHP code directly in a workflow step without saving it to a file. Set shell: php {0} on the step and write your PHP code in the run block:

- name: Setup PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'

- name: Run PHP code
  shell: php {0}
  run: |
    <?php
    $welcome = "Hello, world";
    echo $welcome;

This is useful for multi-line PHP scripts that perform setup or validation tasks inline in your workflow without needing a dedicated script file.

Force update setup

Pre-installed PHP versions are not updated to their latest patch release by default. Set the update environment variable to true to force an update to the latest patch version:

- name: Setup PHP with latest patch
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
  env:
    update: true

If ppa:ondrej/php is missing from the Ubuntu GitHub runner environment, setup-php automatically updates PHP to the latest patch release regardless of this flag.

Verbose debugging

When troubleshooting a workflow, switch from the v2 tag to the verbose tag. The verbose tag outputs all setup logs and is kept in sync with the latest releases:

- name: Setup PHP with verbose logs
  uses: shivammathur/setup-php@verbose
  with:
    php-version: '8.5'

Switch back to v2 once your issue is resolved to keep your workflow logs clean.

Debug builds

Production PHP builds do not include debugging symbols by default. Set the debug environment variable to true to install a build with debugging symbols (supported on PHP 5.6 and above):

- name: Setup PHP with debugging symbols
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
  env:
    debug: true

Debug symbol locations vary by OS:

Linux

Debug symbols are added as debug info files in the /usr/lib/debug/.build-id directory. These files match the build-id in the ELF section of the PHP binaries, and tools like gdb resolve symbols automatically.

Windows

Debug symbols are added as .pdb files in the PHP installation directory.

macOS

Debug symbols are compiled directly into the binaries.

JIT configuration

Just-in-time compilation is available on PHP 8.0 and above. To enable it:

1. Enable opcache in CLI mode

   JIT requires opcache to be active on the CLI. Add opcache.enable_cli=1 to your ini-values.

2. Disable coverage drivers

   JIT conflicts with Xdebug, PCOV, and any extension that overrides zend_execute_ex. Set coverage: none and disable any such extensions.

3. Configure JIT mode and buffer size

   The defaults are opcache.jit=1235 and opcache.jit_buffer_size=256M (128M on ARM). Override them via ini-values to suit your workload.

Example enabling JIT in tracing mode with a 64 MB buffer:

- 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

JIT mode reference

Value	Mode
disable	JIT disabled
off	JIT compiled but not used
on	Alias for tracing
tracing	Trace-based JIT (recommended for most workloads)
function	Function-level JIT
1235	Default numeric mode (tracing with optimizations)

Refer to the official PHP opcache documentation for the full list of JIT configuration directives.

Versioning best practices

Use the v2 rolling tag

The v2 tag is a rolling tag kept in sync with the latest minor and patch releases. Using it means you automatically receive bug fixes, security patches, new PHP version support, and new features without updating your workflow file.

uses: shivammathur/setup-php@v2

Use Dependabot to track semantic versions

If you prefer pinned semantic release versions (for example, v2.33.0) over the rolling v2 tag, enable Dependabot for GitHub Actions to receive automated PRs whenever a new version is released.

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

Avoid commit SHAs unless you have automated tooling

Pinning to a commit SHA provides the strongest supply-chain guarantee, but SHA pins go stale silently. Only use commit SHAs if you have tooling in place to update them with each release.

Never use the main branch

Do not reference the main branch as your version. The main branch may contain in-progress breaking changes and does not guarantee a stable API.

# Avoid this
uses: shivammathur/setup-php@main

# Use this instead
uses: shivammathur/setup-php@v2

Migrating from v1

The v1 tag is no longer supported. If your workflow still references setup-php@v1 or a 1.x.y version, follow the switch to v2 guide to migrate.