1<?php
2
3namespace MediaWiki\Storage\Hook;
4
5use CommentStoreComment;
6use MediaWiki\Revision\RevisionRecord;
7use MediaWiki\Storage\EditResult;
8use MediaWiki\User\UserIdentity;
9use WikiPage;
10
11/**
12 * This is a hook handler interface, see docs/Hooks.md.
13 * Use the hook name "BeforeRevertedTagUpdate" to register handlers implementing this interface.
14 *
15 * @stable to implement
16 * @ingroup Hooks
17 */
18interface BeforeRevertedTagUpdateHook {
19	/**
20	 * This hook is called before scheduling a RevertedTagUpdateJob.
21	 *
22	 * Various content management extensions that involve some kind of approval mechanism
23	 * for edits can use this to indicate that the RevertedTagUpdate should not be performed
24	 * right after the edit is made, but rather it should wait for the edit to be approved.
25	 * To delay the execution of the update simply implement this hook and set the $approved
26	 * parameter to false when the user does not have an "autoreview" user right or similar.
27	 *
28	 * The update can be later rescheduled using RevertedTagUpdateManager. In your code
29	 * that marks an edit as "approved" use:
30	 *
31	 *  ```php
32	 *  $revertedTagUpdateManager =
33	 *    MediaWikiServices::getInstance()->getRevertedTagUpdateManager();
34	 *  $revertedTagUpdateManager->approveRevertedTagForRevision( $acceptedRevisionId );
35	 *  ```
36	 *
37	 * And that's it.
38	 *
39	 * There should be no adverse effects due to enqueueing the same update multiple times.
40	 *
41	 * @since 1.36
42	 *
43	 * @param WikiPage $wikiPage WikiPage modified
44	 * @param UserIdentity $user User performing the modification
45	 * @param CommentStoreComment $summary Edit summary/comment
46	 * @param int $flags Flags passed to WikiPage::doUserEditContent()
47	 * @param RevisionRecord $revisionRecord New RevisionRecord of the article
48	 * @param EditResult $editResult Object storing information about the effects of this
49	 *   edit, including which edits were reverted and which edit is this based on (for
50	 *   reverts and null edits).
51	 * @param bool &$approved Whether the edit is considered approved. Setting it to false
52	 *   will abort the update, true will cause the update to be executed normally. If
53	 *   patrolling is enabled, the passed value will indicate whether the edit is
54	 *   autopatrolled or not. In case patrolling is disabled on the wiki, the passed
55	 *   value will always be true, unless modified by other extensions.
56	 * @return void This hook must not abort, it must return no value
57	 */
58	public function onBeforeRevertedTagUpdate(
59		$wikiPage,
60		$user,
61		$summary,
62		$flags,
63		$revisionRecord,
64		$editResult,
65		&$approved
66	): void;
67}
68