SiteLanguages

WS >= 0.95

SiteLanguages предоставляет список языков сайта и помогает выбирать язык по коду или URL-префиксу.

Поддерживает

проверку состояния языковых настроек
получение всех или только активных языков
получение языка по умолчанию
поиск языка по коду
поиск активного языка по URL-префиксу
проверку и нормализацию переданного кода языка
работу с основной или переданной базой данных

Для работы создайте экземпляр класса:

php

$languages = new SiteLanguages();

Быстрый старт

php

$languages = new SiteLanguages();

if (!$languages->isValid()) {
    return;
}

foreach ($languages->all(true) as $language) {
    echo $language['code'] . ': ' . $language['label'];
}

Аргумент true передаётся в all(), чтобы получить только активные языки.

Состояние настроек

isValid(): bool

Возвращает true, если языковые настройки заполнены корректно:

php

if (!$languages->isValid()) {
    return;
}

Корректные настройки должны содержать активные языки и один активный язык по умолчанию.

isEnabled(): bool

Возвращает состояние мультиязычности:

php

if ($languages->isEnabled()) {
    // На сайте используются языковые URL.
}

false может означать, что мультиязычность отключена или языковые настройки недействительны. Для проверки настроек отдельно используйте isValid().

Формат данных языка

Методы, возвращающие один язык, предоставляют массив следующего вида:

Ключ	Тип	Описание
`code`	`string`	Код языка.
`label`	`string`	Отображаемое название языка.
`prefix`	`string`	Префикс языка в URL.
`default`	`bool`	Является ли язык языком по умолчанию.
`active`	`bool`	Активен ли язык.
`order`	`int`	Порядок языка в списке.

Код и URL-префикс являются отдельными значениями и могут различаться.

Получение списка

all(bool $activeOnly = false): array

Без аргумента возвращает все настроенные языки:

php

$allLanguages = $languages->all();

Чтобы получить только активные языки, передайте true:

php

$activeLanguages = $languages->all(true);

Языки возвращаются в настроенном порядке.

Если языковые настройки недействительны, метод возвращает пустой массив.

Язык по умолчанию

getDefault(): ?array

Возвращает активный язык сайта по умолчанию:

php

$defaultLanguage = $languages->getDefault();

if ($defaultLanguage !== null) {
    echo $defaultLanguage['label'];
}

Если язык по умолчанию недоступен, метод возвращает null.

defaultCode(string $fallback = 'ru'): string

Возвращает код языка по умолчанию:

php

$code = $languages->defaultCode();

Можно передать резервный код:

php

$code = $languages->defaultCode('en');

Резервное значение используется, если код языка по умолчанию получить невозможно. Недопустимое резервное значение заменяется на ru.

Поиск по коду

getByCode(string $code, bool $activeOnly = true): ?array

Возвращает активный язык по его коду:

php

$language = $languages->getByCode('en');

По умолчанию неактивные языки не возвращаются. Для поиска среди всех настроенных языков передайте false:

php

$language = $languages->getByCode('en', false);

Если язык не найден, метод возвращает null.

Код перед поиском приводится к нижнему регистру, а пробелы по краям удаляются.

Поиск по префиксу

getByPrefix(string $prefix): ?array

Возвращает активный язык по URL-префиксу:

php

$language = $languages->getByPrefix('en');

Передавайте префикс без символов /.

Если активный язык с таким префиксом не найден, метод возвращает null.

Определение кода

resolveCode(?string $code, bool $activeOnly = true, string $fallback = 'ru'): string

Проверяет переданный код и возвращает его, если соответствующий язык существует:

php

$code = $languages->resolveCode('en');

Если код пустой, имеет неверный формат или язык недоступен, возвращается код языка по умолчанию:

php

$code = $languages->resolveCode(null);

Чтобы разрешить неактивный язык, передайте false вторым параметром:

php

$code = $languages->resolveCode('en', false);

Третий параметр задаёт резервный код на случай, если язык по умолчанию получить невозможно:

php

$code = $languages->resolveCode(null, true, 'en');

База данных

__construct(?Database $db = null)

Без аргументов класс использует основную базу данных CMS:

php

$languages = new SiteLanguages();

При необходимости можно передать другой экземпляр Database:

php

$languages = new SiteLanguages($database);

Важные замечания

экземпляр получает состояние языков при создании
isValid() проверяет настройки, а isEnabled() — состояние мультиязычности
all() без аргумента включает неактивные языки
getDefault() возвращает только активный язык
getByCode() по умолчанию ищет только активные языки
getByPrefix() всегда ищет только среди активных языков
код языка и его URL-префикс могут различаться