Skip to main content

​
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:
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.
Debug symbols are added as .pdb files in the PHP installation directory.
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

ValueMode
disableJIT disabled
offJIT compiled but not used
onAlias for tracing
tracingTrace-based JIT (recommended for most workloads)
functionFunction-level JIT
1235Default numeric mode (tracing with optimizations)
Refer to the official PHP opcache documentation for the full list of JIT configuration directives.

​
Versioning best practices

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

Build docs developers (and LLMs) love

Get started for freeTalk to us