lastdragon-ru/path

Provides utilities for working with file and directory paths in an object-oriented way for all path types.

dev-main 2025-12-07 11:46 UTC

Requires

• php: ^8.3|^8.4
• ext-mbstring: *
• symfony/polyfill-php85: ^1.33

Requires (Dev)

• lastdragon-ru/lara-asp-testing: dev-main
• mockery/mockery: ^1.6.6
• phpunit/phpunit: ^11.2.0|^12.0.0

MIT

• php
• file
• path
• directory

README

Provides utilities for working with file and directory paths in an object-oriented way for all path types.

Requirements

Requirement	Constraint	Supported by
PHP	^8.4	HEAD , 9.2.0
	^8.3	HEAD , 9.2.0

Installation

composer require lastdragon-ru/path

Motivation

Most similar packages consider file/directory paths as strings. It is work until we need to modify and/or actively work with them. Relative path resolution depends on the type of base path, for example:

• /path/to/directory/file.md + ../file.txt = /path/to/file.txt
• /path/to/directory + ../file.txt = /path/to/file.txt

The strings (in general case) don't allow us to distinguish the directory path from the file path, and so resolve the path of file.txt correctly. Strings also cannot ensure type safety - there is no way to disallow passing a directory path where only a file path is wanted, and vice versa. Etc. To solve all these problems, the package defines DirectoryPath and FilePath.

<?php declare(strict_types = 1);

namespace LastDragon_ru\Path\Docs\Examples;

use LastDragon_ru\LaraASP\Dev\App\Example;
use LastDragon_ru\Path\DirectoryPath;
use LastDragon_ru\Path\FilePath;

$baseDirectory = new DirectoryPath('/path/to/directory');
$baseFile      = new FilePath('/path/to/directory/file.md');
$file          = new FilePath('../file.txt');

Example::dump((string) $baseDirectory->resolve($file));
Example::dump((string) $baseFile->resolve($file));
Example::dump((string) $baseFile->file('../../file.md'));

The (string) $baseDirectory->resolve($file) is:

"/path/to/file.txt"

The (string) $baseFile->resolve($file) is:

"/path/to/file.txt"

The (string) $baseFile->file('../../file.md') is:

"/path/file.md"

What is supported

The package works only with paths, not with URL/URI/etc, and doesn't interact with OS. The following table shows possible path types.

Type	Example	Root
Type::Absolute	/path	/
Type::Relative	path, ./path, ../path	​
Type::Home	~, ~/, ~/path	~/
Type::User	~username, ~username/path	~username/
Type::Unc	\\ComputerName\SharedFolder\Resource	\\ComputerName\SharedFolder
Type::WindowsAbsolute	C:\path	C:\
Type::WindowsRelative	C:path	C:/<current directory>1 or C:\1

As a path separator, any/mix of //\ can be used, but in the normalized form all \ will always be converted into /:

<?php declare(strict_types = 1);

namespace LastDragon_ru\Path\Docs\Examples;

use LastDragon_ru\LaraASP\Dev\App\Example;
use LastDragon_ru\Path\DirectoryPath;
use LastDragon_ru\Path\FilePath;

$base = new DirectoryPath('\\path\\.\\to\\directory');
$file = new FilePath('../path/../to/../file.txt');
$win  = new FilePath('c:/path/../to/../file.txt');

Example::dump((string) $base->resolve($file));
Example::dump((string) $win->normalized());

The (string) $base->resolve($file) is:

"/path/to/file.txt"

The (string) $win->normalized() is:

"C:/file.txt"

Home ~/

OS independent means that unlike e.g. \Symfony\Component\Filesystem\Path the user home directory ~/ will not be replaced to the actual path, moreover paths stated with ~/ will be treatment like absolute paths (because in almost all cases it is an absolute path).

<?php declare(strict_types = 1);

namespace LastDragon_ru\Path\Docs\Examples;

use LastDragon_ru\LaraASP\Dev\App\Example;
use LastDragon_ru\Path\DirectoryPath;
use LastDragon_ru\Path\FilePath;

$home = new DirectoryPath('~/path');
$file = new FilePath('file.txt');

Example::dump($home->type);
Example::dump((string) $home->resolve($file));
Example::dump((string) $home->file('../../../file.md')); // !

The $home->type is:

LastDragon_ru\Path\Type {
  +name: "Home"
}

The (string) $home->resolve($file) is:

"~/path/file.txt"

The (string) $home->file('../../../file.md') is:

"~/file.md"

Windows

Nothing special here except how the relative path resolves¹:

<?php declare(strict_types = 1);

namespace LastDragon_ru\Path\Docs\Examples;

use LastDragon_ru\LaraASP\Dev\App\Example;
use LastDragon_ru\Path\DirectoryPath;
use LastDragon_ru\Path\FilePath;

$base = new DirectoryPath('C:/path');

Example::dump(
    (string) $base->resolve(new FilePath('C:file.txt')),
);

Example::dump(
    (string) $base->resolve(new FilePath('D:file.txt')),
);

The (string) $base->resolve(new FilePath('C:file.txt')) is:

"C:/path/file.txt"

The (string) $base->resolve(new FilePath('D:file.txt')) is:

"D:/file.txt"

Universal Naming Convention (UNC)

In UNC, the root is \\server\share, so relative paths resolve based on it:

<?php declare(strict_types = 1);

namespace LastDragon_ru\Path\Docs\Examples;

use LastDragon_ru\LaraASP\Dev\App\Example;
use LastDragon_ru\Path\DirectoryPath;
use LastDragon_ru\Path\FilePath;

$base = new DirectoryPath('//server/share/directory');
$file = new FilePath('../../../../../file.txt');

Example::dump((string) $base->resolve($file));

The (string) $base->resolve($file) is:

"//server/share/file.txt"

Making path relative

<?php declare(strict_types = 1);

namespace LastDragon_ru\Path\Docs\Examples;

use LastDragon_ru\LaraASP\Dev\App\Example;
use LastDragon_ru\Path\DirectoryPath;
use LastDragon_ru\Path\FilePath;

$base = new DirectoryPath('~/path/to/directory');

Example::dump((string) $base->relative(new FilePath('~/file.txt')));
Example::dump($base->relative(new FilePath('/file.txt'))); // `null`, because type differ

The (string) $base->relative(new FilePath('~/file.txt')) is:

"../../../file.txt"

The $base->relative(new FilePath('/file.txt')) is:

null

Upgrading

Please follow Upgrade Guide.

Contributing

This package is the part of Awesome Set of Packages for Laravel. Please use the main repository to report issues, send pull requests, or ask questions.

Footnotes

1. https://learn.microsoft.com/en-us/dotnet/standard/io/file-path-formats ↩ ↩² ↩³