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/nicoverbruggen/phpmon 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.

WAIT — Solo project — review before adopting

• Last commit 6d ago
• MIT licensed
• Tests present
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ No CI workflows detected

_{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 nicoverbruggen/phpmon repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/nicoverbruggen/phpmon.

What it runs against: a local clone of nicoverbruggen/phpmon — 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 nicoverbruggen/phpmon | 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 ≤ 36 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of nicoverbruggen/phpmon. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/nicoverbruggen/phpmon.git
#   cd phpmon
#
# 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 nicoverbruggen/phpmon and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "nicoverbruggen/phpmon(\\.git)?\\b" \\
  && ok "origin remote is nicoverbruggen/phpmon" \\
  || miss "origin remote is not nicoverbruggen/phpmon (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 "phpmon/AppDelegate.swift" \\
  && ok "phpmon/AppDelegate.swift" \\
  || miss "missing critical file: phpmon/AppDelegate.swift"
test -f "PHP Monitor.xcodeproj/project.pbxproj" \\
  && ok "PHP Monitor.xcodeproj/project.pbxproj" \\
  || miss "missing critical file: PHP Monitor.xcodeproj/project.pbxproj"
test -f ".swiftlint.yml" \\
  && ok ".swiftlint.yml" \\
  || miss "missing critical file: .swiftlint.yml"
test -f "DEVELOPER.md" \\
  && ok "DEVELOPER.md" \\
  || miss "missing critical file: DEVELOPER.md"
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 36 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~6d)"
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/nicoverbruggen/phpmon"
  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).

PHP Monitor is a native macOS menu bar application written in Swift that displays and manages the active PHP version in your status bar. It provides tight integration with Laravel Valet to enable global and per-site PHP version switching, quick access to PHP config files, extension management, and service restarts—solving the friction of managing multiple PHP installations on macOS for local development. Single Xcode project (PHP Monitor.xcodeproj) with four build schemes (PHP Monitor, PHP Monitor EAP, PHP Monitor Self-Updater, Unit Tests). Main app code lives in phpmon/ directory with asset bundling (AppIcon.icon, Assets.xcassets). Separate phpmon-updater/ target handles auto-updates. Uses SwiftUI/AppKit for native macOS menu bar UI.

macOS developers (primarily Laravel/PHP developers) who use Homebrew-managed PHP and Laravel Valet for local development, and need to quickly switch between PHP versions globally or per-project without terminal commands.

Actively maintained and production-ready. The repo shows significant investment (926KB Swift code), uses SwiftLint for code quality, has structured issue templates and PR processes (see .github/), multiple release schemes (PHP Monitor EAP, Self-Updater), and appears to have regular updates based on the asset refresh (icon-2025.svg). The presence of SECURITY.md with version support info indicates mature security practices.

Low-to-moderate risk: single maintainer (nicoverbruggen), macOS-only (no cross-platform testing), and tight coupling to specific Homebrew paths and Laravel Valet versions (v2–v4). The app requires admin privileges for certificate generation and core features depend on external tools (Homebrew, Valet) being installed correctly. No visible test suite in file list (no Tests/ directory shown) is a gap.

Project has active maintenance tasks (see @tasks/ directory with changelog.md, new_translations.md, pretag.md) suggesting organized release workflow. Recent icon work (icon-2025.svg) and EAP scheme indicate active feature development. Structured pull request and contribution templates in .github/ indicate ongoing community engagement.

git clone https://github.com/nicoverbruggen/phpmon.git
cd phpmon
open 'PHP Monitor.xcodeproj'

Then in Xcode: select 'PHP Monitor' scheme, set your Team ID in signing, and press Cmd+R to build and run. Requires Xcode 14+ with Swift 5.9+.

Daily commands:

1. Open PHP Monitor.xcodeproj in Xcode. 2. Select 'PHP Monitor' scheme from top-left dropdown. 3. Press Cmd+R to build and run on your Mac. For testing: select 'Unit Tests' scheme and press Cmd+U.

• phpmon/AppDelegate.swift — Main application entry point and lifecycle manager for the macOS menu bar app; handles initialization and event routing.
• PHP Monitor.xcodeproj/project.pbxproj — Xcode project configuration defining build targets, schemes, and dependencies; essential for understanding the build process.
• .swiftlint.yml — SwiftLint configuration defining code style standards that all contributors must follow to maintain consistency.
• DEVELOPER.md — Developer setup and contribution guide explaining how to build, test, and extend the application.
• README.md — Project overview describing PHP Monitor's purpose, architecture, and Laravel Valet integration requirements.
• .github/contributing.md — Contribution guidelines and community standards for submitting pull requests and reporting issues.

