Download the PHP package voku/itp-context without Composer

🎯 itp-context

A small PHP library for attaching architecture rules to code via PHP attributes and resolving those rules directly from typed enums.

It gives you:

• typed rule identifiers via enums
• repeatable #[Rule(...)] attributes for classes, methods and functions
• inline enum rule definitions with ownership, rationale, references and proof metadata
• validation helpers for broken or incomplete rule definitions
• summary output for annotated PHP symbols, including multiple symbols per file
• compact markdown context exports with searchable metadata for coding agents and repository assistants
• a small query helper for searching exported context by rule, owner, proof, refs or free text
• a small generator for bootstrapping new rule enums

Index

• Install
• Why?
• Usage
• Local Development
• Project Structure
• CLI Tools
• Tests
• License

Install via "composer require"

Why?

When architecture guidance only lives in ADRs and wikis, it drifts away from the code that is supposed to follow it.

itp-context keeps the rule identifier, definition, and supporting context references together in one typed enum instead of splitting them across sibling catalog files. That gives you a compact way to:

• attach architecture intent to classes, methods and functions
• validate whether enum cases still expose usable definitions
• summarize relevant architecture context for one PHP file

The goal is to add context without burning tokens:

• prefer a few broad, high-signal rules over many narrow ones
• annotate central symbols, not every class in the tree
• export compact markdown that is easy for humans and LLMs to scan

Usage

1. Create a rule enum in your project

Use refs for the context you want nearby: ADRs, docs, design notes, diagrams, tickets or related code.

2. Annotate your code

Keep annotations selective: tag the classes or methods where architecture context changes decisions, not every file.

3. Validate the enum definitions

Validation walks every enum case and calls getDefinition(), so broken match arms or incomplete inline definitions fail in one place.

4. Summarize one file

Example output:

5. Export agent-friendly context for a source tree

This writes:

• var/itp-context/index.md
• one markdown file per annotated PHP symbol under var/itp-context/php/

The export is intentionally lean:

• annotate only the few symbols that carry important architecture context
• use broad rules that stay stable as the code evolves
• keep frontmatter small: id, title, source_path, kind and rule_ids

This repository dogfoods that approach with a few high-signal ItpContext\Context\PackageRules annotations on core services, and a committed self-export snapshot lives under docs/package-export/.

That docs/package-export/ tree is meant to be a ready-made reference for coding agents: it shows the compact export shape, the searchable metadata (owners, refs, verified_by, annotated_methods) and the level of abstraction that keeps context useful without wasting tokens.

Local Development

If you want to test the package before publishing it, use a Composer path repository in a separate project:

Then install it via Composer:

After that the package CLIs are available in the consumer project via:

Project Structure

This package only contains generic framework code under the ItpContext\\ namespace.

Your project-specific files stay in your own codebase, for example:

• src/Context/ArchitectureRules.php

A minimal example project is included under examples/basic-domain, and the repository's self-export snapshot lives under docs/package-export.

The example project also includes sample context docs under examples/basic-domain/docs/, including ADR-style notes referenced from the enum definitions.

Portable agent skills

This repository keeps one shared, repo-owned coding-agent skill under docs/skills/itp-context.md.

Agent-specific entrypoints stay thin and point back to that file:

• AGENTS.md
• .github/copilot-instructions.md
• CODEX.md
• CLAUDE.md
• GEMINI.md

That keeps the actual guidance in one place while still exposing it to different agent runtimes.

CLI Tools

The package ships with five small CLI helpers.

itp-context-summarize

itp-context-validate

itp-context-generate

This creates or extends:

• src/Context/ArchitectureRules.php

The generator only updates the enum: it adds the new case plus a matching getDefinition() arm and seeds statement, owner, rationale, verifiedBy, and refs placeholders so new rules start with a fuller definition.

itp-context-export

The export contains:

• index.md with an overview of all exported symbols
• one markdown file per annotated PHP symbol under php/
• compact frontmatter fields for id, title, source_path, kind, rule_ids, owners, refs, verified_by, annotated_methods and rule_count

itp-context-query

For small libraries, prefer a tiny export with a few high-value symbols over exhaustive annotation. The goal is context density, not full documentation coverage.

Tests

There is also a package smoke check in tests/smoke/package_smoke.php.

License

MIT