PHPackages                             consolidation/site-alias - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. consolidation/site-alias

ActiveLibrary[Utility & Helpers](/categories/utility)

consolidation/site-alias
========================

Manage alias records for local and remote sites.

4.1.2(6mo ago)6148.8M—4.1%15[7 issues](https://github.com/consolidation/site-alias/issues)[1 PRs](https://github.com/consolidation/site-alias/pulls)12MITPHPPHP >=7.4CI passing

Since Jun 21Pushed 1mo ago2 watchersCompare

[ Source](https://github.com/consolidation/site-alias)[ Packagist](https://packagist.org/packages/consolidation/site-alias)[ RSS](/packages/consolidation-site-alias/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (8)Versions (66)Used By (12)

SiteAlias
=========

[](#sitealias)

Manage alias records for local and remote sites.

[![ci](https://github.com/consolidation/site-alias/workflows/CI/badge.svg)](https://travis-ci.org/consolidation/site-alias)[![scrutinizer](https://camo.githubusercontent.com/834083097a22dfc434aa22c9bfc6fadb897c609341af88cbc719e917f4827d29/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f636f6e736f6c69646174696f6e2f736974652d616c6961732f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/consolidation/site-alias/?branch=master)[![codecov](https://camo.githubusercontent.com/cbfd7cfe974674abd244e8d29ca138f0fc533ab7d7e29379d6b538c0eaf408b1/68747470733a2f2f636f6465636f762e696f2f67682f636f6e736f6c69646174696f6e2f736974652d616c6961732f6272616e63682f6d61696e2f67726170682f62616467652e7376673f746f6b656e3d43416142376f66687878)](https://codecov.io/gh/consolidation/site-alias)[![License](https://camo.githubusercontent.com/48ec640df7aa98ffef21cc458ad62f485e8c6afaab5ab4da8d13d84e1cd7779e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d3430383637372e737667)](LICENSE)

Overview
--------

[](#overview)

This project provides the implementation for Drush site aliases. It is used in Drush 9 and later. It would also be possible to use this library to manage site aliases for similar commandline tools.

### Alias naming conventions

[](#alias-naming-conventions)

Site alias names always begin with a `@`, and typically are divided in three parts: the alias file location (optional), the site name, and the environment name, each separated by a dot. None of these names may contain a dot. An example alias that referenced the `dev` environment of the site `example` in the `myisp` directory might therefore look something like:

```
@myisp.example.dev

```

The location name is optional. If specified, it will only consider alias files located in directories with the same name as the provided location name. The remainder of the path is immaterial; only the directory that is the immediate parent of the site alias file is relevant. The location name may be omitted, e.g.:

```
@example.dev

```

If the location is not specified, then the alias manaager will consider all locations for an applicable site alias file. Note that by default, deep searching is disabled; unless deep searching is enabled, the location name must refer to a directory that is explicitly listed as a location to place site alias files (e.g. in the application's configuration file).

It is also possible to use single-word aliases. These can sometimes be ambiguous; the site alias manager will resolve single-word aliases as follows:

1. `@self` is interpreted to mean the site that has already been selected, or the site that would be selected in the absence of any alias.
2. `@none` is interpreted as the empty alias--an alias with no items defined.
3. `@`, for any `` is equivalent to `@self.` if such an alias is defined. See below.
4. `@`, for any `` is equivalent to the default environment of ``, e.g. `@.`. The default environment defaults to `dev`, but may be explicitly set in the alias.

### Alias placement on commandline

[](#alias-placement-on-commandline)

It is up to each individual commandline tools how to utilize aliases. There are two primary examples:

1. Site selection alias: `tool @sitealias command`
2. Alias parameters: `tool command @source @destination`

In the first example, with the site alias appearing before the command name, the alias is used to determine the target site for the current command. In the second example, the arguments of the command are used to specify source and destination sites.

### Alias filenames and locations

[](#alias-filenames-and-locations)

It is also up to each individual commandline tool where to search for alias files. Search locations may be added to the SiteAliasManager via an API call. By default, alias files are only found if they appear immediately inside one of the specified search locations. Deep searching is only done if explicitly enabled by the application.

Aliases are typically stored in Yaml files, although other formats may also be used if a custom alias data file loader is provided. The extension of the file determines the loader type (.yml for Yaml). The base name of the file, sans its extension, is the site name used to address the alias on the commandline. Site names may not contain periods.

### Alias file contents

[](#alias-file-contents)

The canonical site alias will contain information about how to locate the site on the local file system, and how the site is addressed on the network (when accessed via a web browser).

```
dev:
  root: /path/to/site
  uri: https://example.com

```

A more complex alias might also contain information about the server that the site is running on (when accessed via ssh for deployment and maintenance).

```
dev:
  root: /path/to/site
  uri: https://example.com
  remote: server.com
  user: www-data

```

### Wildcard environments

[](#wildcard-environments)

It is also possible to define "wildcard" environments that will match any provided environment name. This is only possible to do in instances where the contents of the wildcard aliases are all the same, except for places where the environment name appears. To substitute the name of the environment into a wildcard domain, use the variable replacement string `${env-name}`. For example, a wildcard alias that will match any multisite in a Drupal site might look something like the following example:

```
'*':
  root: /wild/path/to/wild
  uri: https://${env-name}.example.com

```

### 'Self' environment aliases

[](#self-environment-aliases)

As previously mentioned, an alias in the form of `@` is interpreted as `@self.`. This allows sites to define a `self.site.yml` file that contains common aliases shared among a team--for example, `@stage` and `@live`.

Site specifications
-------------------

[](#site-specifications)

Site specifications are specially-crafted commandline arguments that can serve as replacements for simple site aliases. Site specifications are particularly useful for scripts that may wish to operate on a remote site without generating a temporary alias file.

The basic form for a site specification is:

```
user.name@example.com/path#uri

```

This is equivalent to the following alias record:

```
env:
  user: user.name
  host: example.com
  root: /path
  uri: somemultisite

```

Getting Started
---------------

[](#getting-started)

To get started contributing to this project, simply clone it locally and then run `composer install`.

### Running the tests

[](#running-the-tests)

The test suite may be run locally by way of some simple composer scripts:

TestCommandRun all tests`composer test`PHPUnit tests`composer unit`PHP linter`composer lint`Code style`composer cs`Fix style errors`composer cbf`### Development Commandline Tool

[](#development-commandline-tool)

This library comes with a commandline tool called `alias-tool`. The only purpose this tool serves is to provide a way to do ad-hoc experimentation and testing for this library.

Example:

```
$ ./alias-tool site:list tests/fixtures/sitealiases/sites/

 ! [NOTE] Add search location: tests/fixtures/sitealiases/sites/

'@single.alternate':
  foo: bar
  root: /alternate/path/to/single
'@single.dev':
  foo: bar
  root: /path/to/single
'@wild.*':
  foo: bar
  root: /wild/path/to/wild
  uri: 'https://*.example.com'
'@wild.dev':
  foo: bar
  root: /path/to/wild
  uri: 'https://dev.example.com'

$ ./alias-tool site:get tests/fixtures/sitealiases/sites/ @single.dev

 ! [NOTE] Add search location: tests/fixtures/sitealiases/sites/

 ! [NOTE] Alias parameter: '@single.dev'

foo: bar
root: /path/to/single

```

See `./alias-tool help` and `./alias-tool list` for more information.

Release Procedure
-----------------

[](#release-procedure)

To create a release:

- Edit the `VERSION` file to contain the version to release, and commit the change.
- Run `composer release`

Built With
----------

[](#built-with)

This library was created with the [g1a/starter](https://github.com/g1a/starter) project, a fast way to create php libraries and [Robo](https://robo.li/) / [Symfony](https://symfony.com/) applications.

Contributing
------------

[](#contributing)

Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on the process for submitting pull requests to us.

Versioning
----------

[](#versioning)

We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [releases](https://github.com/consolidation/site-alias/releases) page.

Authors
-------

[](#authors)

- **Greg Anderson**
- **Moshe Weitzman**

See also the list of [contributors](https://github.com/consolidation/site-alias/contributors) who participated in this project. Thanks also to all of the [drush contributors](https://github.com/drush-ops/drush/contributors) who contributed directly or indirectly to site aliases.

License
-------

[](#license)

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details

###  Health Score

66

—

FairBetter than 99% of packages

Maintenance78

Regular maintenance activity

Popularity64

Solid adoption and visibility

Community30

Small or concentrated contributor base

Maturity77

Established project with proven stability

 Bus Factor1

Top contributor holds 86.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~73 days

Recently: every ~281 days

Total

38

Last Release

185d ago

Major Versions

1.1.10 → 2.0.02018-11-01

1.1.11 → 2.1.12019-01-03

2.1.1 → 3.0.0-alpha12019-03-02

3.1.6 → 4.0.02022-10-14

3.1.7 → 4.0.12023-04-29

PHP version history (2 changes)0.1.0PHP >=5.5.0

4.0.0PHP >=7.4

### Community

Maintainers

![](https://www.gravatar.com/avatar/b34cc6bd882277b6c6dda19bf6631ae5c3a909fd667c826a15121642cdc051b2?d=identicon)[greg.1.anderson](/maintainers/greg.1.anderson)

---

Top Contributors

[![greg-1-anderson](https://avatars.githubusercontent.com/u/612191?v=4)](https://github.com/greg-1-anderson "greg-1-anderson (113 commits)")[![weitzman](https://avatars.githubusercontent.com/u/7740?v=4)](https://github.com/weitzman "weitzman (5 commits)")[![ossobuffo](https://avatars.githubusercontent.com/u/1753478?v=4)](https://github.com/ossobuffo "ossobuffo (5 commits)")[![andypost](https://avatars.githubusercontent.com/u/73713?v=4)](https://github.com/andypost "andypost (3 commits)")[![esolitos](https://avatars.githubusercontent.com/u/401819?v=4)](https://github.com/esolitos "esolitos (1 commits)")[![larowlan](https://avatars.githubusercontent.com/u/555254?v=4)](https://github.com/larowlan "larowlan (1 commits)")[![claudiu-cristea](https://avatars.githubusercontent.com/u/473868?v=4)](https://github.com/claudiu-cristea "claudiu-cristea (1 commits)")[![BrianGilbert](https://avatars.githubusercontent.com/u/114017?v=4)](https://github.com/BrianGilbert "BrianGilbert (1 commits)")[![wongjn](https://avatars.githubusercontent.com/u/11310624?v=4)](https://github.com/wongjn "wongjn (1 commits)")

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/consolidation-site-alias/health.svg)

```
[![Health](https://phpackages.com/badges/consolidation-site-alias/health.svg)](https://phpackages.com/packages/consolidation-site-alias)
```

###  Alternatives

[symfony/maker-bundle

Symfony Maker helps you create empty commands, controllers, form classes, tests and more so you can forget about writing boilerplate code.

3.4k111.1M568](/packages/symfony-maker-bundle)[consolidation/robo

Modern task runner

2.7k62.9M410](/packages/consolidation-robo)[drush/drush

Drush is a command line shell and scripting interface for Drupal, a veritable Swiss Army knife designed to make life easier for those of us who spend some of our working hours hacking away at the command prompt.

2.4k57.4M685](/packages/drush-drush)[symplify/monorepo-builder

Not only Composer tools to build a Monorepo.

5205.3M82](/packages/symplify-monorepo-builder)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

728272.9k20](/packages/civicrm-civicrm-core)[friendsoftypo3/content-blocks

TYPO3 CMS Content Blocks - Content Types API | Define reusable components via YAML

96374.6k23](/packages/friendsoftypo3-content-blocks)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)