Helper classes doc

master
Anton Smirnov 2021-11-06 05:33:24 +02:00
parent 844d094d49
commit 0283f79c7b
4 changed files with 92 additions and 15 deletions

73
docs/helper_classes.rst Normal file
View File

@ -0,0 +1,73 @@
Helper Classes
##############
PathFactory
===========
``parse()``
-----------
.. code-block:: php
<?php
PathFactory::parse(
string $path,
array $urlSchemes = [],
array $streamSchemes = []
): PathInterface;
The ``parse`` function tries to detect the type of the given string path in the following order:
* Unix path
* Windows path
* Url/Scheme paths:
* If both ``$urlSchemes`` and ``$streamSchemes`` are empty, all scheme prefixed paths are parsed as URLs.
* If at least one of the lists is non-empty, all unknown schemes throw an exception.
* Known schemes are parsed according to which list they belong.
* Relative path of the current OS type.
* Since there is no way to separate root relative path from Unix path, root relative paths are never returned.
All paths are returned by the ``parse()`` constructor in a non strict mode.
PathUtils
=========
``resolveRelativePath()``
-------------------------
.. code-block:: php
<?php
PathUtils::resolveRelativePath(
string|PathInterface $basePath,
string|PathInterface $relativePath
): string;
Resolves relative path from the base path.
If a string is passed: it goes through ``PathFactory::parse()``.
If ``relativePath`` is an absolute path, it is converted to string and returned.
Otherwise ``$basePath->resolveRelative($relativePath)->toString()`` is returned.
``makeRelativePath()``
----------------------
.. code-block:: php
<?php
PathUtils::makeRelativePath(
string|AbsolutePathInterface $basePath,
string|AbsolutePathInterface $targetPath
): string;
Makes relative path from two absolute paths.
If a string is passed: it goes through ``PathFactory::parse()``.
If any of the paths is a relative path, an exception is thrown.
Otherwise ``$basePath->makeRelative($targetPath)->toString()`` is returned.

View File

@ -20,6 +20,7 @@ Documentation
path_interfaces
path_classes
helper_classes
License
=======

View File

@ -7,12 +7,14 @@ RelativePath
The only concrete implementation of ``RelativePathInterface``.
In non-root relative paths first component returned by ``getComponents()`` is either ``'.'`` or ``'..'``.
When resolving relative, windows-ness of the resulting relative will be inherited from the base path.
Available constructors:
.. code-block:: php
<?php
public function __construct(string $path, bool $windows = false);
new RelativePath(string $path, bool $windows = false);
``$windows = false``: Unix-like path. Path separators are slashes.
@ -22,21 +24,21 @@ When exporting a string, backslashes are used.
.. code-block:: php
<?php
public static function unix(string $path): self;
RelativePath::unix(string $path): self;
Same as ``new RelativePath($path, windows: false)``
.. code-block:: php
<?php
public static function windows(string $path): self;
RelativePath::windows(string $path): self;
Same as ``new RelativePath($path, windows: true)``
.. code-block:: php
<?php
public static function currentOS(string $path): self;
RelativePath::currentOS(string $path): self;
If Windows is detected, create a Windows-like path, otherwise create Unix-like path.
@ -45,7 +47,7 @@ If Windows is detected, create a Windows-like path, otherwise create Unix-like p
.. code-block:: php
<?php
public static function parse(string $path): self;
RelativePath::parse(string $path): self;
Alias of ``currentOS()``.
@ -59,7 +61,7 @@ No default constructor, only a named constructor is available:
.. code-block:: php
<?php
public static function parse(string $path, bool $strict = false): self
FilesystemPath::parse(string $path, bool $strict = false): self;
If Windows is detected, create a Windows path, otherwise create a Unix path.
Strict mode does not allow to have relative components that traverse beyond root.
@ -85,8 +87,8 @@ The prefix is ``'/'``
<?php
// these are equal
public function __construct(string $path, bool $strict = false);
public static function parse(string $path, bool $strict = false): self;
new UnixPath(string $path, bool $strict = false);
UnixPath::parse(string $path, bool $strict = false): self;
WindowsPath
-----------
@ -97,6 +99,7 @@ WindowsPath
The library doesn't check for that even in strict mode.
A class for Windows paths.
``makeRelative()`` returns relatives of the Windows-like type.
Supported paths:
@ -121,8 +124,8 @@ Supported paths:
<?php
// these are equal
public function __construct(string $path, bool $strict = false);
public static function parse(string $path, bool $strict = false): self;
new WindowsPath(string $path, bool $strict = false);
WindowsPath::parse(string $path, bool $strict = false): self;
UrlPath
=======
@ -134,8 +137,8 @@ The prefix is scheme + hostname.
<?php
// these are equal
public function __construct(string $path, bool $strict = false);
public static function parse(string $path, bool $strict = false): self;
new UrlPath(string $path, bool $strict = false);
UrlPath::parse(string $path, bool $strict = false): self;
StreamPath
==========
@ -152,5 +155,5 @@ The prefix is scheme.
<?php
// these are equal
public function __construct(string $path, bool $strict = false);
public static function parse(string $path, bool $strict = false): self;
new StreamPath(string $path, bool $strict = false);
StreamPath::parse(string $path, bool $strict = false): self;

View File

@ -20,7 +20,7 @@ final class PathFactory
return self::parseUrlLike($path, $matches[1], $urlSchemes, $streamSchemes);
}
return DIRECTORY_SEPARATOR === '\\' ? RelativePath::windows($path) : RelativePath::unix($path);
return RelativePath::currentOS($path);
}
private static function parseUrlLike(