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 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
19 *
20 * @file
21 */
22
23namespace MediaWiki\HookContainer;
24
25use InvalidArgumentException;
26
27class DeprecatedHooks {
28
29    /**
30     * @var array[] List of deprecated hooks. Value arrays for each hook contain:
31     *  - deprecatedVersion: (string) Version in which the hook was deprecated,
32     *    to pass to wfDeprecated().
33     *  - component: (string, optional) $component to pass to wfDeprecated().
34     *  - silent (bool, optional) If true, no deprecation warning will be raised
35     * @phpcs-require-sorted-array
36     */
37    private $deprecatedHooks = [
38        'AddNewAccount' => [ 'deprecatedVersion' => '1.27' ],
39        'ArticleDelete' => [ 'deprecatedVersion' => '1.37', 'silent' => true ],
40        'ArticleDeleteComplete' => [ 'deprecatedVersion' => '1.37', 'silent' => true ],
41        'ArticleUndelete' => [ 'deprecatedVersion' => '1.40', 'silent' => true ],
42        'EditPageBeforeEditToolbar' => [ 'deprecatedVersion' => '1.36' ],
43        'EmailUser' => [ 'deprecatedVersion' => '1.41', 'silent' => true ],
44        'EmailUserPermissionsErrors' => [ 'deprecatedVersion' => '1.41' ],
45        'InterwikiLoadPrefix' => [ 'deprecatedVersion' => '1.36' ],
46        'LocalFile::getHistory' => [ 'deprecatedVersion' => '1.37' ],
47        'MagicWordwgVariableIDs' => [ 'deprecatedVersion' => '1.35', 'silent' => true ],
48        'MessageCache::get' => [ 'deprecatedVersion' => '1.41' ],
49        'OutputPageMakeCategoryLinks' => [ 'deprecatedVersion' => '1.43' ],
50        'PageContentSave' => [ 'deprecatedVersion' => '1.35', 'silent' => true ],
51        'PrefixSearchBackend' => [ 'deprecatedVersion' => '1.27' ],
52        'ProtectionForm::buildForm' => [ 'deprecatedVersion' => '1.36', 'silent' => true ],
53        'RollbackComplete' => [ 'deprecatedVersion' => '1.36', 'silent' => true ],
54        'SearchDataForIndex' => [ 'deprecatedVersion' => '1.40', 'silent' => true ],
55        'SkinCopyrightFooter' => [ 'deprecatedVersion' => '1.43', 'silent' => true ],
56        'userCan' => [ 'deprecatedVersion' => '1.37' ],
57        'UserCanSendEmail' => [ 'deprecatedVersion' => '1.41', 'silent' => true ],
58        'WikiPageDeletionUpdates' => [ 'deprecatedVersion' => '1.32', 'silent' => true ],
59    ];
60
61    /**
62     * @param array[] $deprecatedHooks List of hooks to mark as deprecated.
63     * Value arrays for each hook contain:
64     *  - deprecatedVersion: (string) Version in which the hook was deprecated,
65     *    to pass to wfDeprecated().
66     *  - component: (string, optional) $component to pass to wfDeprecated().
67     *  - silent: (bool, optional) True to not raise any deprecation warning
68     */
69    public function __construct( array $deprecatedHooks = [] ) {
70        foreach ( $deprecatedHooks as $hook => $info ) {
71            $this->markDeprecated(
72                $hook,
73                $info['deprecatedVersion'],
74                $info['component'] ?? false,
75                $info['silent'] ?? false
76            );
77        }
78    }
79
80    /**
81     * For use by extensions, to add to list of deprecated hooks.
82     * Core-defined hooks should instead be added to $this->$deprecatedHooks directly.
83     * However, the preferred method of marking a hook deprecated is by adding it to
84     * the DeprecatedHooks attribute in extension.json
85     *
86     * @param string $hook
87     * @param string $version Version in which the hook was deprecated, to pass to wfDeprecated()
88     * @param string|null $component (optional) component to pass to wfDeprecated().
89     * @param bool $silent True to not raise any deprecation warning
90     * @throws InvalidArgumentException Hook has already been marked deprecated
91     */
92    public function markDeprecated(
93        string $hook, string $version, ?string $component = null, bool $silent = false
94    ): void {
95        if ( isset( $this->deprecatedHooks[$hook] ) ) {
96            throw new InvalidArgumentException(
97                "Cannot mark hook '$hook' deprecated with version $version. " .
98                "It is already marked deprecated with version " .
99                $this->deprecatedHooks[$hook]['deprecatedVersion']
100            );
101        }
102        $hookInfo = [
103            'deprecatedVersion' => $version,
104            'silent' => $silent
105        ];
106        if ( $component ) {
107            $hookInfo['component'] = $component;
108        }
109        $this->deprecatedHooks[$hook] = $hookInfo;
110    }
111
112    /**
113     * Checks whether hook is marked deprecated
114     * @param string $hook Hook name
115     * @return bool
116     */
117    public function isHookDeprecated( string $hook ): bool {
118        return isset( $this->deprecatedHooks[$hook] );
119    }
120
121    /**
122     * Gets deprecation info for a specific hook or all hooks if hook not specified
123     * @param string|null $hook (optional) Hook name
124     * @return array|null Value array from $this->deprecatedHooks for a specific hook or all hooks
125     */
126    public function getDeprecationInfo( ?string $hook = null ): ?array {
127        if ( !$hook ) {
128            return $this->deprecatedHooks;
129        }
130        return $this->deprecatedHooks[$hook] ?? null;
131    }
132}