1	<?php
2
3	namespace WikibaseQuality\ConstraintReport\ConstraintCheck;
4
5	use WikibaseQuality\ConstraintReport\Constraint;
6	use WikibaseQuality\ConstraintReport\ConstraintCheck\Context\Context;
7	use WikibaseQuality\ConstraintReport\ConstraintCheck\Helper\ConstraintParameterException;
8	use WikibaseQuality\ConstraintReport\ConstraintCheck\Helper\SparqlHelperException;
9	use WikibaseQuality\ConstraintReport\ConstraintCheck\Result\CheckResult;
10
11	/**
12	* Checks a constraint on some constraint checking context.
13	* Most implementations only support one constraint type.
14	*
15	* @license GPL-2.0-or-later
16	*/
17	interface ConstraintChecker {
18
19	/**
20	* Convenience constant, returned by most {@link getSupportedEntityTypes} implementations.
21	*/
22	public const ALL_ENTITY_TYPES_SUPPORTED = [
23	'item' => CheckResult::STATUS_COMPLIANCE,
24	'property' => CheckResult::STATUS_COMPLIANCE,
25	'lexeme' => CheckResult::STATUS_COMPLIANCE,
26	'form' => CheckResult::STATUS_COMPLIANCE,
27	'sense' => CheckResult::STATUS_COMPLIANCE,
28	'mediainfo' => CheckResult::STATUS_COMPLIANCE,
29	];
30
31	/**
32	* Convenience constant, returned by many {@link getSupportedContextTypes} implementations.
33	*/
34	public const ALL_CONTEXT_TYPES_SUPPORTED = [
35	Context::TYPE_STATEMENT => CheckResult::STATUS_COMPLIANCE,
36	Context::TYPE_QUALIFIER => CheckResult::STATUS_COMPLIANCE,
37	Context::TYPE_REFERENCE => CheckResult::STATUS_COMPLIANCE,
38	];
39
40	/**
41	* Determines which context types this constraint type supports.
42	* checkConstraint() should only be called for contexts with one of the supported types.
43	*
44	* Returns an array from context types
45	* (i. e., Context::TYPE_* constants)
46	* to result status (i. e., CheckResult::STATUS_* constants).
47	* STATUS_COMPLIANCE means that the constraint type supports this context type
48	* (checkConstraint() might of course return a different status, e. g. VIOLATION);
49	* STATUS_TODO means that the constraint type might support this context type in the future,
50	* but it is not currently supported;
51	* and STATUS_NOT_IN_SCOPE means that the constraint type does not support this context type.
52	*
53	* For example, the array
54	*
55	*     [
56	*         Context::TYPE_STATEMENT => CheckResult::STATUS_COMPLIANCE,
57	*         Context::TYPE_QUALIFIER => CheckResult::STATUS_TODO,
58	*         Context::TYPE_REFERENCE => CheckResult::STATUS_NOT_IN_SCOPE,
59	*     ]
60	*
61	* indicates that a constraint type makes sense on statements and qualifiers
62	* (but not references), but has only been implemented on statements so far.
63	*
64	* Many implementations can just return {@link ALL_CONTEXT_TYPES_SUPPORTED}.
65	*
66	* @return string[]
67	*/
68	public function getSupportedContextTypes();
69
70	/**
71	* Determines the context types where this constraint type is checked
72	* if the constraint scope has not been explicitly specified as a constraint parameter.
73	* Returns an array of context types (i. e., Context::TYPE_* constants).
74	*
75	* For example, the array [ Context::TYPE_STATEMENT ] indicates that,
76	* by default, a constraint should only be checked on the main snak of a statement.
77	* Depending on the {@link getSupportedContextTypes supported context types},
78	* it might also be checked on other context types
79	* if the constraint explicitly specifies a different scope
80	* (which might not even include the “statement” scope).
81	*
82	* Many implementations can just return {@link Context::ALL_CONTEXT_TYPES}.
83	*
84	* @return string[]
85	*/
86	public function getDefaultContextTypes();
87
88	/**
89	* Determines which entity types this constraint type supports.
90	* checkConstraint() should only be called for contexts with one of the supported entity types.
91	*
92	* Returns an array from entity types to result status (CheckResult::STATUS_* constants).
93	* The meaning of STATUS_COMPLIANCE, STATUS_TODO and STATUS_NOT_IN_SCOPE
94	* is the same as for {@link getSupportedContextTypes}.
95	*
96	* Most implementations can just return {@link ALL_ENTITY_TYPES_SUPPORTED}.
97	*
98	* @return string[]
99	*/
100	public function getSupportedEntityTypes();
101
102	/**
103	* @param Context $context
104	* @param Constraint $constraint
105	*
106	* @return CheckResult
107	*
108	* @throws ConstraintParameterException if the constraint parameters are invalid
109	* @throws SparqlHelperException if the checker uses SPARQL and the query times out or some other error occurs
110	*/
111	public function checkConstraint( Context $context, Constraint $constraint );
112
113	/**
114	* Check if the constraint parameters of $constraint are valid.
115	* Returns a list of ConstraintParameterExceptions, one for each problematic parameter;
116	* if the list is empty, all constraint parameters are okay.
117	*
118	* @param Constraint $constraint
119	*
120	* @return ConstraintParameterException[]
121	*/
122	public function checkConstraintParameters( Constraint $constraint );
123
124	}