1	<?php
2
3	namespace MediaWiki\Extension\CommunityConfiguration\Store;
4
5	use MediaWiki\Linker\LinkTarget;
6	use MediaWiki\Permissions\Authority;
7	use StatusValue;
8
9	/**
10	* Representation of the configuration store
11	*
12	* Store object defines where/how is a configuration stored and is able to both read from and
13	* write to that location. Reads/writes happen at the blob level (meaning all values are inserted
14	* at once). This is to maximize the number of use cases CC2.0 can have, and considering most
15	* traffic is read (which can be cached) and writes are very rare, it should be fine.
16	*
17	* Supported store objects are defined in $wgCommunityConfigurationStores, which can look
18	* like this (dict of ObjectFactory specs keyed by store name):
19	* {
20	*     "static": {
21	*         "class": "MediaWiki\\Extension\\CommunityConfiguration\\Store\\StaticStore",
22	*         "services": []
23	*     },
24	*     "wikipage": {
25	*         "class": "MediaWiki\\Extension\\CommunityConfiguration\\Store\\WikiPageStore",
26	*         "services": []
27	*     }
28	* }
29	*
30	* Configuration store does not provide validation; ensure you validate the config via an
31	* appropriate IValidator instance (ideally through IConfigurationProvider::getValidator). Unless you
32	* are certain this is what you need, consider using IConfigurationProvider's methods for
33	* writing configuration instead.
34	*
35	* Store implementations are recommended to inherit AbstractStore.
36	*/
37	interface IConfigurationStore {
38
39	/**
40	* Set store options
41	*
42	* Options are used by the store to adapt its behavior; options cannot be queried outside of
43	* the store.
44	*
45	* @see AbstractStore::getOption()
46	* @param array $options A map of option name => option value
47	* @return void
48	*/
49	public function setOptions( array $options ): void;
50
51	/**
52	* @return LinkTarget|null
53	*/
54	public function getInfoPageLinkTarget(): ?LinkTarget;
55
56	/**
57	* Invalidate internal cache
58	*
59	* @return void
60	*/
61	public function invalidate(): void;
62
63	/**
64	* Get version for the currently stored data
65	*
66	* @return string|null null if version was not stored
67	*/
68	public function getVersion(): ?string;
69
70	/**
71	* Load the configuration without any caching
72	*
73	* @return StatusValue
74	*/
75	public function loadConfigurationUncached(): StatusValue;
76
77	/**
78	* Load the configuration (cached)
79	*
80	* @return StatusValue
81	*/
82	public function loadConfiguration(): StatusValue;
83
84	/**
85	* Store the configuration
86	*
87	* Permissions are checked by the store.
88	*
89	* @param mixed $config The configuration value to store. Can be any JSON serializable type.
90	* @param string|null $version Version of the data (null means store no version data)
91	* @param Authority $authority
92	* @param string $summary
93	* @return mixed
94	*/
95	public function storeConfiguration(
96	$config,
97	?string $version,
98	Authority $authority,
99	string $summary = ''
100	);
101
102	/**
103	* Store the configuration
104	*
105	* Permissions need to be checked by the caller.
106	*
107	* @param mixed $config The configuration value to store. Can be any JSON serializable type.
108	* @param string|null $version Version of the data (null means store no version data)
109	* @param Authority $authority
110	* @param string $summary
111	* @return StatusValue
112	*/
113	public function alwaysStoreConfiguration(
114	$config,
115	?string $version,
116	Authority $authority,
117	string $summary = ''
118	): StatusValue;
119
120	/**
121	* Authorize a given authority to edit the configuration.
122	*
123	* This method offers a fast, lightweight check,
124	* It is intended for determining which UI elements should be offered to the user.
125	* It provides a check similar to Authority::probablyCan
126	*
127	* @param Authority $authority The authority whose permissions are to be checked.
128	* @return bool True if the authority is authorized to edit the configuration, otherwise false.
129	*/
130	public function probablyCanEdit( Authority $authority ): bool;
131
132	/**
133	* Authorize a given authority to edit the configuration.
134	*
135	* This method performs a thorough check. It is intended to be used when a user is intending to
136	* edit the configuration, but has not yet committed to it. It provides a check similar to Authority::definitelyCan
137	*
138	* @param Authority $authority The authority whose permissions are to be checked.
139	* @return bool True if the authority is authorized to edit the configuration, otherwise false.
140	*/
141	public function definitelyCanEdit( Authority $authority ): bool;
142	}