If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/shivammathur/homebrew-php shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1d ago
• 2 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 96% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live shivammathur/homebrew-php repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/shivammathur/homebrew-php.

What it runs against: a local clone of shivammathur/homebrew-php — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in shivammathur/homebrew-php | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of shivammathur/homebrew-php. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/shivammathur/homebrew-php.git
#   cd homebrew-php
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of shivammathur/homebrew-php and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "shivammathur/homebrew-php(\\.git)?\\b" \\
  && ok "origin remote is shivammathur/homebrew-php" \\
  || miss "origin remote is not shivammathur/homebrew-php (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Formula/php.rb" \\
  && ok "Formula/php.rb" \\
  || miss "missing critical file: Formula/php.rb"
test -f ".github/workflows/build.yml" \\
  && ok ".github/workflows/build.yml" \\
  || miss "missing critical file: .github/workflows/build.yml"
test -f ".github/scripts/sync.sh" \\
  && ok ".github/scripts/sync.sh" \\
  || miss "missing critical file: .github/scripts/sync.sh"
test -f ".github/autobump.txt" \\
  && ok ".github/autobump.txt" \\
  || miss "missing critical file: .github/autobump.txt"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/shivammathur/homebrew-php"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A Homebrew tap (custom package repository) that provides pre-compiled PHP binaries for macOS and Linux across versions 5.6 through 8.6, with variants for debug, thread-safe (ZTS), and debug+ZTS builds. It solves the problem of installing multiple PHP versions without compiling from source, offering fast setup for developers who need legacy or cutting-edge PHP alongside system defaults. Flat formula structure under Formula/ directory with parallel variants: base formula files (php.rb, php@5.6.rb through php@7.4.rb, etc.), each with debug and ZTS counterparts (php@7.4-debug.rb, php@7.4-zts.rb, php@7.4-debug-zts.rb). Aliases/ directory provides version shortcuts. Build automation lives in .github/workflows/ (build.yml, autopublish.yml, dispatch-build-bottle.yml). Ruby dominates (~891KB) with small PHP test utilities (~12KB).

macOS and Linux developers who need to test code across multiple PHP versions (5.6 legacy through 8.6 nightly builds), PHP framework developers, CI/CD pipeline maintainers, and open-source project maintainers who require parallel PHP environments without complex Docker setups.

Production-ready and actively maintained. The repo shows continuous CI/CD automation (9 workflows in .github/workflows/), regular automated builds and bottle publishing, and nightly builds for PHP 8.6. Recent activity includes autopublish, bump, and sync workflows indicating active upkeep, though exact commit timestamps aren't visible in the provided data.

Moderate risk from single-maintainer dependency (shivammathur as primary owner). Risk factors include: fragile coupling to PHP release cycles and upstream source changes, complex cross-platform compilation (x86_64 Intel macOS, arm64 Apple Silicon, Linux x86_64), and the maintenance burden of 20+ formula variants (each PHP version × 4 build types). Nightly PHP 8.6 builds may have instability.

Active nightly builds for PHP 8.6, continuous formula bumps via bump.yml workflow, automated bottle publishing via publish-commit-bottles.yml, and branch synchronization via sync-default-branches.yml. The autobump.txt file suggests automated version tracking. Focus appears to be on keeping formulae current and automating the build→test→publish pipeline.

git clone https://github.com/shivammathur/homebrew-php.git
cd homebrew-php
brew tap shivammathur/php
brew install php@8.5  # Example: install PHP 8.5

Daily commands: This is a package distribution repository, not a runnable application. To use: brew tap shivammathur/php && brew install php@8.4. To develop/test formulae locally: brew test-bot Formula/php@8.4.rb (requires Homebrew development environment and test-bot plugin).

• Formula/php.rb — Primary formula for the latest PHP version; defines the core build configuration, dependencies, and installation logic that all other versioned formulae inherit from or mirror.
• .github/workflows/build.yml — CI/CD workflow that orchestrates building and bottling PHP formulae; essential to understand how releases are automated and tested.
• .github/scripts/sync.sh — Synchronization script that maintains consistency across multiple PHP version formulae; critical for understanding how formula updates are propagated.
• .github/autobump.txt — Configuration for automated version bumping; controls which PHP versions are automatically updated and built nightly.
• README.md — Documentation and usage guide for the tap; required reading for understanding the project's purpose, supported versions, and installation instructions.
• .github/CONTRIBUTING.md — Contribution guidelines; mandatory for any contributor to understand the project's standards, testing requirements, and PR process.

Add support for a new PHP version

