1	<?php
2	/**
3	* @license GPL-2.0-or-later
4	* @file
5	*/
6
7	namespace MediaWiki\Storage;
8
9	use StatusValue;
10
11	/**
12	* Service for loading and storing data blobs.
13	*
14	* @note This was written to act as a drop-in replacement for the corresponding
15	*       static methods in the old Revision class (which was later removed in 1.37).
16	*
17	* @since 1.31
18	*/
19	interface BlobStore {
20
21	/**
22	* Hint key for use with storeBlob, indicating the general role the block
23	* takes in the application. For instance, it should be "page-content" if
24	* the blob represents a Content object.
25	*/
26	public const DESIGNATION_HINT = 'designation';
27
28	/**
29	* Hint key for use with storeBlob, indicating the page the blob is associated with.
30	* This may be used for sharding.
31	*/
32	public const PAGE_HINT = 'page_id';
33
34	/**
35	* Hint key for use with storeBlob, indicating the slot the blob is associated with.
36	* May be relevant for reference counting.
37	*/
38	public const ROLE_HINT = 'role_name';
39
40	/**
41	* Hint key for use with storeBlob, indicating the revision the blob is associated with.
42	* This may be used for differential storage and reference counting.
43	*/
44	public const REVISION_HINT = 'rev_id';
45
46	/**
47	* Hint key for use with storeBlob, indicating the parent revision of the revision
48	* the blob is associated with. This may be used for differential storage.
49	*/
50	public const PARENT_HINT = 'rev_parent_id';
51
52	/**
53	* Hint key for use with storeBlob, providing the SHA1 hash of the blob as passed to the
54	* method. This can be used to avoid re-calculating the hash if it is needed by the BlobStore.
55	*/
56	public const SHA1_HINT = 'cont_sha1';
57
58	/**
59	* Hint key for use with storeBlob, indicating the model of the content encoded in the
60	* given blob. May be used to implement optimized storage for some well known models.
61	*/
62	public const MODEL_HINT = 'cont_model';
63
64	/**
65	* Hint key for use with storeBlob, indicating the serialization format used to create
66	* the blob, as a MIME type. May be used for optimized storage in the underlying database.
67	*/
68	public const FORMAT_HINT = 'cont_format';
69
70	/**
71	* Hint key for an image name.
72	*/
73	public const IMAGE_HINT = 'img_name';
74
75	/**
76	* Retrieve a blob, given an address.
77	*
78	* MCR migration note: this replaced Revision::loadText
79	*
80	* @param string $blobAddress The blob address as returned by storeBlob(),
81	*        such as "tt:12345" or "ex:DB://s16/456/9876".
82	* @param int $queryFlags See IDBAccessObject.
83	*
84	* @throws BlobAccessException
85	* @return string binary blob data
86	*/
87	public function getBlob( $blobAddress, $queryFlags = 0 );
88
89	/**
90	* A batched version of BlobStore::getBlob.
91	*
92	* @param string[] $blobAddresses An array of blob addresses.
93	* @param int $queryFlags See IDBAccessObject.
94	* @throws BlobAccessException
95	* @return StatusValue A status with a map of blobAddress => binary blob data or null
96	*         if fetching the blob has failed. Fetch failures errors are the
97	*         warnings in the status object.
98	* @since 1.34
99	*/
100	public function getBlobBatch( $blobAddresses, $queryFlags = 0 );
101
102	/**
103	* Stores an arbitrary blob of data and returns an address that can be used with
104	* getBlob() to retrieve the same blob of data,
105	*
106	* @param string $data raw binary data
107	* @param array $hints An array of hints. Implementations may use the hints to optimize storage.
108	* All hints are optional, supported hints depend on the implementation. Hint names by
109	* convention correspond to the names of fields in the database. Callers are encouraged to
110	* provide the well known hints as defined by the XXX_HINT constants.
111	*
112	* @throws BlobAccessException
113	* @return string an address that can be used with getBlob() to retrieve the data.
114	*/
115	public function storeBlob( $data, $hints = [] );
116
117	/**
118	* Check if the blob metadata or backing blob data store is read-only
119	*
120	* @return bool
121	*/
122	public function isReadOnly();
123	}