README

Утилитарный класс для построения и манипуляции файловыми путями. Поддерживает как обычные пути файловой системы, так и URL-схемы (https://, ftp:// и т.д.).

Установка

Класс входит в состав пакета arris/entity. Подключается через автозагрузчик Composer:

use Arris\Entity\Path;

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

// Создать путь из строки
$path = new Path('/var/www/html');
echo $path; // /var/www/html

// Создать через фабричный метод
$path = Path::create('uploads/images');
echo $path->toString(); // uploads/images

// Соединить с подпутём
$full = Path::create('/var/www')->join('html/index.php');
echo $full; // /var/www/html/index.php

// URL-адрес тоже работает
$url = new Path('https://cdn.example.com/assets/app.js');
echo $url; // https://cdn.example.com/assets/app.js

Создание экземпляра

Конструктор

new Path(string|array|Path $path, ?bool $isAbsolutePath = null, ?bool $hasTrailingSeparator = null)

Принимает путь в одном из трёх форматов:

// Строка
$p = new Path('/foo/bar/baz');

// Массив сегментов
$p = new Path(['foo', 'bar', 'baz']);

// Другой экземпляр Path
$copy = new Path($existingPath);

Автоопределение флагов из строки:

Множественные слэши автоматически схлопываются: foo//bar///baz → foo/bar/baz.

Фабричный метод create()

Path::create(string|array|Path $path, ?bool $isAbsolutePath = null, ?bool $hasTrailingSeparator = null): Path

Эквивалентен конструктору, но удобнее для цепочек вызовов:

$path = Path::create('/var/www')
    ->setTrailingSeparator(true);

Методы

Получение строки

toString(bool $hasTrailingSeparator = false): string

Экспортирует путь в строку. Аргумент позволяет принудительно добавить завершающий разделитель:

$p = new Path('/var/www/html');
$p->toString();       // /var/www/html
$p->toString(true);   // /var/www/html/

Внимание: вызов toString(true) мутирует внутренний флаг $hasTrailingSeparator.

__toString(): string

Псевдоним toString() без аргументов. Позволяет использовать объект в строковом контексте:

echo new Path('/etc/nginx'); // /etc/nginx

Соединение путей

join(mixed $data): Path

Возвращает новый экземпляр с добавленным сегментом. Наследует флаги isAbsolutePath и hasTrailingSeparator из текущего объекта.

$base = new Path('/var/www');
$full = $base->join('html');
echo $full; // /var/www/html

// Можно передать массив, строку или Path
$base->join(['assets', 'css']);  // /var/www/assets/css
$base->join(new Path('logs'));   // /var/www/logs

joinName(mixed $data): Path

Аналог join(), но принудительно устанавливает hasTrailingSeparator = false. Удобно для добавления имени файла:

$dir  = new Path('/var/www/');
$file = $dir->joinName('index.php');
echo $file; // /var/www/index.php

Установка флагов

Все методы мутируют текущий объект и возвращают $this для цепочек вызовов.

setAbsolutePath(bool $is_present = true): Path

$path = new Path('foo/bar');
$path->setAbsolutePath(true);
echo $path; // /foo/bar

setTrailingSeparator(bool $is_present = true): Path

$path = new Path('/var/www');
$path->setTrailingSeparator(true);
echo $path->toString(true); // /var/www/

setOptions(array $options): Path

Устанавливает сразу несколько флагов. Поддерживает ключи isAbsolute и hasTrailingSeparator:

$path->setOptions([
    'isAbsolute'           => true,
    'hasTrailingSeparator' => false,
]);

Неизвестные ключи игнорируются. Значение null также игнорируется (ключ должен присутствовать с непустым значением).

Проверка файловой системы

isPresent(): bool

Возвращает true, если по данному пути существует директория.

if ((new Path('/var/log'))->isPresent()) { /* ... */ }

isFile(): bool

Возвращает true, если путь указывает на существующий читаемый файл.

if ((new Path('/etc/hosts'))->isFile()) { /* ... */ }

makePath(int $access_rights = 0777): bool

Создаёт директорию рекурсивно (аналог mkdir -p). Возвращает true при успехе или если директория уже существует.

$created = (new Path('/tmp/app/cache'))->makePath(0755);

Внутренние свойства

Поддержка URL

Класс содержит внутренний механизм («костыль») для работы с URL-схемами: :// при разборе заменяется на :||, а при экспорте возвращается обратно. Это позволяет использовать Path для сборки URL, хотя для полноценной работы с URL рекомендуется использовать специализированный класс.

$url = new Path('https://example.com/api/v1');
echo $url; // https://example.com/api/v1

// Двойной слэш в пути (не в схеме) схлопывается
$url = new Path('https://cdn.example.com/a//b');
echo $url; // https://cdn.example.com/a/b

Совместимость и требования

• PHP 8.2+
• Реализует интерфейс PathInterface
• Разделитель сегментов: DIRECTORY_SEPARATOR (на Unix — /, на Windows — \)

Известные особенности поведения

• toString(true) мутирует объект — флаг hasTrailingSeparator изменяется внутри. Если нужно неизменяемое поведение, используйте Path::create($this)->toString(true).
• Сегмент . (точка) превращается во внутренний пустой атом ''. При экспорте двойной разделитель схлопывается — итоговая строка остаётся корректной.
• Пустой атом ('') в середине массива сегментов при проходе через validateAtom не добавляется в $atoms.

Лицензия

MIT