1. Create a new versioned formula file (e.g., Formula/php@X.Y.rb) by copying the latest Formula/php.rb and updating the version number and download URL (Formula/php@X.Y.rb)
2. Create corresponding debug variant by copying Formula/php-debug.rb and adjusting class name and version references (Formula/php@X.Y-debug.rb)
3. Create ZTS variant by copying Formula/php-zts.rb with version-specific adjustments (Formula/php@X.Y-zts.rb)
4. Update .github/autobump.txt to include the new PHP version in the automated build pipeline (.github/autobump.txt)
5. Run .github/scripts/sync.sh to propagate common patches and build option updates across all versions (.github/scripts/sync.sh)
6. Verify the formula builds locally using 'brew install --build-from-source shivammathur/php/php@X.Y' (Formula/php@X.Y.rb)

Add a new build option or patch to all PHP versions

1. Edit the base formula to add the new option (e.g., --with-newextension) and document it in the option block (Formula/php.rb)
2. Apply the same option definition to all versioned formulae (php@5.6.rb through php@8.4.rb) (Formula/php@8.4.rb)
3. Run .github/scripts/sync.sh to automatically propagate the change across all version formulae (.github/scripts/sync.sh)
4. Test the build by triggering .github/workflows/build.yml on a feature branch (.github/workflows/build.yml)

Publish a new PHP release (e.g., 8.4.1)

1. Update the version constant in the relevant formula file(s) (e.g., Formula/php@8.4.rb) and update the SHA256 checksum (Formula/php@8.4.rb)
2. Run .github/scripts/release-tools.sh to validate checksums and generate bottle URLs (.github/scripts/release-tools.sh)
3. Commit changes and push to trigger .github/workflows/build.yml which compiles and publishes bottles (.github/workflows/build.yml)
4. Monitor .github/workflows/publish-commit-bottles.yml to ensure bottles are published to GitHub Releases (.github/workflows/publish-commit-bottles.yml)

• Homebrew / Ruby DSL — Industry-standard macOS package manager; formulae define build recipes declaratively; native support for versioning, options, and dependencies.
• GitHub Actions — Automates CI/CD for building, testing, and publishing bottles; integrates tightly with GitHub releases for distribution.
• Shell scripts (.sh) — Lightweight automation for version syncing, checksums, and release management; portable across CI environments.
• GitHub Releases & pre-built bottles — Eliminates compilation time for end users; bottles are platform-specific (Intel/ARM macOS) binaries; distributes via CDN.

• Maintain separate formula files for each PHP version (php@5.6.rb, php@7.0.rb, …, php@8.4.rb) instead of a single dynamic formula

  • Why: Allows version-specific patches, dependencies, and build options; simplifies Homebrew integration; clear version pinning for users.
  • Consequence: High duplication across formula files; requires sync scripts (sync.sh) to propagate shared changes; increases maintenance burden but improves stability.

• Provide debug and ZTS (Zend Thread Safety) variants alongside standard PHP

  • Why: Developers need debugging symbols for Xdebug; multithreaded applications require ZTS variant; variants cannot coexist in a single install.
  • Consequence: 3× the number of formulae to maintain; 3× the CI/CD build time; users must choose the correct variant at install time.

• Build and publish pre-built bottles for Intel and ARM macOS architectures

  • Why: Eliminates 15–30 minute compilation on user machines; reduces load on end-user systems; faster adoption of new PHP releases.
  • Consequence: CI infrastructure cost increases; requires managing architecture-specific builds; binaries must be updated for macOS SDK changes.

• Automate version bumps and nightly builds via GitHub Actions (bump.yml, build.yml)

  • Why: Keeps tap synchronized with upstream PHP releases; catches breaking changes early; reduces manual operational overhead.
  • Consequence: Requires careful CI workflow design; build failures must be diagnosed quickly; false negatives in automated testing can ship broken bottles.

• Does not support Linux; macOS-exclusive (Homebrew runs only on macOS).
• Does not provide Windows builds or WSL packages.
• Does not include pre-installed extensions beyond core (users install extensions separately via PECL or Composer).
• Does not manage PHP configuration files (php.ini); users configure post-install.
• Does not provide Docker images or container orchestration.

