Generator Laravel Package

Product Decisions This Supports

• Build vs. buy for developer documentation: Adopt an AST-based extractor instead of hand-maintaining a hook reference that rots the moment someone renames a filter. The package parses PHP source and emits JSON — a build artifact, not a runtime dependency.
• Feature scoping for a developer portal: Gives us a credible path to auto-generated hook docs (name, type, arguments, docblock, file/line) shipped alongside each release, without writing a PHP parser ourselves.
• Roadmap bets on DX: Unlocks adjacent features at low marginal cost — hook autocomplete in IDE extensions, "undocumented hook" linting in CI, deprecation/breaking-change detection between versions, and a machine-readable hook manifest for agency/partner integrations.
• Integration risk audits: Can be run against third-party plugins/themes we depend on, so we can assess which hooks we're coupled to before a vendor upgrade, rather than discovering it in production.
• Architecture decision: Output is plain JSON, so downstream consumers (docs site, IDE plugin, internal portal) stay decoupled from the generator itself — low lock-in, easy to swap or fork.
• Prioritization: Cheap to validate. A one-sprint spike with one engineer answers "is generated hook documentation good enough to ship?" before we commit roadmap space.

When to Consider This Package

Adopt when:

• We maintain a WordPress plugin/theme — or a Laravel product with a WP companion plugin, headless WP integration, or migration tooling — and hook documentation is currently manual or absent.
• Documentation drift is a real cost: many hooks, frequent releases, support tickets asking "what changed."
• We need structured hook metadata for tooling (IDE extension, CI gate, changelog generator), not just prose docs.
• We're on PHP 8+ with Composer and a working CI/release pipeline, and a one-shot CLI generation step fits naturally.
• We want the source of truth to be the code, and we're comfortable owning a thin internal wrapper around a small dependency.

Look elsewhere when:

• The codebase is Laravel-only. Laravel events/listeners are introspectable via reflection and php artisan event:list; this package solves a WordPress-specific problem we don't have.
• We only need a handful of hooks documented once — hand-writing is cheaper than adding a parser dependency.
• We need runtime behavior (which callbacks are actually attached), not static declarations — that's $wp_filter, not this.
• We need the WordPress core hook catalog rather than our own code — use the prebuilt wp-hooks/wordpress-core-hooks dataset instead of generating it.
• We require a commercial SLA, security review, or a large maintainer community. At 87 stars and zero dependents, this is a thin, effectively single-maintainer dependency: pin the version, wrap it behind an internal adapter, and budget for a fork.

How to Pitch It (Stakeholders)

For executives: This is a low-cost, low-risk developer-experience investment. It converts manual hook documentation — work that decays every release — into an automated build step, and produces a JSON manifest we can render as docs, feed to IDE tooling, or hand to integration partners. Because the output is a plain file, we are not betting the roadmap on the package: if it stalls, we keep the JSON and swap the generator.

For engineering: composer require --dev wp-hooks/generator, run it in the release job, commit or publish the JSON, render it however we like. No runtime code changes, no production dependency, no framework coupling. Small surface area: it's a static analyzer over our source. We wrap it in an internal script so the interface we depend on is ours, not the package's.

The ask: one engineer, one sprint spike. Success criteria: (1) a hook manifest generated for our plugin in CI, (2) one docs page rendered from it, (3) a CI check that flags newly added undocumented hooks. If those three land, we have a repeatable DX capability; if not, we've spent a sprint and kept the option open.