• AppDelegate (Swift, NSApplication, NSStatusBar) — Manages application lifecycle, menu bar setup, event handling, and routes user actions to appropriate services.
  • Failure mode: App hangs or crashes if event loop blocked by long-running shell commands; requires async/background execution.
• Shell Command Executor (Foundation Process, shell escaping) — Wraps Process/Task to execute PHP, Valet, and system binaries; parses output and returns structured data.
  • Failure mode: Command timeouts, permission errors, or changed CLI output break detection logic; requires error handling and version checks.
• Laravel Valet Integration Layer (Shell execution, valet CLI parsing) — Discovers Valet installation, queries domain proxies, switches PHP versions, and manages site linking/unlinking.
  • Failure mode: Valet missing, outdated, or misconfigured causes feature loss; gracefully degrades if Valet unavailable.
• Menu Bar Renderer (NSMenu, NSMenuItem, custom NSView) — Updates status icon, menu items, and text dynamically based on current PHP state and Valet domains.
  • Failure mode: Menu becomes stale or unresponsive if refresh cycle blocks main thread; requires off-main-thread state updates.
• Self-Updater (phpmon-updater) (Swift, URLSession, file operations) — Standalone executable that downloads, verifies, and replaces the main app binary; runs with elevated privileges.
  • Failure mode: Corrupted download, permission denial, or verification failure leaves app in broken state; critical for graceful rollback.

• User menu bar click → AppDelegate event handler — NSStatusBar triggers menu opening or action callback
• AppDelegate → Shell Command Executor — Requests PHP version, Valet status, or extension list
• Shell executor → PHP binary / Valet CLI — Spawns subprocess to run php -v, valet proxies, valet switch, etc.
• CLI output → AppDelegate state — Parse version string, domain list, or extension status into app model
• Updated state → Menu Bar UI — Re-render status icon color, version text, and menu items to reflect current system state
• User selects PHP version → undefined — undefined

Add a New Menu Bar Action

1. Create a new menu item class conforming to macOS NSMenuItem patterns in the UI layer (phpmon/AppDelegate.swift)
2. Implement the action handler that calls the appropriate service (PHP management, Valet, etc.) (phpmon/AppDelegate.swift)
3. Register the menu item in the status bar menu setup method (phpmon/AppDelegate.swift)

Add Support for a New PHP Extension

1. Extend the extension detection logic to parse the new extension from php -m output (phpmon/AppDelegate.swift)
2. Add installation logic via pecl or other package manager (phpmon/AppDelegate.swift)
3. Update the menu to display the extension status with appropriate icon from Assets (phpmon/Assets.xcassets/Checkmark.imageset)

Integrate a New Third-Party Tool

1. Create a shell command wrapper to interact with the tool's CLI (phpmon/AppDelegate.swift)
2. Parse the tool's output and update application state (phpmon/AppDelegate.swift)
3. Add a menu item and status indicator for the tool (similar to Valet integration) (phpmon/AppDelegate.swift)

• Swift + SwiftUI — Native macOS app framework providing direct system integration, menu bar support, and native UI polish required for a status bar utility.
• Shell command execution (Process/Task) — PHP Monitor needs to detect PHP versions, manage Valet, and execute system commands; subprocess execution is the standard way to interact with CLI tools.
• Laravel Valet CLI integration — Core requirement to manage PHP versions globally, switch between installations, and control local domain proxying on macOS.
• Xcode & xcodeproj — Required for building native macOS applications; project configuration manages code signing, entitlements, and multi-target builds.

• macOS-only (menu bar app vs cross-platform CLI)

  • Why: Menu bar provides seamless, always-visible access to PHP status without opening terminals or windows; native macOS integration is superior for developer workflow.
  • Consequence: Users on Linux/Windows cannot use PHP Monitor; trade-off is intentional for focused UX on Mac ecosystem.

• Strong Valet dependency rather than standalone PHP manager

  • Why: Valet is the dominant macOS PHP dev environment (part of Laravel ecosystem); tight integration reduces duplication and provides best UX for primary use case.
  • Consequence: Limited functionality without Valet; users without Valet cannot access version switching or domain management features.

• Shell-based system interaction vs native APIs

  • Why: PHP and Valet expose functionality via CLI; shell execution avoids reverse-engineering or brittle binary parsing.
  • Consequence: Subprocess overhead (~50–100ms per check) and potential fragility if command output changes; acceptable for periodic menu refreshes.