Homebrew build environment required: Contributors need Homebrew installed locally to test formula changes. Bottle dependency: Pre-compiled bottles are OS/architecture-specific (Intel x86_64 vs arm64); building on one platform produces bottles invalid on another. PHP source mirrors: Formulas fetch from PHP.net; network issues or upstream URL changes break builds. Variant explosion: 4 variants per version (NTS, Debug, ZTS, Debug+ZTS) means changes must be replicated 4× or use shared patches carefully. GHA runners: Nightly PHP 8.6 builds depend on GitHub Actions availability; outages prevent publishing. macOS SDK assumptions: Some build flags target specific macOS SDK versions; universal arm64 support requires conditional compilation flags in Formula/php.rb.

• Homebrew Tap — This entire repo is a tap—a custom Homebrew package repository; understanding tap architecture (formula definitions, bottle caching, auto-update workflows) is foundational to modifying anything here
• Bottle (Homebrew Artifact) — Bottles are pre-compiled binaries cached on Bintray/GitHub Releases; they enable brew install php@8.5 to complete in seconds instead of 20min compilation—the core value proposition of this tap
• PHP Thread-Safe (ZTS) vs Non-Thread-Safe (NTS) — This tap offers both variants because ZTS adds thread-safety for SAPI (e.g., Apache mod_php) while NTS is faster for CLI; choosing wrong breaks certain extensions or degrades performance
• PHP Debug Build Symbols — Debug variants include unoptimized code and gdb symbols, making profiling/debugging possible; production uses NTS variant, debugging uses debug variant—different use cases
• GitHub Actions Workflow Dispatch — dispatch-build-bottle.yml and dispatch-rebottle.yml allow manual re-triggering of builds without code commits; critical for emergency fixes or rebuilding bottles on new GitHub runner OS versions
• Formula Inheritance & Templating — Ruby formulae share patches, configuration flags, and dependency declarations across versions; a single bug fix in build logic must be carefully propagated or risk breaking 20+ formula variants
• Cross-Platform Binary Compatibility (x86_64 vs arm64) — Bottles built on Intel macOS are incompatible with Apple Silicon (arm64); this tap must maintain separate build pipelines—key complexity driver for GitHub Actions automation

• Homebrew/homebrew-core — Official Homebrew community repository; maintains single-version PHP formula that this tap augments with multiple parallel versions
• phpenv/phpenv — Alternative PHP version manager using rbenv pattern; solves same multi-version problem but via source compilation rather than pre-built bottles
• shivammathur/setup-php — Sister GitHub Action that automates PHP installation on CI runners, often uses this tap on macOS jobs and directly benefits from new formula versions
• FriendsOfPHP/docker-php — Docker-based PHP runtime distribution; complementary approach for containerized environments where this tap wouldn't apply
• php/php-src — Upstream PHP source repository; the actual binaries this tap compiles, understanding its release cycle is essential for maintaining formula currency

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add CI workflow to validate formula syntax and Homebrew lint rules

The repo has 40+ PHP formula files (php.rb, php@5.6.rb through php@8.4.rb and their debug/zts variants) but no automated validation workflow. A new workflow should run brew audit and brew style on all Formula files to catch syntax errors, style inconsistencies, and deprecation warnings before merge. This prevents broken formulae from being published.

• [ ] Create .github/workflows/formula-lint.yml with steps to install Homebrew and run brew audit/style on Formula/ directory
• [ ] Configure the workflow to run on pull_request events and comment results on PRs
• [ ] Add matrix strategy to test multiple macOS versions if needed
• [ ] Document in CONTRIBUTING.md that formula lint checks must pass before merge

Create automated test suite for formula installation across PHP versions

The .github/workflows/test.yml exists but its scope is unclear. With 40+ formula variants, there should be explicit integration tests verifying each php@X.Y formula installs correctly and the resulting binary works. Currently, test coverage across all supported PHP versions (5.6-8.6) appears incomplete given the complexity of managing debug/ZTS variants.

• [ ] Extend .github/workflows/test.yml or create new workflow that tests installation of core formulae: php@5.6.rb, php@7.4.rb, php@8.0.rb, php@8.3.rb, and latest (php.rb)
• [ ] Add steps to verify: php --version, php -m (extensions), php-fpm --version for each variant
• [ ] Test at least one debug variant (php@8.3-debug.rb) and one ZTS variant (php@8.3-zts.rb) to validate build matrix
• [ ] Add failure notifications and logs to identify which formula/version fails

Consolidate duplicate build configuration across 40+ formula files using a shared helper module

The Formula directory contains highly repetitive files (php.rb, php@5.6.rb, php@7.0.rb... php@8.4.rb and their -debug/-zts variants). Each likely shares 80%+ identical configuration logic. Creating a shared helper module (e.g., Formula/php_helper.rb or .brew/php_formula_builder.rb) would reduce maintenance burden, ensure consistency, and make future PHP version additions faster.

