Функции для работы с файловой системой сайта в Битриксе: GetPagePath()

В платформе 1С-Битрикс для работы с файловой системой и манипулирования путями страниц используется несколько полезных функций. Одна из них — это функция GetPagePath(), которая позволяет легко получить путь к странице сайта относительно корня, при этом она учитывает различные нюансы, такие как индексные файлы разделов.

В этой статье мы подробно рассмотрим, как работает функция GetPagePath(), какие параметры она принимает, а также приведем примеры ее использования.

Описание функции GetPagePath

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

Функция GetPagePath() возвращает строку, которая содержит путь к странице относительно корня сайта.

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

1. page (необязательный параметр):
   • Параметр, определяющий путь страницы, для которой нужно получить путь относительно корня. Если параметр не передан, то будет использован текущий путь, в котором находится запрашиваемая страница.
   • Пример: если в параметре передан путь /ru/about/, то функция вернет путь к этой странице с учетом всех возможных нюансов (например, если это индексная страница, будет добавлен index.php).
2. get_index_page (необязательный параметр):
   • Указывает, нужно ли для индексной страницы раздела возвращать путь, который заканчивается на index.php (если значение true), или достаточно пути, заканчивающегося на / (если значение false).
   • Этот параметр важен, когда нужно точно указать индексный файл каталога. Если он не задан, то по умолчанию будет использоваться значение константы BX_DISABLE_INDEX_PAGE, которая регулирует поведение для индексных страниц.
3. obj (служебный параметр):
   • Это параметр, который не используется в обычной работе и остается для внутренних нужд. Как правило, он передается с значением false.

Алгоритм работы функции

Функция сначала проверяет, передан ли параметр пути страницы. Если путь не передан, используется текущий URI, который можно получить из глобальной переменной $_SERVER["REQUEST_URI"]. Затем функция очищает путь от параметров запроса (например, из URL будет удален символ ? и все, что после него), а также декодирует его в нужной кодировке.

Если путь указывает на каталог, а не на файл, функция попытается определить индексный файл (например, index.php). После этого путь будет возвращен в виде строки, которая может быть использована для дальнейшей работы.

Пример использования функции GetPagePath

Пример 1: Получение пути текущей страницы использовать функцию без параметров:

<?php
echo GetPagePath(); // Вернет путь к текущей странице
?>

Этот код вернет путь страницы, на которой сейчас находится пользователь, без параметров запроса.

Пример 2: Получение пути для конкретной страницы

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

<?php
echo GetPagePath("/about/"); // Вернет путь /about/index.php (если это индексная страница)
?>

Если в папке /about/ есть файл index.php, функция вернет путь с добавлением этого файла.

Пример 3: Получение пути для страницы с параметрами запроса

Если передан URL с параметрами запроса, например, /product/?id=123, то функция вернет путь без этих параметров:

<?php
echo GetPagePath("/product/?id=123"); // Вернет путь /product/
?>

Это полезно, когда нужно работать с чистыми путями без учета параметров URL.

Пример 4: Учет индексного файла

Если вы хотите получить путь, который обязательно будет содержать index.php для каталогов, то передайте параметр true для get_index_page:

<?php
echo GetPagePath("/about/", true); // Вернет путь /about/index.php
?>

Если параметр get_index_page равен false, то результатом будет путь без указания index.php:

<?php
echo GetPagePath("/about/", false); // Вернет путь /about/
?>

Пример 5: Обработка сложных путей с кодировкой

Функция также обрабатывает кодировку пути, что важно для работы с международными URL. Если путь содержит символы в кодировке UTF-8, они будут корректно декодированы:

<?php
echo GetPagePath("/ru/о_нас/"); // Корректно обработает путь с кириллицей
?>

Реализация функции GetPagePath

Ниже приведена исходная реализация функции GetPagePath() из файла bitrix/modules/main/tools.php. Мы рассмотрим, как она работает и какие шаги выполняет:

function GetPagePath($page=false, $get_index_page=null)
{
    if (null === $get_index_page)
    {
        if (defined('BX_DISABLE_INDEX_PAGE'))
            $get_index_page = !BX_DISABLE_INDEX_PAGE;
        else
            $get_index_page = true;
    }

    if($page === false && !empty($_SERVER["REQUEST_URI"]))
        $page = $_SERVER["REQUEST_URI"];
    if($page ===SCRIPT_NAME"];

    $sPath = $page;

    static $terminate = array("?", "#");
    foreach($terminate as $term)
    {
        if(($found = mb_strpos($sPath, $term)) !== false)
        {
            $sPath = mb_substr($sPath, 0, $found);
        }
    }

    $sPath = preg_replace("/%+[0-9a-f]{0,1}$/i", "", $sPath);
    $sPath = urldecode($sPath);
    $sPath = Text\Encoding::convertEncodingToCurrent($sPath);

    if(mb_substr($sPath, -1, 1) == "/" && $get_index_page)
    {
        $sPath .= GetDirectoryIndex($sPath);
    }

    $sPath = Rel2Abs("/", $sPath);

    static $aSearch = array("<", ">", "\"", "'", "%", "\r", "\n", "\t", "\\");
    static $aReplace = array("<", ">", """, "'", "%25", "%0d", "%0a", "%09", "%5C");
    $sPath = str_replace($aSearch, $aReplace, $sPath);

    return $sPath;
}

Описание кода

1. Параметры по умолчанию: Функция проверяет, задан ли параметр get_index_page. Если он не задан, используется значение константы BX_DISABLE_INDEX_PAGE.
2. Обработка пути: Если параметр $page не передан, используется текущий URI. Затем удаляются параметры запроса, и путь декодируется и конвертируется в правильную кодировку.
3. Индексная страница: Если путь указывает на каталог и требуется, функция добавляет index.php в путь.
4. Замена символов: Для безопасности все специальные символы в пути заменяются на соответствующие HTML-суффиксы.

Заключение

Функция GetPagePath() в Битрикс — это инструмент для работы с путями страниц сайта. Она упрощает манипуляцию с URL, обеспечивая правильное преобразование путей, обработку индексных страниц и поддержку различных кодировок. Приведенные примеры помогут вам эффективно использовать эту функцию для решения различных задач на сайте, работающем на платформе 1С-Битрикс.