1	<?php
2	/**
3	* This program is free software; you can redistribute it and/or modify
4	* it under the terms of the GNU General Public License as published by
5	* the Free Software Foundation; either version 2 of the License, or
6	* (at your option) any later version.
7	*
8	* This program is distributed in the hope that it will be useful,
9	* but WITHOUT ANY WARRANTY; without even the implied warranty of
10	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11	* GNU General Public License for more details.
12	*
13	* You should have received a copy of the GNU General Public License along
14	* with this program; if not, write to the Free Software Foundation, Inc.,
15	* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16	* http://www.gnu.org/copyleft/gpl.html
17	*
18	* @file
19	*/
20	namespace MediaWiki\Rest\Handler\Helper;
21
22	use MediaWiki\Parser\ParserOutput;
23	use MediaWiki\Rest\LocalizedHttpException;
24	use MediaWiki\Rest\ResponseInterface;
25	use Wikimedia\Bcp47Code\Bcp47Code;
26	use Wikimedia\Parsoid\Core\ClientError;
27
28	/**
29	* @since 1.40
30	* @unstable
31	*/
32	interface HtmlOutputHelper {
33
34	/**
35	* Fetch the HTML for rendering of a given page. If the rendering is
36	* available in parsoid parser cache, return that. Otherwise, perform
37	* a parse and return the result while caching it in the parser cache.
38	*
39	* NOTE: Caching can be explicitly disabled or a force parse action
40	*    can be issued. Stashing and rate limiting on stashing also applies
41	*    here if specified.
42	*
43	* @return ParserOutput a tuple with html and content-type
44	* @throws LocalizedHttpException
45	* @throws ClientError
46	*/
47	public function getHtml(): ParserOutput;
48
49	/**
50	* Returns an ETag uniquely identifying the HTML output.
51	*
52	* @see Handler::getETag()
53	*
54	* @param string $suffix A suffix to attach to the etag.
55	*        Must consist of characters that are legal in ETags.
56	*
57	* @return string|null We return null when there is no etag.
58	*/
59	public function getETag( string $suffix = '' ): ?string;
60
61	/**
62	* Returns the time at which the HTML was rendered.
63	*
64	* @see Handler::getLastModified()
65	*
66	* @return string|null
67	*/
68	public function getLastModified(): ?string;
69
70	/**
71	* Gets the request parameters of this request.
72	*
73	* @see Handler::getParamSettings()
74	*
75	* @return array
76	*/
77	public function getParamSettings(): array;
78
79	/**
80	* Set the language to be used for variant conversion.
81	*
82	* If $targetLanguage is a string, it may be a list of language ranges as
83	* specified by RFC 9110 for use in the Accept-Language header.
84	* Implementations must be able to process this format, and may use the
85	* information provided to choose a supported target language that is
86	* desirable to the client.
87	*
88	* @param Bcp47Code|string $targetLanguage
89	* @param Bcp47Code|string|null $sourceLanguage
90	*/
91	public function setVariantConversionLanguage(
92	$targetLanguage,
93	$sourceLanguage = null
94	): void;
95
96	/**
97	* Set the HTTP headers based on the response generated
98	*
99	* @param ResponseInterface $response
100	* @param bool $forHtml Whether the response will be HTML (rather than JSON)
101	*
102	* @return void
103	*/
104	public function putHeaders( ResponseInterface $response, bool $forHtml = true ): void;
105
106	}