{"id":37008783,"url":"https://github.com/mschop/pathogen","last_synced_at":"2026-01-14T00:50:23.147Z","repository":{"id":40381467,"uuid":"240463071","full_name":"mschop/pathogen","owner":"mschop","description":"General-purpose path library for PHP.","archived":false,"fork":true,"pushed_at":"2024-12-29T11:28:30.000Z","size":3343,"stargazers_count":5,"open_issues_count":2,"forks_count":3,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-16T20:25:08.286Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"eloquent/pathogen","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mschop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-02-14T08:37:49.000Z","updated_at":"2024-12-29T11:28:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mschop/pathogen","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mschop/pathogen","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mschop%2Fpathogen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mschop%2Fpathogen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mschop%2Fpathogen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mschop%2Fpathogen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mschop","download_url":"https://codeload.github.com/mschop/pathogen/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mschop%2Fpathogen/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28407176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T00:40:43.272Z","status":"ssl_error","status_checked_at":"2026-01-14T00:40:42.636Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-14T00:50:23.040Z","updated_at":"2026-01-14T00:50:23.134Z","avatar_url":"https://github.com/mschop.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# !!! WARNING !!!\nYou are watching the documentation for v1.X (unreleased). For current stable release see https://github.com/mschop/pathogen/tree/0.7.1\n\n# Pathogen\n\n*General-purpose path library for PHP.*\n\n[![Run Unit Tests](https://github.com/mschop/pathogen/actions/workflows/docker-image.yml/badge.svg)](https://github.com/mschop/pathogen/actions/workflows/docker-image.yml)\n\n\n## Future development\n\nThis package is a fork of the abandoned package eloquent/pathogen. I will continue the work on this lib. Please feel\nfree to issue feature requests or bug reports.\n\n## Installation and documentation\n\n- Available as [Composer] package [mschop/pathogen].\n- [API documentation] available.\n\n[API documentation]: http://lqnt.co/pathogen/artifacts/documentation/api/\n[Composer]: http://getcomposer.org/\n[eloquent/pathogen]: https://packagist.org/packages/eloquent/pathogen\n\n## What is Pathogen?\n\n*Pathogen* is a library for path manipulation. *Pathogen* supports file system\npaths including Unix and Windows style paths, but is truly a general-purpose\npath implementation, capable of representing URI paths and other path-like\nstructures while providing a comprehensive API.\n\n## Table of contents\n\n- [Pathogen concepts](#pathogen-concepts)\n    - [Path parts](#path-parts)\n        - [Path atoms](#path-atoms)\n        - [Path name](#path-name)\n        - [Path name extensions](#path-name-extensions)\n        - [Trailing separators](#trailing separators)\n    - [Absolute and relative paths](#absolute-and-relative-paths)\n    - [Special paths](#special-paths)\n    - [Creating paths](#creating-paths)\n        - [Static factory methods](#static-factory-methods)\n    - [Path resolution](#path-resolution)\n        - [Resolution methods](#resolution-methods)\n        - [Resolver objects](#resolver-objects)\n    - [Path normalization](#path-normalization)\n        - [Normalize method](#normalize-method)\n        - [Normalizer objects](#normalizer-objects)\n    - [File system paths](#file-system-paths)\n    - [Immutability of paths](#immutability-of-paths)\n    - [Windows path support](#windows-path-support)\n    - [Dependency consumer traits](#dependency-consumer-traits)\n        - [Available dependency consumer traits](#available-dependency-consumer-traits)\n- [Usage examples](#usage-examples)\n    - [Resolving a user-provided path against the current working directory](#resolving-a-user-provided-path-against-the-current-working-directory)\n    - [Determining whether one path exists inside another](#determining-whether-one-path-exists-inside-another)\n    - [Appending an extension to a path](#appending-an-extension-to-a-path)\n    - [Replacing a path's extension](#replacing-a-paths-extension)\n    - [Replacing a section of a path](#replacing-a-section-of-a-path)\n\n## Pathogen concepts\n\n### Path parts\n\nThe overall structure of a *Pathogen* path can be broken down into smaller\nparts. This diagram shows some of these named parts as they apply to a typical\npath:\n\n      A   A   ___ A ___\n     / \\ / \\ /         \\\n    /foo/bar/baz.qux.pop\n             \\_________/\n                name\n    \\__________________/\n            path\n\n    A = atom\n\nThe 'name' portion can be further broken down as follows:\n\n      NWE    E\n    /     \\ / \\\n    baz.qux.pop\n    \\_/ \\_____/\n     NP   NS\n\n    NWE = name without extension\n      E = extension\n     NP = name prefix\n     NS = name suffix\n\n#### Path atoms\n\nIn *Pathogen*, a path consists of a sequence of 'atoms'. Atoms are the\nindividual sections of the path hierarchy. Given the path `/path/to/foo`, the\nsequence of atoms would be `path`, `to`, `foo`. The slash character is referred\nto as the 'separator'.\n\nThe atoms `.` and `..` have special meaning in *Pathogen*. The single dot (`.`)\nis referred to as the 'self atom' and is typically used to reference the current\npath. The double dot (`..`) is referred to as the 'parent atom' and is used to\nreference the path above the current one. Anyone familiar with typical file\nsystem paths should be familiar with their behaviour already.\n\nGiven a path instance, the atoms of the path can be determined as follows:\n\n```php\n$atoms = $path-\u003eatoms(); // returns an array of strings\n```\n\n#### Path name\n\nThe 'name' section of a path is simply the last atom of a path. If a path has no\natoms, its name is an empty string. Given a path instance, the name of the path\ncan be determined like so:\n\n```php\n$name = $path-\u003ename(); // returns a string\n```\n\n#### Path name extensions\n\nThe name of a path can be further divided using extension separators (`.`). For\nexample, given the path name `foo.bar.baz`, *Pathogen* can determine the 'name\nwithout extension' (`foo.bar`), the 'name prefix' (`foo`), the 'name suffix'\n(`bar.baz`), and the 'extension' (`baz`).\n\nGiven a path instance, the various sections can be retrieved as follows:\n\n```php\n$nameWithoutExtension = $path-\u003enameWithoutExtension(); // returns a string\n$namePrefix = $path-\u003enamePrefix(); // returns a string\n$nameSuffix = $path-\u003enameSuffix(); // returns a string or null\n$extension = $path-\u003eextension(); // returns a string or null\n```\n\n#### Trailing separators\n\n*Pathogen* is capable of representing a path with a trailing separator (`/`).\nThis is useful in the case that a trailing separator has a special meaning to\nsome logic, such as the behaviour of the Unix cp command. The trailing separator\nsupport is purely for the use of developers utilizing *Pathogen*; it does not\naffect any logic used by *Pathogen* itself.\n\nIt is worth noting that all new path instances produced by *Pathogen* will strip\nany trailing slashes unless it is explicitly stated otherwise.\n\n### Absolute and relative paths\n\nIn *Pathogen*, absolute and relative paths are represented by two different\nclasses. While both classes implement a common [PathInterface], other methods\nare provided by the [AbsolutePathInterface] or the [RelativePathInterface]\nrespectively.\n\nThis distinction provides, amongst other benefits, the ability to harness PHP's\ntype hinting to restrict the type of path required:\n\n```php\nuse Pathogen\\AbsolutePathInterface;use Pathogen\\Path;use Pathogen\\RelativePathInterface;\n\nfunction anyPath(Path $path)\n{\n    // accepts any path\n}\n\nfunction absoluteOnly(AbsolutePathInterface $path)\n{\n    // accepts only absolute paths\n}\n\nfunction relativeOnly(RelativePathInterface $path)\n{\n    // accepts only relative paths\n}\n```\n\n[AbsolutePathInterface]: http://lqnt.co/pathogen/artifacts/documentation/api/Eloquent/Pathogen/AbsolutePathInterface.html\n[PathInterface]: http://lqnt.co/pathogen/artifacts/documentation/api/Eloquent/Pathogen/PathInterface.html\n[RelativePathInterface]: http://lqnt.co/pathogen/artifacts/documentation/api/Eloquent/Pathogen/RelativePathInterface.html\n\n### Special paths\n\nThe 'root' path is considered the top-most absolute path, and is represented as\na single separator with no atoms (`/`).\n\nThe 'self' path is considered to point to the 'current' path, and is represented\nas a single self atom (`.`).\n\n### Creating paths\n\n#### Static factory methods\n\nNormally you do create a path the static factory methods.To use this method effectively, simply choose the most\nappropriate  class for the type of path:\n\n```php\nuse Pathogen\\AbsolutePath;\nuse Pathogen\\FileSystem\\FileSystemPath;\nuse Pathogen\\Path;\nuse Pathogen\\RelativePath;\nuse Pathogen\\Exception\\PathTypeMismatchException;\n\n$path = Path::fromString('/path/to/foo'); // returns AbsolutePath\n$path = Path::fromString('\\path\\to\\foo'); // returns AbsolutePath\n$path = Path::fromString('bar/baz'); // returns RelativePath\n$path = Path::fromString('bar\\baz'); // returns RelativePath\n\n# Specific classes\n$path = RelativePath::fromString('bar/baz'); // returns RelativePath\n$path = RelativePath::fromString('/bar/baz'); // !!! throws PathTypeMismatchException \n$path = AbsolutePath::fromString('/bar/baz'); // returns AbsolutePath\n$path = AbsolutePath::fromString('bar/baz'); // !!! throws PathTypeMismatchException\n\n# Drive Anchoring (Windows)\n$path = Path::fromString('C:/bar/baz'); // returns AbsoluteDriveAnchoredPath\n$path = Path::fromString('C:\\bar\\baz'); // returns AbsoluteDriveAnchoredPath\n$path = Path::fromString('C:bar/baz'); // returns RelativeDriveAnchoredPath\n```\n\nYou can also use the constructor to create new instances of Path.\n\n```php\nuse Pathogen\\Path;\nuse Pathogen\\AbsoluteDriveAnchoredPath;\n\n// Equivalent to '/path/to/foo'\n$atoms = ['path', 'to', 'foo'];\n$path = new Path($atoms, hasTrailingSeparator: false);\n\n// Equivalent to 'C:\\path\\to\\foo'\n$path = new AbsoluteDriveAnchoredPath(atoms: $atoms, hasTrailingSeparator: false, drive: 'C');\n```\n\n### Path resolution\n\nResolution of a path involves taking a path which may be relative or absolute,\nand figuring out where that path points to, given a known 'base' path. The\nresult of path resolution will always be an absolute path.\n\nFor example, consider a current path of `/path/to/foo`. A relative path of\n`bar/baz`, will resolve to `/path/to/foo/bar/baz` against this path. Conversely,\nan absolute path of `/path/to/qux` will not change after resolution, as it is\nalready an absolute path.\n\n#### Resolution methods\n\nThe simplest way to achieve path resolution with *Pathogen* is to use the\nmost appropriate method on a path:\n\n```php\nuse Pathogen\\FileSystem\\FileSystemPath;\n\n$basePath = FileSystemPath::fromString('/path/to/foo');\n$relativePath = FileSystemPath::fromString('bar/baz');\n$absolutePath = FileSystemPath::fromString('/path/to/qux');\n\necho $basePath-\u003eresolve($relativePath); // outputs '/path/to/foo/bar/baz'\necho $basePath-\u003eresolve($absolutePath); // outputs '/path/to/qux'\n\necho $relativePath-\u003eresolveAgainst($basePath); // outputs '/path/to/foo/bar/baz'\n```\n\n#### Resolver objects\n\nPath resolvers are also a standalone concept in *Pathogen*. A simple example of\ntheir usage follows:\n\n```php\nuse Pathogen\\FileSystem\\FileSystemPath;\nuse Pathogen\\Resolver\\PathResolver;\n\n$resolver = new PathResolver;\n\n$basePath = FileSystemPath::fromString('/path/to/foo');\n$relativePath = FileSystemPath::fromString('bar/baz');\n$absolutePath = FileSystemPath::fromString('/path/to/qux');\n\necho $resolver-\u003eresolve($basePath, $relativePath); // outputs '/path/to/foo/bar/baz'\necho $resolver-\u003eresolve($basePath, $absolutePath); // outputs '/path/to/qux'\n```\n\n### Path normalization\n\nNormalization of a path is the process of converting a path to its simplest or\n*canonical* form. This means resolving as many of the self and parent atoms as\npossible. For example, the path `/path/to/foo/../bar` normalizes to\n`/path/to/bar`.\n\nNormalization works differently for absolute and relative paths. Absolute paths\ncan always be resolved to a canonical form with no self or parent atoms.\nRelative paths can often be simplified, but may still contain these special\natoms. For example, the path `../foo/../..` will actually normalize to `../..`.\n\nNote that for absolute paths, the root path (`/`) is the top-most path to which\nparent atoms will normalize. That is, paths with more parent atoms than regular\natoms, like `/..`, `/../..`, or `/foo/../..` will all normalize to be the root\npath (`/`).\n\nNormalization typically never takes place in *Pathogen* unless it is required\nfor a calculation, or done manually through the API. If a normalized path is\nrequired for some reason, this is left to the developer to handle.\n\n#### Normalize method\n\nThe simplest way to normalize a path is to use the `normalize()` method:\n\n```php\nuse Pathogen\\FileSystem\\FileSystemPath;\n\n$path = FileSystemPath::fromString('/path/./to/foo/../bar');\n\necho $path-\u003enormalize(); // outputs '/path/to/bar'\n```\n\n#### Normalizer objects\n\nPath normalizers are also a standalone concept in *Pathogen*. A simple example\nof their usage follows:\n\n```php\nuse Pathogen\\FileSystem\\FileSystemPath;\nuse Pathogen\\FileSystem\\Normalizer\\FileSystemPathNormalizer;\n\n$normalizer = new FileSystemPathNormalizer;\n\n$path = FileSystemPath::fromString('/path/./to/foo/../bar');\n\necho $normalizer-\u003enormalize($path); // outputs '/path/to/bar'\n```\n\n### File system paths\n\n*Pathogen* provides support for dealing with file system paths in a *platform\nagnostic* way. There are two approaches supported by *Pathogen*, which can be\napplied depending on the situation.\n\nThe first approach is to inspect the path string and create an appropriate path\ninstance based upon a 'best guess'. This is handled by the [FileSystemPath]\nclass:\n\n```php\nuse Pathogen\\FileSystem\\FileSystemPath;\n\n$pathFoo = FileSystemPath::fromString('/path/to/foo');   // creates a Unix-style path\n$pathBar = FileSystemPath::fromString('C:/path/to/bar'); // creates a Windows path\n```\n\nThe second approach is to create paths based upon the current platform the code\nis running under. That is, when running under Linux or Unix, create Unix-style\npaths, and when running under Windows, create windows paths. This is handled by\nthe [PlatformFileSystemPath]:\n\n```php\nuse Pathogen\\FileSystem\\PlatformFileSystemPath;\n\n// creates a path to match the current platform\n$path = PlatformFileSystemPath::fromString('/path/to/foo');\n```\n\nNote that [FileSystemPath] and [PlatformFileSystemPath] are only utility classes\nwith static methods. The actual path class used will depend on the input. If it\nis necessary to type hint for a file system path, [FileSystemPathInterface] or\none of its more specialized child interfaces should be used instead.\n\n[FileSystemPath]: http://lqnt.co/pathogen/artifacts/documentation/api/Eloquent/Pathogen/FileSystem/FileSystemPath.html\n[FileSystemPathInterface]: http://lqnt.co/pathogen/artifacts/documentation/api/Eloquent/Pathogen/FileSystem/FileSystemPathInterface.html\n[PlatformFileSystemPath]: http://lqnt.co/pathogen/artifacts/documentation/api/Eloquent/Pathogen/FileSystem/PlatformFileSystemPath.html\n\n### Immutability of paths\n\nPaths in *Pathogen* are *immutable*, meaning that once they are created, they\ncannot be modified. When performing some mutating operation on a path, such as\nnormalization or resolution, a new path instance is produced, rather than the\noriginal instance being altered. This allows a path to be exposed as part of an\ninterface without creating a leaky abstraction.\n\n### Windows path support\n\n*Pathogen* provides support for Windows paths. In addition to the methods\navailable to Unix-style paths, Windows paths contain an optional drive\nspecifier. The drive specifier is available via the `drive()` method:\n\n```php\n$drive = $path-\u003edrive(); // returns a single-character string, or null\n```\n\n### Dependency consumer traits\n\n*Pathogen* provides some [traits] to make consuming its services extremely\nsimple for code targeting PHP 5.4 and higher.\n\nThe concept of a dependency consumer trait is simple. If a class requires, for\nexample, a path factory, it can simply use a `PathFactoryTrait`. This gives the\nclass `setPathFactory()` and `pathFactory()` methods for managing the path\nfactory dependency.\n\nThis example demonstrates how to use the file system path factory trait:\n\n```php\nuse Pathogen\\FileSystem\\Factory\\Consumer\\FileSystemPathFactoryTrait;\n\nclass ExampleConsumer\n{\n    use FileSystemPathFactoryTrait;\n}\n\n$consumer = new ExampleConsumer;\necho get_class($consumer-\u003epathFactory()); // outputs 'Pathogen\\FileSystem\\Factory\\FileSystemPathFactory'\n```\n\n[traits]: http://php.net/traits\n\n#### Available dependency consumer traits\n\n- [PlatformFileSystemPathFactoryTrait](src/Eloquent/Pathogen/FileSystem/Factory/Consumer/PlatformFileSystemPathFactoryTrait.php)\n- [FileSystemPathFactoryTrait](src/Eloquent/Pathogen/FileSystem/Factory/Consumer/FileSystemPathFactoryTrait.php)\n- [PathFactoryTrait](src/Eloquent/Pathogen/Factory/Consumer/PathFactoryTrait.php)\n\n## Usage examples\n\n### Resolving a user-provided path against the current working directory\n\n```php\nuse Pathogen\\FileSystem\\Factory\\PlatformFileSystemPathFactory;\n\n$factory = new PlatformFileSystemPathFactory;\n$workingDirectoryPath = $factory-\u003ecreateWorkingDirectoryPath();\n\n$path = $workingDirectoryPath-\u003eresolve(\n    $factory-\u003ecreate($_SERVER['argv'][1])\n);\n```\n\n### Resolving a path against another arbitrary path\n\n```php\nuse Pathogen\\Path;\n\n$basePath = Path::fromString('/path/to/base');\n$path = Path::fromString('../child');\n\n$resolvedPath = $basePath-\u003eresolve($path);\n\necho $resolvedPath-\u003estring();              // outputs '/path/to/base/../child'\necho $resolvedPath-\u003enormalize()-\u003estring(); // outputs '/path/to/child'\n```\n\n### Determining whether one path exists inside another\n\n```php\nuse Pathogen\\Path;\n\n$basePath = Path::fromString('/path/to/foo');\n$pathA = Path::fromString('/path/to/foo/bar');\n$pathB = Path::fromString('/path/to/somewhere/else');\n\nvar_dump($basePath-\u003eisAncestorOf($pathA)); // outputs 'bool(true)'\nvar_dump($basePath-\u003eisAncestorOf($pathB)); // outputs 'bool(false)'\n```\n\n### Appending an extension to a path\n\n```php\nuse Pathogen\\Path;\n\n$path = Path::fromString('/path/to/foo.bar');\n$pathWithExtension = $path-\u003ejoinExtensions('baz');\n\necho $pathWithExtension-\u003estring(); // outputs '/path/to/foo.bar.baz'\n```\n\n### Replacing a path's extension\n\n```php\nuse Pathogen\\Path;\n\n$path = Path::fromString('/path/to/foo.bar');\n$pathWithNewExtension = $path-\u003ereplaceExtension('baz');\n\necho $pathWithNewExtension-\u003estring(); // outputs '/path/to/foo.baz'\n```\n\n### Replacing a section of a path\n\n```php\nuse Pathogen\\Path;\n\n$path = Path::fromString('/path/to/foo/bar');\n$pathWithReplacement = $path-\u003ereplace(1, array('for', 'baz'), 2);\n\necho $pathWithReplacement-\u003estring(); // outputs '/path/for/baz/bar'\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmschop%2Fpathogen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmschop%2Fpathogen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmschop%2Fpathogen/lists"}