PHPackages                             bolt/pathogen - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [File & Storage](/categories/file-storage)
4. /
5. bolt/pathogen

AbandonedArchivedLibrary[File & Storage](/categories/file-storage)

bolt/pathogen
=============

Fork of pathogen, a general-purpose path library for PHP, but without using isolator.

0.6.2(8y ago)9273.0k↓21.9%21MITPHPPHP >=5.3

Since Nov 3Pushed 8y ago1 watchersCompare

[ Source](https://github.com/bolt/pathogen)[ Packagist](https://packagist.org/packages/bolt/pathogen)[ Docs](https://github.com/bolt/pathogen)[ RSS](/packages/bolt-pathogen/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (2)Dependencies (3)Versions (3)Used By (1)

Pathogen
========

[](#pathogen)

*General-purpose path library for PHP.*

NOTE: this is the Bolt fork of pathogen
---------------------------------------

[](#note-this-is-the-bolt-fork-of-pathogen)

It does not include nor work with the isolator package.

[![The most recent stable version is 0.6.1](https://camo.githubusercontent.com/fab44862e601c8d680d07d35539be2266f1798e216890444225be7e3aefba7e7/687474703a2f2f696d672e736869656c64732e696f2f3a73656d7665722d302e362e312d79656c6c6f772e737667 "This project uses semantic versioning")](http://semver.org/)[![Current build status image](https://camo.githubusercontent.com/34c71918fe1526c829d075e06991f92e8ef6442c9233a7c0f07e47c09b978fac/687474703a2f2f696d672e736869656c64732e696f2f7472617669732f656c6f7175656e742f706174686f67656e2f646576656c6f702e737667 "Current build status for the develop branch")](https://travis-ci.org/eloquent/pathogen)[![Current coverage status image](https://camo.githubusercontent.com/cd98ca917aa027d398b22fd6bbfba218bd59c1fc28f164b37c7e7c22c22d8379/687474703a2f2f696d672e736869656c64732e696f2f636f766572616c6c732f656c6f7175656e742f706174686f67656e2f646576656c6f702e737667 "Current test coverage for the develop branch")](https://coveralls.io/r/eloquent/pathogen)

Installation and documentation
------------------------------

[](#installation-and-documentation)

- Available as [Composer](http://getcomposer.org/) package [eloquent/pathogen](https://packagist.org/packages/eloquent/pathogen).
- [API documentation](http://lqnt.co/pathogen/artifacts/documentation/api/) available.

What is Pathogen?
-----------------

[](#what-is-pathogen)

*Pathogen* is a library for path manipulation. *Pathogen* supports file system paths including Unix and Windows style paths, but is truly a general-purpose path implementation, capable of representing URI paths and other path-like structures while providing a comprehensive API.

Table of contents
-----------------

[](#table-of-contents)

- [Pathogen concepts](#pathogen-concepts)
    - [Path parts](#path-parts)
        - [Path atoms](#path-atoms)
        - [Path name](#path-name)
        - [Path name extensions](#path-name-extensions)
        - \[Trailing separators\](#trailing separators)
    - [Absolute and relative paths](#absolute-and-relative-paths)
    - [Special paths](#special-paths)
    - [Creating paths](#creating-paths)
        - [Static factory methods](#static-factory-methods)
        - [Factory objects](#factory-objects)
    - [Path resolution](#path-resolution)
        - [Resolution methods](#resolution-methods)
        - [Resolver objects](#resolver-objects)
    - [Path normalization](#path-normalization)
        - [Normalize method](#normalize-method)
        - [Normalizer objects](#normalizer-objects)
    - [File system paths](#file-system-paths)
    - [Immutability of paths](#immutability-of-paths)
    - [Windows path support](#windows-path-support)
    - [Dependency consumer traits](#dependency-consumer-traits)
        - [Available dependency consumer traits](#available-dependency-consumer-traits)
- [Usage examples](#usage-examples)
    - [Resolving a user-provided path against the current working directory](#resolving-a-user-provided-path-against-the-current-working-directory)
    - [Determining whether one path exists inside another](#determining-whether-one-path-exists-inside-another)
    - [Appending an extension to a path](#appending-an-extension-to-a-path)
    - [Replacing a path's extension](#replacing-a-paths-extension)
    - [Replacing a section of a path](#replacing-a-section-of-a-path)

Pathogen concepts
-----------------

[](#pathogen-concepts)

### Path parts

[](#path-parts)

The overall structure of a *Pathogen* path can be broken down into smaller parts. This diagram shows some of these named parts as they apply to a typical path:

```
  A   A   ___ A ___
 / \ / \ /         \
/foo/bar/baz.qux.pop
         \_________/
            name
\__________________/
        path

A = atom

```

The 'name' portion can be further broken down as follows:

```
  NWE    E
/     \ / \
baz.qux.pop
\_/ \_____/
 NP   NS

NWE = name without extension
  E = extension
 NP = name prefix
 NS = name suffix

```

#### Path atoms

[](#path-atoms)

In *Pathogen*, a path consists of a sequence of 'atoms'. Atoms are the individual sections of the path hierarchy. Given the path `/path/to/foo`, the sequence of atoms would be `path`, `to`, `foo`. The slash character is referred to as the 'separator'.

The atoms `.` and `..` have special meaning in *Pathogen*. The single dot (`.`) is referred to as the 'self atom' and is typically used to reference the current path. The double dot (`..`) is referred to as the 'parent atom' and is used to reference the path above the current one. Anyone familiar with typical file system paths should be familiar with their behaviour already.

Given a path instance, the atoms of the path can be determined as follows:

```
$atoms = $path->atoms(); // returns an array of strings
```

#### Path name

[](#path-name)

The 'name' section of a path is simply the last atom of a path. If a path has no atoms, its name is an empty string. Given a path instance, the name of the path can be determined like so:

```
$name = $path->name(); // returns a string
```

#### Path name extensions

[](#path-name-extensions)

The name of a path can be further divided using extension separators (`.`). For example, given the path name `foo.bar.baz`, *Pathogen* can determine the 'name without extension' (`foo.bar`), the 'name prefix' (`foo`), the 'name suffix' (`bar.baz`), and the 'extension' (`baz`).

Given a path instance, the various sections can be retrieved as follows:

```
$nameWithoutExtension = $path->nameWithoutExtension(); // returns a string
$namePrefix = $path->namePrefix(); // returns a string
$nameSuffix = $path->nameSuffix(); // returns a string or null
$extension = $path->extension(); // returns a string or null
```

#### Trailing separators

[](#trailing-separators)

*Pathogen* is capable of representing a path with a trailing separator (`/`). This is useful in the case that a trailing separator has a special meaning to some logic, such as the behaviour of the Unix cp command. The trailing separator support is purely for the use of developers utilizing *Pathogen*; it does not affect any logic used by *Pathogen* itself.

It is worth noting that all new path instances produced by *Pathogen* will strip any trailing slashes unless it is explicitly stated otherwise.

### Absolute and relative paths

[](#absolute-and-relative-paths)

In *Pathogen*, absolute and relative paths are represented by two different classes. While both classes implement a common [PathInterface](http://lqnt.co/pathogen/artifacts/documentation/api/Eloquent/Pathogen/PathInterface.html), other methods are provided by the [AbsolutePathInterface](http://lqnt.co/pathogen/artifacts/documentation/api/Eloquent/Pathogen/AbsolutePathInterface.html) or the [RelativePathInterface](http://lqnt.co/pathogen/artifacts/documentation/api/Eloquent/Pathogen/RelativePathInterface.html)respectively.

This distinction provides, amongst other benefits, the ability to harness PHP's type hinting to restrict the type of path required:

```
use Eloquent\Pathogen\AbsolutePathInterface;
use Eloquent\Pathogen\PathInterface;
use Eloquent\Pathogen\RelativePathInterface;

function anyPath(PathInterface $path)
{
    // accepts any path
}

function absoluteOnly(AbsolutePathInterface $path)
{
    // accepts only absolute paths
}

function relativeOnly(RelativePathInterface $path)
{
    // accepts only relative paths
}
```

### Special paths

[](#special-paths)

The 'root' path is considered the top-most absolute path, and is represented as a single separator with no atoms (`/`).

The 'self' path is considered to point to the 'current' path, and is represented as a single self atom (`.`).

### Creating paths

[](#creating-paths)

#### Static factory methods

[](#static-factory-methods)

The easiest way to create a *Pathogen* path is via the use of static factory methods. To use this method effectively, simply choose the most appropriate class for the type of path:

```
use Eloquent\Pathogen\AbsolutePath;
use Eloquent\Pathogen\FileSystem\FileSystemPath;
use Eloquent\Pathogen\Path;
use Eloquent\Pathogen\RelativePath;
use Eloquent\Pathogen\Unix\UnixPath;
use Eloquent\Pathogen\Windows\AbsoluteWindowsPath;
use Eloquent\Pathogen\Windows\WindowsPath;

$path = Path::fromString('/path/to/foo'); // absolute path
$path = Path::fromString('bar/baz');      // relative path

$path = AbsolutePath::fromString('/path/to/foo'); // only creates absolute paths
$path = RelativePath::fromString('bar/baz');      // only creates relative paths

$path = FileSystemPath::fromString('/path/to/foo');   // Unix path
$path = FileSystemPath::fromString('C:\path\to\foo'); // Windows path

$path = UnixPath::fromString('/path/to/foo');      // only creates Unix paths
$path = WindowsPath::fromString('C:\path\to\foo'); // only creates Windows paths

$path = AbsoluteWindowsPath::fromString('C:\path\to\foo'); // only creates absolute Windows paths
```

In addition to the `fromString()` method, there are other factory methods, some common to all paths, others more specialized:

```
use Eloquent\Pathogen\Path;
use Eloquent\Pathogen\Windows\AbsoluteWindowsPath;

// Equivalent to '/path/to/foo'
$path = Path::fromAtoms(array('path', 'to', 'foo'));

// Equivalent to 'C:\path\to\foo'
$path = AbsoluteWindowsPath::fromDriveAndAtoms(array('path', 'to', 'foo'), 'C');
```

#### Factory objects

[](#factory-objects)

*Pathogen* provides factory classes for creating paths. All path factories implement [PathFactoryInterface](http://lqnt.co/pathogen/artifacts/documentation/api/Eloquent/Pathogen/Factory/PathFactoryInterface.html) which allows a path to be created from various kinds of input.

A simple example of path factory usage is as follows:

```
use Eloquent\Pathogen\FileSystem\Factory\FileSystemPathFactory;

$factory = new FileSystemPathFactory;

$pathFoo = $factory->create('/path/to/foo');
$pathBar = $factory->create('C:/path/to/bar');
```

### Path resolution

[](#path-resolution)

Resolution of a path involves taking a path which may be relative or absolute, and figuring out where that path points to, given a known 'base' path. The result of path resolution will always be an absolute path.

For example, consider a current path of `/path/to/foo`. A relative path of `bar/baz`, will resolve to `/path/to/foo/bar/baz` against this path. Conversely, an absolute path of `/path/to/qux` will not change after resolution, as it is already an absolute path.

#### Resolution methods

[](#resolution-methods)

The simplest way to achieve path resolution with *Pathogen* is to use the most appropriate method on a path:

```
use Eloquent\Pathogen\FileSystem\FileSystemPath;

$basePath = FileSystemPath::fromString('/path/to/foo');
$relativePath = FileSystemPath::fromString('bar/baz');
$absolutePath = FileSystemPath::fromString('/path/to/qux');

echo $basePath->resolve($relativePath); // outputs '/path/to/foo/bar/baz'
echo $basePath->resolve($absolutePath); // outputs '/path/to/qux'

echo $relativePath->resolveAgainst($basePath); // outputs '/path/to/foo/bar/baz'
```

#### Resolver objects

[](#resolver-objects)

Path resolvers are also a standalone concept in *Pathogen*. A simple example of their usage follows:

```
use Eloquent\Pathogen\FileSystem\FileSystemPath;
use Eloquent\Pathogen\Resolver\PathResolver;

$resolver = new PathResolver;

$basePath = FileSystemPath::fromString('/path/to/foo');
$relativePath = FileSystemPath::fromString('bar/baz');
$absolutePath = FileSystemPath::fromString('/path/to/qux');

echo $resolver->resolve($basePath, $relativePath); // outputs '/path/to/foo/bar/baz'
echo $resolver->resolve($basePath, $absolutePath); // outputs '/path/to/qux'
```

### Path normalization

[](#path-normalization)

Normalization of a path is the process of converting a path to its simplest or *canonical* form. This means resolving as many of the self and parent atoms as possible. For example, the path `/path/to/foo/../bar` normalizes to `/path/to/bar`.

Normalization works differently for absolute and relative paths. Absolute paths can always be resolved to a canonical form with no self or parent atoms. Relative paths can often be simplified, but may still contain these special atoms. For example, the path `../foo/../..` will actually normalize to `../..`.

Note that for absolute paths, the root path (`/`) is the top-most path to which parent atoms will normalize. That is, paths with more parent atoms than regular atoms, like `/..`, `/../..`, or `/foo/../..` will all normalize to be the root path (`/`).

Normalization typically never takes place in *Pathogen* unless it is required for a calculation, or done manually through the API. If a normalized path is required for some reason, this is left to the developer to handle.

#### Normalize method

[](#normalize-method)

The simplest way to normalize a path is to use the `normalize()` method:

```
use Eloquent\Pathogen\FileSystem\FileSystemPath;

$path = FileSystemPath::fromString('/path/./to/foo/../bar');

echo $path->normalize(); // outputs '/path/to/bar'
```

#### Normalizer objects

[](#normalizer-objects)

Path normalizers are also a standalone concept in *Pathogen*. A simple example of their usage follows:

```
use Eloquent\Pathogen\FileSystem\FileSystemPath;
use Eloquent\Pathogen\FileSystem\Normalizer\FileSystemPathNormalizer;

$normalizer = new FileSystemPathNormalizer;

$path = FileSystemPath::fromString('/path/./to/foo/../bar');

echo $normalizer->normalize($path); // outputs '/path/to/bar'
```

### File system paths

[](#file-system-paths)

*Pathogen* provides support for dealing with file system paths in a *platform agnostic* way. There are two approaches supported by *Pathogen*, which can be applied depending on the situation.

The first approach is to inspect the path string and create an appropriate path instance based upon a 'best guess'. This is handled by the [FileSystemPath](http://lqnt.co/pathogen/artifacts/documentation/api/Eloquent/Pathogen/FileSystem/FileSystemPath.html)class:

```
use Eloquent\Pathogen\FileSystem\FileSystemPath;

$pathFoo = FileSystemPath::fromString('/path/to/foo');   // creates a Unix-style path
$pathBar = FileSystemPath::fromString('C:/path/to/bar'); // creates a Windows path
```

The second approach is to create paths based upon the current platform the code is running under. That is, when running under Linux or Unix, create Unix-style paths, and when running under Windows, create windows paths. This is handled by the [PlatformFileSystemPath](http://lqnt.co/pathogen/artifacts/documentation/api/Eloquent/Pathogen/FileSystem/PlatformFileSystemPath.html):

```
use Eloquent\Pathogen\FileSystem\PlatformFileSystemPath;

// creates a path to match the current platform
$path = PlatformFileSystemPath::fromString('/path/to/foo');
```

Note that [FileSystemPath](http://lqnt.co/pathogen/artifacts/documentation/api/Eloquent/Pathogen/FileSystem/FileSystemPath.html) and [PlatformFileSystemPath](http://lqnt.co/pathogen/artifacts/documentation/api/Eloquent/Pathogen/FileSystem/PlatformFileSystemPath.html) are only utility classes with static methods. The actual path class used will depend on the input. If it is necessary to type hint for a file system path, [FileSystemPathInterface](http://lqnt.co/pathogen/artifacts/documentation/api/Eloquent/Pathogen/FileSystem/FileSystemPathInterface.html) or one of its more specialized child interfaces should be used instead.

### Immutability of paths

[](#immutability-of-paths)

Paths in *Pathogen* are *immutable*, meaning that once they are created, they cannot be modified. When performing some mutating operation on a path, such as normalization or resolution, a new path instance is produced, rather than the original instance being altered. This allows a path to be exposed as part of an interface without creating a leaky abstraction.

### Windows path support

[](#windows-path-support)

*Pathogen* provides support for Windows paths. In addition to the methods available to Unix-style paths, Windows paths contain an optional drive specifier. The drive specifier is available via the `drive()` method:

```
$drive = $path->drive(); // returns a single-character string, or null
```

### Dependency consumer traits

[](#dependency-consumer-traits)

*Pathogen* provides some [traits](http://php.net/traits) to make consuming its services extremely simple for code targeting PHP 5.4 and higher.

The concept of a dependency consumer trait is simple. If a class requires, for example, a path factory, it can simply use a `PathFactoryTrait`. This gives the class `setPathFactory()` and `pathFactory()` methods for managing the path factory dependency.

This example demonstrates how to use the file system path factory trait:

```
use Eloquent\Pathogen\FileSystem\Factory\Consumer\FileSystemPathFactoryTrait;

class ExampleConsumer
{
    use FileSystemPathFactoryTrait;
}

$consumer = new ExampleConsumer;
echo get_class($consumer->pathFactory()); // outputs 'Eloquent\Pathogen\FileSystem\Factory\FileSystemPathFactory'
```

#### Available dependency consumer traits

[](#available-dependency-consumer-traits)

- [PlatformFileSystemPathFactoryTrait](src/Eloquent/Pathogen/FileSystem/Factory/Consumer/PlatformFileSystemPathFactoryTrait.php)
- [FileSystemPathFactoryTrait](src/Eloquent/Pathogen/FileSystem/Factory/Consumer/FileSystemPathFactoryTrait.php)
- [PathFactoryTrait](src/Eloquent/Pathogen/Factory/Consumer/PathFactoryTrait.php)

Usage examples
--------------

[](#usage-examples)

### Resolving a user-provided path against the current working directory

[](#resolving-a-user-provided-path-against-the-current-working-directory)

```
use Eloquent\Pathogen\FileSystem\Factory\PlatformFileSystemPathFactory;

$factory = new PlatformFileSystemPathFactory;
$workingDirectoryPath = $factory->createWorkingDirectoryPath();

$path = $workingDirectoryPath->resolve(
    $factory->create($_SERVER['argv'][1])
);
```

### Resolving a path against another arbitrary path

[](#resolving-a-path-against-another-arbitrary-path)

```
use Eloquent\Pathogen\Path;

$basePath = Path::fromString('/path/to/base');
$path = Path::fromString('../child');

$resolvedPath = $basePath->resolve($path);

echo $resolvedPath->string();              // outputs '/path/to/base/../child'
echo $resolvedPath->normalize()->string(); // outputs '/path/to/child'
```

### Determining whether one path exists inside another

[](#determining-whether-one-path-exists-inside-another)

```
use Eloquent\Pathogen\Path;

$basePath = Path::fromString('/path/to/foo');
$pathA = Path::fromString('/path/to/foo/bar');
$pathB = Path::fromString('/path/to/somewhere/else');

var_dump($basePath->isAncestorOf($pathA)); // outputs 'bool(true)'
var_dump($basePath->isAncestorOf($pathB)); // outputs 'bool(false)'
```

### Appending an extension to a path

[](#appending-an-extension-to-a-path)

```
use Eloquent\Pathogen\Path;

$path = Path::fromString('/path/to/foo.bar');
$pathWithExtension = $path->joinExtensions('baz');

echo $pathWithExtension->string(); // outputs '/path/to/foo.bar.baz'
```

### Replacing a path's extension

[](#replacing-a-paths-extension)

```
use Eloquent\Pathogen\Path;

$path = Path::fromString('/path/to/foo.bar');
$pathWithNewExtension = $path->replaceExtension('baz');

echo $pathWithNewExtension->string(); // outputs '/path/to/foo.baz'
```

### Replacing a section of a path

[](#replacing-a-section-of-a-path)

```
use Eloquent\Pathogen\Path;

$path = Path::fromString('/path/to/foo/bar');
$pathWithReplacement = $path->replace(1, array('for', 'baz'), 2);

echo $pathWithReplacement->string(); // outputs '/path/for/baz/bar'
```

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity38

Limited adoption so far

Community20

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 84.2% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~949 days

Total

2

Last Release

3265d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/1835343?v=4)[Bob van de Vijver](/maintainers/bobvandevijver)[@bobvandevijver](https://github.com/bobvandevijver)

![](https://avatars.githubusercontent.com/u/3901745?v=4)[Tobias Feijten](/maintainers/tobias-93)[@tobias-93](https://github.com/tobias-93)

![](https://avatars.githubusercontent.com/u/1833361?v=4)[Bob den Otter](/maintainers/bobdenotter)[@bobdenotter](https://github.com/bobdenotter)

![](https://www.gravatar.com/avatar/bb774a9149ae85475a046cd26ce14deb2d7fba6530a5e1a0a71f2a1d21471a2e?d=identicon)[GDmac](/maintainers/GDmac)

---

Top Contributors

[![ezzatron](https://avatars.githubusercontent.com/u/100152?v=4)](https://github.com/ezzatron "ezzatron (154 commits)")[![darianbr](https://avatars.githubusercontent.com/u/1787188?v=4)](https://github.com/darianbr "darianbr (21 commits)")[![GDmac](https://avatars.githubusercontent.com/u/156334?v=4)](https://github.com/GDmac "GDmac (4 commits)")[![GwendolenLynch](https://avatars.githubusercontent.com/u/1427081?v=4)](https://github.com/GwendolenLynch "GwendolenLynch (2 commits)")[![bobdenotter](https://avatars.githubusercontent.com/u/1833361?v=4)](https://github.com/bobdenotter "bobdenotter (1 commits)")[![rixbeck](https://avatars.githubusercontent.com/u/761149?v=4)](https://github.com/rixbeck "rixbeck (1 commits)")

---

Tags

filesystemmanipulationpathfile

### Embed Badge

![Health badge](/badges/bolt-pathogen/health.svg)

```
[![Health](https://phpackages.com/badges/bolt-pathogen/health.svg)](https://phpackages.com/packages/bolt-pathogen)
```

###  Alternatives

[league/flysystem

File storage abstraction for PHP

13.6k639.1M2.2k](/packages/league-flysystem)[league/flysystem-aws-s3-v3

AWS S3 filesystem adapter for Flysystem.

1.6k263.6M790](/packages/league-flysystem-aws-s3-v3)[knplabs/gaufrette

PHP library that provides a filesystem abstraction layer

2.5k39.8M123](/packages/knplabs-gaufrette)[knplabs/knp-gaufrette-bundle

Allows to easily use the Gaufrette library in a Symfony project

72428.6M91](/packages/knplabs-knp-gaufrette-bundle)[league/flysystem-local

Local filesystem adapter for Flysystem.

225231.8M39](/packages/league-flysystem-local)[league/flysystem-memory

In-memory filesystem adapter for Flysystem.

8533.6M194](/packages/league-flysystem-memory)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)