Привести путь к каноническому виду Path::normalize

Модуль: main — подключать отдельно не нужно

Метод Path::normalize приводит путь к каноническому виду. Метод работает со строкой и не проверяет, есть ли путь в файловой системе.

Сигнатура метода в классе Bitrix\Main\IO\Path:

public static function normalize($path)

Параметры

Обязательные параметры обозначены *

Параметр Тип Описание
path* string Задает путь

Тип в таблице описывает назначение аргумента. Сигнатура PHP не объявляет его.

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

Метод возвращает строку или null, если путь — пустая строка или не строка. Метод сохраняет ведущую косую черту. Например, для /upload//units/./kg/../g/ метод вернет /upload/units/g.

Исключения

Исключение Когда возникает
Bitrix\Main\IO\InvalidPathException Путь содержит нулевой байт или частей .. больше, чем частей перед ними, например a/../.. или /../../etc

Особенности

Метод меняет путь по шагам:

  1. Заменяет повторные косые черты одной. В Windows метод заменяет на / и обратную косую черту.
  2. Убирает части . и сворачивает каждую часть .. вместе с предыдущей частью.
  3. Убирает завершающую косую черту. В Windows метод убирает в конце еще точки, пробелы и +.

Особые случаи:

  • Если путь свернулся в пустую строку, метод возвращает /. Например, для a/.. и . метод вернет /, то есть относительный путь становится корнем.
  • Для абсолютного пути одна часть .. в начале не вызывает исключение. Например, для /../etc метод вернет /etc.

Чтобы путь не вышел за пределы каталога, проверяйте, что результат начинается с нужного каталога. Метод normalize такой защиты не дает.

Примеры

Пример. Код нормализует путь и проверяет, что он внутри каталога /upload/:

<?php
use Bitrix\Main\IO\Path;

require $_SERVER['DOCUMENT_ROOT'] . '/bitrix/modules/main/include/prolog_before.php';

$path = Path::normalize('/upload//units/./kg/../g/');

echo $path . ' ' . (str_starts_with($path . '/', '/upload/') ? 'inside' : 'outside');

Код выведет /upload/units/g inside.

Смотрите также