1:   2:   3:   4:   5:   6:   7:   8:   9:  10:  11:  12:  13:  14:  15:  16:  17:  18:  19:  20:  21:  22:  23:  24:  25:  26:  27:  28:  29:  30:  31:  32:  33:  34:  35:  36:  37:  38:  39:  40:  41:  42:  43:  44:  45:  46:  47:  48:  49:  50:  51:  52:  53:  54:  55:  56:  57:  58:  59:  60:  61:  62:  63:  64:  65:  66:  67:  68:  69:  70:  71:  72:  73:  74:  75:  76:  77:  78:  79:  80:  81:  82:  83:  84:  85:  86:  87:  88:  89:  90:  91:  92:  93:  94:  95:  96:  97:  98:  99: 100: 101: 102: 103: 104: 105: 106: 107: 108: 109: 110: 111: 112: 113: 114: 115: 116: 117: 118: 119: 120: 121: 122: 123: 124: 125: 126: 127: 128: 129: 130: 131: 132: 133: 134: 135: 136: 137: 138: 139: 140: 141: 142: 143: 144: 145: 146: 147: 148: 149: 150: 151: 152: 153: 154: 155: 156: 157: 158: 159: 160: 161: 162: 163: 164: 165: 166: 167: 168: 169: 

<?php

/**
 * MvcCore
 *
 * This source file is subject to the BSD 3 License
 * For the full copyright and license information, please view
 * the LICENSE.md file that are distributed with this source code.
 *
 * @copyright   Copyright (c) 2016 Tom Flidr (https://github.com/mvccore)
 * @license     https://mvccore.github.io/docs/mvccore/5.0.0/LICENCE.md
 */

namespace MvcCore\Ext\Routers;

interface IModule {

    /**
     * URL param name to build absolute URL by desired module domain route .
     */
    const URL_PARAM_MODULE = 'module';

    /**
     * Clear all possible previously configured module domain routes and set new 
     * given routes again collection again. If there is no module property 
     * configured in given route item in array configuration, route module is set
     * by given `$routes` array key, if key is not numeric.
     *
     * Routes could be defined in various forms:
     * Example:
     * `\MvcCore\Router::GetInstance()->SetDomainRoutes([
     *      "blog"  => [
     *          "pattern"               => "//blog.%sld%.%tld%",
     *          "namespace"             => "Blog",
     *          "defaults"              => ["page" => 1],
     *          "constraints"           => ["page" => "\d+"],
     *          "allowedLocalizations"  => ["en-US"],
     *          "allowedMediaVersions"  => ["full" => ""]
     *      ],
     *      "main"  => [
     *          "pattern"               => "//%domain%",
     *          "allowedLocalizations"  => ["en-US", "de-DE"],
     *          "allowedMediaVersions"  => ["mobile" => "m", "full" => ""]
     *      ]
     * ]);`
     * or:
     * `\MvcCore\Router::GetInstance()->SetDomainRoutes([
     *      new \MvcCore\Ext\Routers\Modules\Route(
     *          "//blog.%sld%.%tld%",   // pattern
     *          "blog",                 // module
     *          "Blog",                 // namespace
     *          ["page" => 1],          // defaults
     *          ["page" => "\d+"],      // constraints
     *          [                       // advanced configuration
     *              "allowedLocalizations"  => ["en-US"],
     *              "allowedMediaVersions"  => ["full" => ""]
     *          ]
     *      ),
     *      new \MvcCore\Ext\Routers\Modules\Route([
     *          "pattern"               => "//%domain%",
     *          "module"                => "main",
     *          "allowedLocalizations"  => ["en-US", "de-DE"],
     *          "allowedMediaVersions"  => ["mobile" => "m", "full" => ""]
     *      ])
     * ]);`
     * @param \MvcCore\Ext\Routers\Modules\Route[]|array|array[] $routes 
     * @param bool $autoInitialize 
     * @throws \InvalidArgumentException 
     * @return \MvcCore\Ext\Routers\Module
     */
    public function SetDomainRoutes ($routes = [], $autoInitialize = TRUE);

