1	<?php
2	/**
3	* @license GPL-2.0-or-later
4	* @file
5	*/
6	namespace MediaWiki\Rest\Handler\Helper;
7
8	use MediaWiki\Parser\ParserOutput;
9	use MediaWiki\Rest\LocalizedHttpException;
10	use MediaWiki\Rest\ResponseInterface;
11	use Wikimedia\Bcp47Code\Bcp47Code;
12	use Wikimedia\Parsoid\Core\ClientError;
13
14	/**
15	* @since 1.40
16	* @unstable
17	*/
18	interface HtmlOutputHelper {
19
20	/**
21	* Fetch the HTML for rendering of a given page. If the rendering is
22	* available in parsoid parser cache, return that. Otherwise, perform
23	* a parse and return the result while caching it in the parser cache.
24	*
25	* NOTE: Caching can be explicitly disabled or a force parse action
26	*    can be issued. Stashing and rate limiting on stashing also applies
27	*    here if specified.
28	*
29	* @return ParserOutput a tuple with html and content-type
30	* @throws LocalizedHttpException
31	* @throws ClientError
32	*/
33	public function getHtml(): ParserOutput;
34
35	/**
36	* Returns an ETag uniquely identifying the HTML output.
37	*
38	* @see Handler::getETag()
39	*
40	* @param string $suffix A suffix to attach to the etag.
41	*        Must consist of characters that are legal in ETags.
42	*
43	* @return string|null We return null when there is no etag.
44	*/
45	public function getETag( string $suffix = '' ): ?string;
46
47	/**
48	* Returns the time at which the HTML was rendered.
49	*
50	* @see Handler::getLastModified()
51	*
52	* @return string|null
53	*/
54	public function getLastModified(): ?string;
55
56	/**
57	* Gets the request parameters of this request.
58	*
59	* @see Handler::getParamSettings()
60	*
61	* @return array
62	*/
63	public static function getParamSettings(): array;
64
65	/**
66	* Set the language to be used for variant conversion.
67	*
68	* If $targetLanguage is a string, it may be a list of language ranges as
69	* specified by RFC 9110 for use in the Accept-Language header.
70	* Implementations must be able to process this format, and may use the
71	* information provided to choose a supported target language that is
72	* desirable to the client.
73	*
74	* @param Bcp47Code|string $targetLanguage
75	* @param Bcp47Code|string|null $sourceLanguage
76	*/
77	public function setVariantConversionLanguage(
78	$targetLanguage,
79	$sourceLanguage = null
80	): void;
81
82	/**
83	* Set the HTTP headers based on the response generated
84	*
85	* @param ResponseInterface $response
86	* @param bool $forHtml Whether the response will be HTML (rather than JSON)
87	*
88	* @return void
89	*/
90	public function putHeaders( ResponseInterface $response, bool $forHtml = true ): void;
91
92	}