README

语言服务提供了一种管理PHP应用程序语言的方式。

入门

运行以下命令添加运行中的语言服务项目最新版本。

composer require tobento/service-language

要求

PHP 8.0 或更高版本

亮点

框架无关，与任何项目兼容
解耦设计

文档

语言

创建语言

使用提供的工厂轻松创建语言

use Tobento\Service\Language\LanguageFactory;
use Tobento\Service\Language\LanguageInterface;

$languageFactory = new LanguageFactory();

$language = $languageFactory->createLanguage('en');

var_dump($language instanceof LanguageInterface);
// bool(true)

参数

use Tobento\Service\Language\LanguageFactory;

$languageFactory = new LanguageFactory();

$language = $languageFactory->createLanguage(
    locale: 'en-US',
    name: 'English',
    key: 'en-us',
    id: 1,
    iso: 'en',
    region: 'US',
    slug: 'en',
    directory: 'enUs',
    direction: 'ltr',
    area: 'frontend',
    domain: 'example.com',
    url: 'https://www.example.com',
    fallback: 'en',
    default: false,
    active: true,
    editable: true,
    order: 2,
);

语言界面

use Tobento\Service\Language\LanguageFactory;
use Tobento\Service\Language\LanguageInterface;

$languageFactory = new LanguageFactory();

$language = $languageFactory->createLanguage('en-US');

var_dump($language instanceof LanguageInterface);
// bool(true)

var_dump($language->locale());
// string(5) "en-US"

var_dump($language->iso());
// string(2) "en"

var_dump($language->region());
// string(2) "US" or returns NULL if no region.

var_dump($language->name());
// string(5) "en-US"

var_dump($language->key());
// string(5) "en-us"

var_dump($language->id());
// int(0)

var_dump($language->slug());
// string(5) "en-us"

var_dump($language->directory());
// string(5) "en-us"

var_dump($language->direction());
// string(3) "ltr"

var_dump($language->area());
// string(7) "default"

var_dump($language->domain());
// NULL or returns string if has domain.

var_dump($language->url());
// NULL or returns string if has url.

var_dump($language->fallback());
// NULL or returns string if has fallback

var_dump($language->default());
// bool(false)

var_dump($language->active());
// bool(true)

var_dump($language->editable());
// bool(true)

var_dump($language->order());
// int(2)

语言

创建语言

use Tobento\Service\Language\LanguageFactory;
use Tobento\Service\Language\Languages;
use Tobento\Service\Language\LanguagesInterface;

$languageFactory = new LanguageFactory();

$languages = new Languages(
    $languageFactory->createLanguage('en', default: true),
    $languageFactory->createLanguage('de', fallback: 'en'),
    $languageFactory->createLanguage('de-CH', fallback: 'de'),
    $languageFactory->createLanguage('fr', fallback: 'en', active: false),
    $languageFactory->createLanguage('it', fallback: 'de', active: false),
);

var_dump($languages instanceof LanguagesInterface);
// bool(true)

从数组创建语言

use Tobento\Service\Language\LanguageFactory;
use Tobento\Service\Language\Languages;
use Tobento\Service\Language\LanguagesInterface;

$languageFactory = new LanguageFactory();

$languages = new Languages(
    ...$languageFactory->createLanguagesFromArray([
        ['locale' => 'en', 'default' => true],
        ['locale' => 'de', 'fallback' => 'en'],
        ['locale' => 'fr', 'fallback' => 'en'],
    ])
);

var_dump($languages instanceof LanguagesInterface);
// bool(true)

获取语言

use Tobento\Service\Language\LanguageFactory;
use Tobento\Service\Language\Languages;
use Tobento\Service\Language\LanguagesInterface;
use Tobento\Service\Language\LanguageInterface;

$languageFactory = new LanguageFactory();

$languages = new Languages(
    $languageFactory->createLanguage('en', default: true),
    $languageFactory->createLanguage('de', fallback: 'en'),
);

$language = $languages->get('de-CH');
// supports locale, id, key or slug values (all are case-insensitive).

var_dump($language instanceof LanguageInterface);
// bool(true)

// Will return the default language as language does not exist.
var_dump($languages->get('it')->locale());
// string(2) "en"

// Without fallback
var_dump($languages->get('fr', fallback: false)?->locale());
// NULL

var_dump($languages->get('it', fallback: false)?->locale());
// NULL

检查语言是否存在

// supports locale, id, key or slug values (all are case-insensitive).

var_dump($languages->has('de-CH')); 
// bool(true)

var_dump($languages->has('fr'));
// bool(false)

默认语言

use Tobento\Service\Language\LanguageInterface;

$defaultLanguage = $languages->default();

var_dump($defaultLanguage instanceof LanguageInterface);
// bool(true)

当前语言

设置当前语言

$languages->current('en');
// supports locale, id, key or slug values (all are case-insensitive).

⚠️ 如果语言不存在，将设置默认语言为当前语言，但前提是没有定义任何语言。

获取当前语言

use Tobento\Service\Language\LanguageInterface;

$currentLanguage = $languages->current();

var_dump($currentLanguage instanceof LanguageInterface);
// bool(true)

所有语言

use Tobento\Service\Language\LanguageInterface;

$allLanguages = $languages->all();
// array<int, LanguageInterface>

// or just
foreach($languages as $language) {}

列

