Функция cot_langfile в Cotonti

Описание функции cot_langfile.

Функция cot_langfile предназначена для получения пути к языковому файлу для расширений (модулей или плагинов) или основной части системы. Она проверяет наличие языкового файла для заданного расширения (или части системы) в разных местах и возвращает путь к первому найденному файлу.

/**
 * Returns a language file path for an extension or core part.
 *
 * @param string $name Part name (area code or plugin name)
 * @param string $type Part type: 'plug', 'module' or 'core'
 * @param string $default Default (fallback) language code
 * @param string $lang Set this to override global $lang
 * @return ?string Langfile path or NULL if no suitable files were found
 */
function cot_langfile($name, $type = ExtensionsDictionary::TYPE_PLUGIN, $default = 'en', $lang = null): ?string
{
    global $cfg;

    if (!is_string($lang)) {
        global $lang;
    }

    if ($type === ExtensionsDictionary::TYPE_MODULE) {
        if (@file_exists($cfg['lang_dir'] . "/$lang/modules/$name.$lang.lang.php")) {
            return $cfg['lang_dir'] . "/$lang/modules/$name.$lang.lang.php";
        }
        if (@file_exists($cfg['modules_dir'] . "/$name/lang/$name.$lang.lang.php")) {
            return $cfg['modules_dir'] . "/$name/lang/$name.$lang.lang.php";
        }
        if (@file_exists($cfg['modules_dir'] . "/$name/lang/$name.$default.lang.php")) {
            return $cfg['modules_dir'] . "/$name/lang/$name.$default.lang.php";
        }
    } elseif ($type === ExtensionsDictionary::TYPE_CORE) {
        if (@file_exists($cfg['lang_dir'] . "/$lang/$name.$lang.lang.php")) {
            return $cfg['lang_dir'] . "/$lang/$name.$lang.lang.php";
        }
        if (@file_exists($cfg['lang_dir'] . "/$default/$name.$default.lang.php")) {
            return $cfg['lang_dir'] . "/$default/$name.$default.lang.php";
        }
    } else {
        if (@file_exists($cfg['lang_dir'] . "/$lang/plugins/$name.$lang.lang.php")) {
            return $cfg['lang_dir'] . "/$lang/plugins/$name.$lang.lang.php";
        }
        if (@file_exists($cfg['plugins_dir']."/$name/lang/$name.$lang.lang.php")) {
            return $cfg['plugins_dir'] . "/$name/lang/$name.$lang.lang.php";
        }
        if (@file_exists($cfg['plugins_dir']."/$name/lang/$name.$default.lang.php")) {
            return $cfg['plugins_dir'] . "/$name/lang/$name.$default.lang.php";
        }
    }

    return null;
}

Давайте разберем эту функцию по частям.

Параметры функции:

$name (string): Имя расширения, модуля или части системы, для которой ищется языковой файл.
$type (string, по умолчанию ExtensionsDictionary::TYPE_PLUGIN): Тип части системы, для которой ищется языковой файл. Это может быть:
ExtensionsDictionary::TYPE_MODULE — для модуля.
ExtensionsDictionary::TYPE_CORE — для основного компонента системы.
ExtensionsDictionary::TYPE_PLUGIN — для плагина.
$default (string, по умолчанию 'en'): Языковой код по умолчанию, который используется, если нужный языковой файл не найден для заданного языка.
$lang (string, по умолчанию null): Язык для загрузки. Если не задан, используется глобальная переменная $lang.

Логика работы:

Проверка языка:

Если параметр $lang не задан, то используется глобальная переменная $lang.
Поиск файла в зависимости от типа расширения:

Модуль ($type === ExtensionsDictionary::TYPE_MODULE):
Проверяется наличие языкового файла для модуля в директориях для языка пользователя.
Если файл для заданного языка не найден, пробуется файл для языка по умолчанию.
Основная часть ($type === ExtensionsDictionary::TYPE_CORE):
Путь к языковому файлу проверяется для основного компонента системы (например, ядра).
Плагин ($type === ExtensionsDictionary::TYPE_PLUGIN):
Путь к языковому файлу проверяется для плагина.