    /**
     * Append or prepend new module domain routes. If there is no module property 
     * configured in given route item in array configuration, route module is set
     * by given `$routes` array key, if key is not numeric.
     *
     * Routes could be defined in various forms:
     * Example:
     * `\MvcCore\Router::GetInstance()->AddDomainRoutes([
     *      "blog"  => [
     *          "pattern"               => "//blog.%sld%.%tld%",
     *          "namespace"             => "Blog",
     *          "defaults"              => ["page" => 1],
     *          "constraints"           => ["page" => "\d+"],
     *          "allowedLocalizations"  => ["en-US"],
     *          "allowedMediaVersions"  => ["full" => ""]
     *      ],
     *      "main"  => [
     *          "pattern"               => "//%domain%",
     *          "allowedLocalizations"  => ["en-US", "de-DE"],
     *          "allowedMediaVersions"  => ["mobile" => "m", "full" => ""]
     *      ]
     * ]);`
     * or:
     * `\MvcCore\Router::GetInstance()->AddDomainRoutes([
     *      new \MvcCore\Ext\Routers\Modules\Route(
     *          "//blog.%sld%.%tld%",   // pattern
     *          "blog",                 // module
     *          "Blog",                 // namespace
     *          ["page" => 1],          // defaults
     *          ["page" => "\d+"],      // constraints
     *          [                       // advanced configuration
     *              "allowedLocalizations"  => ["en-US"],
     *              "allowedMediaVersions"  => ["full" => ""]
     *          ]
     *      ),
     *      new \MvcCore\Ext\Routers\Modules\Route([
     *          "pattern"               => "//%domain%",
     *          "module"                => "main",
     *          "allowedLocalizations"  => ["en-US", "de-DE"],
     *          "allowedMediaVersions"  => ["mobile" => "m", "full" => ""]
     *      ])
     * ]);`
     * @param \MvcCore\Ext\Routers\Modules\Route[]|array|array[] $routes 
     * @param bool $prepend 
     * @param bool $throwExceptionForDuplication 
     * @throws \InvalidArgumentException 
     * @return \MvcCore\Ext\Routers\Module
     */
    public function AddDomainRoutes ($routes, $prepend = FALSE, $throwExceptionForDuplication = TRUE);

    /**
     * Append or prepend new module domain route.
     * Example:
     * `\MvcCore\Router::GetInstance()->AddDomainRoute([
     *      "blog"  => [
     *          "pattern"               => "//blog.%sld%.%tld%",
     *          "namespace"             => "Blog",
     *          "defaults"              => ["page" => 1],
     *          "constraints"           => ["page" => "\d+"],
     *          "allowedLocalizations"  => ["en-US"],
     *          "allowedMediaVersions"  => ["full" => ""]
     *      ],
     *      "main"  => [
     *          "pattern"               => "//%domain%",
     *          "allowedLocalizations"  => ["en-US", "de-DE"],
     *          "allowedMediaVersions"  => ["mobile" => "m", "full" => ""]
     *      ]
     * ]);`
     * or:
     * `\MvcCore\Router::GetInstance()->AddDomainRoute([
     *      new \MvcCore\Ext\Routers\Modules\Route(
     *          "//blog.%sld%.%tld%",   // pattern
     *          "blog",                 // module
     *          "Blog",                 // namespace
     *          ["page" => 1],          // defaults
     *          ["page" => "\d+"],      // constraints
     *          [                       // advanced configuration
     *              "allowedLocalizations"  => ["en-US"],
     *              "allowedMediaVersions"  => ["full" => ""]
     *          ]
     *      ),
     *      new \MvcCore\Ext\Routers\Modules\Route([
     *          "pattern"               => "//%domain%",
     *          "module"                => "main",
     *          "allowedLocalizations"  => ["en-US", "de-DE"],
     *          "allowedMediaVersions"  => ["mobile" => "m", "full" => ""]
     *      ])
     * ]);`
     * @param \MvcCore\Ext\Routers\Modules\Route|array $routeCfgOrRoute 
     * @param bool $prepend 
     * @param bool $throwExceptionForDuplication 
     * @throws \InvalidArgumentException 
     * @return \MvcCore\Ext\Routers\Module
     */
    public function AddDomainRoute ($routeCfgOrRoute, $prepend = FALSE, $throwExceptionForDuplication = TRUE);
}