1<?php
2
3namespace ComboStrap;
4
5use ComboStrap\Web\Url;
6
7/**
8 *
9 *
10 * A class that returns
11 *
12 * It represents a fetch of:
13 *   * a {@link IFetcherPath::getFetchPath() file}
14 *   * or {@link IFetcherString::getFetchString() string}
15 *
16 * Example
17 *   * serving a svg file with different request properties (if the requested image width is set, it will generate a new svg from the source)
18 *
19 * The request may come from:
20 *   * a {@link IFetcher::buildFromUrl() URL}
21 *   * a {@link IFetcher::buildFromTagAttributes() attributes}
22 *
23 * TODO: The handler/fetcher should also be able to be call in a process function
24 *   passing the the {@link ExecutionContext} and pass it the result (a string or a file or whatever)
25 *   you get then a functional interface (Then we don't need to know the returned type
26 *   and the interface {@link IFetcherPath} and {@link IFetcherString} are not needed
27 *   we could also add a function that could cast the result
28 *
29 * The hierarchy is {@link Mime} based.
30 *
31 * Example:
32 *   * {@link FetcherTraitImage} such as:
33 *     * {@link FetcherSvg} that can process and return svg
34 *     * {@link FetcherRaster} that can process and return raster image
35 *     * {@link FetcherVignette} that returns a raster image from page metadata
36 *     * {@link FetcherScreenshot} that returns a snapshot image from a page
37 *   * {@link FetcherRawLocalPath} that returns all type of local file without processing
38 *
39 */
40interface IFetcher
41{
42    /**
43     * buster got the same value
44     * that the `rev` attribute (ie mtime)
45     * We don't use rev as cache buster because Dokuwiki still thinks
46     * that this is an old file and search in the attic
47     * as seen in the function {@link mediaFN()}
48     *
49     * The value used by Dokuwiki for the buster is tseed.
50     */
51    public const CACHE_BUSTER_KEY = "tseed";
52
53    /**
54     * The property in the URL that identify the fetcher
55     */
56    public const FETCHER_KEY = "fetcher";
57
58
59    /**
60     * Return the URL where the resource can be fetched
61     * @param Url|null $url - the url to be able to pass along in the hierarchy
62     * @return Url
63     */
64    function getFetchUrl(Url $url = null): Url;
65
66
67    /**
68     * The buster that should be added to the url.
69     * @return string
70     * @throws ExceptionNotFound - if the buster cannot be calculated (file does not exist for instance)
71     */
72    function getBuster(): string;
73
74
75    /**
76     * @return Mime - the mime of the output
77     *
78     * You can also ask it via {@link IFetcher::getFetchPath()} but it will
79     * perform the processing. If you want to create a cache file path with the good extension
80     * this is the way to go.
81     */
82    public function getMime(): Mime;
83
84    /**
85     * A convenient way to build a fetcher from a URL
86     * This method calls the function {@link IFetcher::buildFromTagAttributes()}
87     * @param Url $url
88     * @return IFetcher
89     */
90    public function buildFromUrl(Url $url): IFetcher;
91
92    /**
93     * @param TagAttributes $tagAttributes - the attributes
94     * @return IFetcher
95     */
96    public function buildFromTagAttributes(TagAttributes $tagAttributes): IFetcher;
97
98    /**
99     * Get the cache value requested
100     * @throws ExceptionNotFound
101     * @return string
102     */
103    public function getRequestedCache(): string;
104
105    /**
106     * @return LocalPath - the cache if any
107     * @throws ExceptionNotSupported
108     */
109    public function getContentCachePath(): LocalPath;
110
111    /**
112     * @return string - an unique name that is added in the fetcher key of the URL
113     *
114     * Note that because dokuwiki does a sanitizing on the do custom action.
115     * The name should not have any space or separator (What fuck up is fucked up)
116     */
117    public function getFetcherName(): string;
118
119
120    /**
121     * @return IFetcher - process and feed the cache
122     * @throws ExceptionNotSupported - if the cache is not supported
123     */
124    public function process(): IFetcher;
125
126    /**
127     * @return string - a label to the resource returned (used in img tag, ...)
128     *
129     * If the resource is:
130     * - based on a local path, it may be the path name
131     * - generated from a page, it may be the page title
132     * ...
133     */
134    public function getLabel(): string;
135
136
137}
138