Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
100.00% covered (success)
100.00%
24 / 24
100.00% covered (success)
100.00%
4 / 4
 CRAP
100.00% covered (success)
100.00%
1 / 1
DeprecatedHooks
100.00% covered (success)
100.00%
24 / 24
100.00% covered (success)
100.00%
4 / 4
 8
100.00% covered (success)
100.00%
1 / 1
 __construct
100.00% covered (success)
100.00%
7 / 7
100.00% covered (success)
100.00%
1 / 1
 2
 markDeprecated
100.00% covered (success)
100.00%
13 / 13
100.00% covered (success)
100.00%
1 / 1
 3
 isHookDeprecated
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 getDeprecationInfo
100.00% covered (success)
100.00%
3 / 3
100.00% covered (success)
100.00%
1 / 1
 2
1<?php
2/**
3 * Holds list of deprecated hooks and methods for retrieval
4 *
5 * @license GPL-2.0-or-later
6 * @file
7 */
8
9namespace MediaWiki\HookContainer;
10
11use InvalidArgumentException;
12
13class DeprecatedHooks {
14
15    /**
16     * @var array[] List of deprecated hooks. Value arrays for each hook contain:
17     *  - deprecatedVersion: (string) Version in which the hook was deprecated,
18     *    to pass to wfDeprecated().
19     *  - component: (string, optional) $component to pass to wfDeprecated().
20     *  - silent (bool, optional) If true, no deprecation warning will be raised
21     * @phpcs-require-sorted-array
22     */
23    private $deprecatedHooks = [
24        'AbortEmailNotification' => [ 'deprecatedVersion' => '1.45' ],
25        'AbortTalkPageEmailNotification' => [ 'deprecatedVersion' => '1.44' ],
26        'AddNewAccount' => [ 'deprecatedVersion' => '1.27' ],
27        'ArticleDelete' => [ 'deprecatedVersion' => '1.37', 'silent' => true ],
28        'ArticleDeleteComplete' => [ 'deprecatedVersion' => '1.37', 'silent' => true ],
29        'ArticleUndelete' => [ 'deprecatedVersion' => '1.40', 'silent' => true ],
30        'AutopromoteCondition' => [ 'deprecatedVersion' => '1.46' ],
31        'EditPageBeforeEditToolbar' => [ 'deprecatedVersion' => '1.36' ],
32        'EmailUser' => [ 'deprecatedVersion' => '1.41', 'silent' => true ],
33        'EmailUserPermissionsErrors' => [ 'deprecatedVersion' => '1.41' ],
34        'InterwikiLoadPrefix' => [ 'deprecatedVersion' => '1.36' ],
35        'LocalFile::getHistory' => [ 'deprecatedVersion' => '1.37' ],
36        'MagicWordwgVariableIDs' => [ 'deprecatedVersion' => '1.35' ],
37        'MessageCache::get' => [ 'deprecatedVersion' => '1.41' ],
38        'PageContentSave' => [ 'deprecatedVersion' => '1.35' ],
39        'PrefixSearchBackend' => [ 'deprecatedVersion' => '1.27' ],
40        'ProtectionForm::buildForm' => [ 'deprecatedVersion' => '1.36', 'silent' => true ],
41        'RecentChangesPurgeRows' => [ 'deprecatedVersion' => '1.45', 'silent' => true ],
42        'RollbackComplete' => [ 'deprecatedVersion' => '1.36', 'silent' => true ],
43        'SearchDataForIndex' => [ 'deprecatedVersion' => '1.40', 'silent' => true ],
44        'SendWatchlistEmailNotification' => [ 'deprecatedVersion' => '1.45' ],
45        'UpdateUserMailerFormattedPageStatus' => [ 'deprecatedVersion' => '1.45' ],
46        'userCan' => [ 'deprecatedVersion' => '1.37' ],
47        'UserCanSendEmail' => [ 'deprecatedVersion' => '1.41', 'silent' => true ],
48        'UserIsBlockedGlobally' => [ 'deprecatedVersion' => '1.40' ],
49        'WatchedItemQueryServiceExtensionsHook' => [ 'deprecatedVersion' => '1.46' ],
50        'WikiPageDeletionUpdates' => [ 'deprecatedVersion' => '1.32', 'silent' => true ],
51    ];
52
53    /**
54     * @param array[] $deprecatedHooks List of hooks to mark as deprecated.
55     * Value arrays for each hook contain:
56     *  - deprecatedVersion: (string) Version in which the hook was deprecated,
57     *    to pass to wfDeprecated().
58     *  - component: (string, optional) $component to pass to wfDeprecated().
59     *  - silent: (bool, optional) True to not raise any deprecation warning
60     */
61    public function __construct( array $deprecatedHooks = [] ) {
62        foreach ( $deprecatedHooks as $hook => $info ) {
63            $this->markDeprecated(
64                $hook,
65                $info['deprecatedVersion'],
66                $info['component'] ?? false,
67                $info['silent'] ?? false
68            );
69        }
70    }
71
72    /**
73     * For use by extensions, to add to list of deprecated hooks.
74     * Core-defined hooks should instead be added to $this->$deprecatedHooks directly.
75     * However, the preferred method of marking a hook deprecated is by adding it to
76     * the DeprecatedHooks attribute in extension.json
77     *
78     * @param string $hook
79     * @param string $version Version in which the hook was deprecated, to pass to wfDeprecated()
80     * @param string|null $component (optional) component to pass to wfDeprecated().
81     * @param bool $silent True to not raise any deprecation warning
82     * @throws InvalidArgumentException Hook has already been marked deprecated
83     */
84    public function markDeprecated(
85        string $hook, string $version, ?string $component = null, bool $silent = false
86    ): void {
87        if ( isset( $this->deprecatedHooks[$hook] ) ) {
88            throw new InvalidArgumentException(
89                "Cannot mark hook '$hook' deprecated with version $version. " .
90                "It is already marked deprecated with version " .
91                $this->deprecatedHooks[$hook]['deprecatedVersion']
92            );
93        }
94        $hookInfo = [
95            'deprecatedVersion' => $version,
96            'silent' => $silent
97        ];
98        if ( $component ) {
99            $hookInfo['component'] = $component;
100        }
101        $this->deprecatedHooks[$hook] = $hookInfo;
102    }
103
104    /**
105     * Checks whether hook is marked deprecated
106     * @param string $hook Hook name
107     * @return bool
108     */
109    public function isHookDeprecated( string $hook ): bool {
110        return isset( $this->deprecatedHooks[$hook] );
111    }
112
113    /**
114     * Gets deprecation info for a specific hook or all hooks if hook not specified
115     * @param string|null $hook (optional) Hook name
116     * @return array|null Value array from $this->deprecatedHooks for a specific hook or all hooks
117     */
118    public function getDeprecationInfo( ?string $hook = null ): ?array {
119        if ( !$hook ) {
120            return $this->deprecatedHooks;
121        }
122        return $this->deprecatedHooks[$hook] ?? null;
123    }
124}