2 namespace Drush\SiteAlias;
5 * Parse a string that contains a site alias name, and provide convenience
6 * methods to access the parts.
8 * When provided by users, aliases must be in one of the following forms:
10 * - @sitename.env: List only sitename and environment.
12 * - @env: Look up a named environment in instances where the site root
13 * is known (e.g. via cwd). In this form, there is an implicit sitename
14 * 'self' which is replaced by the actual site alias name once known.
16 * - @sitename: Provides only the sitename; uses the 'default' environment,
17 * or 'dev' if there is no 'default' (or whatever is there if there is
18 * only one). With this form, the site alias name has no environment
19 * until the appropriate default environment is looked up. This form
20 * is checked only after `@env` returns no matches.
22 * There are also two special aliases that are recognized:
24 * - @self: The current bootstrapped site.
26 * - @none: No alias ('root' and 'uri' unset).
28 * The special alias forms have no environment component.
30 * When provided to an API, the '@' is optional.
32 * Note that @sitename and @env are ambiguous. Aliases in this form
33 * (that are not one of the special aliases) will first be assumed
34 * to be @env, and may be converted to @sitename later.
38 * - 'sitename' and 'env' MUST NOT contain a '.' (unlike previous
40 * - Users SHOULD NOT create any environments that have the same name
41 * as any site name (and visa-versa).
42 * - All environments in one site record SHOULD be different versions
43 * of the same site (e.g. dev / test / live).
51 * Match the parts of a regex name.
53 const ALIAS_NAME_REGEX = '%^@?([a-zA-Z0-9_-]+)(\.[a-zA-Z0-9_-]+)?$%';
56 * Create a new site alias name
59 * @return SiteAliasName
61 public static function parse($item)
63 $aliasName = new self();
64 $aliasName->doParse($item);
69 * Creae a SiteAliasName object from an alias name string.
71 * @param string $sitename The alias name for the site.
72 * @param string $env The name for the site's environment.
74 public function __construct($sitename = null, $env = null)
76 $this->sitename = $sitename;
81 * Convert an alias name back to a string.
85 public function __toString()
87 $parts = [ $this->sitename() ];
88 if ($this->hasEnv()) {
89 $parts[] = $this->env();
91 return '@' . implode('.', $parts);
95 * Determine whether or not the provided name is an alias name.
97 * @param string $aliasName
100 public static function isAliasName($aliasName)
102 // Alias names provided by users must begin with '@'
103 if (empty($aliasName) || ($aliasName[0] != '@')) {
106 return preg_match(self::ALIAS_NAME_REGEX, $aliasName);
110 * Return the sitename portion of the alias name. By definition,
111 * every alias must have a sitename. If the site name is implicit,
112 * then 'self' is assumed.
116 public function sitename()
118 return empty($this->sitename) ? 'self' : $this->sitename;
122 * Set the sitename portion of the alias name
124 * @param string $sitename
126 public function setSitename($sitename)
128 $this->sitename = $sitename;
132 * In general, all aliases have a sitename. The time when one will not
133 * is when an environment name `@env` is used as a shortcut for `@self.env`
137 public function hasSitename()
139 return !empty($this->sitename);
143 * Return true if this alias name contains an 'env' portion.
147 public function hasEnv()
149 return !empty($this->env);
153 * Set the environment portion of the alias record.
157 public function setEnv($env)
163 * Return the 'env' portion of the alias record.
167 public function env()
173 * Return true if this alias name is the 'self' alias.
177 public function isSelf()
179 return ($this->sitename == 'self') && !isset($this->env);
183 * Return true if this alias name is the 'none' alias.
185 public function isNone()
187 return ($this->sitename == 'none') && !isset($this->env);
191 * Convert the parts of an alias name to its various component parts.
193 * @param string $aliasName a string representation of an alias name.
195 protected function doParse($aliasName)
197 // Example contents of $matches:
211 if (!preg_match(self::ALIAS_NAME_REGEX, $aliasName, $matches)) {
215 // If $matches contains only two items, then assume the alias name
216 // contains only the environment.
217 if (count($matches) == 2) {
218 return $this->processSingleItem($matches[1]);
221 $this->sitename = $matches[1];
222 $this->env = ltrim($matches[2], '.');
227 * Process an alias name provided as '@sitename'.
229 * @param string $sitename
232 protected function processSingleItem($item)
234 if ($this->isSpecialAliasName($item)) {
235 $this->setSitename($item);
238 $this->sitename = '';
244 * Determine whether the requested name is a special alias name.
246 * @param string $item
249 protected function isSpecialAliasName($item)
251 return ($item == 'self') || ($item == 'none');