Surveyor Laravel Package

Product Decisions This Supports

• Build vs. buy for code-intelligence. Surveyor is the "buy" answer to a recurring question: how do we programmatically know what a Laravel codebase actually is? It hands back classes, namespaces, inheritance, methods, parameters, return types, properties, visibility, constants, and validation rules as structured DTOs. That is months of PHP-parser work we would otherwise own. Adopt it as a dependency rather than building a bespoke AST pipeline.
• Type generation and frontend/backend contracts. The built-in type system (StringType, ArrayShapeType, UnionType, ClassType, etc.) plus validation-rule extraction makes this a credible substrate for generating TypeScript types, form schemas, or API client stubs from Laravel code. The "Ignore Markers" design — where the consumer ships its own attribute implementing Ignored, with when/unless conditions and comment tags for array keys — is a clear tell that the intended use case is codegen that must let application authors exclude things like secrets or internal-only fields.
• Eloquent-aware documentation and schema visibility. Model analysis surfaces database attributes and their types, relationships, accessors/mutators, and casts. That directly supports generated data dictionaries, ER-style docs, admin-panel scaffolding, and onboarding material that stays in sync with the schema instead of rotting in a wiki.
• Roadmap input for developer-experience investments. If we are evaluating "should we invest in internal tooling for upgrade automation, dead-code detection, or architecture linting," Surveyor is the cheap first experiment. It tells us whether Laravel-native semantics (container bindings, model metaschema) materially beat generic PHP tooling before we staff a team.
• Pairing decision with Laravel Ranger. Surveyor deliberately returns low-level analysis; Ranger returns high-level DTOs. If our use case is "consume results," budget for Ranger or a thin internal adapter — Surveyor alone is a primitives layer, not a product.
• CI and quality-gate placement. Because it exposes method-level metadata deterministically, it fits behind a CI job for contract checks ("this public method's signature changed"), separate from rule enforcement, which is not its job.

When to Consider This Package

Adopt when:

• We are building a tool that consumes application structure: typegen, docs generation, scaffolding, upgrade assistants, architecture mapping, admin/CRUD generation.
• We need Laravel-specific semantics — Eloquent casts, relationships, container bindings — that generic PHP static analyzers cannot see.
• We can accept a Beta API with no stability guarantee before v1.0.0, and can isolate it behind our own interface so a breaking change is a one-file fix.
• We can tolerate the acknowledged performance and memory shortcomings, ideally mitigated by the disk cache (SURVEYOR_CACHE_ENABLED, SURVEYOR_CACHE_DIR), which tracks file mtimes and cross-file dependencies (parent classes, traits) for invalidation.
• We can provide a database connection in the analysis environment — it is explicitly "not strictly static": it inspects models (brief DB connection) and app bindings.

Look elsewhere when:

• We need a linter or rule enforcer. Use PHPStan/Larastan; Surveyor extracts, it does not judge.
• We need enterprise-grade stability, an SLA, or a support contract. 94 stars and 0 dependents means effectively zero production validation; treat it as a tech preview.
• Analysis happens in a hardened CI context where granting DB credentials to a static-analysis step is unacceptable, or where analysis must be hermetic and reproducible. "Mostly static" implies nondeterminism across environments.
• Performance is on the critical path — e.g., re-analyzing a large monorepo on every save or every PR with a tight latency budget. The maintainers themselves flag speed and memory as unresolved.
• We only need simple reflection. PHP's native Reflection* API and composer autoload data cover a surprising amount at zero dependency cost.
• We need conditional-ignore semantics out of the box. Condition resolution requires us to register a resolver via Markers::registerConditionResolver() before reading results, and until then every conditional marker hides — a sharp edge worth pricing in.

How to Pitch It (Stakeholders)

To executives: This is a free, first-party Laravel package that reads our codebase and returns a structured description of it — classes, methods, types, validation rules, database-backed model attributes and relationships. It is the foundation layer for automating work we currently do by hand: generating frontend types, keeping API and data documentation accurate, scaffolding admin screens, and eventually assisting framework upgrades. Cost is a Composer dependency; the alternative is building and maintaining a PHP parser ourselves, which is a multi-engineer, multi-quarter effort with no product differentiation. The honest caveat: it is officially in Beta with a pre-1.0 API, near-zero public adoption, and known performance limits. We therefore propose a time-boxed, contained pilot behind our own abstraction layer, pinned to an exact version, with a go/no-go before we let any shipped feature depend on it. Downside is bounded to one engineer-quarter; upside is a reusable capability across several roadmap items.

To engineering: You get parsed class metadata, a full PHP type system, Eloquent model introspection (casts, relations, accessors), and a dependency-aware disk cache so repeat analysis is cheap. You do not get to skip the integration work: the API will change before 1.0.0, so wrap Analyzer and ClassLikeResult behind an internal interface and never let package types leak into domain code. Expect to need a database connection at analysis time and to profile memory on our largest app before committing. Ignore-marker semantics are subtle — conditions are resolved when a member is read, not when the file is analyzed, so cached analyses store the condition and not its answer; register a condition resolver early and test it. Pair with Laravel Ranger if we want ready-made DTOs instead of raw results. Plan a version-pin and a quarterly upgrade review, and contribute back on the performance work — the maintainers are explicitly soliciting it, which is the cheapest way to buy influence over a dependency we may come to rely on.