AmaTeam\Pathetic\Path

Complexity

Total Complexity

91

Size/Duplication

Total Lines	632
Duplicated Lines	0 %

Coupling/Cohesion

Components	1
Dependencies	0

Test Coverage

Coverage

100%

Importance

Changes

0

38 Methods

Rating	Name	Duplication	Size	Complexity
A	__construct()	0	7	1
B	parse()	0	18	8
A	extractScheme()	0	8	2
A	stripScheme()	0	4	2
A	containsRoot()	0	13	4
A	getPlatformBySeparator()	0	12	3
A	detectPlatform()	0	4	1
B	tryAdapt()	0	12	5
A	adapt()	0	8	2
B	normalize()	0	24	6
A	enumerate()	0	14	2
A	iterator()	0	4	1
A	getParents()	0	6	1
A	isAbsolute()	0	4	1
A	isRelative()	0	4	1
A	isRoot()	0	4	2
B	isDescendantOf()	0	21	6
A	isAncestorOf()	0	4	1
A	isChildOf()	0	9	2
A	isParentOf()	0	4	1
A	isSiblingOf()	0	8	3
A	getParent()	0	9	2
A	resolve()	0	10	2
B	relativize()	0	33	6
C	compareTo()	0	29	8
A	compareStrings()	0	10	4
A	equals()	0	4	1
A	getScheme()	0	4	1
A	getRoot()	0	4	1
A	getSegments()	0	4	1
A	getSeparator()	0	4	1
A	withScheme()	0	6	1
A	withoutScheme()	0	4	1
A	withRoot()	0	6	1
A	withoutRoot()	0	4	1
A	assemble()	0	11	3
A	__toString()	0	4	1
A	toPlatformString()	0	4	1

<?php

namespace AmaTeam\Pathetic;

use ArrayIterator;
use Iterator;
use RuntimeException;

/**
 * This class represents abstract filesystem path - regardless of underlying
 * operating system. It is represented just as (sometimes) scheme, (sometimes)
 * root point, and a list of segments of which path consists. It provides lots
 * of auxiliary methods (like hierarchy comparison or paths resolution) that
 * help to deal with paths in an OS-independent way, which, i hope, will result
 * in easier pathwork in any library.
 *
 * @author Etki <etki@etki.me>
 */
class Path
{
    const PLATFORM_UNIX = 'unix';
    const PLATFORM_WINDOWS = 'windows';

    /**
     * Separator that is used to render platform-independent representations.
     */
    const SEPARATOR = '/';

    /**
     * Path scheme, if any was used.
     *
     * @var string|null
     */
    private $scheme;

    /**
     * Path root. May be null (relative path), empty string (unix root or
     * windows path \like\that) or drive name (windows-only).
     *
     * @var string|null
     */
    private $root;

    /**
     * List of path segments.
     *
     * @var string[]
     */
    private $segments;

    /**
     * Separator that will be used to assemble path back.
     *
     * @var string
     */
    private $separator;

    /**
     * @param string|null $scheme
     * @param string|null $root
     * @param string[] $segments
     * @param string $separator
     */
    public function __construct($scheme, $root, array $segments, $separator)
    {
        $this->scheme = $scheme;
        $this->root = $root;
        $this->segments = $segments;
        $this->separator = $separator;
    }

    /**
     * Parses provided path into {@link Path} instance, acting as a public
     * constructor for whole Path class.
     *
     * @param string $input Path to be parsed
     * @param string|null $platform Platform used to determine correct
     * algorithm. If omitted/set to null, will be detected automatically.
     *
     * @return Path
     */
    public static function parse($input, $platform = null)
    {
        $platform = $platform ?: static::detectPlatform();
        $separator = $platform === static::PLATFORM_UNIX ? '/' : '\\';
        $scheme = static::extractScheme($input);
        $scheme = empty($scheme) ? null : $scheme;
        $path = static::stripScheme($input, $scheme);
        if ($platform === static::PLATFORM_WINDOWS) {
            $path = str_replace('\\', '/', $path);
        }
        $segments = $path === '' ? [] : explode('/', $path);
        $root = null;
        if (static::containsRoot($segments, $platform)) {
            $root = array_shift($segments);
            $segments = $segments === [''] ? [] : $segments;
        }
        return new static($scheme, $root, $segments, $separator);
    }

