File Path Manager
For application versatility and portability, all operations involving file and directory path references within the project must be relative to its root directory.
In the HLEB2 framework, the file path manager is handled by the Path service. It enables manipulation of relative file paths in the project by providing a wrapper over the corresponding PHP functions.
Usage of Path in controllers (and any classes inheriting from Hleb\Base\Container) as an example of obtaining a full path from the root directory:
use Hleb\Reference\PathInterface;
$path = $this->container->get(PathInterface::class)->getReal('@storage/public/files');
// variant 2
$path = $this->container->path()->getReal('@storage/public/files');
Example of defining a file path in the application code:
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');
The Path object can also be obtained through dependency injection via the Hleb\Reference\Interface\Path interface.
To simplify examples, only usage through Hleb\Static\Path will be shown in further examples.
#The @ Symbol
In the examples above, there is a '@' symbol at the beginning of the relative path. It indicates that the path starts from the root directory of the project.
If the project's root directory is /var/www/hleb/, the example would return the string '/var/www/hleb/storage/public/files'.
On Windows, the result would look slightly different, but it would still be a valid full path to the specified folder.
The prefix '@storage' is predefined for the framework. Here is a list of other assigned mappings:
'@' - the root directory of the project with the HLEB2 framework.
The path can be specified arbitrarily, for example '@/other/folder'.
'@app' - the path to the project's /app/ folder.
'@public' - the path to the project's /public/ folder with public project files, which is targeted by the web server.
Even if the name is changed, it will still correspond to '@public'.
'@storage' - the path to the project's /storage/ folder, where caches, logs, and other auxiliary files are stored.
'@resources' - the path to the project's /resources/ folder.
This folder contains various project resources: page templates, email templates, build templates, etc.
'@views' - the path to the project's /resources/views/ folder.
'@modules' - the path to the project's /modules/ folder, even if the module directory name has been changed in the settings.
'@vendor' - the path to the project's library folder, which remains the same even if the folder name is different.
Thus, any path within the project is allowed, so transferring to a server with a different directory structure or to another folder won't be an issue, as paths will always point to the correct location.
The Path service has several methods that correctly recognize relative paths starting with '@'.
A trailing slash for a relative path string, such as '@storage/logs/', is significant. The full path returned by the method will include the trailing slash in this case.
#getReal()
The getReal() method can be seen in the examples above.
It returns a string with the full path derived from a relative one.
If the specified path does not exist, the method returns false.
The hl_realpath() framework function works in the same way.
#get()
The get() method differs from getReal() in that it will return a string for the full path even if the path does not exist, without checking for existence.
The function hl_path() can be used as an alternative to this method.
$dir = Path::get('@/non-existent/dir');
$file = Path::get('@/non-existent/file.txt');
$file = hl_path('@/non-existent/file.txt');
#relative()
This method differs from other methods of the Path service in that it takes a full path and returns a relative one with '@' at the beginning. Sometimes it is necessary to output the relative path in project logs or in other places, hiding the full path. The relative() method helps in such cases.
$path = Path::relative(__FILE__);
The example shows obtaining the relative path to the current file.
#createDirectory()
The createDirectory() method creates a directory (if it does not exist) along with any nested subfolders by the specified relative path with '@' at the beginning or a full path.
#exists()
The exists() method is used to check for the existence of a file or directory.
It accepts both full paths and relative paths with '@' at the beginning.
The framework function hl_file_exists() has a similar action.
#contents()
The contents() method is a wrapper around file_get_contents(), but it can also accept a relative path starting with '@' in addition to a full path.
This method is duplicated by the framework function hl_file_get_contents().
#put()
This method is similar to the file_put_contents() function.
Besides a full path, the put() method can also accept a relative path starting with '@'.
The framework function hl_file_put_contents() can be used as an alternative to this method.
#isDir()
The isDir() method is a wrapper around the is_dir() function, and it can accept both a full path and a relative path starting with '@'.
The function hl_is_dir() can be used instead of this method.
#Asynchronous Requests
Some file operations, such as writing to a file, are blocking for asynchronous calls, so it is recommended to use their asynchronous-supported alternatives.
← Logging DB Service →