README

Helper class for working with local paths in PHP.

Compatibility

This package requires PHP 5.4.0 or later.

Overview

Look at one of the following topics to learn more about Path Helper

• Path Helper
• Compatibility
• Overview
  • Installation
  • Usage
    • Using static method
    • Using method of instance
    • Using built-in function
  • Available methods
    • Normalize the directory separators of the path
    • Restyle the path
      • Restyle to Unix style
      • Restyle to Windows style
      • Restyle belong to current OS
    • Create the absolute path
    • Create the relative path
    • Check the form of the path
      • Check the absolute form
      • Check the relative form
    • Check the mutual wrapping of paths
      • Check if the path is ancestor of another
      • Check if the path is descendant of another
  • Available functions
• License

Installation

Download a latest package or use Composer:

$ composer require jackiedo/path-helper

Usage

After requiring composer autoloader, you can use the package in the following ways:

Using static method

use Jackiedo\PathHelper\Path;

// ...

$return = Path::doSomething();

Using method of instance

use Jackiedo\PathHelper\Path;

// ...

$helper = new Path;
$return = $helper->doSomething();

Using built-in function

See here for more details.

Available methods

Normalize the directory separators of the path

Formats the directory separators of a given path with a specific string.

Syntax:

/**
 * Formats the directory separators of a given path with a specific string.
 *
 * @param string $path      the path want to normalize
 * @param string $separator the directory separator want to use
 *
 * @return string
 */
public static function normalize($path, $separator = DIRECTORY_SEPARATOR);

Example:

$return1 = Path::normalize('path\\to/specific/file/or\\directory');
// The result returned will depend on the operating system
//     On Windows -> path\to\specific\file\or\directory
//     On Unix    -> path/to/specific/file/or/directory

$return2 = Path::normalize('path\\to/specific/file/or\\directory', '/');
// path/to/specific/file/or/directory

$return3 = Path::normalize('path\\to/specific/file/or\\directory', ' > ');
// path > to > specific > file > or > directory

Restyle the path

Restyle to Unix style

Alternative to normalize($path, '/') method.

Syntax:

/**
 * Normalize directory separators of a given path according to Unix OS style.
 *
 * @param string $path the path want to normalize
 *
 * @return string
 */
public static function unixStyle($path);

Example:

$return = Path::unixStyle('path\\to/specific/file/or\\directory');
// path/to/specific/file/or/directory

Restyle to Windows style

Alternative to normalize($path, '\\') method.

Syntax:

/**
 * Normalize directory separators of a given path according to Windows OS style.
 *
 * @param string $path the path want to normalize
 *
 * @return string
 */
public static function winStyle($path);

Example:

$return = Path::winStyle('path\\to/specific/file/or\\directory');
// path\to\specific\file\or\directory

Restyle belong to current OS

Alternative to normalize($path, DIRECTORY_SEPARATOR) method.

Syntax:

/**
 * Normalize directory separators of a given path according to the current OS style.
 *
 * @param string $path the path want to normalize
 *
 * @return string
 */
public static function osStyle($path);

Example:

$return = Path::osStyle('path\\to/specific/file/or\\directory');
// The result returned will depend on the operating system
//     On Windows -> path\to\specific\file\or\directory
//     On Unix    -> path/to/specific/file/or/directory

Create the absolute path

Create the absolute path from a given path.

Syntax:

/**
 * Return absolute path from a given path.
 *
 * This method is an alternative to `realpath()` function for non-existent paths.
 *
 * @param string $path      the path want to format
 * @param string $separator the directory separator want to use in the result
 *
 * @return string
 */
public static function absolute($path, $separator = DIRECTORY_SEPARATOR);

Example:

$return = Path::absolute('./this\\is/../sample/path');
// The result returned will depend on the operating system and current working directory
// You will probably get the following result: /home/www/public_html/this/sample/path

Note:

This method looks like PHP's realpath() function at first glance, but it actually works in a different way.

The realpath() function returns the absolute path to the existing directory or file, while this method does not check for actual existence.

Create the relative path

Create the relative path from a given file or directory to another location.

Syntax:

/**
 * Return relative path from a given file or directory to another location.
 *
 * @param string $from      the path of departure file or directory
 * @param string $to        the path of destination file or directory
 * @param string $separator the directory separator want to use in the result
 *
 * @return string
 */
public static function relative($from, $to, $separator = DIRECTORY_SEPARATOR);

Example:

$return = Path::absolute('./this\\is/../sample/path', '/home/www/another/directory');
// The result returned will depend on the operating system and current working directory
// You will probably get the following result: ../../../../another/directory

Check the form of the path

Check the absolute form

Syntax:

/**
 * Check if a given path is an absolute path.
 *
 * @param string $path the path want to check
 *
 * @return bool
 */
public static function isAbsolute($path);

Example:

$return = Path::isAbsolute('/home/www/public_html');      // true
$return = Path::isAbsolute('sample/../path');             // false
$return = Path::isAbsolute('D:\\home\\www\\public_html'); // true
$return = Path::isAbsolute('sample\\..\\path');           // false

Check the relative form

Syntax:

/**
 * Check if a given path is a relative path.
 *
 * @param string $path the path want to check
 *
 * @return bool
 */
public static function isRelative($path);

Example:

$return = Path::isRelative('/home/www/public_html');      // false
$return = Path::isRelative('sample/../path');             // true
$return = Path::isRelative('D:\\home\\www\\public_html'); // false
$return = Path::isRelative('sample\\..\\path');           // true

Check the mutual wrapping of paths

Check if the path is ancestor of another

Syntax:

/**
 * Check if a given path is ancestor of the another path.
 *
 * Return true if the input path is ancestor of the comparison
 *
 * @param string $path       the path want to check
 * @param string $comparison the target path used for comparison
 *
 * @return bool
 */
public static function isAncestor($path, $comparison);

Example:

$return = Path::isAncestor('/home/www', '/home/www/public/assets/css/../images/sample.png');     // true
$return = Path::isAncestor('/home/www', '/another_home/public/assets/css/../images/sample.png'); // false

Check if the path is descendant of another

Syntax:

/**
 * Check if a given path is descendant of the another path.
 *
 * Return true if the input path is descendant of the comparison
 *
 * @param string $path       the path want to check
 * @param string $comparison the target path used for comparison
 *
 * @return bool
 */
public static function isDescendant($path, $comparison);

Example:

$return = Path::isDescendant('/home/www/public/assets/css/../images/sample.png', '/home/www');     // true
$return = Path::isDescendant('/another_home/public/assets/css/../images/sample.png', '/home/www'); // false

Available functions

This package contains several built-in functions to alternative using the methods of the Path class. However, the use of these functions is not recommended, because they may conflict with the functions of other packages.

License

MIT © Jackie Do