Surveyor Laravel Package

Technical Evaluation

Architecture fit. Surveyor is an in-process library, not a service or CLI. You resolve Analyzer from the container, hand it a file path or FQCN, and get back ClassLikeResult objects carrying methods, properties, constants, validation rules, and a typed type graph. That makes it a good fit for products that introspect a Laravel app to generate something — TypeScript/API contract generation, documentation, admin or scaffold generation, IDE/agent tooling. It is a poor fit as a generic "analyze any PHP" component, and a poor fit for a polyglot pipeline without taking the asArray()/asJson() serialization path.

Integration feasibility. Install is one Composer require; first result is a few lines. The real constraint is that it must run inside a bootstrapped Laravel app — it reads container bindings and opens a database connection to inspect Eloquent models. That rules out dropping it into a bare CLI script or a stateless worker and makes it an artisan-command/CI-step shape rather than a runtime dependency.

Technical risk.

• Beta API churn is stated, not hypothetical. The README explicitly warns the API will likely change before v1.0.0. Any code that touches Surveyor types directly is on a countdown.
• "Mostly" static. DB and container inspection mean output is environment-dependent. Analysis in CI, locally, and in a staging container can legitimately disagree.
• Self-declared performance problem. Maintainers say it is slower and more memory-hungry than they want. Treat caching as mandatory, not an optimization.
• Near-zero external validation. 94 stars, zero dependents. No third-party battle-testing, no ecosystem of examples, no community support corpus. We would be an early adopter bearing discovery cost.
• Markers are a security control. If we generate client-side code, Ignored/ConditionallyIgnored attributes and comment tags are the only thing standing between a database column and a shipped bundle.

Key questions.

1. What is the downstream consumer? If we are not generating an artifact from this metadata, there is no product here.
2. Can analysis run against a disposable/schema-only database, or does it need real data to infer attribute types?
3. Does its PHP/Laravel constraint matrix match every app we intend to point it at?
4. Who owns the upgrade when the beta API moves, and what is our pinned-version escape hatch?
5. Is the marker system expressive enough for our actual sensitive-field inventory, including conditionals?
6. Does laravel/ranger already provide the shaping layer we would otherwise build?

Integration Approach

Stack fit. Highest possible fit for a Laravel monolith introspecting itself: container-native, Eloquent-aware, env-configured cache (SURVEYOR_CACHE_ENABLED, SURVEYOR_CACHE_DIR). No fit for non-Laravel PHP frameworks. Do not attempt to run it from a separate analysis service on day one.

Migration path. Effectively greenfield — there is no incumbent to displace. The critical move is to wrap Surveyor behind our own narrow interface (e.g. SchemaExtractor returning our DTOs) and never let Laravel\Surveyor\Types\* or ClassLikeResult leak into domain code. With a beta dependency and zero dependents, the adapter is the entire risk mitigation: a v1.0 breaking change, an abandonment, or a fork becomes a one-file swap rather than a refactor.

Compatibility. Verify Composer constraints per target app before committing — beta packages often bump minimum PHP/Laravel in minor releases. Verify behavioral parity across local, CI, and any environment where models are analyzed; divergent DB or binding state is the most likely source of "works on my machine" metadata.

Sequencing.

1. Spike against one representative app: record wall time, peak memory, class count, and whether it runs with schema-only DB access.
2. Define the consumer contract — exactly which metadata we consume (methods, return types, model attributes, relationships, validation rules). Nothing more.
3. Build the adapter and pin an exact version.
4. Wire into CI as a build step, warming the cache and persisting a JSON artifact so downstream jobs consume the artifact, never re-analyze.
5. Harden markers: register our tag vocabulary and attribute classes, add registerConditionResolver, and write tests asserting sensitive fields are absent from output.
6. Build the product feature on top.
7. Gate broad rollout on either v1.0 or internal confidence in the adapter plus golden-file coverage.

Operational Impact

Maintenance. We inherit beta upgrade risk. Budget a recurring task per release: read changelog, bump pinned version, run golden tests, fix adapter. Our own surface — the adapter, the marker registry (Markers::registerTags, registerAttributes, condition resolver) — is code we own and must test. Assume the possibility of vendoring a fork if the package stalls.

Support. No commercial support, no LTS, no deprecation guarantees pre-v1.0. Support is the GitHub issue tracker and the changelog. Low adoption means bugs we hit may sit unfixed; plan for self-service.

Scaling. Two axes. Codebase size: analysis is per-file with dependency-tracked caching, and memory is the binding constraint — a large monorepo will need chunking and a warm disk cache. Run frequency: analysis belongs in build/CI only. Never in a request path, never in a user-triggered job.

Failure modes.

• Missing/unreachable DB → model attributes and cast types silently absent or hard error.
• Unbootstrapped container → binding analysis degrades.
• Stale or misconfigured CI cache → wrong metadata with no error raised.
• OOM on large codebases → truncated/partial artifact downstream.
• Type misclassification → wrong generated output, discovered by consumers, not by us.
• Marker regression → sensitive field leaks into generated client code. Highest severity; instrument it with explicit negative assertions per sensitive field.
• Pinned-version drift → the upgrade becomes urgent and unbudgeted at the worst moment.

Ramp-up. Low to first result — any Laravel developer gets output in an afternoon. Moderate-to-high to productionize: cache strategy, adapter, marker policy, golden tests, CI wiring, and an upgrade owner. Evaluate laravel/ranger first; if it supplies the high-level DTOs we need, it removes a meaningful chunk of that work.