Возвращаемое значение:

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

Пример записи

require_once cot_langfile('forums', 'module');

Пример использования:
 

$langFilePath = cot_langfile('gallery', 'plug', 'en', 'fr');

В этом примере:

Ищется языковой файл для плагина gallery.
Если файл для языка fr (французский) не найден, будет использоваться файл для языка по умолчанию — en (английский).

Давайте подробно разберем, что происходит внутри функции cot_langfile.

Функция: cot_langfile

 
function cot_langfile($name, $type = ExtensionsDictionary::TYPE_PLUGIN, $default = 'en', $lang = null): ?string
{
    global $cfg;
    
    

Параметры функции:

$name — имя расширения или части системы (например, имя плагина или модуля).
$type — тип расширения. Он определяет, будет ли это плагин, модуль или основная часть системы. Если не передан, по умолчанию используется значение ExtensionsDictionary::TYPE_PLUGIN.
$default — код языка по умолчанию, если для выбранного языка не удается найти файл. По умолчанию используется 'en' (английский).
$lang — язык, который следует использовать. Если не задан, используется глобальная переменная $lang.
Глобальная переменная $cfg используется для доступа к конфигурационным данным, таким как директории для языковых файлов.

Блок: Проверка языка

 
    if (!is_string($lang)) {
        global $lang;
    }
    

    
Здесь проверяется, является ли параметр $lang строкой. Если нет (то есть, если $lang не передан), то используется глобальная переменная $lang, которая, вероятно, устанавливается в другом месте в коде (например, на основе предпочтений пользователя или настроек сайта).

Блок: Поиск файлов для типа "module"
 

    if ($type === ExtensionsDictionary::TYPE_MODULE) {
        if (@file_exists($cfg['lang_dir'] . "/$lang/modules/$name.$lang.lang.php")) {
            return $cfg['lang_dir'] . "/$lang/modules/$name.$lang.lang.php";
        }
        if (@file_exists($cfg['modules_dir'] . "/$name/lang/$name.$lang.lang.php")) {
            return $cfg['modules_dir'] . "/$name/lang/$name.$lang.lang.php";
        }
        if (@file_exists($cfg['modules_dir'] . "/$name/lang/$name.$default.lang.php")) {
            return $cfg['modules_dir'] . "/$name/lang/$name.$default.lang.php";
        }
    }
    

    
Тип "module": Если тип расширения — это модуль ($type === ExtensionsDictionary::TYPE_MODULE), функция проверяет наличие языкового файла в следующих местах:
В директории для языковых файлов с учетом языка пользователя: $cfg['lang_dir'] . "/$lang/modules/$name.$lang.lang.php".
В директории модуля: $cfg['modules_dir'] . "/$name/lang/$name.$lang.lang.php".
Если ни один из этих файлов не найден, проверяется файл для языка по умолчанию: $cfg['modules_dir'] . "/$name/lang/$name.$default.lang.php".
Если один из файлов найден, возвращается его путь.

Блок: Поиск файлов для типа "core"
 

    elseif ($type === ExtensionsDictionary::TYPE_CORE) {
        if (@file_exists($cfg['lang_dir'] . "/$lang/$name.$lang.lang.php")) {
            return $cfg['lang_dir'] . "/$lang/$name.$lang.lang.php";
        }
        if (@file_exists($cfg['lang_dir'] . "/$default/$name.$default.lang.php")) {
            return $cfg['lang_dir'] . "/$default/$name.$default.lang.php";
        }
    }
    

    
Тип "core": Если тип расширения — это основная часть системы ($type === ExtensionsDictionary::TYPE_CORE), функция ищет языковой файл:
В директории для языковых файлов системы: $cfg['lang_dir'] . "/$lang/$name.$lang.lang.php".
Если не найден, проверяется файл для языка по умолчанию: $cfg['lang_dir'] . "/$default/$name.$default.lang.php".
Если найден файл, его путь возвращается.

Блок: Поиск файлов для типа "plugin"
 

    else {
        if (@file_exists($cfg['lang_dir'] . "/$lang/plugins/$name.$lang.lang.php")) {
            return $cfg['lang_dir'] . "/$lang/plugins/$name.$lang.lang.php";
        }
        if (@file_exists($cfg['plugins_dir']."/$name/lang/$name.$lang.lang.php")) {
            return $cfg['plugins_dir'] . "/$name/lang/$name.$lang.lang.php";
        }
        if (@file_exists($cfg['plugins_dir']."/$name/lang/$name.$default.lang.php")) {
            return $cfg['plugins_dir'] . "/$name/lang/$name.$default.lang.php";
        }
    }
    

Тип "plugin": Если тип расширения — это плагин ($type === ExtensionsDictionary::TYPE_PLUGIN), функция ищет языковой файл:
В директории для языковых файлов плагинов: $cfg['lang_dir'] . "/$lang/plugins/$name.$lang.lang.php".
В директории плагина: $cfg['plugins_dir']."/$name/lang/$name.$lang.lang.php".
Если не найден, проверяется файл для языка по умолчанию: $cfg['plugins_dir']."/$name/lang/$name.$default.lang.php".
Если найден файл, его путь возвращается.

Завершающая часть

 
    return null;
}

