1<?php
2
3
4namespace ComboStrap;
5
6use ComboStrap\Web\Url;
7
8/**
9 * Interface Path
10 * @package ComboStrap
11 *
12 * An interface that represents a path.
13 *
14 * For the path operations, see {@link FileSystems}
15 *
16 * The {@link Path::toAbsoluteId()} function is just the path part (no other URI query parameters)
17 *
18 * A lot of overlap with {@link Url}
19 */
20interface Path
21{
22
23    /**
24     * @param string $uri
25     * @return Path
26     */
27    public static function createFromUri(string $uri): Path;
28
29    /**
30     * @return string
31     * @throws ExceptionNotFound - if the path does not have any extension
32     */
33    function getExtension(): string;
34
35    /**
36     * @return string
37     * @throws ExceptionNotFound - if the path does not have any last name
38     */
39    function getLastNameWithoutExtension(): string;
40
41    function getScheme();
42
43    /**
44     * The last name of the path with or without an extension
45     *
46     * The Path class does not have a notion of "extension"
47     * because the file does not have one but we provide the
48     * {@link PathAbs::getExtension()} as utility
49     *
50     * @return string
51     * @throws ExceptionNotFound - if the path does not have any last name
52     */
53    function getLastName(): string;
54
55    /**
56     * @return mixed - the names are the words between the separator
57     */
58    function getNames();
59
60    /**
61     * @return mixed - the names but without the extension
62     */
63    function getNamesWithoutExtension();
64
65    /**
66     * @return Path
67     * @throws ExceptionNotFound - for the root
68     */
69    function getParent(): Path;
70
71    /**
72     *
73     * @return string only the string representation of the path
74     *
75     * Same concept than the {@link WikiPath::getWikiId()} but enhanced to other
76     * type of path.
77     *
78     * This is:
79     * * the {@link WikiPath::getWikiId()} with the root for a WikiPath and the extension if not a wiki file to be compliant
80     * * the path element for all others
81     *
82     * It's used mostly as common identifier that can be used with any path
83     * (such as {@link LocalPath} or {@link WikiPath} path
84     *
85     */
86    function toAbsoluteId(): string;
87
88    /**
89     * @return string the uri string representation of this path (with all information, scheme, drive, attributes)
90     */
91    function toUriString(): string;
92
93    /**
94     *
95     * @return Path the absolute representation of the path
96     *
97     *
98     * This is:
99     * * the {@link WikiPath::getWikiId()} with the root character for a WikiPath and the extension (txt, ...)
100     * * the asbolute path element for all others
101     *
102     * It's used mostly as common identifier that can be used with any path
103     * (such as {@link LocalPath} or {@link WikiPath} path
104     *
105     */
106    function toAbsolutePath(): Path;
107
108    /**
109     * @return Mime the mime from the extension
110     * @deprecated Uses {@link FileSystems::getMime()} instead
111     */
112    function getMime(): ?Mime;
113
114    function resolve(string $name): Path;
115
116    /**
117     * @return Url - the local URL
118     * For external path (ie {@link Url}, there is no {@link IFetcher} implementation
119     * To create a {@link ThirdMediaLink}, we use therefore this url
120     */
121    function getUrl(): Url;
122
123    /**
124     * Needed for the file protocol URI {@link LocalPath}
125     * @return string
126     */
127    function getHost(): string;
128
129    /**
130     * @return WikiPath an utility function
131     * @throws ExceptionCast
132     */
133    function toWikiPath(): WikiPath;
134
135    /**
136     * @return LocalPath an utility function
137     * @throws ExceptionCast
138     */
139    function toLocalPath(): LocalPath;
140
141
142}
143