PHP - Composer (Beta)

Beta. Composer support is actively maintained but may have rough edges. Report issues at github.com/rootio-avr/rootio_patcher.

Root Library Catalog supports PHP projects managed with Composer. Patched packages are published to pkg.root.io/composer/ as a Composer repository and consumed via the Root Patcher CLI, which rewrites your composer.json and runs composer update to apply the patches.

Prerequisites

The Root Patcher CLI (rootio_patcher) is required to analyze your dependencies and apply patches. Install it before configuring your project.

# macOS (Apple Silicon)
curl -sL https://github.com/rootio-avr/rootio_patcher/releases/latest/download/rootio_patcher_darwin_arm64.tar.gz | tar xz
chmod +x rootio_patcher && sudo mv rootio_patcher /usr/local/bin/

# Linux (x86_64)
curl -sL https://github.com/rootio-avr/rootio_patcher/releases/latest/download/rootio_patcher_linux_x86_64.tar.gz | tar xz
chmod +x rootio_patcher && sudo mv rootio_patcher /usr/local/bin/

For macOS Intel and Windows, see the full installation instructions. Then set your API key:

export ROOTIO_API_KEY="your-api-key-here"

composer.lock must exist before running the patcher. If it is missing, run composer install first. The patcher reads exact resolved versions from the lock file to determine what is installed.

How Composer patching works

The patcher uses pre-install patching:

Reads exact resolved versions from composer.lock
Queries Root’s API for available patches
Updates composer.json — direct dependencies have their version constraint updated in place; transitive dependencies are explicitly pinned in require
Adds the Root Composer repository entry (pkg.root.io/composer/) permanently to composer.json
Automatically runs composer update --with-dependencies <affected-packages> to download patched versions and update composer.lock

The vendor/ directory is fully populated after the patcher runs — no separate install step needed.

Platform requirements (php, ext-*) are not patched — they are managed by the OS, not Composer.

Authentication

The patcher passes credentials to Composer via the COMPOSER_AUTH environment variable. Set it before running the patcher with --dry-run=false:

export COMPOSER_AUTH='{"http-basic":{"pkg.root.io":{"username":"","password":"your-api-key"}}}'

Subsequent composer install runs also require COMPOSER_AUTH. Once the patcher adds the pkg.root.io repository to composer.json, every future composer install in CI/CD needs this variable set so Composer can authenticate to fetch patched packages.

Patching your project

1. Preview available patches

rootio_patcher composer remediate

Example output:

=== DRY-RUN MODE ===
The following packages in composer.json would be updated:

1. Package: vendor/package
   Current version: 2.1.0
   Patched version: 2.1.4
   CVEs Fixed: [CVE-2024-12345]

To apply these patches:
  Run: rootio_patcher composer remediate --dry-run=false
  Then ensure COMPOSER_AUTH is configured in your CI/CD environment

2. Apply patches

export COMPOSER_AUTH='{"http-basic":{"pkg.root.io":{"username":"","password":"your-api-key"}}}'
rootio_patcher composer remediate --dry-run=false

The patcher updates composer.json and composer.lock and populates vendor/.

3. Commit the changes

git add composer.json composer.lock
git commit -m "Apply Root patches for Composer packages"

Flags:

Flag	Default	Description
`--dry-run`	`true`	Preview changes without applying
`--file`	`composer.json`	Path to the target `composer.json`
`--ignore`	-	Exclude `package@version` from patching (repeatable, comma-separated). Merged with a `.rootioignore` file. See Ignoring Packages.

CI/CD Configuration

GitHub Actions

- name: Set up PHP
  uses: shivammathur/setup-php@v2
  with:
    php-version: '8.2'

- name: Install dependencies
  run: composer install --no-interaction

- name: Patch vulnerabilities
  env:
    ROOTIO_API_KEY: ${{ secrets.ROOTIO_API_KEY }}
    COMPOSER_AUTH: '{"http-basic":{"pkg.root.io":{"username":"","password":"${{ secrets.ROOTIO_API_KEY }}"}}}'
  run: rootio_patcher composer remediate --dry-run=false

- name: Commit changes
  run: |
    git config user.name "Root.io Patcher"
    git config user.email "bot@root.io"
    git add composer.json composer.lock
    git commit -m "chore: apply Root.io security patches" || echo "No changes"
    git push

For subsequent composer install runs in other jobs or pipelines, set COMPOSER_AUTH as a repository secret and inject it into any step that runs Composer:

- name: Install dependencies
  env:
    COMPOSER_AUTH: ${{ secrets.COMPOSER_AUTH }}
  run: composer install --no-interaction

GitLab CI

patch:
  script:
    - composer install --no-interaction
    - rootio_patcher composer remediate --dry-run=false
  variables:
    ROOTIO_API_KEY: $ROOTIO_API_KEY
    COMPOSER_AUTH: '{"http-basic":{"pkg.root.io":{"username":"","password":"$ROOTIO_API_KEY"}}}'

Docker

FROM php:8.2-cli

COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

WORKDIR /app
COPY composer.json composer.lock ./

RUN curl -sL https://github.com/rootio-avr/rootio_patcher/releases/latest/download/rootio_patcher_linux_x86_64.tar.gz | tar xz && \
    chmod +x rootio_patcher && \
    mv rootio_patcher /usr/local/bin/

ARG ROOTIO_API_KEY
ENV ROOTIO_API_KEY=${ROOTIO_API_KEY}
ENV COMPOSER_AUTH='{"http-basic":{"pkg.root.io":{"username":"","password":"'"${ROOTIO_API_KEY}"'"}}}'

RUN composer install --no-interaction && \
    rootio_patcher composer remediate --dry-run=false

COPY . .
CMD ["php", "index.php"]

Subsequent composer install steps (e.g. in a multi-stage build) require COMPOSER_AUTH to authenticate with pkg.root.io.

Troubleshooting

Issue	Solution
`composer.lock not found`	Run `composer install` first to generate the lock file, then re-run the patcher
`file not found: composer.json`	Run from your project root, or use `--file=./path/to/composer.json`
`composer update` fails after patching	Ensure `COMPOSER_AUTH` is set with valid credentials for `pkg.root.io`
Future `composer install` fails in CI/CD	Add `COMPOSER_AUTH` to your CI/CD secrets — the `pkg.root.io` repository entry is permanent in `composer.json`
`401 Unauthorized`	Verify your API key is valid and that `COMPOSER_AUTH` is correctly formatted

​Prerequisites

​How Composer patching works

​Authentication

​Patching your project

​1. Preview available patches

​2. Apply patches

​3. Commit the changes

​CI/CD Configuration

​GitHub Actions

​GitLab CI

​Docker

​Troubleshooting

Prerequisites

How Composer patching works

Authentication

Patching your project

1. Preview available patches

2. Apply patches

3. Commit the changes

CI/CD Configuration

GitHub Actions

GitLab CI

Docker

Troubleshooting