Если никакой из файлов не найден в предыдущих шагах, функция возвращает null, что означает, что соответствующий языковой файл не существует.

Заключение

Функция cot_langfile эффективно находит путь к языковому файлу для расширений (модулей, плагинов) или основной части системы. Она проверяет несколько возможных мест, где может находиться нужный файл, и возвращает путь к первому найденному файлу. Если файл не найден, возвращается null.

Функция cot_langfile полезна для работы с языковыми файлами расширений и позволяет гибко искать файлы в зависимости от типа расширения (модуль, плагин или ядро) и текущего языка пользователя. Она сначала ищет языковые файлы для указанного языка, а если их нет — пытается найти файл для языка по умолчанию.

Пояснения:

Типы расширений (module, core, plugin) позволяют определить, где именно искать языковой файл для каждого типа расширения.
Поиск с учетом языка пользователя: функция сначала ищет файлы для заданного языка, и только если их не находит, использует язык по умолчанию.

разберем такой пример применения этой функции

if ($i18n_locale) {
    require_once cot_langfile('i18n', 'plug', Cot::$cfg['defaultlang'], $i18n_locale);
}

 

Этот фрагмент кода использует функцию cot_langfile() для загрузки языкового файла для плагина i18n (интернационализации).

Давайте разберем по шагам:

Проверка переменной $i18n_locale:

