axy / syspaths
Specifying paths within the system
Requires
- php: >=5.4.0
- axy/errors: ~1.0.2
This package is auto-updated.
Last update: 2024-10-08 03:14:33 UTC
README
Specifying paths within the system.
- The library does not require any dependencies (except composer packages).
- Tested on PHP 5.4+, PHP 7, HHVM (on Linux), PHP 5.5 (on Windows).
- Install:
composer require axy/syspaths
. - License: MIT.
Documentation
The library allows to store of the directories structure within a certain system. Inside an application for example.
/* App init. __DIR__ is /www/example.loc */ use axy\syspaths\Paths; $paths = new Paths(__DIR__, [ 'htdocs' => 'www', 'source' => 'src', 'templates' => 'templates', ]); /* Further */ $tplFN = $app->paths->templates.'/default.twig'; // /www/example.loc/templates/default.twig
Define paths in one place makes it easy to change the structure.
API
The library provides a single class axy\syspaths\Paths
.
The constructor:
Paths::__construct(string $root [, array $patterns]);
The only required arguments is $root
- the root directory of the system.
$patterns
$patterns
specifies a list of sub-paths.
It can be specified via the constructor (as in the example above).
Or by overriding:
/** * @property-read string $www * @property-read string $templates */ class MyPaths extends Paths { protected $patterns = [ 'htdocs' => 'www', 'templates' => 'templates', ]; }
Now available autocomplete in IDE.
Or you can define the property $patterns
and also specify the argument of the constructor.
In this case these two list recursively merged.
For example, define a system class and redefine some paths for tests.
Access to paths
Via magic methods.
$paths->templates; // /www/example.loc/templates $paths->root; // /www/example.loc isset($paths->htdocs); // TRUE $paths->htdocs = 'new-www'; // Exception: Paths is read-only
Patterns
[ 'www' => 'www', 'images' => ':www:/i', 'icons' => ':images:/icons', 'logo' => ':icons:/logo.gif', 'tmp' => '/tmp', ]
If a path pattern begins with a colon then it is a link to the other path. Such links are processed recursively (circular references are not tracked):
$paths->icons; // /www/example.loc/www/i/icons/logo.gif
If a path pattern begins with /
then it is an absolute path:
$paths->tmp; // /tmp
Other patterns is relative to the root.
www
is equivalent to :root:/www
.
Nested paths
[ 'htdocs' => 'www', 'templates' => [ 'root' => 'templates', 'layouts' => 'layouts', 'admin' => ':layouts:/admin', 'profile' => ':admin:/profile.twig', ], ]
An array defines a nested object Paths.
$paths->templates->profile; // /www/example.loc/templates/layouts/admin/profile.twig
For Paths-objects defined __toString()
:
$paths->templates.'/mails'; // /www/example.loc/templates/mails
The nested array must contains the field root
.
It may be link: 'root' => ':htdocs:/templates'
.
The nested array may contains the field __classname
for the class of the nested path.
By defaults it is axy\syspaths\Paths
.
/** * @property-read string $htdocs * @property-read TemplatesPaths $templates */ class MyPaths extends Paths { $patterns = [ 'htdocs' => 'www', 'templates' => [ 'root' => 'templates', '__classname' => 'TemplatesPaths', ], ] } /** * @property-read string $layout * @property-read string $admin * @property-read string $profile */ class TemplatesPaths extends Paths { $patterns = [ 'layouts' => 'layouts', 'admin' => ':layouts:/admin', 'profile' => ':admin:/profile.twig', ]; }
Now we have the full auto-complete: $app->paths->templates->profile
.
Links can consist of several components:
[ 'templates' => [ 'root' => 'templates', 'layouts' => 'layouts', 'admin' => ':layouts:/admin', ], 'profileTemplate' => ':templates.admin:/profile.twig', ]
Creating paths
$paths->templates->layouts.'/tpl.twig';
Or via the method create
(or __invoke
):
$paths->create(':templates.layouts:/tpl.twig'); $paths(':templates.layouts:/tpl.twig');
Paths::create($pattern, $real = false);
If specified the second argument $real
executed realpath()
for the result.
If the path is not exists then returned NULL
.
Exceptions
In the namespace axy\syspaths\errors
.
RequirePatterns
-$patterns
not defined nor in the property, nor in the constructor.PatternNotFound
- where access via__get
or in a link form other pattern.InvalidPattern
- not closed link, a nested array is not containsroot
,__classname
in not exists and etc.