    protected static function extractScheme($input)
    {
        $position = strpos($input, '://');
        if ($position === false) {
            return null;
        }
        return substr($input, 0, $position);
    }

    protected static function stripScheme($input, $scheme)
    {
        return empty($scheme) ? $input : substr($input, strlen($scheme) + 3);
    }

    protected static function containsRoot(array $segments, $platform)
    {
        if (empty($segments)) {
            return false;
        }
        if ($segments[0] === '') {
            return true;
        }
        if ($platform === static::PLATFORM_UNIX) {
            return false;
        }
        return strpos($segments[0], ':') > 0;
    }

    /**
     * Returns platform matching the separator. Exists for 100% coverage :P
     *
     * @param string $separator
     * @return string
     */
    public static function getPlatformBySeparator($separator)
    {
        switch ($separator) {
            case '/':
                return static::PLATFORM_UNIX;
            case '\\':
                return static::PLATFORM_WINDOWS;
            default:
                $format = 'Unknown directory separator %s';
                throw new RuntimeException(sprintf($format, $separator));
        }
    }

    /**
     * Detects current platform.
     *
     * @return string
     */
    public static function detectPlatform()
    {
        return static::getPlatformBySeparator(DIRECTORY_SEPARATOR);
    }

    /**
     * Converts input into path. Throws runtime exception if that's not
     * possible.
     *
     * @param Path|string|mixed $input
     * @return Path|null
     */
    protected function tryAdapt($input)
    {
        if ($input instanceof Path) {
            return $input;
        }
        if (is_object($input)) {
            if (method_exists($input, '__toString')) {
                $input = $input->__toString();
            }
        }
        return is_string($input) ? static::parse($input) : null;
    }

    /**
     * Converts input into path. Throws runtime exception if that's not
     * possible.
     *
     * @param Path|string $input
     * @return Path
     */
    protected function adapt($input)
    {
        $input = $this->tryAdapt($input);
        if ($input === null) {
            throw new RuntimeException('Invalid input provided');
        }
        return $input;
    }

    /**
     * Creates new path, destroying as much empty ('') and dot-entries
     * ('.', '..') as possible, so path 'node/./../leaf' will be truncated
     * just to leaf, but 'node/../../leaf' would result in '../leaf'.
     *
     * @return Path
     */
    public function normalize()
    {
        /**
         * @param string[] $carrier
         * @param string $segment
         * @return string[]
         */
        $reducer = function ($carrier, $segment) {
            if ($segment === '' || $segment === '.') {
                return $carrier;
            }
            if ($segment === '..' && !empty($carrier) && end($carrier) !== '..') {
                array_pop($carrier);
                return $carrier;
            }
            $carrier[] = $segment;
            return $carrier;
        };
        $copy = clone $this;
        /** @var string[] $segments */
        $segments = array_reduce($this->segments, $reducer, []);
        $copy->segments = $segments;
        return $copy;
    }

    /**
     * Returns hierarchy branch from the topmost node (root, if present) down
     * to current node, so `/a/b/c` will result in `/a`, `  /a/b` and `/a/b/c`,
     * and `a/b` in `a` and `a/b`.
     *
     * @return Path[]
     */
    public function enumerate()
    {
        $accumulator = [];
        $results = [];
        $normalized = $this->normalize();
        foreach ($normalized->segments as $segment) {
            $copy = clone $normalized;
            $copy->segments = $accumulator;
            $results[] = $copy;
            $accumulator[] = $segment;
        }
        $results[] = $this;
        return $results;
    }

    /**
     * Returns iterator that will iterate hierarchy branch according to
     * {@link #enumerate} rules.
     *
     * @return Iterator Iterator that emits Path instances.
     */
    public function iterator()
    {
        return new ArrayIterator($this->enumerate());
    }

    /**
     * Returns list of path parents, starting from the topmost one and going
     * down one by one, similar to {@link #enumerate}.
     *
     * @return Path[]
     */
    public function getParents()
    {
        $enumeration = $this->enumerate();
        array_pop($enumeration);
        return $enumeration;
    }

