1	<?php
2	/**
3	* WikiLambda Abstract Wikipedia - Service class to handle AW Article Section storage.
4	*
5	* This store provides access to two semantically different objects:
6	*
7	* * AWSection: identified by the Topic qid, the Section qid, and the locale.
8	*   The store contains one row for each Article Section generated for a allowed language.
9	*   This is the main object that contains the rendered output that will be concatenated
10	*   when displaying an Abstract Wikipedia article.
11	*
12	* * AWArticleMetadata: identified by the Topic qid.
13	*   The store contains one Metadata row for each Article from the allowed topics.
14	*   The Metadata object is kept up to date when rendering the article sections, and
15	*   provides important information to concatenate Article Sections and build the
16	*   final Abstract Wikipedia Article.
17	*
18	* Both objects are also indexed by a schema version, which can be incremented if any
19	* of the payload expectations changes in a non-backwards-compatible way.
20	*
21	* @file
22	* @ingroup Extensions
23	* @copyright 2020– Abstract Wikipedia team; see AUTHORS.txt
24	* @license MIT
25	*/
26
27	namespace MediaWiki\Extension\WikiLambda\AWStorage;
28
29	abstract class AWArticleStore {
30
31	public const AW_STORAGE_VIRTUAL_DOMAIN = 'virtual-awstorage';
32	public const AW_STORAGE_SCHEMA_VERSION = 1;
33	public const AW_STORAGE_METADATA_KEY = '_metadata';
34	public const AW_STORAGE_LOCALE_MULTILINGUAL = 'mul';
35
36	/**
37	* Get a specific section for a topic + locale.
38	*
39	* @param string $topicQid
40	* @param string $sectionQid
41	* @param string $locale
42	* @param int $schemaVersion
43	* @return ?AWSection
44	*/
45	abstract public function getSection(
46	string $topicQid,
47	string $sectionQid,
48	string $locale,
49	int $schemaVersion = self::AW_STORAGE_SCHEMA_VERSION
50	): ?AWSection;
51
52	/**
53	* Get all stored sections for a topic + locale.
54	*
55	* @param string $topicQid
56	* @param string $locale
57	* @param int $schemaVersion
58	* @return AWSection[]
59	*/
60	abstract public function getSectionsForTopic(
61	string $topicQid,
62	string $locale,
63	int $schemaVersion = self::AW_STORAGE_SCHEMA_VERSION
64	): array;
65
66	/**
67	* Persist a section.
68	*
69	* @param AWSection $section
70	* @return bool
71	*/
72	abstract public function setSection( AWSection $section ): bool;
73
74	/**
75	* Delete a section.
76	*
77	* @param string $topicQid
78	* @param string $sectionQid
79	* @param string $locale
80	* @param int $schemaVersion
81	*/
82	abstract public function deleteSection(
83	string $topicQid,
84	string $sectionQid,
85	string $locale,
86	int $schemaVersion = self::AW_STORAGE_SCHEMA_VERSION
87	): void;
88
89	/**
90	* Get article metadata.
91	*
92	* @param string $topicQid
93	* @param int $schemaVersion
94	* @return ?AWArticleMetadata
95	*/
96	abstract public function getArticleMetadata(
97	string $topicQid,
98	int $schemaVersion = self::AW_STORAGE_SCHEMA_VERSION
99	): ?AWArticleMetadata;
100
101	/**
102	* Persist article metadata.
103	*
104	* @param AWArticleMetadata $metadata
105	* @return bool
106	*/
107	abstract public function setArticleMetadata( AWArticleMetadata $metadata ): bool;
108	}