• Dual-build scheme (EAP + stable) + self-updater

  • Why: Allows parallel release channels and automatic updates without App Store submission delays.
  • Consequence: Increased build complexity and updater maintenance burden; separate executable for updater required.

• Does not provide cross-platform support (Linux, Windows); macOS-only menu bar app.
• Does not replace Laravel Valet; acts as a convenience layer on top of Valet CLI.
• Does not manage non-PHP development tools or runtimes (e.g., Node.js, Python).
• Does not provide GUI for advanced PHP configuration beyond extension installation; CLI-centric.
• Does not work without Homebrew-installed PHP or Valet; assumes standard macOS dev environment.

1. Homebrew path assumption: app expects Homebrew in /usr/local/homebrew or /opt/homebrew; custom Homebrew installations will break core functionality. 2. Admin privileges required for some features (e.g., certificate generation via valet trust)—testing those paths requires sudo or admin setup. 3. Laravel Valet version sensitivity: app supports v2–v4 but features vary per version; you must test against the specific Valet version. 4. Swift version lock: project likely requires Swift 5.9+ and Xcode 14+; older toolchains will fail to build. 5. No visible dependency manager (SPM package list); dependencies are likely bundled in Xcode project or system frameworks.

• macOS Menu Bar Applications (Status Bar Apps) — PHP Monitor is fundamentally a menu bar app; understanding the AppKit/SwiftUI menu bar lifecycle, NSStatusBar, and popover presentation is core to modifying the UI and interaction model
• Shell Script Execution & Process Spawning — The app heavily relies on invoking Homebrew and Laravel Valet CLI commands; understanding Process (Foundation), stdout/stderr capture, and shell escaping is critical to adding new system integrations or fixing command execution bugs
• Privilege Escalation & Admin Prompts — Features like valet trust (certificate generation) require admin/sudo privileges; understanding how to safely request and execute privileged operations on macOS (AuthorizationServices or osascript) is essential for secure feature implementation
• Per-Site PHP Version Isolation (Valet Site Isolation) — A key phpmon feature is per-site PHP version switching via Valet's isolate command; understanding how Valet's site-level PHP configuration works is necessary to implement or debug this functionality
• Homebrew Package Discovery & Version Enumeration — The app scans for installed PHP versions and extensions via Homebrew; understanding Homebrew's cellar structure (/usr/local/Cellar or /opt/homebrew/Cellar), linked binaries, and formula introspection is essential to adding new PHP/extension detection logic
• Xcode Build Schemes & Multi-Target Projects — The project has separate schemes for main app, EAP (Early Access Program), and Self-Updater; understanding how Xcode manages build targets, scheme dependencies, and code signing per target is important for releases and CI/CD changes
• macOS Signed Code & Auto-Update Security — The phpmon-updater/ target handles app updates; understanding code signing, notarization, and secure update verification (likely Sparkle-based) is crucial to maintaining security and preventing update-related vulnerabilities

• laravel/valet — PHP Monitor is tightly integrated with Valet; understanding Valet's PHP version management and site isolation is essential to understanding phpmon's core features
• homebrew/homebrew-core — PHP Monitor relies on Homebrew's php formula and system paths to discover PHP installations; familiarity with Homebrew formulae helps understand how phpmon locates and manages PHP versions
• shivammathur/homebrew-php — Alternative PHP tap for Homebrew with additional PHP versions; some users may use this instead of homebrew-core's php, and phpmon may need to account for both sources
• nicoverbruggen/phpmon-docs — Likely companion repo containing user-facing documentation and FAQs separate from the main codebase (if it exists; mentioned in README)
• Sparkle-Project/Sparkle — Standard macOS app auto-update framework; phpmon-updater likely uses or mimics Sparkle's approach for secure delta updates

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 GitHub Actions workflow for Swift build verification on PRs

The repo has multiple Xcode schemes (PHP Monitor, PHP Monitor EAP, PHP Monitor Self-Updater, Unit Tests) defined in .xcschemes but no GitHub Actions CI pipeline to verify builds pass before merge. This is critical for a macOS native app where build failures can be caught early. The DEVELOPER.md likely documents build steps that could be automated.

• [ ] Create .github/workflows/build.yml to run xcodebuild for all schemes in PHP Monitor.xcodeproj
• [ ] Add matrix strategy to test against multiple macOS versions (12, 13, 14)
• [ ] Run the 'Unit Tests' scheme to ensure test suite passes on every PR
• [ ] Reference DEVELOPER.md build instructions to ensure CI steps match documented process

Add comprehensive localization test suite for translation keys

