Менеджер файловых путей
Для универсальности разрабатываемого приложения и его переносимости — все операции с направляющими адресами к файлам и директориям проекта должны быть относительными к его корневой директории.
Во фреймворке HLEB2 менеджером файловых путей служит сервис Path. Он делает доступным манипулирование с относительными файловыми путями в проекте, предоставляя обёртку над соответствующими функциями PHP.
Способы использования Path в контроллерах (и всех классах, унаследованных от Hleb\Base\Container) на примере получения полного пути от корневой директории:
use Hleb\Reference\PathInterface;
$path = $this->container->get(PathInterface::class)->getReal('@storage/public/files');
// variant 2
$path = $this->container->path()->getReal('@storage/public/files');
Пример определения файлового пути в коде приложения:
use Hleb\Static\Container;
use Hleb\Reference\PathInterface;
$path = Container::get(PathInterface::class)->getReal('@storage/public/files');
// variant 2
use Hleb\Static\Path;
$path = Path::getReal('@storage/public/files');
Также объект Path может быть получен через внедрение зависимостей по интерфейсу Hleb\Reference\Interface\Path.
Для упрощения примеров, далее они будут содержать только обращение через Hleb\Static\Path.
#Символ @
В приведённых выше примерах присутствует символ '@' в начале относительного пути.
Он означает, что путь начинается с корневой директории проекта.
Если корневая директория проекта /var/www/hleb/, то в примере вернулась бы строка '/var/www/hleb/storage/public/files'.
Для Windows результат выглядел бы немного иначе, но это все равно был бы существующий полный путь к указанной папке.
Префикс '@storage' здесь является предопределенным для фреймворка, вот список других назначенных соответствий:
'@' - корневая директория проекта с фреймворком HLEB2.
Путь может быть указан произвольным, например '@/other/folder'.
'@app' - путь к папке /app/ проекта.
'@public' - путь к папке /public/ проекта c публичными файлами проекта, в эту папку направлен веб-сервер.
Даже если название её изменено, все равно для соответствия будет '@public'.
'@storage' - путь к папке /storage/ проекта, здесь хранятся кеши, логи и другие вспомогательные файлы.
'@resources' - путь к папке /resources/ проекта.
Это папка с различными ресурсами проекта: шаблоны страниц, шаблоны писем, шаблоны для сборки и тд.
'@views' - путь к папке /resources/views/ проекта.
'@modules' - путь к папке /modules/ проекта, даже если название директории с модулями изменено в настройках.
'@vendor' - путь к папке c библиотеками проекта, остаётся таким же в случае, если название папки отличается.
Таким образом, допускается любой путь в пределах проекта, поэтому перенос на сервер с другим устройством директорий или в другую папку не будет проблемой, пути всегда будут указывать в нужное место.
Для сервиса Path существует несколько методов, правильно распознающих относительные пути с начальной '@'.
Конечный слеш для строки с относительным путем, например '@storage/logs/', имеет значение, возвращённый методом полный путь к папке в этом случае будет включать слеш в конце.
#getReal()
Метод getReal() можно наблюдать в примерах выше.
Он возвращает строку с полным путём, полученным из относительного.
Если указанный путь не существует, то метод возвращает false.
Таким же образом действует функция фреймворка hl_realpath().
#get()
Метод get() отличается от getReal() тем, что при несуществующем пути все равно вернет строку для полного пути, не проверяя существование.
Заменой этого метода может быть функция hl_path().
$dir = Path::get('@/non-existent/dir');
$file = Path::get('@/non-existent/file.txt');
$file = hl_path('@/non-existent/file.txt');
#relative()
Этот метод отличается от других методов сервиса Path, он принимает полный путь, а возвращает относительный с '@' в начале. Бывает необходимость вывести в пользовательские логи или в ином месте относительный путь в проекте, скрывая полный. Метод relative() поможет в таком случае.
$path = Path::relative(__FILE__);
В примере отображено получение относительного пути к текущему файлу.
#createDirectory()
Метод createDirectory() создает директорию (при её отсутствии) со всеми вложенными подпапками по указанному относительному пути c '@' в начале или полному.
#exists()
Для проверки существования файла или директории предназначен метод exists().
Он принимает для проверки как полный, так и относительный путь с '@' в начале.
Во фреймворке есть функция hl_file_exists() с аналогичным действием.
#contents()
Метод contents() является оберткой над file_get_contents(), только кроме полного пути может принимать и относительный путь с '@' в начале.
Дублирует этот метод функция фреймворка hl_file_get_contents().
#put()
Этот метод аналогичен функции file_put_contents().
Кроме полного пути метод put() может принимать и относительный путь с '@' в начале.
Для замены метода есть функция фреймворка hl_file_put_contents().
#isDir()
Метод isDir() является обёрткой над функцией is_dir(), кроме полного пути может принимать и относительный путь с '@' в начале.
Вместо этого метода есть возможность использовать функцию hl_is_dir().
#Асинхронные запросы
Некоторые операции над файлами, такие как запись в файл, являются блокирующими для асинхронных вызовов, поэтому рекомендуется использовать их аналоги, поддерживающие асинхронность.
← Логирование Сервис DB →