Site Alias Laravel Package

Technical Evaluation

Architecture fit

consolidation/site-alias is a framework-agnostic PHP library, not a Laravel package. It ships no service provider, no facade, no publishable config, and no Laravel contracts. Its job is narrow and well-defined: discover *.site.yml alias files across a set of search paths, parse and merge them (including @self, @parent, @none inheritance and env-style variable interpolation), and expose typed AliasRecord objects with resolved root/uri plus a spec array. It is the canonical alias engine behind Drush and Pantheon Terminus.

For a Laravel codebase this is a "library you wrap," not a "package you install and configure." The realistic fit is a Laravel app that already operates on Drupal/Drush estates — a multi-site control panel, a deployment dashboard, a backup/sync orchestrator, a CI helper service. In a pure Laravel product with no Drush footprint, there is no problem here to solve and the package adds surface area for nothing.

Integration feasibility

Mechanically low cost. composer require consolidation/site-alias, construct a SiteAliasManager with one or more search locations, and you have a typed API replacing ad-hoc YAML globbing or shelling out to drush sa --format=json. The main integration work is not the library — it is deciding where alias files live in your runtime (repo path, mounted volume, object storage sync) and making that location configurable rather than hardcoded.

Technical risk

• License: NOASSERTION. This is the single largest blocker for a commercial product. The upstream ecosystem is MIT in practice, but "NOASSERTION" means no machine-readable declaration; legal must clear it explicitly before this enters a shipped dependency graph. Treat as a gate, not a footnote.
• Small, concentrated maintainership. 60 stars and a single-org maintainer set. The mitigating factor is that Drush and Terminus depend on it, so abandonment is unlikely while that ecosystem lives; the risk is slow response and breaking changes landing in minor releases.
• CLI-oriented design. Filesystem scanning, YAML parsing, and interpolation are assumed to happen in a short-lived process. Used per-request in a web app without caching, this becomes a latency and I/O tax.
• Implicit conventions. The package encodes Drush's alias semantics. Anyone on the team who does not know the .site.yml format will misread behavior — particularly inheritance resolution order and @self fallback.

Key questions

1. Does any part of the target product actually consume Drush aliases, or is this speculative?
2. Has legal signed off on a NOASSERTION license in a distributed artifact?
3. What is the alias file source of truth, and how does it reach each runtime instance?
4. Do we need inheritance/multi-source merging, or would a single validated YAML file suffice?
5. What is our fallback if upstream stalls — fork, pin, or vendor the parser?

Integration Approach

Stack fit

Wrap it, do not scatter it. A thin SiteAliasServiceProvider binds a singleton SiteAliasManager built from a config/site-alias.php search-path list, exposed behind a small application-level interface (AliasRepository::all(), ::get($name)). Consumers depend on your interface, not on AliasRecord, which keeps the vendor type out of your domain and makes a later swap to a hand-rolled parser a one-file change. Wrap access in Laravel's cache with a file-mtime-aware key so discovery does not run on every request.

Migration path

Identify every place the app currently shells out to drush sa, globs *.site.yml, or hand-parses YAML for host/root/uri. Replace those with the repository interface, in that order of confidence — the shell-out call sites are the best evidence the library is earning its place (you delete a subprocess and a parsing failure mode at once). Leave anything that only needs one or two static fields alone; the library is not worth a dependency for reading a single hardcoded hostname.

Compatibility

Check PHP constraint against your runtime floor, and — more importantly — symfony/yaml version range against what Laravel's ecosystem already resolves. YAML is the most likely conflict point; if you cannot align, stop and reconsider. Pin to an exact minor version rather than a caret range until you have run a full upgrade cycle against it.

Sequencing

1. Legal clearance on license.
2. Spike: load a representative alias set, confirm inheritance and interpolation behave as expected.
3. Build the provider + interface + cache.
4. Migrate shell-out call sites.
5. Add validation: fail loudly on malformed alias files rather than silently returning an empty set.
6. Only then consider broader adoption.

Operational Impact

Maintenance

Low ongoing code maintenance — the library does one thing. The real cost is format stewardship: someone must own the alias files, their schema, and their review process. Budget a few hours per quarter for dependency bumps and a re-read of upstream changes, more if you rely on inheritance.

Support

Thin. Expect GitHub issues rather than a vendor. Internal documentation is mandatory, specifically a short page on the alias file format and resolution order. Do not assume a new hire can infer behavior from the code.

Scaling

Discovery is O(files × parse cost) per uncached call. At tens of aliases this is trivial; at hundreds across many search paths in a request path it is not. Cache aggressively, key on directory mtime, and keep the manager out of hot request paths entirely — resolve aliases at deploy/queue time and persist the flattened result.

Failure modes

• Malformed YAML — silent empty results or partial loads. Mitigate with explicit validation and a health check that asserts a known alias resolves.
• Missing or unmounted alias directory — the manager happily returns nothing; downstream code then operates on an empty set. Assert non-empty at boot for critical paths.
• Variable interpolation failure — unresolved ${env.X} yields literal or null values that surface far from the cause. Validate resolved fields at the boundary.
• Cache staleness — alias files edited without a key invalidation produce ghost hosts. Prefer mtime in the key over TTL alone.
• Inheritance surprises — @self fallback and @parent chains can silently point at the wrong site. Test the resolution order explicitly.
• Downstream blast radius — a wrong alias means deploys, syncs, or backups hit the wrong environment. This is the category of failure that justifies the validation work up front.

Ramp-up

A Laravel developer can integrate this in under a day. The non-obvious cost is domain literacy: understanding Drush alias semantics, inheritance, and where files come from in your topology. That is a half-day of reading plus one paired session with whoever owns the Drupal estate. Without that person, do not proceed.