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: 

<?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\Extendeds;

/**
 * Responsibility: configurable protected properties with getters and setters,
 *                 internal protected properties and internal methods used 
 *                 in most extended router implementations bellow.
 * Trait for classes:
 * - `\MvcCore\Ext\Routers\Media`
 * - `\MvcCore\Ext\Routers\Localization`
 * - `\MvcCore\Ext\Routers\MediaAndLocalization`
 */
trait Url {

    /**
     * Complete semi-finished result URL as two section strings and system 
     * params array. First section as base section with scheme, domain and base 
     * path, second section as application requested path and query string and 
     * third section as system params like `localization` or `media_version`.
     * Those params could be inserted between first two sections as system 
     * params in result URL by router behaviour and default values. Or it could 
     * be inserted into domain part in more extended routers.
     * Example:
     *  Input (`\MvcCore\Route::$reverse`):
     *  `[
     *      "en"    => "/products-list/<name>/<color>"`,
     *      "de"    => "/produkt-liste/<name>/<color>"`,
     *  ]`
     *  Input ($params):
     *      `array(
     *          "name"          => "cool-product-name",
     *          "color"         => "red",
     *          "variant"       => ["L", "XL"],
     *          "localization"  => "en-US",
     *          "media_version" => "mobile",
     *      );`
     *  Output:
     *      `[
     *          "/application/base/bath", 
     *          "/products-list/cool-product-name/blue?variant[]=L&amp;variant[]=XL", 
     *          ["media_version" => "m", "localization" => "en-US"]
     *      ]`
     * @param \MvcCore\Route $route
     * @param array $params
     * @param string $urlParamRouteName
     * @return array `string $urlBaseSection, string $urlPathWithQuerySection, array $systemParams`
     */
    protected abstract function urlByRouteSections (\MvcCore\IRoute $route, array & $params = [], $urlParamRouteName = NULL);

    /**
     * Get `TRUE` if path with query string target homepage - `/` (or `/index.php` - request script name)
     * @param string $pathWithQueryString URL path part with possible query string.
     * @return bool
     */
    protected function urlIsHomePath ($pathWithQueryString) {
        /** @var $this \MvcCore\Ext\Routers\Extended */
        $questionMarkPos = mb_strpos($pathWithQueryString, '?');
        $pathWithoutQueryString = $questionMarkPos !== FALSE 
            ? mb_substr($pathWithQueryString, 0, $questionMarkPos)
            : $pathWithQueryString;
        return trim($pathWithoutQueryString, '/') === '' || $pathWithoutQueryString == $this->request->GetScriptName();
    }

    /**
     * Complete final URL, simply concatenate strings from three given sources:
     * - `$urlBaseSection`
     *   - Begin URL part containing http, domain and base path like:
     *     `https://domain.com/path/to/app`
     * - `$urlPathWithQuerySection`
     *   - Subject url part with application path and possible query string:
     *     `/some/path?with=query`
     * - `$systemParams`
     *   - Array to implode it's values into string with system params 
     *     like media site version or localization:
     *     `['media_version' => 'm', 'localization' => 'en-US']`
     * Example output:
     * - `https://domain.com/path/to/app/m/en-US/some/path?with=query`
     * @param string    $urlBaseSection             URL section with domain part and possible base path part.
     * @param string    $urlPathWithQuerySection    URL section with path and query string.
     * @param array     $systemParams               System params to create URL prefixes from array values.
     * @param bool      $urlPathWithQueryIsHome     `TRUE` if URL section with path and query string targets `/` 
     *                                              (or `/index.php` - request script name)
     * @return string
     */
    protected function urlByRoutePrefixSystemParams ($urlBaseSection, $urlPathWithQuerySection, array $systemParams = [], $urlPathWithQueryIsHome = NULL) {
        /** @var $this \MvcCore\Ext\Routers\Extended */
        // complete prefixes section from system params
        $urlPrefixesSection = trim(implode('/', array_values($systemParams)), '/');
        $urlPrefixesSectionHasValue = $urlPrefixesSection !== '';

        if ($urlPrefixesSectionHasValue) {
            $urlPrefixesSection = '/' . $urlPrefixesSection;

            // finalizing possible trailing slash after prefix if any prefix
            if ($this->trailingSlashBehaviour === \MvcCore\IRouter::TRAILING_SLASH_REMOVE) {
                if ($urlPathWithQueryIsHome === NULL)
                    $urlPathWithQueryIsHome = $this->urlIsHomePath($urlPathWithQuerySection);
                if ($urlPathWithQueryIsHome)
                    $urlPathWithQuerySection = ltrim($urlPathWithQuerySection, '/');    
            }
        }

        return $urlBaseSection . $urlPrefixesSection . $urlPathWithQuerySection;
    }
}