Docs for path classes

master
Anton Smirnov 11 months ago
parent ca67c164fe
commit 844d094d49
  1. 3
      docs/index.rst
  2. 156
      docs/path_classes.rst
  3. 4
      docs/path_interfaces.rst

@ -18,7 +18,8 @@ Documentation
.. toctree::
:maxdepth: 2
interfaces
path_interfaces
path_classes
License
=======

@ -0,0 +1,156 @@
Path Classes
############
RelativePath
============
The only concrete implementation of ``RelativePathInterface``.
In non-root relative paths first component returned by ``getComponents()`` is either ``'.'`` or ``'..'``.
Available constructors:
.. code-block:: php
<?php
public function __construct(string $path, bool $windows = false);
``$windows = false``: Unix-like path. Path separators are slashes.
``$windows = true``: Windows-like path. Path separators are both slashes and backslashes.
When exporting a string, backslashes are used.
.. code-block:: php
<?php
public static function unix(string $path): self;
Same as ``new RelativePath($path, windows: false)``
.. code-block:: php
<?php
public static function windows(string $path): self;
Same as ``new RelativePath($path, windows: true)``
.. code-block:: php
<?php
public static function currentOS(string $path): self;
If Windows is detected, create a Windows-like path, otherwise create Unix-like path.
.. note:: Windows is detected by the ``DIRECTORY_SEPARATOR`` constant.
.. code-block:: php
<?php
public static function parse(string $path): self;
Alias of ``currentOS()``.
FilesystemPath
==============
A base class for ``UnixPath`` and ``WindowsPath``.
No default constructor, only a named constructor is available:
.. code-block:: php
<?php
public static function 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.
.. note:: Windows is detected by the ``DIRECTORY_SEPARATOR`` constant.
.. code-block:: php
<?php
use Arokettu\Path\FilesystemPath;
// on windows
FilesystemPath::parse('C:\Windows\..\..\..\Users'); // C:\Users
FilesystemPath::parse('C:\Windows\..\..\..\Users' strict: true); // exception
UnixPath
--------
A class for Unix paths.
The prefix is ``'/'``
.. code-block:: php
<?php
// these are equal
public function __construct(string $path, bool $strict = false);
public static function parse(string $path, bool $strict = false): self;
WindowsPath
-----------
.. warning::
Windows usually have much more restrictions on file path than unix-like operating systems
like forbidding characters like ``|`` and ``:``.
The library doesn't check for that even in strict mode.
A class for Windows paths.
Supported paths:
* DOS-like paths.
The classic paths with a drive letter: ``C:\Path``.
Both slashes and backslashes are supported as component separators.
Relative components are resolved on creation like in most other classes here.
The prefix here is a drive letter.
* UNC paths.
Examples:
* Local paths like ``\\*\C:\Path``. The prefix here is ``\\*\C:\``.
* Network paths like ``\\AROKETTUPC\c$``. The prefix here is ``\\AROKETTUPC\``.
UNC paths do not allow forward slashes and relative components.
.. note::
Relative paths with drive letter like ``C:Path\Path`` are valid in Windows
but are not supported by the library in any way.
.. code-block:: php
<?php
// these are equal
public function __construct(string $path, bool $strict = false);
public static function parse(string $path, bool $strict = false): self;
UrlPath
=======
A class for URL paths.
The prefix is scheme + hostname.
.. code-block:: php
<?php
// these are equal
public function __construct(string $path, bool $strict = false);
public static function parse(string $path, bool $strict = false): self;
StreamPath
==========
A class for PHP stream like paths.
Examples include php streams like ``php://temp``.
It can be useful with libraries that create virtual file systems like `adlawson/vfs`_ and `mikey179/vfsstream`_.
The prefix is scheme.
.. _adlawson/vfs: https://packagist.org/packages/adlawson/vfs
.. _mikey179/vfsstream: https://packagist.org/packages/mikey179/vfsstream
.. code-block:: php
<?php
// these are equal
public function __construct(string $path, bool $strict = false);
public static function parse(string $path, bool $strict = false): self;

@ -1,5 +1,5 @@
Interfaces
##########
Path Interfaces
###############
PathInterface
=============
Loading…
Cancel
Save