Cleanup and readme.

Author: pmelab

README.md

@@ -0,0 +1,64 @@
+# Contextual aliases
+
+This module allows to split Drupal's url aliases into different contexts that allow to use the *same* alias for
+*different* source paths. The most prominent use case is a setup with different domains, where the same path is
+supposed to point to a different node, depending on the current domain.
+
+```
+http://a.com/imprint -> /node/1
+http://b.com/imprint -> /node/2
+http://c.com/imprint -> /node/3
+```
+
+**Disclaimer:** This is an advanced module that requires coding and knowledge about cache configuration.
+
+## How it works
+
+When saving a new alias, the module will search for services tagged with `alias_context_resolver` that implement the
+`AliasContextResolverInterface`, and use them to determine the context for a given path.
+
+```
+/node/1 -> a
+/node/2 -> b
+/node/3 -> NULL
+```
+
+It will store this path and use it for resolving paths from aliases and vice versa. There it will consult the context
+resolver again to obtain the *current* context (e.g. the domain the request was sent to). If the result matches the
+stored context for this alias, it will behave normal. If not, aliases will prefixed (both ways) with their context.
+Non-contextual aliases remain functional, but will be picked with a lower priority.
+
+### Current context: none
+```
+/node/1 -> /a/imprint
+/node/2 -> /b/imprint
+/node/3 -> /imprint
+
+/imprint -> /node/3
+```
+
+### Current context: 'a'
+```
+/node/1 -> /imprint
+/node/2 -> /b/imprint
+/node/3 -> /imprint
+
+/imprint -> /node/1
+```
+
+### Current context: 'b'
+```
+current context: b
+
+/node/1 -> /a/imprint
+/node/2 -> /imprint
+/node/3 -> /imprint
+
+/imprint -> /node/2
+```
+
+## How to use it
+The module requires you to implement your own context resolvers and add them as services tagged with
+`alias_context_resolver` and (more importantly) configure caching in a way it also respects the same contextual
+information. Otherwise you will have a very bad time watching your page cache serving random pages.
+

contextual_aliases.install

@@ -2,6 +2,12 @@
 
 use Drupal\Core\Database\Database;
 
+/**
+ * Implements hook_install().
+ *
+ * Alter the existing schema for `url_alias`. Add a `context` column and
+ * indices that include it.
+ */
 function contextual_aliases_install() {
   $spec = array(
     'description' => "The context for this alias..",
@@ -27,6 +33,11 @@ function contextual_aliases_install() {
   ], $table);
 }
 
