> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/shivammathur/setup-php/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

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

<Note>
  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.
</Note>

### GitHub Enterprise

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

```yaml theme={null}
- 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](https://packagist.com) for private Composer dependencies, set the `PACKAGIST_TOKEN` environment variable:

```yaml theme={null}
- 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](https://getcomposer.org/doc/articles/authentication-for-private-packages.md).

```yaml theme={null}
- 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:

```yaml theme={null}
- 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:

```yaml theme={null}
- name: Setup PHP with latest patch
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.5'
  env:
    update: true
```

<Tip>
  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.
</Tip>

## 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:

```yaml theme={null}
- 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):

```yaml theme={null}
- 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:

<AccordionGroup>
  <Accordion title="Linux">
    Debug symbols are added as [debug info files](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Separate-Debug-Files.html) 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.
  </Accordion>

  <Accordion title="Windows">
    Debug symbols are added as `.pdb` files in the PHP installation directory.
  </Accordion>

  <Accordion title="macOS">
    Debug symbols are compiled directly into the binaries.
  </Accordion>
</AccordionGroup>

## JIT configuration

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

<Steps>
  <Step title="Enable opcache in CLI mode">
    JIT requires opcache to be active on the CLI. Add `opcache.enable_cli=1` to your `ini-values`.
  </Step>

  <Step title="Disable coverage drivers">
    JIT conflicts with Xdebug, PCOV, and any extension that overrides `zend_execute_ex`. Set `coverage: none` and disable any such extensions.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

```yaml theme={null}
- 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](https://www.php.net/manual/en/opcache.configuration.php#ini.opcache.jit) for the full list of JIT configuration directives.

## Versioning best practices

<AccordionGroup>
  <Accordion title="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.

    ```yaml theme={null}
    uses: shivammathur/setup-php@v2
    ```
  </Accordion>

  <Accordion title="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](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot) to receive automated PRs whenever a new version is released.

    ```yaml theme={null}
    # .github/dependabot.yml
    version: 2
    updates:
      - package-ecosystem: "github-actions"
        directory: "/"
        schedule:
          interval: "weekly"
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.

    ```yaml theme={null}
    # Avoid this
    uses: shivammathur/setup-php@main

    # Use this instead
    uses: shivammathur/setup-php@v2
    ```
  </Accordion>

  <Accordion title="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](https://github.com/shivammathur/setup-php/wiki/Switch-to-v2) to migrate.
  </Accordion>
</AccordionGroup>