1<?php
2
3
4namespace ComboStrap\Meta\Api;
5
6use ComboStrap\ExceptionBadArgument;
7use ComboStrap\Meta\Api\Metadata;
8use ComboStrap\ResourceCombo;
9
10/**
11 * Where to store a metadata
12 *
13 * Not that a metadata may be created even if the file does not exist
14 * (when the page is rendered for the first time for instance)
15 *
16 */
17interface MetadataStore
18{
19
20    /**
21     * Return if the data has the dokuwiki format
22     * @return bool
23     */
24    public function isDokuWikiStore(): bool;
25
26
27    /**
28     * Set the {@link Metadata::getValue()} for a {@link Metadata::getResource()}
29     * with the name {@link Metadata::getName()}
30     * @param Metadata $metadata
31     * @throws ExceptionBadArgument
32     */
33    public function set(Metadata $metadata);
34
35    /**
36     * Return the {@link Metadata::getValue()} for a {@link Metadata::getResource()}
37     * and the name {@link Metadata::getName()}
38     * @param Metadata $metadata
39     * @param null $default - the default value to return if no data is found
40     */
41    public function get(Metadata $metadata, $default = null);
42
43    public function getResource(): ResourceCombo;
44
45    /**
46     * This function permits to get a metadata value without creating a {@link Metadata} class
47     *
48     * @param string $name -  the {@link Metadata::getName()} of the metadata
49     * @param null $default - the default value to return if no data is found
50     * @return null|string|array|boolean
51     */
52    public function getFromName(string $name, $default = null);
53
54    /**
55     * This function permits to set a metadata value without creating a {@link Metadata} class
56     * @param string $name - the {@link Metadata::getName()} of the metadata
57     * @param null|string|array|boolean $value - the value
58     * @param null $default - if the value is equals to the default, the data will not be stored
59     */
60    public function setFromPersistentName(string $name, $value, $default = null);
61
62    /**
63     *
64     * Flush to disk on a file system or commit in a database
65     * @return mixed
66     *
67     *
68     * Don't persist in the setter function of the metadata object
69     *
70     * Why ?
71     *   - We set normally a lot of metadata at once, we persist at the end of the function
72     *   - In a metadata list with a lot of value, it's normal to persist when all values are in the batch
73     *   - This is not always needed for instance modification of the frontmatter is just a modification of the persistence value
74     *   - For scalar, it means that we need to persist
75     *   - Goal is to persist at the end of the HTTP request
76     */
77    public function persist();
78
79    /**
80     * @return bool - true if the data is stored in a array text based format
81     * Used to send
82     *   * the string `false` and not the false value for instance
83     *   * and json in a array format
84     */
85    public function isHierarchicalTextBased(): bool;
86
87    /**
88     * Reset (Delete all data in memory)
89     */
90    public function reset();
91
92    /**
93     * @return string
94     */
95    public function getCanonical(): string;
96
97    /**
98     * @param ResourceCombo $resourceCombo
99     * @return MetadataStore
100     */
101    static function getOrCreateFromResource(ResourceCombo $resourceCombo): MetadataStore;
102
103}
104