First pass at adding event dispatching for sites not found

composer.json

@@ -25,6 +25,7 @@
     "require": {
         "php": ">=7.4",
         "consolidation/config": "^1.2.1 || ^2",
+        "symfony/event-dispatcher":"^5|| ^6",
         "symfony/filesystem": "^5.4 || ^6",
         "symfony/finder": "^5 || ^6"
     },

src/Events/AliasNotFoundEvent.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Consolidation\SiteAlias\Events;
+
+use Consolidation\SiteAlias\SiteAlias;
+use Symfony\Contracts\EventDispatcher\Event;
+
+class AliasNotFoundEvent extends Event
+{
+
+    protected $aliasName;
+
+    protected $alias = false;
+
+    const NAME = 'alias-not-found';
+
+    public function __construct($aliasName)
+    {
+        $this->aliasName = $aliasName;
+    }
+
+    public function setAlias(SiteAlias $alias)
+    {
+        $this->alias = $alias;
+    }
+
+    public function hasAlias()
+    {
+        return $this->alias !== false;
+    }
+
+    public function getAlias()
+    {
+        return $this->alias;
+    }
+}

src/SiteAliasManager.php

@@ -1,6 +1,9 @@
 <?php
 namespace Consolidation\SiteAlias;
 
+use Consolidation\SiteAlias\Events\AliasNotFoundEvent;
+use Symfony\Component\EventDispatcher\EventDispatcher;
+
 /**
  * Site Alias manager
  */
@@ -10,6 +13,7 @@ class SiteAliasManager implements SiteAliasManagerInterface, SiteAliasManagerIni
     protected $selfSiteAlias;
     protected $specParser;
     protected $root = '';
+    protected $dispatcher;
 
     /**
      * Constructor for SiteAliasManager
@@ -21,6 +25,7 @@ public function __construct($aliasLoader = null, $root = '')
         $this->aliasLoader = $aliasLoader ?: new SiteAliasFileLoader();
         $this->specParser = new SiteSpecParser();
         $this->selfSiteAlias = new SiteAlias();
+        $this->dispatcher = new EventDispatcher();
         $this->setRoot($root);
     }
 
@@ -97,7 +102,16 @@ public function searchLocations()
     public function get($name)
     {
         if (SiteAliasName::isAliasName($name)) {
-            return $this->getAlias($name);
+            $alias =  $this->getAlias($name);
+            if (!$alias) {
+                //TODO, call all registered listeners here - if none of them return an alias, we return false
+                $event = new AliasNotFoundEvent($name);
+                $this->dispatcher->dispatch($event, AliasNotFoundEvent::NAME);
+                if ($event->hasAlias()) {
+                    return $event->getAlias();
+                }
+                return false;
+            }
         }
 
         if ($this->specParser->validSiteSpec($name)) {
@@ -212,4 +226,9 @@ public function listAllFilePaths($location = '')
     {
         return $this->aliasLoader->listAll($location);
     }
+
+    public function addListener($hook, callable $callback)
+    {
+        $this->dispatcher->addListener($hook, $callback);
+    }
 }

tests/SiteAliasManagerTest.php

@@ -1,9 +1,12 @@
 <?php
 namespace Consolidation\SiteAlias;
 
+use Consolidation\SiteAlias\Events\AliasNotFoundEvent;
 use Consolidation\SiteAlias\Util\YamlDataFileLoader;
 use PHPUnit\Framework\TestCase;
+use Symfony\Component\EventDispatcher\GenericEvent;
 use Symfony\Component\Yaml\Yaml;
+use Symfony\Contracts\EventDispatcher\Event;
 
 class SiteAliasManagerTest extends TestCase
 {
@@ -162,6 +165,26 @@ public function testGetMultiple()
         $this->assertEquals('@other.single.dev,@other.single.other', implode(',', $allNames));
     }
 
+    /**
+     * This tests registering a custom site alias resolver when sites are not found using the standard resolution methods
+     *
+     */
+    public function testEventListener()
+    {
+        /* @var SiteAlias $alias */
+        $alias = $this->manager->get('@nonexistent.me');
+        $this->assertFalse($alias, false);
+        $this->manager->addListener(
+            AliasNotFoundEvent::NAME,
+            function (AliasNotFoundEvent $event) {
+                $event->setAlias(new SiteAlias(['test' => 'isset']));
+            }
+        );
+
+        $alias = $this->manager->get('@nonexistent.site');
+        $this->assertEquals('isset', $alias->get('test'));
+    }
+
     /**
      * @covers \Consolidation\SiteAlias\SiteAlias::root()
      */