+/**
+ * Implements hook_uninstall().
+ *
+ * Revert changes from `contextual_aliases_install`.
+ */
 function contextual_aliases_uninstall() {
   $schema = Database::getConnection()->schema();
 

contextual_aliases.module

@@ -13,10 +13,6 @@
  */
 class ContextualAliasStorage extends AliasStorage {
 
-  protected $currentContexts = NULL;
-
-  protected $cachedContexts = [];
-
   /**
    * The list of alias context resolvers.
    *
@@ -32,18 +28,18 @@ public function addContextResolver(AliasContextResolverInterface $resolver) {
   }
 
   /**
-   * Retrieve the list of current contexts.
+   * Retrieve the current context.
    *
-   * @return array
-   *   The list of current contexts.
+   * @return string
+   *   The identifier for the current context.
    */
   protected function getCurrentContext() {
-    if (is_null($this->currentContexts)) {
-      $this->currentContexts = array_filter(array_map(function (AliasContextResolverInterface $resolver) {
-        return $resolver->getCurrentContext();
-      }, $this->contextResolvers));
+    foreach ($this->contextResolvers as $resolver) {
+      if ($context = $resolver->getCurrentContext()) {
+        return $context;
+      }
     }
-    return $this->currentContexts ? $this->currentContexts[0] : NULL;
+    return NULL;
   }
 
   /**
@@ -53,15 +49,12 @@ protected function getCurrentContext() {
    *   The list of source contexts.
    */
   protected function getSourceContext($source) {
-    if (!array_key_exists($source, $this->cachedContexts)) {
-      $this->cachedContexts[$source] = NULL;
-      foreach ($this->contextResolvers as $resolver) {
-        if ($context = $resolver->resolveContext($source)) {
-          $this->cachedContexts[$source] = $context;
-        }
+    foreach ($this->contextResolvers as $resolver) {
+      if ($context = $resolver->resolveContext($source)) {
+        return $context;
       }
     }
-    return $this->cachedContexts[$source];
+    return NULL;
   }
 
   protected function _contextCondition($select, $context, $prefix = FALSE) {

src/ContextualAliasStorage.php

@@ -111,50 +111,74 @@ public function testServiceInjection() {
     $this->assertInstanceOf(ContextualAliasStorage::class, $storage);
   }
 
+  /**
+   * Test for vanilla aliases without contexts.
+   */
   public function testNoContextSimpleAlias() {
     $this->resolver->getCurrentContext()->willReturn(NULL);
     $this->assertEquals('/c', $this->manager->getPathByAlias('/C'));
     $this->assertEquals('/C', $this->manager->getAliasByPath('/c'));
   }
 
+  /**
+   * Test contextual aliases outside of global context.
+   */
   public function testNoContextContextualAlias() {
     $this->resolver->getCurrentContext()->willReturn(NULL);
     $this->assertEquals('/A', $this->manager->getPathByAlias('/A'));
     $this->assertEquals('/a', $this->manager->getPathByAlias('/one/A'));
     $this->assertEquals('/one/A', $this->manager->getAliasByPath('/a'));
   }
 
+  /**
+   * Test contextual aliases within a matching global context.
+   */
   public function testContextMatchingAlias() {
     $this->resolver->getCurrentContext()->willReturn('one');
     $this->assertEquals('/a', $this->manager->getPathByAlias('/A'));
     $this->assertEquals('/a', $this->manager->getPathByAlias('/one/A'));
     $this->assertEquals('/A', $this->manager->getAliasByPath('/a'));
   }
 
+  /**
+   * Test contextual aliases within a different global context.
+   */
   public function testContextNotMatchingAlias() {
     $this->resolver->getCurrentContext()->willReturn('two');
     $this->assertEquals('/A', $this->manager->getPathByAlias('/A'));
     $this->assertEquals('/a', $this->manager->getPathByAlias('/one/A'));
     $this->assertEquals('/one/A', $this->manager->getAliasByPath('/a'));
   }
 
+  /**
+   * Test aliases that contain another context's prefix.
+   */
   public function testNonContextualConflictingAlias() {
     $this->resolver->getCurrentContext()->willReturn(NULL);
     $this->assertEquals('/d', $this->manager->getPathByAlias('/one/D'));
     $this->assertEquals('/one/D', $this->manager->getAliasByPath('/d'));
+
     $this->resolver->getCurrentContext()->willReturn('one');
     $this->assertEquals('/d', $this->manager->getPathByAlias('/one/D'));
     $this->assertEquals('/one/D', $this->manager->getAliasByPath('/d'));
   }
 
+  /**
+   * Test contextual aliases that contain another context's prefix.
+   */
   public function testContextualConflictingAlias() {
     $this->resolver->getCurrentContext()->willReturn(NULL);
     $this->assertEquals('/e', $this->manager->getPathByAlias('/two/one/E'));
     $this->assertEquals('/two/one/E', $this->manager->getAliasByPath('/e'));
+
     $this->resolver->getCurrentContext()->willReturn('one');
     $this->assertEquals('/two/E', $this->manager->getPathByAlias('/two/E'));
     $this->assertEquals('/e', $this->manager->getPathByAlias('/two/one/E'));
     $this->assertEquals('/two/one/E', $this->manager->getAliasByPath('/e'));
+
+    $this->resolver->getCurrentContext()->willReturn('two');
+    $this->assertEquals('/e', $this->manager->getPathByAlias('/one/E'));
+    $this->assertEquals('/one/E', $this->manager->getAliasByPath('/e'));
   }
 
 }