The repo has @tasks/new_translations.md task file indicating active translation management. With multiple language support, there's likely risk of missing translation keys, untranslated strings, or broken key references. No obvious test file exists to validate localization completeness across supported languages.

• [ ] Audit all .strings or .stringsdict files in phpmon/Assets and phpmon-updater/Assets directories
• [ ] Create a Unit Test target (or extend existing one) that loads each language bundle
• [ ] Verify all UI strings reference valid localization keys with no missing translations
• [ ] Add test to catch hardcoded strings that should be localized (grep Swift source files)

Document and add tests for Laravel Valet integration points

README explicitly states 'you need to have [Laravel Valet] set up if you want to use all of the functionality' but there's no documented API contract or integration tests. The app interacts with Valet in specific ways (finding PHP installations, config files, switching versions). This integration should have explicit tests and documentation of expected Valet behavior.

• [ ] Create VALET_INTEGRATION.md documenting the specific Valet commands/files phpmon depends on
• [ ] Add integration tests in Unit Tests scheme that mock or verify Valet shell command execution
• [ ] Document the expected directory structure and config file locations that phpmon reads from Valet
• [ ] Add error handling tests for scenarios where Valet is not installed or misconfigured

• Add unit tests for shell script execution paths: The repo has a 'Unit Tests' scheme but no visible Tests/ folder in the file list. A contributor could create XCTest files to verify that shell invocations for Homebrew and Valet commands are properly escaped and executed, reducing bugs in system interaction.
• Expand documentation for first-time setup in DEVELOPER.md: Currently, README requires Laravel Valet and Homebrew but DEVELOPER.md may lack step-by-step macOS system setup (Xcode command-line tools, Homebrew install, PHP version management). A junior could add a checklist and troubleshooting section.
• Internationalization for new locales: The @tasks/new_translations.md file suggests translation is an ongoing task. A contributor could extract hardcoded strings from Swift files and add entries to localization files (likely .strings files) for a new language (French, German, Spanish, etc.), leveraging the existing translation infrastructure.

PHP Monitor is a native macOS application with a reasonable security baseline. The primary concerns are around the auto-update mechanism (which requires careful implementation), potential shell command execution risks when managing PHP installations, and insufficient documentation of security practices. The codebase appears well-organized with a dedicated SECURITY.md file indicating security awareness. No obvious hardcoded credentials, SQL injection risks, or infrastructure misconfigurations were detected from the file structure provided. The application's local-only operation (menu bar utility) and tight integration with Valet limit exposure to remote attacks. Recommended improvements include: (1) comprehensive audit of the update system, (2) detailed documentation of privilege handling, (3) input validation review for all shell commands, and (4) clarification of code signing/notarization practices.

• Medium · Potential insecure auto-update mechanism — phpmon-updater/ directory and PHP Monitor.xcodeproj build targets. The presence of 'phpmon-updater' as a separate build target suggests an auto-update mechanism. Without examining the update implementation details, auto-update systems can be vulnerable to MITM attacks, unsigned update verification failures, or unsafe extraction of update packages. Fix: Ensure that: (1) all updates are signed with valid certificates, (2) update URLs use HTTPS with certificate pinning, (3) downloaded binaries are cryptographically verified before execution, (4) update process runs with minimal privileges, and (5) conduct a security audit of the update mechanism
• Low · Missing code signing documentation — DEVELOPER.md and project configuration. While the app uses Apple's native build system, there is no explicit documentation regarding code signing and notarization requirements. This is important for macOS apps to ensure they haven't been tampered with and meet Apple's security requirements. Fix: Document the code signing and notarization process in DEVELOPER.md, including requirements for valid Apple Developer certificates, notarization with Apple, and validation of signatures
• Low · Potential privilege escalation through shell execution — phpmon/ (Swift codebase - specific files not provided). As a macOS utility that manages PHP installations and interacts with Laravel Valet (which may require elevated permissions), the app likely executes shell commands. Without careful input validation and proper privilege separation, this could lead to command injection or privilege escalation. Fix: Review all shell command execution points to ensure: (1) input is properly escaped/parameterized, (2) commands use absolute paths to prevent PATH-based attacks, (3) minimal necessary privileges are requested, (4) user confirmation is required for privileged operations
• Low · No visible dependency management file — Project root (Package.swift, Podfile, or Cartfile not shown). The codebase shows Swift/Xcode project structure but no Package.swift or CocoaPods dependency file was provided in the analysis. This makes it difficult to assess third-party dependency vulnerabilities. Fix: Maintain an up-to-date dependency manifest and regularly audit dependencies using tools like 'swift package audit' or Dependabot integration. Document all external dependencies with their purposes and security considerations

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.