improve documentation

lazervel · Nov 19, 2024 · 10e8999 · 10e8999
1 parent 5537b6c
commit 10e8999
Show file tree

Hide file tree

Showing 2 changed files with 179 additions and 7 deletions.
diff --git a/README.md b/README.md
@@ -27,7 +27,7 @@ or add it by hand to your `composer.json` file.
 ## The Features of PHP Path
 - [Path::basename($path[, $suffix])](#pathbasenamepath-suffix)
 - [Path::canonicalize($path)](#pathcanonicalizepath)
-- [Path::changeExt($path, $newExt)]()
+- [Path::changeExt($path, $newExt)](#pathchangeextpath-newext)
 - [Path::combine($paths, $names)](#pathcombinepaths-names)
 - [Path::checkLength($path)](#pathchecklengthpath)
 - [Path::delimiter](#pathdelimiter)
@@ -36,7 +36,7 @@ or add it by hand to your `composer.json` file.
 - [Path::filename($path)](#pathfilenamepath)
 - [Path::format($pathObject)](#pathformatpathobject)
 - [Path::getcwd()](#pathgetcwd)
-- [Path::hasExt($path)]()
+- [Path::hasExt($path)](#pathhasextpath)
 - [Path::info()](#pathinfo)
 - [Path::isAbsolute($path)](#pathisabsolutepath)
 - [Path::isLocal($path)](#pathislocalpath)
@@ -50,8 +50,8 @@ or add it by hand to your `composer.json` file.
 - [Path::pathToURL($path, $origin[, ?$query, ?$hash])](#pathpathtourlpath-origin-query-hash)
 - [Path::posix](#pathposix)
 - [Path::relative($from, $to)](#pathrelativefrom-to)
-- [Path::removeExt($path)]()
-- [Path::resolve($path)](#pathresolvepath)
+- [Path::removeExt($path)](#pathremoveextpath)
+- [Path::resolve(...$paths)](#pathresolvepath)
 - [Path::rootname($path)](#pathrootnamepath)
 - [Path::sep](#pathsep)
 - [Path::tmp($path)](#pathtmppath)
@@ -66,6 +66,13 @@ require 'vendor/autoload.php';
 
 ## Path::basename($path[, $suffix])
 
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- `$suffix` <font color="blue">string</font>  An optional suffix to remove
+- <font color="blue">Returns:</font> <font color="blue">string</font>
+
+The `Path::basename()` method returns the last portion of a path, similar to the Unix basename command. Trailing `directory separators` are ignored.
+
 For example, on POSIX:
 
 ```php
@@ -88,6 +95,9 @@ Path::basename('/home/local/user/example.html', '.html');
 
 ## Path::canonicalize($path)
 
+canonicalize function converts a given path into its canonical (absolute and standardized) form. It resolves relative paths, symbolic links, and eliminates redundant or unnecessary components
+like '.' and '..' to return a clean and absolute version of the path.
+
 For example, on POSIX:
 
 ```php
@@ -103,6 +113,15 @@ Path::canonicalize('/path/composer.json');
 ```
 
 ## Path::changeExt($path, $newExt)
+
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- `$newExt` <font color="blue">string</font>
+- Return: <font color="blue">string</font>
+
+Returns a path string with changed initial extension to replaced new extension.<br>
+If path extension and givent new extension are same then changeExt will be not modify and return path with initial extension.
+
 ```php
 Path::changeExt('/foo/bar/baz/asdf/quux.html', '.php');
 // Returns: '/foo/bar/baz/asdf/quux.php'
@@ -113,6 +132,13 @@ Path::changeExt('/foo/bar/baz/asdf/vector.gif', 'svg');
 
 ## Path::combine($paths, $names)
 
+**Parameters:**
+- `$paths` <font color="blue">array</font>
+- `$names` <font color="blue">array</font>
+- Return: <font color="blue">array</font>
+
+Creates an array by using one array for paths and another for its names. And creates multiple files combined with paths from to file names.
+
 For example, on POSIX:
 
 ```php
@@ -146,6 +172,13 @@ Path::combine(['C:\\xampp\\htdocs', '\\path'], ['example.html', 'foot.txt', '.en
 ```
 
 ## Path::checkLength($path)
+
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- Return: <font color="blue">void</font>
+
+Check a valid path length and report exception.
+
 ```php
 // Check maximum path length on your system use \PHP_MAXPATHLEN constant.
 Path::checkLength('your-path');
@@ -185,6 +218,14 @@ explode(Path::delimiter, getenv('PATH'));
 
 ## Path::dirname($path[, $suffix, $levels])
 
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- `$suffix` <font color="blue">string</font>
+- `$levels` <font color="blue">int</font>
+- Return: <font color="blue">string</font>
+
+Get the directory name of a given path with optional suffix removal and level adjustment. This function returns the parent directory's path of the provided file or directory path. It also allows for an optional suffix to be removed from the base name and specifies how many levels up the directory to go.
+
 For example, on POSIX:
 
 ```php
@@ -203,6 +244,13 @@ Path::dirname('/foo/bar/baz/asdf/quux\\abcd\\xyz');
 ```
 
 ## Path::extname($path)
+
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- Return: <font color="blue">string</font>
+
+Returns extname method a path extension name from given path, Its used to get file extention.
+
 ```php
 Path::extname('C:\\xampp\\htdocs\\example.html');
 // Returns: '.html'
@@ -224,6 +272,13 @@ Path::extname('C:\\xampp\\htdocs\\example.md');
 ```
 
 ## Path::filename($path)
+
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- Return: <font color="blue">string</font>
+
+Returns a filename without extention of given path.
+
 ```php
 Path::filename('/foo/bar/baz/asdf/quux.html');
 // Returns: 'quux.html'
@@ -243,6 +298,12 @@ Path::filename('C:\\path\\dir\\file.txt');
 
 ## Path::format($pathObject)
 
+**Parameters:**
+- `$pathObject` <font color="blue">array</font>
+- Return: <font color="blue">string</font>
+
+Returns a path string from an array-object - the opposite of parse(). format method are same work as `phpinfo` method But there install the extra property `root` property to getting current root [dir] of path
+
 For example, on POSIX:
 
 ```php
@@ -295,6 +356,8 @@ Path::format([
 
 ## Path::getcwd()
 
+Retrieves the current working directory based on the operating system. This method returns the current working directory in a format appropriate for the platform. For `POSIX` systems, it returns a path like `/xampp/htdocs/`, while for Windows systems, it returns a path like `C:/xampp/htdocs/`.
+
 For example, on POSIX:
 
 ```php
@@ -311,6 +374,13 @@ Path::getcwd(); // Returns: C:\\xampp\\htdocs
 ```
 
 ## Path::hasExt($path)
+
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- Return: <font color="blue">bool</font>
+
+hasExt method will check extension exists or not exists of given path and matcher Extensions, if Given extensions in matched path extension then return true, Otherwise return false.
+
 ```php
 Path::hasExt('/foo/bar/baz/asdf/vector.png', ['.gif', '.jpg', '.png']); // Returns: true
 Path::hasExt('/foo/bar/baz/asdf/vector.gif', '.gif');                   // Returns: true
@@ -325,6 +395,8 @@ Path::hasExt('/foo/bar/baz/asdf/vector.gif', ['svg', 'jpeg', 'png']);   // Retur
 
 ## Path::info()
 
+Returns information about a file path.
+
 For example, on POSIX:
 
 ```php
@@ -353,6 +425,12 @@ Path::info('C:\\xampp\\htdocs\\path\\Path.php');
 
 ## Path::isAbsolute($path)
 
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- Return: <font color="blue">bool</font>
+
+Determines whether {path} is an absolute path. An absolute path will always resolve to the same location,regardless of the working directory.
+
 For example, on POSIX:
 
 ```php
@@ -374,6 +452,13 @@ Path::isAbsolute('.');           // Returns: false
 ```
 
 ## Path::isLocal($path)
+
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- Return: <font color="blue">bool</font>
+
+isLocal function checks whether the provided path is local or not. It determines if the given path refers to a local file or directory.
+
 ```php
 Path::isLocal('C:Users\JohnDoe\Documents\file.txt');  // Returns: 'false'
 Path::isLocal('//home/user/file.txt');                // Returns: 'false'
@@ -389,6 +474,12 @@ Path::isLocal('E:\Music\Rock\song.mp3');              // Returns: 'true'
 
 ## Path::isURIPath($path)
 
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- Return: <font color="blue">bool</font>
+
+Check if the given path is a valid network path. A valid network path starts with two backslashes `\\` or `//` followed by the server name, and can include subdirectories.
+
 **Support:** working only Windows:
 
 ```php
@@ -402,6 +493,13 @@ Path::isURIPath('C:/xampp/htdocs/');   // Returns: false
 ```
 
 ## Path::join([...$paths])
+
+**Parameters:**
+- `...$paths` <font color="blue">string</font>
+- Return: <font color="blue">string</font>
+
+Join all arguments together and normalize the resulting path.
+
 ```php
 Path::join('/foo', 'bar', 'baz/asdf', 'quux', '..');
 // Returns: '/foo/bar/baz/asdf'
@@ -417,6 +515,12 @@ Path::join('foo', [], 'bar');
 
 ## Path::normalize($path)
 
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- Return: <font color="blue">string</font>
+
+Normalize a string path, reducing `..` and `.` parts. When multiple slashes are found, they're replaced by a single one; when the path contains a trailing slash, it is preserved. On Windows backslashes are used.
+
 For example, on POSIX:
 
 ```php
@@ -444,6 +548,12 @@ Path::win32::normalize('C:////temp\\\\/\\/\\/foo/bar');
 
 ## Path::parse($path)
 
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- Return: <font color="blue">array</font>&lt;<font color="blue">string</font>,<font color="blue">string</font>&gt;
+
+Returns an object from a path string - the opposite of `format()`.
+
 For example, on POSIX:
 
 ```php
@@ -494,6 +604,12 @@ path.parse('C:\\path\\dir\\file.txt');
 
 ## Path::pathname($path)
 
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- Return: <font color="blue">string</font>
+
+Get the path name of a given file or directory. This function returns the path name without any suffix or modification and without drive.
+
 For example, on POSIX:
 
 ```php
@@ -543,6 +659,15 @@ Since Windows recognizes multiple path separators, both separators will be repla
 
 ## Path::pathToURL($path, $origin[, ?$query, ?$hash])
 
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- `$origin` <font color="blue">string</font>
+- `$query` <font color="blue">string</font>
+- `$hash` <font color="blue">string</font>
+- Return: <font color="blue">string</font>
+
+pathToURL - Convert path to url, Returns path to url combination with `(e.g., path, origin, ?query, ?hash)`.
+
 **Notice:** Don't use syntax `Path::win32::pathToURL()` or `Path::posix::pathToURL()`, This a common bugs. but don't worry we fix this bugs to next expected version `[v10.2.0]`.
 
 For example, on POSIX:
@@ -585,6 +710,13 @@ The API is accessible via `Path\Path::posix` or `Path\Linux\Linux::class`.
 
 ## Path::relative($from, $to)
 
+**Parameters:**
+- `$from` <font color="blue">string</font>
+- `$to` <font color="blue">string</font>
+- Return: <font color="blue">string</font>
+
+Solve the relative path from `from` to `to` based on the current working directory. At times we have two absolute paths, and we need to derive the relative path from one to the other. This is actually the reverse transform of path.resolve.
+
 For example, on POSIX:
 
 ```php
@@ -600,6 +732,13 @@ Path::relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb');
 ```
 
 ## Path::removeExt($path)
+
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- Return: <font color="blue">string</font>
+
+Returns a path string with removed path extension.
+
 ```php
 Path::removeExt('/var/www/web.php');
 // Returns: '/var/www/web'
@@ -617,7 +756,13 @@ Path::removeExt('G:/path/.github');
 // Returns: 'G:/path/' bugs detected
 ```
 
-## Path::resolve($path)
+## Path::resolve(...$path)
+
+**Parameters:**
+- `...$paths` <font color="blue">string</font> A sequence of path segments.
+- Return: <font color="blue">string</font>
+
+The right-most parameter is considered `to`. Other parameters are considered an array of `from`. Starting from leftmost `from` parameter, resolves `to` to an absolute path. If `to` isn't already absolute, `from` arguments are prepended in right to left order, until an absolute path is found. If after using all `from` paths still no absolute path is found, the current working directory is used as well. The resulting path is normalized, and trailing slashes are removed unless the path gets resolved to the root directory.
 
 For example, on POSIX:
 
@@ -649,6 +794,12 @@ Path::resolve('wwwroot', 'static_files/png/', '../gif/image.gif');
 
 ## Path::rootname($path)
 
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- Return: <font color="blue">string</font>
+
+Retrieves the root name of the path. This method extracts the root component of a given path, which can be useful for determining the base directory or starting point for further path manipulations.
+
 For example, on POSIX:
 
 ```php
@@ -707,6 +858,12 @@ On Windows, both the forward slash (`/`) and backward slash (`\`) are accepted a
 
 ## Path::tmp($path)
 
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- Return: <font color="blue">string</font>
+
+Returns tmp name, To make a tmp name with dirname of given path.
+
 For example, on POSIX:
 
 ```php
@@ -728,6 +885,13 @@ Path::tmp('foot\\bar\\baz');
 ```
 
 ## Path::toNamespacedPath($path)
+
+**Parameters:**
+- `$path` <font color="blue">string</font>
+- Return: <font color="blue">string</font>
+
+On `Windows` systems only, returns an equivalent namespace-prefixed path for the given path. If path is not a string, path will be returned without modifications. This method is meaningful only on Windows system. On `POSIX` systems, the method is non-operational and always returns path without modifications.
+
 ```php
 Path::toNamespacedPath('\\foo\\bar/baz\\asdfquux\\abcd\\xyz');
 // Returns: '\\\\?\\G:\\foo\\bar\\baz\\asdfquux\\abcd\\xyz'
@@ -738,6 +902,12 @@ Path::toNamespacedPath('//foo\\bar/baz\\asdfquux\\abcd\\xyz');
 
 ## Path::UrlToPath($url)
 
+**Parameters:**
+- `$url` <font color="blue">string</font>
+- Return: <font color="blue">string</font>
+
+To convert url `https://example.com/home/parent/current/path` to `/home/parent/current/path`.
+
 For example, on POSIX:
 
 ```php