README

通过他们的“基础”模板帮助工作与URL。
例如，你项目URL的基础结构是 "gb.example.com/en/london/"。在这个例子中，你的模板URL有以下的参数：“country”，“language”和“city”。
让我们为这个例子创建一个模板: "{country}.example.com/{language}/{city}"

安装

$ composer require ali-translator/url-template

代码示例

use ALI\UrlTemplate\UrlTemplateConfig;
use ALI\UrlTemplate\UrlTemplateResolver;

$urlTemplateConfig = new UrlTemplateConfig(
    '{country}.example.com',
    '{language}/{city}/',
    // Regular expressions that match the parameters  
    [
        'country' => ['uk','ua','pl'],
        'language' => '[a-z]{2}', // be careful with some free regular expressions
        'city' => ['kiev','berlin','paris','london'],
    ],
    // If you have some default parameters that may be empty in url, set them here
    [
        'city' => 'berlin',
        'language' => 'en',
    ],
    // hide defaults parameters from url ?
    true
);
$urlTemplateResolver = new UrlTemplateResolver($urlTemplateConfig);

$url = 'https://gb.example.com/de/london/';

// Parse exist url
$parsedUrlTemplate = $urlTemplateResolver->parseCompiledUrl($url);
var_dump($parsedUrlTemplate->getFullParameters());

// Change some parameter on existed url
$parsedUrlTemplate->setParameter('country','pl');
$urlWithAnotherCountry = $urlTemplateResolver->compileUrl($parsedUrlTemplate);
var_dump($urlWithAnotherCountry);

// Get clear url(without template parameters) for application routing
$simplifiedUrl = $urlTemplateResolver->getSimplifiedUrl($parsedUrlTemplate);
var_dump($simplifiedUrl); // -> "https://example.com"

// Generate full url from simplified url(which application return)
$parsedUrlTemplate = $urlTemplateResolver->generateParsedUrlTemplate('https://example.com/some-category/item?sale=1',[
    'country' => 'uk',
    'city' => 'london',
     // 'language' => 'en', // Default values may be skipped
]);
$compiledUrl = $urlTemplateResolver->compileUrl($parsedUrlTemplate);
var_dump($compiledUrl); // -> "https://uk.example.com/london/some-category/item?sale=1"

// As you may see, in url was skipped default language value "en"
// If you want their in url, you must set "false" to last parameter "isHideDefaultParameters" on constructor of UrlTemplateConfig

警告：在使用某些免费的正则表达式时请小心，例如对于语言'[a-z]{2}'，更好的选择是'(en|de|ua)'

可选默认值

你可以设置参数的可选默认值。为此，你必须为默认值设置可调用的参数。
你的可选参数只能依赖于所需参数。

使用示例

use ALI\UrlTemplate\UrlTemplateConfig;

$urlTemplateConfig = new UrlTemplateConfig(
    '{country}.test.com',
    '/{language}/',
    [
        'country' => ['tr','gb'],
        'language' => ['en','tr','de'],
    ],
    [
        'language' => function ($requiredParameters) {
            switch ($requiredParameters['country']) {
  case 'tr':
                    return 'tr';
                break;
                case 'gb':
                    return 'en';
                break;
                default:
                    throw new Exception('Invalid country alias');
                break;
            }
        },
    ],
    true
);

参数装饰器

有时你需要为URL中的参数添加一些装饰。
例如，如果你想下一个路径模板是"/{country}-{language}/"，你决定隐藏默认语言。
在这种情况下，如果没有装饰器，你将得到以下编译后的URL："/country-/"
过多的字符"-"看起来不好。
你可以使用装饰器解决这个问题。
装饰器 - 实现了 "ParameterDecoratorInterface" 的类。

使用示例

use ALI\UrlTemplate\ParameterDecorators\WrapperParameterDecorator;
use ALI\UrlTemplate\UrlTemplateConfig;

$urlTemplateConfig = new UrlTemplateConfig(
    null,
    '/{country}{language}/',
    [
        'country' => ['ua', 'pl'],
        'language' => ['ua', 'en', 'de'],
    ],
    [
        'city' => 'berlin',
        'language' => 'en',
    ],
    true,
    [
        'language' => new WrapperParameterDecorator('-'),
    ]
);

为了正确地工作装饰器，使用包含要求、可用值的数组，而不是正则表达式。

验证解析模板对象

use \ALI\UrlTemplate\UrlTemplateResolver\ParsedUrlTemplateValidator;
use \ALI\UrlTemplate\ParsedUrlTemplate;

/** @var ParsedUrlTemplate $parsedUrlTemplate */

$urlTemplateValidator = new ParsedUrlTemplateValidator();
$errors = $urlTemplateValidator->validateParameters($parsedUrlTemplate);
// $errors : [key -> (string)'error description']

附加功能

你还可以使用在一个“URL命名空间”中放置几个参数的模板，例如主机"{country}-{language}-{currency}.test.com"和路径"/{country}-{language}/"。
如果你只需要编译“主机URL”或“路径URL”，请使用 $urlTemplateResolver->compileUrl($parsedUrl, $urlTemplateResolver::COMPILE_TYPE_HOST)
如果你需要从URL中排除一些默认参数，你可以设置一个参数名称数组给UrlTemplateConfig类的$hideDefaultParametersFromUrl参数。
如果你有一个可选参数依赖于另一个参数，而这个另一个参数在URL的另一部分（例如，可选参数在“路径URL部分”，它依赖于“主机URL部分”中的参数），那么当需要处理没有主机的相对URL时，可能会出现问题。
为了能够传递可选参数的值，你需要调用一个确定可选参数的函数
```
...
[
  'language' => function ($requiredParametersValues) use ($currentCountryAlias) {
      $countryAlias = $requiredParametersValues['country'] ?? $currentCountryAlias;
...
```

通过现有的创建新的 UrlTemplateConfig

/** @var $urlTemplateConfig ALI\UrlTemplate\UrlTemplateConfig */
$urlTemplateConfigData = $urlTemplateConfig->generateUrlTemplateConfigData();
// Change some config data
$urlTemplateConfigData->setDefaultUrlSchema('https');
// Create new UrlTemplateConfig
$newUrlTemplateConfig = $urlTemplateConfigData->generateUrlTemplateConfig();

测试

在包中存在docker-compose文件，用于测试环境。

docker-compose up -d
docker-compose exec php bash
composer install
./vendor/bin/phpunit

ali-translator / url-template

维护者

详细信息