    /**
     * @return bool
     */
    public function isAbsolute()
    {
        return $this->root !== null;
    }

    /**
     * @return bool
     */
    public function isRelative()
    {
        return $this->root === null;
    }

    /**
     * @return bool
     */
    public function isRoot()
    {
        return $this->root !== null && empty($this->segments);
    }

    /**
     * Returns true if $other is located on the same hierarchy branch higher
     * that current path.
     *
     * If path schemes differ, or not both paths are relative/absolute, this
     * method will instantly return false.
     *
     * @param Path|string $other
     * @return bool
     */
    public function isDescendantOf($other)
    {
        $other = $this->adapt($other)->normalize();
        $current = $this->normalize();
        if ($current->scheme !== $other->scheme) {
            return false;
        }
        if ($current->root !== $other->root) {
            return false;
        }
        if (sizeof($current->segments) <= sizeof($other->segments)) {
            return false;
        }
        $limit = sizeof($other->segments);
        for ($i = 0; $i < $limit; $i++) {
            if ($other->segments[$i] !== $current->segments[$i]) {
                return false;
            }
        }
        return true;
    }

    /**
     * Returns true if $other is located on the same hierarchy branch deeper
     * that current path.
     *
     * If path schemes differ, or not both paths are relative/absolute, this
     * method will instantly return false.
     *
     * @param Path|string $other
     * @return bool
     */
    public function isAncestorOf($other)
    {
        return $this->adapt($other)->isDescendantOf($this);
    }

    /**
     * Returns true if $other is direct parent of current path.
     *
     * If path schemes differ, or not both paths are relative/absolute, this
     * method will instantly return false.
     *
     * @param Path|string $other
     * @return bool
     */
    public function isChildOf($other)
    {
        $other = $this->adapt($other)->normalize();
        $current = $this->normalize();
        if (sizeof($other->segments) !== sizeof($current->segments) - 1) {
            return false;
        }
        return $current->isDescendantOf($other);
    }

    /**
     * Returns true if $other is direct child of current path.
     *
     * If path schemes differ, or not both paths are relative/absolute, this
     * method will instantly return false.
     *
     * @param Path|string $other
     * @return bool
     */
    public function isParentOf($other)
    {
        return $this->adapt($other)->isChildOf($this);
    }

    /**
     * Returns true if $other is located on the smae hierarchy level.
     *
     * If path schemes differ, or not both paths are relative/absolute, this
     * method will instantly return false.
     *
     * @param Path|string $other
     * @return bool
     */
    public function isSiblingOf($other)
    {
        $other = $this->adapt($other);
        if ($other->isRoot()) {
            return $this->isRoot() && $this->root === $other->root;
        }
        return $other->getParent()->isParentOf($this);
    }

    /**
     * Returns direct parent of current path. In case of call on root node
     * exception will be thrown.
     *
     * @return Path
     */
    public function getParent()
    {
        if ($this->isRoot()) {
            throw new RuntimeException('Root cannot have parent node');
        }
        $copy = clone $this;
        $copy->segments[] = '..';
        return $copy->normalize();
    }

    /**
     * Resolves other path against current one (or, in other words, prepends
     * current path to provided one). If provided path is absolute, it is
     * returned as-is, otherwise it is appended to current one:
     *
     * /a/b resolve /c/d => /b/c
     * /a/b resolve c/d => /a/b/c/d
     * a/b resolve c/d => a/b/c/d
     *
     * @param Path|string $other
     *
     * @return Path
     */
    public function resolve($other)
    {
        $other = $this->adapt($other);
        if ($other->isAbsolute()) {
            return $other;
        }
        $copy = clone $this;
        $copy->segments = array_merge($copy->segments, $other->segments);
        return $copy;
    }

