1	<?php
2
3	namespace MediaWiki\Extension\CommunityConfiguration\Provider;
4
5	use MediaWiki\Extension\CommunityConfiguration\Store\IConfigurationStore;
6	use MediaWiki\Extension\CommunityConfiguration\Validation\IValidator;
7	use MediaWiki\Message\Message;
8	use MediaWiki\Permissions\Authority;
9	use MessageLocalizer;
10	use Psr\Log\LoggerAwareInterface;
11	use StatusValue;
12
13	/**
14	* This is the main point of interaction with a community configuration. Each provider is an
15	* implementation of IConfigurationProvider, with a constructor accepting (1) an
16	* IConfigurationStore, (2) an IValidator and (3) arbitrary number of other services or arguments
17	* (services are passed first; after services, arguments are passed). In other words, this is a
18	* valid constructor signature:
19	*
20	*     public function __construct( IConfigurationProvider, IValidator, FooService, bool );
21	*
22	* Supported configuration providers are defined via $wgCommunityConfigurationProviders, which is
23	* a dictionary keyed by provider name; each item must have the following properties:
24	*
25	*     * store: name of the configuration store, or a {"type": "name", "args": [...]} dict if
26	*       the store's constructor needs arguments.
27	*     * validator: name of the validator or a  {"type": "name", "args": [...]} dict if the
28	*       validator's constructor needs arguments.
29	*     * type: fully-qualified class name (must implement IConfigurationProvider)
30	*
31	* and may have the following properties:
32	*     * services: names of services that should be passed to the provider.
33	*     * args: if present, has to be an array of arguments (arguments are passed to __construct
34	*       after all services).
35	*/
36	interface IConfigurationProvider extends LoggerAwareInterface {
37
38	public const OPTION_SKIP_DASHBOARD_LISTING = 'skipDashboardListing';
39	public const OPTION_EDITOR_CAPABILITY = 'editorCapability';
40
41	/**
42	* Get a provider's ID (key under which it is defined)
43	*
44	* This is intended for logging outputs, to make it possible to determine which provider
45	* caused a given log message, so that the issue can be debugged and fixed.
46	*
47	* @return string
48	*/
49	public function getId(): string;
50
51	/**
52	* Get a human-readable name for the provider
53	*
54	* This is intended to be displayed to users when displaying an message/error
55	* concerning a particular provider.
56	*
57	* @return Message
58	*/
59	public function getName( MessageLocalizer $localizer ): Message;
60
61	/**
62	* Get the associated configuration store
63	*
64	* @note Store provides direct access to wherever the configuration is stored. No validation
65	* or access control is done at the store level. Use loadValidConfiguration() and
66	* storeValidConfiguration() whenever possible.
67	*
68	* @return IConfigurationStore
69	*/
70	public function getStore(): IConfigurationStore;
71
72	/**
73	* Get the associated validator
74	*
75	* @return IValidator
76	*/
77	public function getValidator(): IValidator;
78
79	/**
80	* Load (possibly cached) configuration that is guaranteed to be valid
81	*
82	* @return StatusValue if OK, loaded configuration is passed as a value
83	*/
84	public function loadValidConfiguration(): StatusValue;
85
86	/**
87	* Load (uncached) configuration that is guaranteed to be valid
88	*
89	* @return StatusValue if OK, loaded configuration is passed as a value
90	*/
91	public function loadValidConfigurationUncached(): StatusValue;
92
93	/**
94	* Store configuration while guaranteeing it is valid
95	*
96	* The method checks for editing permissions.
97	*
98	* @see IConfigurationProvider::alwaysStoreValidConfiguration(), which skips the permissions
99	* check.
100	* @param mixed $newConfig The configuration value to store. Can be any JSON serializable type
101	* @param Authority $authority
102	* @param string $summary Edit summary
103	* @return StatusValue
104	*/
105	public function storeValidConfiguration(
106	$newConfig,
107	Authority $authority,
108	string $summary = ''
109	): StatusValue;
110
111	/**
112	* Store configuration while guaranteeing it is valid
113	*
114	* The method SKIPS any permission checks, and leaves them as the caller's responsibility.
115	* Use storeValidConfiguration() if that is not what you want.
116	*
117	* @see IConfigurationProvider::storeValidConfiguration()
118	* @param mixed $newConfig The configuration value to store. Can be any JSON serializable type.
119	* @param Authority $authority
120	* @param string $summary
121	* @return StatusValue
122	*/
123	public function alwaysStoreValidConfiguration(
124	$newConfig,
125	Authority $authority,
126	string $summary = ''
127	): StatusValue;
128
129	/**
130	* Retrieves the value of a specified option for a configuration provider.
131	*
132	* @param string $optionName The name of the option to retrieve.
133	* @return mixed|null The value of the specified option, or null if not available.
134	*/
135	public function getOptionValue( string $optionName );
136	}