if ($i18n_locale) {

Здесь выполняется проверка на наличие значения в переменной $i18n_locale. Если переменная установлена (т.е. имеет значение, не равное null, пустой строке или false), тогда код внутри блока выполняется.

Вызов функции cot_langfile():

require_once cot_langfile('i18n', 'plug', Cot::$cfg['defaultlang'], $i18n_locale);

'i18n' — это имя части, для которой загружается языковой файл. В данном случае, это плагин с кодом i18n, отвечающий за локализацию и интернационализацию.

'plug' — указывает тип расширения. В данном случае это плагин, поэтому второй аргумент plug говорит, что это плагин, а не модуль или основная часть.

Cot::$cfg['defaultlang'] — это язык по умолчанию, указанный в конфигурации сайта. Он используется, если конкретный языковой файл для текущей локали не найден.

$i18n_locale — переменная, которая может содержит код локали (например, 'en' для английского, 'fr' для французского и т.д.). Эта переменная переопределяет глобальный язык, если задана.

Что делает функция cot_langfile()?

Функция cot_langfile() пытается найти и вернуть путь к языковому файлу в следующем порядке:

Если локаль конкретная (например, не английский), она ищет файл, соответствующий $i18n_locale или использует $defaultlang как резервный вариант.

Загрузка файла:
Если языковой файл найден, он загружается с помощью require_once. Это означает, что файл подключается только один раз, и его можно использовать для локализации текстов в плагине i18n.

Итог:
В этом примере код проверяет, задана ли локаль для интернационализации, и если да, то подключает языковой файл, соответствующий этой локали. Если локаль не задана или файл для неё не найден, используется файл по умолчанию.

Какое место и назначение имеет функция cot_langfile в этом php-сценарии?

Модуль приватных сообщений "PM"

declare(strict_types=1);

namespace cot\modules\pm\services;

use Cot;

class LangService
{
    /**
     * Loads and returns the language file for the specified language as an array
     * @param string $code Part name (area code or plugin name)
     * @param string $type Part type: 'plug', 'module' or 'core'
     * @param string $lang Set this to override global $lang
     * @param ?string $defaultLang Default (fallback) language code
     * @return array
     */
    public static function load(string $code, string $type, string $lang, ?string $defaultLang = null): array
    {
        if ($defaultLang === null) {
            $defaultLang = Cot::$cfg['defaultlang'];
        }
        $langFile = cot_langfile($code, $type, $defaultLang, $lang);
        if (!$langFile)  {
            $langFile = cot_langfile($code, $type, 'en', 'en');
        }
        if (!$langFile)  {
            return [];
        }
        include $langFile;

        /** @var array $L */

        return $L;
    }
}

В этом фрагменте кода функция cot_langfile используется в контексте загрузки языковых файлов для определённой части сайта, такого как плагин или модуль, в зависимости от переданных параметров. Давайте разберемся, как она работает в рамках этого сценария.

Контекст использования:

Функция cot_langfile вызывается в методе load класса LangService. Этот класс, судя по названию, отвечает за работу с языковыми файлами, а именно за их загрузку и возвращение в виде массива. Рассмотрим по шагам:

Параметры метода load:

$code — это код части сайта или плагина, для которой нужно загрузить языковой файл (например, pm для модуля сообщений).
$type — тип расширения: может быть 'plug' для плагинов, 'module' для модулей или 'core' для основной части сайта.
$lang — локаль или язык, который нужно загрузить (например, 'en' или 'ru').
$defaultLang — язык по умолчанию, который используется, если не удаётся загрузить языковой файл для указанного языка.

Задание значения по умолчанию для $defaultLang:

if ($defaultLang === null) {
    $defaultLang = Cot::$cfg['defaultlang'];
}

Если параметр $defaultLang не был передан, то используется значение по умолчанию, которое берется из конфигурации сайта (Cot::$cfg['defaultlang']).

Вызов функции cot_langfile:

$langFile = cot_langfile($code, $type, $defaultLang, $lang);

Функция cot_langfile используется для поиска и возврата пути к языковому файлу для конкретной части сайта. Она пытается найти файл с языковыми строками, начиная с указанной локали $lang. Если файл для этой локали не найден, то в качестве резервного используется язык по умолчанию — $defaultLang.

Резервный язык (файл локализации):

if (!$langFile)  {
    $langFile = cot_langfile($code, $type, 'en', 'en');
}

Если файл для указанной локали не найден, тогда используется английский язык (по умолчанию 'en').

Загрузка и возврат данных: После нахождения подходящего языкового файла, он подключается с помощью include, и содержимое этого файла (массив $L, который содержит языковые строки) возвращается из функции.
 

include $langFile;
/** @var array $L */
return $L;

Роль функции cot_langfile:

Функция cot_langfile в этом контексте играет ключевую роль в поиске и возвращении пути к языковому файлу для указанного плагина или модуля, а также для конкретной локали. Она помогает определить путь к нужному файлу, который затем включается и используется для загрузки массива с языковыми строками. Если языковой файл для указанного языка не найден, то используется резервный вариант, что позволяет обеспечивать гибкость и поддержку нескольких языков.

Заключение:
Функция cot_langfile используется для поиска и загрузки языковых файлов, которые содержат переводы для интерфейса сайта, плагина или модуля.
Она обеспечиваёт механизм для динамической загрузки нужных языковых файлов в зависимости от локали пользователя или языка, настроенного на сайте.
В случае отсутствия нужного файла, она возвращает файл на английском языке или по умолчанию.