• [ ] Analyze one complete formula file (e.g., Formula/php@8.3.rb) and one debug variant to extract common patterns: configure options, dependencies, install paths
• [ ] Create Formula/php_formula_helper.rb with methods for common tasks (version-specific options, extension setup, path configuration)
• [ ] Refactor Formula/php@8.3.rb to use the helper module as a proof-of-concept
• [ ] Document the helper in CONTRIBUTING.md with examples for adding new PHP versions
• [ ] In follow-up PRs, gradually refactor remaining 35+ formula files to use the helper

• Add missing test coverage for php@8.3 and php@8.4 debug variants: create spec/formula/php@8.3_spec.rb and spec/formula/php@8.4_spec.rb following the test pattern for older versions: Easy
• Document build customization options in CONTRIBUTING.md: add examples of common ./configure flags (--with-openssl, --with-curl, etc.) that users can pass via brew options, mirroring what's in Formula/php.rb comments: Easy
• Reduce formula duplication by extracting shared build logic (version detection, patch application, bottle setup) into a base module under Formula/_php_base.rb, then have php@X.Y.rb inherit from it, removing ~100 lines of copy-paste per variant: Medium

This Homebrew tap repository has a moderate security posture. The primary concerns are around CI/CD pipeline security (GitHub Actions workflows and shell scripts), potential injection vulnerabilities in automation scripts, and supply chain security for dependencies. The repository lacks visible hardcoded secrets or obvious injection vulnerabilities in the visible structure. Recommendations focus on implementing least-privilege access in workflows, auditing shell scripts for unsafe patterns, maintaining dependency lock files, and masking sensitive information in CI/CD logs. The MIT license and security policy are positive signs of security awareness.

• Medium · Potential Security Risk in Automated Build Workflows — .github/workflows/. Multiple GitHub Actions workflows (autopublish.yml, build.yml, bump.yml, dispatch-build-bottle.yml, etc.) are present without visible access controls. These workflows handle PHP builds and bottle publications, which could be targets for supply chain attacks if workflow permissions are not properly restricted. Fix: Review and implement least-privilege access controls in workflow files. Use 'permissions' keyword to explicitly set minimal required permissions. Implement OIDC token verification and restrict workflow triggers to specific branches/tags. Review branch protection rules.
• Medium · Potential Code Injection via Shell Scripts — .github/scripts/. Multiple shell scripts exist in .github/scripts/ (edit.sh, release-tools.sh, retry.sh, sync.sh) that are likely used in CI/CD pipelines. Without reviewing their content, they could be vulnerable to command injection if they process untrusted input or use unsafe parameter expansion. Fix: Audit all shell scripts for unsafe patterns: use quotes around variables, avoid eval/exec with user input, use 'set -euo pipefail', validate all inputs. Use shellcheck for static analysis.
• Medium · Third-party Dependencies in Node.js Script — .github/scripts/environment.js. A Node.js script exists at .github/scripts/environment.js which likely has npm dependencies. Without seeing package.json or lock files, there's a risk of vulnerable transitive dependencies that could be exploited during CI/CD execution. Fix: Ensure package.json and package-lock.json (or yarn.lock) are present and committed. Regularly run 'npm audit' or 'yarn audit'. Use Dependabot or Snyk to automatically scan for vulnerabilities.
• Low · PHP Source Code Execution Risk — Scripts/pgo_script.php. The Scripts/pgo_script.php file is a PHP script used in performance optimization. If this script processes user input or external data without proper validation, it could be vulnerable to injection attacks or RCE. Fix: Review pgo_script.php for input validation and sanitization. Ensure all external inputs are validated and escaped. Run security linters like Psalm or PHPStan with security rules enabled.
• Low · Missing Dependency Lock Files Visibility — Root directory and .github/scripts/. The file structure provided does not show lock files for dependencies (Gemfile.lock, package-lock.json, composer.lock if applicable). This could indicate missing dependency pinning in CI/CD pipelines, increasing supply chain risk. Fix: Ensure all dependency manifests have corresponding lock files committed to version control. Document dependency management strategy in CONTRIBUTING.md.
• Low · Potential Information Disclosure via Public GitHub Actions — .github/workflows/. Multiple GitHub Actions workflows may log sensitive information (build paths, environment variables, credentials) that could be exposed in public workflow logs or artifacts. Fix: Mask sensitive values in logs using GitHub's 'add-mask' command. Avoid logging secrets. Use GitHub Secrets for sensitive credentials and never print them. Review log retention policies.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.