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