有时你可能只需要从语言中获取特定的列。

$locales = $languages->column('locale');
/*Array
(
    [0] => en
    [1] => de
    [2] => de-CH
)*/

按语言ID索引

$locales = $languages->column('locale', 'id');
/*Array
(
    [1] => en
    [2] => de
    [3] => de-CH
)*/

后备

获取后备

返回所有语言的后备。

// by locale
$fallbacks = $languages->fallbacks();
/*Array
(
    [de] => en
    [de-CH] => de
    [fr] => en
    [it] => de
)*/

// by id:
$fallbacks = $languages->fallbacks('id');
/*Array
(
    [2] => 1
    [3] => 2
    [4] => 1
    [5] => 2
)*/

// by key:
$fallbacks = $languages->fallbacks('key');
/*Array
(
    [de] => en
    [de-ch] => de
    [fr] => en
    [it] => de
)*/

// by slug:
$fallbacks = $languages->fallbacks('slug');
/*Array
(
    [de] => en
    [de-ch] => de
    [fr] => en
    [it] => de
)*/

获取特定区域、ID、键或短语的后备语言

如果没有提供后备语言，将返回默认语言。

use Tobento\Service\Language\LanguageInterface;

$fallbackLanguage = $languages->getFallback('de-CH');

var_dump($fallbackLanguage instanceof LanguageInterface);
// bool(true)

其他方法

first

use Tobento\Service\Language\LanguageInterface;

// returns first found active language:
var_dump($languages->first() instanceof LanguageInterface);
// bool(true) or NULL

// returns first found language:
$firstLanguage = $languages->first(activeOnly: false);

filter

过滤语言，返回新的实例。

use Tobento\Service\Language\LanguageInterface;

$languagesNew = $languages->filter(
    fn(LanguageInterface $l): bool => $l->active()
);

active

返回一个新的实例，包含活动或非活动语言。

use Tobento\Service\Language\LanguageInterface;

$activeLanguages = $languages->active();

$inactiveLanguages = $languages->active(active: false);

domain

返回一个新的实例，其中包含已指定域过滤。

use Tobento\Service\Language\LanguageInterface;

$chLanguages = $languages->domain('example.ch');

$undomainedLanguages = $languages->domain(null);

map

映射每个语言，返回一个新的实例。

use Tobento\Service\Language\LanguageInterface;

$languagesNew = $languages->map(
    fn(LanguageInterface $l): LanguageInterface => $l->withName(strtoupper($l->name()))
);

sort

对语言进行排序，返回一个新的实例。

use Tobento\Service\Language\LanguageInterface;

$languagesNew = $languages->sort(
    fn(LanguageInterface $a, LanguageInterface $b) => $a->locale() <=> $b->locale()
);

区域语言

创建区域语言

use Tobento\Service\Language\LanguageFactory;
use Tobento\Service\Language\AreaLanguages;
use Tobento\Service\Language\AreaLanguagesInterface;
use Tobento\Service\Language\LanguagesFactoryInterface;

$languageFactory = new LanguageFactory();

$areaLanguages = new AreaLanguages(
    null, // null|LanguagesFactoryInterface
    $languageFactory->createLanguage('en', area: 'frontend', default: true),
    $languageFactory->createLanguage('de', area: 'frontend', fallback: 'en'),
    $languageFactory->createLanguage('de-CH', area: 'frontend', fallback: 'de'),   
    $languageFactory->createLanguage('en', area: 'backend', default: true),
    $languageFactory->createLanguage('de', area: 'backend', fallback: 'en'), 
);

var_dump($areaLanguages instanceof AreaLanguagesInterface);
// bool(true)

get / has

use Tobento\Service\Language\LanguagesInterface;

$frontendLanguages = $areaLanguages->get('frontend');

var_dump($frontendLanguages instanceof LanguagesInterface);
// bool(true)

// return NULL if no languages found:
var_dump($areaLanguages->get('api'));
// NULL

var_dump($areaLanguages->has('frontend'));
// bool(true)

当前语言解析器

你可能想使用当前语言解析器来设置当前语言。你也可以根据需要编写自己的解析器，例如CurrentLanguageSessionResolver、CurrentLanguageServerRequestResolver等。

use Tobento\Service\Language\LanguageFactory;
use Tobento\Service\Language\Languages;
use Tobento\Service\Language\LanguagesInterface;
use Tobento\Service\Language\CurrentLanguageResolver;
use Tobento\Service\Language\CurrentLanguageResolverInterface;
use Tobento\Service\Language\CurrentLanguageResolverException;

$languageFactory = new LanguageFactory();

$languages = new Languages(
    $languageFactory->createLanguage('en', default: true),
    $languageFactory->createLanguage('de'),
);

$resolver = new CurrentLanguageResolver(
    currentLanguage: 'fr',
    allowFallbackToDefaultLanguage: false, // default is true
);

var_dump($resolver instanceof CurrentLanguageResolverInterface);
// bool(true)

try {
    $resolver->resolve($languages);
} catch (CurrentLanguageResolverException $e) {
    // do something
}

tobento / service-language

维护者

详细信息

README

目录

入门

要求

亮点

文档

语言

创建语言

语言界面

语言

创建语言

获取语言

默认语言

当前语言

所有语言

列

后备

其他方法

区域语言

当前语言解析器

鸣谢