Download the PHP package gerard/claude-code-hooks without Composer

🤔 What is this?

Claude Code — Anthropic's official CLI for Claude — emits hook events at every interesting moment of a coding session: a tool is about to run, the user submitted a prompt, a session is starting, the context just got compacted, and so on. There are 29 documented events today, each with its own JSON wire shape and decision protocol.

If you want to observe, intercept, redirect, or veto what Claude Code does — from a PHP backend, a CLI, or a Symfony bundle — this package gives you a first-class SDK for it:

• 📥 Decode any inbound hook payload into an immutable typed event. No more array_key_exists() ladders.
• 📤 Encode valid response payloads with fluent builders that match the documented decision shapes byte-for-byte.
• 🔍 Inspect Claude Code's runtime state: stream transcripts, scan installed plugins / skills / agents / MCP servers, compute Sonnet pricing.
• 🛡️ Lint your settings.json so misconfigured hooks fail in dev, not in production.
• 📡 Stay current — a daily CI job diffs the live Anthropic doc and opens a GitHub issue the moment a new event ships.

It's the layer you'd otherwise have to reinvent in every project that touches Claude Code from PHP.

✨ Highlights

🚀 Quick start — 60 seconds

The whole loop is decode → match → respond:

That's it. No manual JSON spelunking, no copy-paste from the docs, no hand-rolled response builders.

📦 Installation

Requirements

• PHP 8.3+
• Extensions: ext-json, ext-mbstring

Runtime dependencies

• psr/log ^3.0
• symfony/http-client ^7.0 (used by AnthropicSpecExtractor)
• symfony/yaml ^7.0 (used by the plugin / skill / agent scanners)

📚 Cookbook

🎯 Intercepting a tool call

PreToolUseEvent::toolInput is typed against the ToolInput interface — pattern-match on the concrete class to read the typed properties.

The four documented decisions — allow, deny, ask, defer — are static factories on PreToolUseResponse. Want to mutate the input before letting it through? ->withUpdatedInput($newInput).

📜 Streaming a transcript

TranscriptReader is a Generator — it never loads the file into memory.

💰 Computing usage cost

Money is closed under addition; sum the cost of every assistant turn in a transcript by chaining ->add().

🪜 Resolving multi-source settings.json

The resolver honours the full documented precedence chain and applies the allowManagedHooksOnly policy filter before merging.

🛠️ Building a settings.json fragment

Note: withHeader('Authorization', …) only accepts ${VAR} placeholders — this layer never holds real secrets. Resolution happens in the future Symfony bundle.

🔎 Linting a config

📤 Producing a structured response

Every response builder is immutable: with*() returns a clone, toArray() ships.

🗂️ All supported events (29)

Anything Anthropic ships after the pinned snapshot date surfaces as UnknownHookEvent — your code keeps running, the daily doc-drift job opens an issue, the next release adds the typed DTO.

🛠️ All supported tool inputs (12 + fallback)

🔌 Wire shapes — three quick references

The wire field names below match the actual shape Claude Code emits, verified against a real-corpus sample of 4 089 events.

💡 One JSON entry point. JsonDecoder::decode() is the only sanctioned JSON parser in the package. It enforces JSON_THROW_ON_ERROR and a depth cap of 64. Raw json_decode() calls in src/ are forbidden by CI.

📡 Staying in sync with the Anthropic spec

Two CLI binaries ship with the package and back the daily doc-drift.yml workflow:

Reblessing the snapshot when Anthropic ships a new event:

Then bump AnthropicSpecExtractor::SNAPSHOT_VERSION to the new date. AnthropicSpecExtractorLiveShapeTest asserts the SHA-256 sidecar still matches.

🧪 Quality bar

This is a security- and observability-critical package. The bar is set accordingly:

• PHPStan level max + phpstan-strict-rules + phpstan-deprecation-rules + phpstan-phpunit + ergebnis/phpstan-rules — zero baseline.
• Psalm errorLevel: 1 + findUnusedCode: true.
• Deptrac — strict layered architecture: Event → Response → Resolver → Transcript → Scanner → Linter → Builder → Conformance → Support.
• PHPUnit 11+ with failOnRisky, failOnWarning, strict coverage metadata.
• 100 % class + method coverage enforced via bin/check-coverage.
• Infection — MSI ≥ 80, Covered MSI ≥ 85.
• Composer audit every CI run.

Run the full local gate:

Or the curated bundles:

🔐 Security highlights

🤝 Contributing

Contributions are welcome — this is a community package and the API is intentionally narrow so it stays reviewable. Please read CONTRIBUTING.md for:

• 🪜 the local quality-gate checklist;
• 🆕 the 3-step "add an event" workflow;
• 📸 the fixture HTML capture protocol (with the tests/Fixtures/html/*.sha256 sidecar);
• 🔐 the #[\SensitiveParameter] convention enforced by the CI grep guard.

Found a bug or a missing event? Open an issue — a failing test fixture in tests/Fixtures/payloads/ is the fastest path to a fix.

See docs/adr/ for architectural decision records.

📄 License

Released under the MIT License. Copyright © 2026 Sébastien Dieunidou and contributors.