    /**
     * Construct a relative path, trying to subtract current path from provided
     * one (thus providing a path required to traverse from current one to
     * provided one). If called with an absolute path against relative or vice
     * versa, will return other path as is.
     *
     * @param Path|string $other
     *
     * @return Path
     */
    public function relativize($other)
    {
        $other = $this->adapt($other);
        if ($other->root !== $this->root) {
            return $other;
        }
        $current = $this->normalize();
        $other = $other->normalize();
        $counter = 0;
        $count = sizeof($current->segments);
        for ($i = 0; $i < $count; $i++) {
            if (!isset($other->segments[$i])) {
                break;
            }
            if ($current->segments[$i] !== $other->segments[$i]) {
                break;
            }
            $counter++;
        }
        /** @var string[] $traversal */
        $traversal = [];
        if ($count - $counter > 0) {
            $traversal = array_fill(0, $count - $counter, '..');
        }
        /** @var string[] $slice */
        $slice = array_slice($other->segments, $counter);
        /** @var string[] $segments */
        $segments = array_merge($traversal, $slice);
        $copy = clone $this;
        $copy->root = null;
        $copy->segments = $segments;
        return $copy;
    }

    /**
     * Lexicographically compares one path to another.
     *
     * @param Path|string|null $other
     * @return int
     */
    public function compareTo($other)
    {
        $other = $this->tryAdapt($other);
        if ($other === null) {
            return 1;
        }
        $other = $other->normalize();
        $current = $this->normalize();
        $schemes = $this->compareStrings($current->scheme, $other->scheme);
        if ($schemes !== 0) {
            return $schemes;
        }
        $roots = $this->compareStrings($current->root, $other->root);
        if ($roots !== 0) {
            return $roots;
        }
        $limit = max(sizeof($current->segments), sizeof($other->segments));
        for ($i = 0; $i < $limit; $i++) {
            if (!isset($current->segments[$i])) {
                return -1;
            } else if (!isset($other->segments[$i])) {
                return 1;
            } else if ($current->segments[$i] === $other->segments[$i]) {
                continue;
            }
            return strcmp($current->segments[$i], $other->segments[$i]);
        }
        return 0;
    }

    /**
     * Helper method for {@link #compareTo()}
     *
     * @param string|null $left
     * @param string|null $right
     * @return int
     */
    protected function compareStrings($left, $right)
    {
        if ($left === null) {
            return $right === null ? 0 : -1;
        }
        if ($right === null) {
            return 1;
        }
        return strcmp($left, $right);
    }

    /**
     * Compares current path to provided one and tells if they are equal.
     *
     * @param Path|string|null $other
     * @return bool
     */
    public function equals($other)
    {
        return $this->compareTo($other) === 0;
    }

    /**
     * @return string|null
     */
    public function getScheme()
    {
        return $this->scheme;
    }

    /**
     * @return string|null
     */
    public function getRoot()
    {
        return $this->root;
    }

    /**
     * @return string[]
     */
    public function getSegments()
    {
        return $this->segments;
    }

    /**
     * @return string
     */
    public function getSeparator()
    {
        return $this->separator;
    }

    /**
     * @param string|null $scheme
     * @return Path
     */
    public function withScheme($scheme)
    {
        $copy = clone ($this);
        $copy->scheme = $scheme;
        return $copy;
    }

    /**
     * @return Path
     */
    public function withoutScheme()
    {
        return $this->withScheme(null);
    }

    /**
     * @param string $root
     * @return Path
     */
    public function withRoot($root)
    {
        $copy = clone $this;
        $copy->root = $root;
        return $copy;
    }

    /**
     * @return Path
     */
    public function withoutRoot()
    {
        return $this->withRoot(null);
    }

    /**
     * Assembles string representation using provided separator.
     *
     * @param string $separator
     * @return string
     */
    protected function assemble($separator)
    {
        $builder = '';
        if (!empty($this->scheme)) {
            $builder .= $this->scheme . '://';
        }
        if ($this->root !== null) {
            $builder .= $this->root . $separator;
        }
        return $builder . implode($separator, $this->segments);
    }

    /**
     * Returns platform-independent representation.
     *
     * @return string
     */
    public function __toString()
    {
        return $this->assemble(static::SEPARATOR);
    }

    /**
     * Returns representation for target platform.
     *
     * @return string
     */
    public function toPlatformString()
    {
        return $this->assemble($this->separator);
    }
}