19798982662

Committed 30 Nov 2025 12:37PM UTC coverage: 98.354% (-0.03%) from 98.383%

Build # 19798982662

Build Type

push

github

Committed by

web-flow

Commit Message

Merge pull request #2009 from PHPCompatibility/feature/drop-support-phpcs-3

Drop support for PHPCS < 4.0

Coverage Stats

60 of 60 new or added lines in 25 files covered. (100.0%)

1 existing line in 1 file now uncovered.

8363 of 8503 relevant lines covered (98.35%)

20.53 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

98.85

/PHPCompatibility/Sniffs/Interfaces/NewInterfacesSniff.php

<?php
/**
 * PHPCompatibility, an external standard for PHP_CodeSniffer.
 *
 * @package   PHPCompatibility
 * @copyright 2012-2020 PHPCompatibility Contributors
 * @license   https://opensource.org/licenses/LGPL-3.0 LGPL3
 * @link      https://github.com/PHPCompatibility/PHPCompatibility
 */

namespace PHPCompatibility\Sniffs\Interfaces;

use PHPCompatibility\Helpers\ComplexVersionNewFeatureTrait;
use PHPCompatibility\Helpers\ScannedCode;
use PHPCompatibility\Sniff;
use PHP_CodeSniffer\Files\File;
use PHPCSUtils\Exceptions\ValueError;
use PHPCSUtils\Tokens\Collections;
use PHPCSUtils\Utils\Constants;
use PHPCSUtils\Utils\ControlStructures;
use PHPCSUtils\Utils\FunctionDeclarations;
use PHPCSUtils\Utils\MessageHelper;
use PHPCSUtils\Utils\ObjectDeclarations;
use PHPCSUtils\Utils\Parentheses;
use PHPCSUtils\Utils\TypeString;
use PHPCSUtils\Utils\UseStatements;
use PHPCSUtils\Utils\Variables;

/**
 * Detect use of new PHP native interfaces and unsupported interface methods.
 *
 * PHP version 5.0+
 *
 * @since 7.0.3
 * @since 7.1.0  Now extends the `AbstractNewFeatureSniff` instead of the base `Sniff` class..
 * @since 7.1.4  Now also detects new interfaces when used as parameter type declarations.
 * @since 8.2.0  Now also detects new interfaces when used as return type declarations.
 * @since 10.0.0 - Now extends the base `Sniff` class and uses the `ComplexVersionNewFeatureTrait`.
 *               - This class is now `final`.
 */
final class NewInterfacesSniff extends Sniff
{
    use ComplexVersionNewFeatureTrait;

    /**
     * A list of new interfaces, not present in older versions.
     *
     * The array lists : version number with false (not present) or true (present).
     * If's sufficient to list the first version where the interface appears.
     *
     * @since 7.0.3
     *
     * @var array<string, array<string, bool|string>>
     */
    protected $newInterfaces = [
        'Traversable' => [
            '4.4' => false,
            '5.0' => true,
        ],
        'Reflector' => [
            '4.4'       => false,
            '5.0'       => true,
            'extension' => 'reflection',
        ],

        'Countable' => [
            '5.0'       => false,
            '5.1'       => true,
            'extension' => 'spl',
        ],
        'OuterIterator' => [
            '5.0'       => false,
            '5.1'       => true,
            'extension' => 'spl',
        ],
        'RecursiveIterator' => [
            '5.0'       => false,
            '5.1'       => true,
            'extension' => 'spl',
        ],
        'SeekableIterator' => [
            '5.0'       => false,
            '5.1'       => true,
            'extension' => 'spl',
        ],
        'Serializable' => [
            '5.0' => false,
            '5.1' => true,
        ],
        'SplObserver' => [
            '5.0'       => false,
            '5.1'       => true,
            'extension' => 'spl',
        ],
        'SplSubject' => [
            '5.0'       => false,
            '5.1'       => true,
            'extension' => 'spl',
        ],

        'JsonSerializable' => [
            '5.3'       => false,
            '5.4'       => true,
            'extension' => 'json',
        ],
        'SessionHandlerInterface' => [
            '5.3' => false,
            '5.4' => true,
        ],

        'DateTimeInterface' => [
            '5.4'       => false,
            '5.5'       => true,
            'extension' => 'datetime',
        ],

        'SessionIdInterface' => [
            '5.5.0' => false,
            '5.5.1' => true,
        ],

        'Throwable' => [
            '5.6' => false,
            '7.0' => true,
        ],
        'SessionUpdateTimestampHandlerInterface' => [
            '5.6' => false,
            '7.0' => true,
        ],

        'Stringable' => [
            '7.4' => false,
            '8.0' => true,
        ],
        'DOMChildNode' => [
            '7.4'       => false,
            '8.0'       => true,
            'extension' => 'dom',
        ],
        'DOMParentNode' => [
            '7.4'       => false,
            '8.0'       => true,
            'extension' => 'dom',
        ],

        'UnitEnum' => [
            '8.0' => false,
            '8.1' => true,
        ],
        'BackedEnum' => [
            '8.0' => false,
            '8.1' => true,
        ],

        'Random\Engine' => [
            '8.1'       => false,
            '8.2'       => true,
            'extension' => 'random',
        ],
        'Random\CryptoSafeEngine' => [
            '8.1'       => false,
            '8.2'       => true,
            'extension' => 'random',
        ],
    ];

    /**
     * A list of methods which cannot be used in combination with particular interfaces.
     *
     * @since 7.0.3
     *
     * @var array<string, array<string, string>> Sub-key should be method name in lowercase.
     */
    protected $unsupportedMethods = [
        'Serializable' => [
            '__sleep'  => 'https://www.php.net/serializable',
            '__wakeup' => 'https://www.php.net/serializable',
        ],
    ];

    /**
     * Current file being scanned.
     *
     * @since 10.0.0
     *
     * @var string
     */
    private $currentFile = '';

    /**
     * Stores information about imported, namespaced declarations with names which are also in use by PHP.
     *
     * When those declarations are used, they do not point to the PHP internal declarations, but to the
     * namespaced, imported declarations and those usages should be ignored by the sniff.
     *
     * The array is indexed by unqualified declarations names in lower case. The value is always true.
     * It is structured this way to utilize the isset() function for faster lookups.
     *
     * @since 10.0.0
     *
     * @var array<string,true>
     */
    private $importedDeclaration = [];

    /**
     * Returns an array of tokens this test wants to listen for.
     *
     * @since 7.0.3
     *
     * @return array<int|string>
     */
    public function register()
    {
        // Handle case-insensitivity of interface names.
        $this->newInterfaces      = \array_change_key_case($this->newInterfaces, \CASE_LOWER);
        $this->unsupportedMethods = \array_change_key_case($this->unsupportedMethods, \CASE_LOWER);

        $targets = [
            \T_USE       => \T_USE,
            \T_INTERFACE => \T_INTERFACE,
            \T_CATCH     => \T_CATCH,
            \T_CONST     => \T_CONST,
        ];

        $targets += Collections::ooCanImplement();
        $targets += Collections::functionDeclarationTokens();
        $targets += Collections::ooPropertyScopes();

        return $targets;
    }


    /**
     * Processes this test, when one of its tokens is encountered.
     *
     * @since 7.0.3
     *
     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
     * @param int                         $stackPtr  The position of the current token in
     *                                               the stack passed in $tokens.
     *
     * @return void
     */
    public function process(File $phpcsFile, $stackPtr)
    {
        $fileName = $phpcsFile->getFilename();
        if ($this->currentFile !== $fileName) {
            // Reset the properties for each new file.
            $this->currentFile         = $fileName;
            $this->importedDeclaration = [];
        }

        $tokens = $phpcsFile->getTokens();

        switch ($tokens[$stackPtr]['code']) {
            case \T_USE:
                $this->processUseToken($phpcsFile, $stackPtr);
                break;

            case \T_INTERFACE:
                $this->processInterfaceToken($phpcsFile, $stackPtr);
                break;

            case \T_CONST:
                $this->processConstantToken($phpcsFile, $stackPtr);
                break;

            case \T_CATCH:
                $this->processCatchToken($phpcsFile, $stackPtr);
                break;
        }

        if (isset(Collections::ooCanImplement()[$tokens[$stackPtr]['code']]) === true) {
            $this->processOOToken($phpcsFile, $stackPtr);
        }

        if (isset(Collections::ooPropertyScopes()[$tokens[$stackPtr]['code']]) === true) {
            $this->processOOProperties($phpcsFile, $stackPtr);
        }

        if (isset(Collections::functionDeclarationTokens()[$tokens[$stackPtr]['code']]) === true) {
            $this->processFunctionToken($phpcsFile, $stackPtr);
        }
    }


    /**
     * Processes this test for when a class token is encountered.
     *
     * - Detect classes and enums implementing the new interfaces.
     * - Detect classes and enums implementing the new interfaces with unsupported functions.
     *
     * @since 7.1.4  Split off from the `process()` method.
     * @since 10.0.0 Renamed from `processClassToken()` to `processOOToken()`.
     *
     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
     * @param int                         $stackPtr  The position of the current token in
     *                                               the stack passed in $tokens.
     *
     * @return void
     */
    private function processOOToken(File $phpcsFile, $stackPtr)
    {
        $interfaces = ObjectDeclarations::findImplementedInterfaceNames($phpcsFile, $stackPtr);

        if (\is_array($interfaces) === false || $interfaces === []) {
            return;
        }

        $this->processInterfaceList($phpcsFile, $stackPtr, $interfaces, 'Classes that implement');
    }


    /**
     * Processes this test for when an interface token is encountered.
     *
     * - Detect interfaces extending the new interfaces.
     * - Detect interfaces extending the new interfaces with unsupported functions.
     *
     * @since 10.0.0
     *
     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
     * @param int                         $stackPtr  The position of the current token in
     *                                               the stack passed in $tokens.
     *
     * @return void
     */
    private function processInterfaceToken(File $phpcsFile, $stackPtr)
    {
        $interfaces = ObjectDeclarations::findExtendedInterfaceNames($phpcsFile, $stackPtr);

        if (\is_array($interfaces) === false || $interfaces === []) {
            return;
        }

        $this->processInterfaceList($phpcsFile, $stackPtr, $interfaces, 'Interfaces that extend');
    }


    /**
     * Processes a list of interfaces being extended/implemented.
     *
     * @since 10.0.0 Split off from the `processClassToken()` method.
     *
     * @param \PHP_CodeSniffer\Files\File $phpcsFile  The file being scanned.
     * @param int                         $stackPtr   The position of the current token in
     *                                                the stack passed in $tokens.
     * @param array                       $interfaces List of interface names.
     * @param string                      $phrase     Start of the error phrase for unsupported functions.
     *
     * @return void
     */
    private function processInterfaceList(File $phpcsFile, $stackPtr, array $interfaces, $phrase)
    {
        $tokens       = $phpcsFile->getTokens();
        $checkMethods = false;

        if (isset($tokens[$stackPtr]['scope_closer'])) {
            $checkMethods = true;
        }

        $ooMethods   = ObjectDeclarations::getDeclaredMethods($phpcsFile, $stackPtr);
        $ooMethodsLc = \array_change_key_case($ooMethods, \CASE_LOWER);

        foreach ($interfaces as $interface) {
            $interface   = \ltrim($interface, '\\');
            $interfaceLc = \strtolower($interface);

            if (isset($this->newInterfaces[$interfaceLc]) === true) {
                $itemInfo = [
                    'name'   => $interface,
                    'nameLc' => $interfaceLc,
                ];
                $this->handleFeature($phpcsFile, $stackPtr, $itemInfo);
            }

            if (isset($this->unsupportedMethods[$interfaceLc]) === true) {
                foreach ($this->unsupportedMethods[$interfaceLc] as $methodName => $see) {
                    if (isset($ooMethodsLc[$methodName])) {
                        $error     = $phrase . ' interface %s do not support the method %s(). See %s';
                        $errorCode = MessageHelper::stringToErrorCode($interfaceLc) . 'UnsupportedMethod';
                        $data      = [
                            $interface,
                            $methodName,
                            $see,
                        ];

                        $phpcsFile->addError($error, $ooMethodsLc[$methodName], $errorCode, $data);
                    }
                }
            }
        }
    }


    /**
     * Processes this test for when a constant token is encountered.
     *
     * - Detect new interfaces when used as a class constant type declaration.
     *
     * @since 10.0.0
     *
     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
     * @param int                         $stackPtr  The position of the current token in
     *                                               the stack passed in $tokens.
     *
     * @return void
     */
    private function processConstantToken(File $phpcsFile, $stackPtr)
    {
        try {
            $properties = Constants::getProperties($phpcsFile, $stackPtr);
        } catch (ValueError $e) {
            // Not an OO constant or parse error.
            return;
        }

        if ($properties['type'] === '') {
            return;
        }

        $this->checkTypeDeclaration($phpcsFile, $properties['type_token'], $properties['type']);
    }


    /**
     * Processes an OO token for properties declared in the OO scope.
     *
     * - Detect new interfaces when used as a property type declaration.
     *
     * @since 10.0.0
     *
     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
     * @param int                         $stackPtr  The position of the current token in
     *                                               the stack passed in $tokens.
     *
     * @return void
     */
    private function processOOProperties(File $phpcsFile, $stackPtr)
    {
        $ooProperties = ObjectDeclarations::getDeclaredProperties($phpcsFile, $stackPtr);
        if (empty($ooProperties)) {
            return;
        }

        $tokens         = $phpcsFile->getTokens();
        $endOfStatement = false;
        foreach ($ooProperties as $variableToken) {
            if ($endOfStatement !== false && $variableToken < $endOfStatement) {
                // Don't throw the same error multiple times for multi-property declarations.
                // Also skip over any other constructor promoted properties.
                continue;
            }

            try {
                $properties = Variables::getMemberProperties($phpcsFile, $variableToken);
            } catch (ValueError $e) {
                /*
                 * This must be constructor property promotion.
                 * Ignore for now and skip over any other promoted properties, these will be handled
                 * via the function token for the constructor.
                 */
                $deepestOpen = Parentheses::getLastOpener($phpcsFile, $variableToken);
                if ($deepestOpen !== false
                    && $stackPtr < $deepestOpen
                    && Parentheses::isOwnerIn($phpcsFile, $deepestOpen, \T_FUNCTION)
                    && isset($tokens[$deepestOpen]['parenthesis_closer'])
                ) {
                    $endOfStatement = $tokens[$deepestOpen]['parenthesis_closer'];
                }

                continue;
            }

            if ($properties['type'] === '') {
                continue;
            }

            $this->checkTypeDeclaration($phpcsFile, $properties['type_token'], $properties['type']);

            $endOfStatement = $phpcsFile->findNext([\T_SEMICOLON, \T_CLOSE_TAG], ($variableToken + 1));
        }
    }


    /**
     * Processes this test for when a function token is encountered.
     *
     * - Detect new interfaces when used as a parameter type hint.
     * - Detect new interfaces when used as a return type hint.
     *
     * @since 7.1.4
     *
     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
     * @param int                         $stackPtr  The position of the current token in
     *                                               the stack passed in $tokens.
     *
     * @return void
     */
    private function processFunctionToken(File $phpcsFile, $stackPtr)
    {
        /*
         * Check parameter type declarations.
         */
        $parameters = FunctionDeclarations::getParameters($phpcsFile, $stackPtr);
        if (empty($parameters) === false && \is_array($parameters) === true) {
            foreach ($parameters as $param) {
                if ($param['type_hint'] === '') {
                    continue;
                }

                $this->checkTypeDeclaration($phpcsFile, $param['type_hint_token'], $param['type_hint']);
            }
        }

        /*
         * Check return type declarations.
         */
        $properties = FunctionDeclarations::getProperties($phpcsFile, $stackPtr);
        if ($properties['return_type'] === '') {
            return;
        }

        $this->checkTypeDeclaration($phpcsFile, $properties['return_type_token'], $properties['return_type']);
    }


    /**
     * Processes a type declaration.
     *
     * @since 10.0.0
     *
     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
     * @param int                         $stackPtr  The position of the current token in
     *                                               the stack passed in $tokens.
     * @param string                      $typeHint  The type declaration.
     *
     * @return void
     */
    private function checkTypeDeclaration($phpcsFile, $stackPtr, $typeHint)
    {
        $types = TypeString::filterOOTypes(TypeString::toArray($typeHint));

        if (empty($types) === true) {
            return;
        }

        foreach ($types as $type) {
            // Strip off potential (global) namespace indication.
            $type = \ltrim($type, '\\');

            if ($type === '') {
                continue;
            }

            $typeLc = \strtolower($type);
            if (isset($this->newInterfaces[$typeLc]) === false) {
                continue;
            }

            $itemInfo = [
                'name'   => $type,
                'nameLc' => $typeLc,
            ];
            $this->handleFeature($phpcsFile, $stackPtr, $itemInfo);
        }
    }


    /**
     * Processes this test for when a catch token is encountered.
     *
     * - Detect interfaces (Throwable) when used in a catch statement.
     *
     * @since 10.0.0
     *
     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
     * @param int                         $stackPtr  The position of the current token in
     *                                               the stack passed in $tokens.
     *
     * @return void
     */
    private function processCatchToken(File $phpcsFile, $stackPtr)
    {
        $exceptions = ControlStructures::getCaughtExceptions($phpcsFile, $stackPtr);
        if (empty($exceptions) === true) {
            return;
        }

        foreach ($exceptions as $exception) {
            // Strip off potential (global) namespace indication.
            $name   = \ltrim($exception['type'], '\\');
            $nameLC = \strtolower($name);

            if (isset($this->newInterfaces[$nameLC]) === true) {
                $itemInfo = [
                    'name'   => $name,
                    'nameLc' => $nameLC,
                ];
                $this->handleFeature($phpcsFile, $exception['type_token'], $itemInfo);
            }
        }
    }

    /**
     * Processes this test for when a use token is encountered.
     *
     * - Save imported declarations for later use.
     *
     * @since 10.0.0
     *
     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
     * @param int                         $stackPtr  The position of the current token in
     *                                               the stack passed in $tokens.
     *
     * @return void
     */
    private function processUseToken(File $phpcsFile, $stackPtr)
    {
        if (UseStatements::isImportUse($phpcsFile, $stackPtr) === false) {
            return;
        }

        $splitUseStatement = UseStatements::splitImportUseStatement($phpcsFile, $stackPtr);

        foreach ($splitUseStatement['name'] as $name => $fullyQualifiedName) {
            $lowerFullyQualifiedName = \strtolower($fullyQualifiedName);

            // If the imported declaration is imported from the internal namespace it will not be excluded.
            if (isset($this->newInterfaces[$lowerFullyQualifiedName])) {
                continue;
            }

            $this->importedDeclaration[\strtolower($name)] = true;
        }
    }

    /**
     * Handle the retrieval of relevant information and - if necessary - throwing of an
     * error for a matched item.
     *
     * @since 10.0.0
     *
     * @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
     * @param int                         $stackPtr  The position of the relevant token in
     *                                               the stack.
     * @param array                       $itemInfo  Base information about the item.
     *
     * @return void
     */
    protected function handleFeature(File $phpcsFile, $stackPtr, array $itemInfo)
    {
        if (isset($this->importedDeclaration[$itemInfo['nameLc']])) {
            return;
        }

        $itemArray   = $this->newInterfaces[$itemInfo['nameLc']];
        $versionInfo = $this->getVersionInfo($itemArray);

        if (empty($versionInfo['not_in_version'])
            || ScannedCode::shouldRunOnOrBelow($versionInfo['not_in_version']) === false
        ) {
            return;
        }

        $this->addError($phpcsFile, $stackPtr, $itemInfo, $versionInfo);
    }


    /**
     * Generates the error for this item.
     *
     * @since 10.0.0
     *
     * @param \PHP_CodeSniffer\Files\File $phpcsFile   The file being scanned.
     * @param int                         $stackPtr    The position of the relevant token in
     *                                                 the stack.
     * @param array                       $itemInfo    Base information about the item.
     * @param string[]                    $versionInfo Array with detail (version) information
     *                                                 relevant to the item.
     *
     * @return void
     */
    protected function addError(File $phpcsFile, $stackPtr, array $itemInfo, array $versionInfo)
    {
        // Overrule the default message template.
        $this->msgTemplate = 'The built-in interface %s is not present in PHP version %s or earlier';

        $msgInfo = $this->getMessageInfo($itemInfo['name'], $itemInfo['nameLc'], $versionInfo);

        $phpcsFile->addError($msgInfo['message'], $stackPtr, $msgInfo['errorcode'], $msgInfo['data']);
    }
}

1	<?php
2	/**
3	* PHPCompatibility, an external standard for PHP_CodeSniffer.
4	*
5	* @package PHPCompatibility
6	* @copyright 2012-2020 PHPCompatibility Contributors
7	* @license https://opensource.org/licenses/LGPL-3.0 LGPL3
8	* @link https://github.com/PHPCompatibility/PHPCompatibility
9	*/
10
11	namespace PHPCompatibility\Sniffs\Interfaces;
12
13	use PHPCompatibility\Helpers\ComplexVersionNewFeatureTrait;
14	use PHPCompatibility\Helpers\ScannedCode;
15	use PHPCompatibility\Sniff;
16	use PHP_CodeSniffer\Files\File;
17	use PHPCSUtils\Exceptions\ValueError;
18	use PHPCSUtils\Tokens\Collections;
19	use PHPCSUtils\Utils\Constants;
20	use PHPCSUtils\Utils\ControlStructures;
21	use PHPCSUtils\Utils\FunctionDeclarations;
22	use PHPCSUtils\Utils\MessageHelper;
23	use PHPCSUtils\Utils\ObjectDeclarations;
24	use PHPCSUtils\Utils\Parentheses;
25	use PHPCSUtils\Utils\TypeString;
26	use PHPCSUtils\Utils\UseStatements;
27	use PHPCSUtils\Utils\Variables;
28
29	/**
30	* Detect use of new PHP native interfaces and unsupported interface methods.
31	*
32	* PHP version 5.0+
33	*
34	* @since 7.0.3
35	* @since 7.1.0 Now extends the `AbstractNewFeatureSniff` instead of the base `Sniff` class..
36	* @since 7.1.4 Now also detects new interfaces when used as parameter type declarations.
37	* @since 8.2.0 Now also detects new interfaces when used as return type declarations.
38	* @since 10.0.0 - Now extends the base `Sniff` class and uses the `ComplexVersionNewFeatureTrait`.
39	* - This class is now `final`.
40	*/
41	final class NewInterfacesSniff extends Sniff
42	{
43	use ComplexVersionNewFeatureTrait;
44
45	/**
46	* A list of new interfaces, not present in older versions.
47	*
48	* The array lists : version number with false (not present) or true (present).
49	* If's sufficient to list the first version where the interface appears.
50	*
51	* @since 7.0.3
52	*
53	* @var array<string, array<string, bool\|string>>
54	*/
55	protected $newInterfaces = [
56	'Traversable' => [
57	'4.4' => false,
58	'5.0' => true,
59	],
60	'Reflector' => [
61	'4.4' => false,
62	'5.0' => true,
63	'extension' => 'reflection',
64	],
65
66	'Countable' => [
67	'5.0' => false,
68	'5.1' => true,
69	'extension' => 'spl',
70	],
71	'OuterIterator' => [
72	'5.0' => false,
73	'5.1' => true,
74	'extension' => 'spl',
75	],
76	'RecursiveIterator' => [
77	'5.0' => false,
78	'5.1' => true,
79	'extension' => 'spl',
80	],
81	'SeekableIterator' => [
82	'5.0' => false,
83	'5.1' => true,
84	'extension' => 'spl',
85	],
86	'Serializable' => [
87	'5.0' => false,
88	'5.1' => true,
89	],
90	'SplObserver' => [
91	'5.0' => false,
92	'5.1' => true,
93	'extension' => 'spl',
94	],
95	'SplSubject' => [
96	'5.0' => false,
97	'5.1' => true,
98	'extension' => 'spl',
99	],
100
101	'JsonSerializable' => [
102	'5.3' => false,
103	'5.4' => true,
104	'extension' => 'json',
105	],
106	'SessionHandlerInterface' => [
107	'5.3' => false,
108	'5.4' => true,
109	],
110
111	'DateTimeInterface' => [
112	'5.4' => false,
113	'5.5' => true,
114	'extension' => 'datetime',
115	],
116
117	'SessionIdInterface' => [
118	'5.5.0' => false,
119	'5.5.1' => true,
120	],
121
122	'Throwable' => [
123	'5.6' => false,
124	'7.0' => true,
125	],
126	'SessionUpdateTimestampHandlerInterface' => [
127	'5.6' => false,
128	'7.0' => true,
129	],
130
131	'Stringable' => [
132	'7.4' => false,
133	'8.0' => true,
134	],
135	'DOMChildNode' => [
136	'7.4' => false,
137	'8.0' => true,
138	'extension' => 'dom',
139	],
140	'DOMParentNode' => [
141	'7.4' => false,
142	'8.0' => true,
143	'extension' => 'dom',
144	],
145
146	'UnitEnum' => [
147	'8.0' => false,
148	'8.1' => true,
149	],
150	'BackedEnum' => [
151	'8.0' => false,
152	'8.1' => true,
153	],
154
155	'Random\Engine' => [
156	'8.1' => false,
157	'8.2' => true,
158	'extension' => 'random',
159	],
160	'Random\CryptoSafeEngine' => [
161	'8.1' => false,
162	'8.2' => true,
163	'extension' => 'random',
164	],
165	];
166
167	/**
168	* A list of methods which cannot be used in combination with particular interfaces.
169	*
170	* @since 7.0.3
171	*
172	* @var array<string, array<string, string>> Sub-key should be method name in lowercase.
173	*/
174	protected $unsupportedMethods = [
175	'Serializable' => [
176	'__sleep' => 'https://www.php.net/serializable',
177	'__wakeup' => 'https://www.php.net/serializable',
178	],
179	];
180
181	/**
182	* Current file being scanned.
183	*
184	* @since 10.0.0
185	*
186	* @var string
187	*/
188	private $currentFile = '';
189
190	/**
191	* Stores information about imported, namespaced declarations with names which are also in use by PHP.
192	*
193	* When those declarations are used, they do not point to the PHP internal declarations, but to the
194	* namespaced, imported declarations and those usages should be ignored by the sniff.
195	*
196	* The array is indexed by unqualified declarations names in lower case. The value is always true.
197	* It is structured this way to utilize the isset() function for faster lookups.
198	*
199	* @since 10.0.0
200	*
201	* @var array<string,true>
202	*/
203	private $importedDeclaration = [];
204
205	/**
206	* Returns an array of tokens this test wants to listen for.
207	*
208	* @since 7.0.3
209	*
210	* @return array<int\|string>
211	*/
212	public function register()	12✔
213	{
214	// Handle case-insensitivity of interface names.
215	$this->newInterfaces = \array_change_key_case($this->newInterfaces, \CASE_LOWER);	12✔
216	$this->unsupportedMethods = \array_change_key_case($this->unsupportedMethods, \CASE_LOWER);	12✔
217
218	$targets = [	6✔
219	\T_USE => \T_USE,	12✔
220	\T_INTERFACE => \T_INTERFACE,	6✔
221	\T_CATCH => \T_CATCH,	6✔
222	\T_CONST => \T_CONST,	6✔
223	];	6✔
224
225	$targets += Collections::ooCanImplement();	12✔
226	$targets += Collections::functionDeclarationTokens();	12✔
227	$targets += Collections::ooPropertyScopes();	12✔
228
229	return $targets;	12✔
230	}
231
232
233	/**
234	* Processes this test, when one of its tokens is encountered.
235	*
236	* @since 7.0.3
237	*
238	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
239	* @param int $stackPtr The position of the current token in
240	* the stack passed in $tokens.
241	*
242	* @return void
243	*/
244	public function process(File $phpcsFile, $stackPtr)	44✔
245	{
246	$fileName = $phpcsFile->getFilename();	44✔
247	if ($this->currentFile !== $fileName) {	44✔
248	// Reset the properties for each new file.
249	$this->currentFile = $fileName;	12✔
250	$this->importedDeclaration = [];	12✔
251	}
252
253	$tokens = $phpcsFile->getTokens();	44✔
254
255	switch ($tokens[$stackPtr]['code']) {	44✔
256	case \T_USE:
257	$this->processUseToken($phpcsFile, $stackPtr);	40✔
258	break;	40✔
259
260	case \T_INTERFACE:
261	$this->processInterfaceToken($phpcsFile, $stackPtr);	40✔
262	break;	40✔
263
264	case \T_CONST:
265	$this->processConstantToken($phpcsFile, $stackPtr);	40✔
266	break;	40✔
267
268	case \T_CATCH:
269	$this->processCatchToken($phpcsFile, $stackPtr);	44✔
270	break;	44✔
271	}
272
273	if (isset(Collections::ooCanImplement()[$tokens[$stackPtr]['code']]) === true) {	44✔
274	$this->processOOToken($phpcsFile, $stackPtr);	40✔
275	}
276
277	if (isset(Collections::ooPropertyScopes()[$tokens[$stackPtr]['code']]) === true) {	44✔
278	$this->processOOProperties($phpcsFile, $stackPtr);	40✔
279	}
280
281	if (isset(Collections::functionDeclarationTokens()[$tokens[$stackPtr]['code']]) === true) {	44✔
282	$this->processFunctionToken($phpcsFile, $stackPtr);	40✔
283	}
284	}	22✔
285
286
287	/**
288	* Processes this test for when a class token is encountered.
289	*
290	* - Detect classes and enums implementing the new interfaces.
291	* - Detect classes and enums implementing the new interfaces with unsupported functions.
292	*
293	* @since 7.1.4 Split off from the `process()` method.
294	* @since 10.0.0 Renamed from `processClassToken()` to `processOOToken()`.
295	*
296	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
297	* @param int $stackPtr The position of the current token in
298	* the stack passed in $tokens.
299	*
300	* @return void
301	*/
302	private function processOOToken(File $phpcsFile, $stackPtr)	40✔
303	{
304	$interfaces = ObjectDeclarations::findImplementedInterfaceNames($phpcsFile, $stackPtr);	40✔
305
306	if (\is_array($interfaces) === false \|\| $interfaces === []) {	40✔
307	return;	40✔
308	}
309
310	$this->processInterfaceList($phpcsFile, $stackPtr, $interfaces, 'Classes that implement');	40✔
311	}	20✔
312
313
314	/**
315	* Processes this test for when an interface token is encountered.
316	*
317	* - Detect interfaces extending the new interfaces.
318	* - Detect interfaces extending the new interfaces with unsupported functions.
319	*
320	* @since 10.0.0
321	*
322	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
323	* @param int $stackPtr The position of the current token in
324	* the stack passed in $tokens.
325	*
326	* @return void
327	*/
328	private function processInterfaceToken(File $phpcsFile, $stackPtr)	40✔
329	{
330	$interfaces = ObjectDeclarations::findExtendedInterfaceNames($phpcsFile, $stackPtr);	40✔
331
332	if (\is_array($interfaces) === false \|\| $interfaces === []) {	40✔
333	return;	40✔
334	}
335
336	$this->processInterfaceList($phpcsFile, $stackPtr, $interfaces, 'Interfaces that extend');	40✔
337	}	20✔
338
339
340	/**
341	* Processes a list of interfaces being extended/implemented.
342	*
343	* @since 10.0.0 Split off from the `processClassToken()` method.
344	*
345	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
346	* @param int $stackPtr The position of the current token in
347	* the stack passed in $tokens.
348	* @param array $interfaces List of interface names.
349	* @param string $phrase Start of the error phrase for unsupported functions.
350	*
351	* @return void
352	*/
353	private function processInterfaceList(File $phpcsFile, $stackPtr, array $interfaces, $phrase)	40✔
354	{
355	$tokens = $phpcsFile->getTokens();	40✔
356	$checkMethods = false;	40✔
357
358	if (isset($tokens[$stackPtr]['scope_closer'])) {	40✔
359	$checkMethods = true;	40✔
360	}
361
362	$ooMethods = ObjectDeclarations::getDeclaredMethods($phpcsFile, $stackPtr);	40✔
363	$ooMethodsLc = \array_change_key_case($ooMethods, \CASE_LOWER);	40✔
364
365	foreach ($interfaces as $interface) {	40✔
366	$interface = \ltrim($interface, '\\');	40✔
367	$interfaceLc = \strtolower($interface);	40✔
368
369	if (isset($this->newInterfaces[$interfaceLc]) === true) {	40✔
370	$itemInfo = [	20✔
371	'name' => $interface,	40✔
372	'nameLc' => $interfaceLc,	40✔
373	];	20✔
374	$this->handleFeature($phpcsFile, $stackPtr, $itemInfo);	40✔
375	}
376
377	if (isset($this->unsupportedMethods[$interfaceLc]) === true) {	40✔
378	foreach ($this->unsupportedMethods[$interfaceLc] as $methodName => $see) {	40✔
379	if (isset($ooMethodsLc[$methodName])) {	40✔
380	$error = $phrase . ' interface %s do not support the method %s(). See %s';	40✔
381	$errorCode = MessageHelper::stringToErrorCode($interfaceLc) . 'UnsupportedMethod';	40✔
382	$data = [	20✔
383	$interface,	40✔
384	$methodName,	40✔
385	$see,	40✔
386	];	20✔
387
388	$phpcsFile->addError($error, $ooMethodsLc[$methodName], $errorCode, $data);	40✔
389	}
390	}
391	}
392	}
393	}	20✔
394
395
396	/**
397	* Processes this test for when a constant token is encountered.
398	*
399	* - Detect new interfaces when used as a class constant type declaration.
400	*
401	* @since 10.0.0
402	*
403	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
404	* @param int $stackPtr The position of the current token in
405	* the stack passed in $tokens.
406	*
407	* @return void
408	*/
409	private function processConstantToken(File $phpcsFile, $stackPtr)	40✔
410	{
411	try {
412	$properties = Constants::getProperties($phpcsFile, $stackPtr);	40✔
413	} catch (ValueError $e) {	40✔
414	// Not an OO constant or parse error.
415	return;	40✔
416	}
417
418	if ($properties['type'] === '') {	40✔
419	return;	40✔
420	}
421
422	$this->checkTypeDeclaration($phpcsFile, $properties['type_token'], $properties['type']);	40✔
423	}	20✔
424
425
426	/**
427	* Processes an OO token for properties declared in the OO scope.
428	*
429	* - Detect new interfaces when used as a property type declaration.
430	*
431	* @since 10.0.0
432	*
433	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
434	* @param int $stackPtr The position of the current token in
435	* the stack passed in $tokens.
436	*
437	* @return void
438	*/
439	private function processOOProperties(File $phpcsFile, $stackPtr)	40✔
440	{
441	$ooProperties = ObjectDeclarations::getDeclaredProperties($phpcsFile, $stackPtr);	40✔
442	if (empty($ooProperties)) {	40✔
443	return;	40✔
444	}
445
446	$tokens = $phpcsFile->getTokens();	40✔
447	$endOfStatement = false;	40✔
448	foreach ($ooProperties as $variableToken) {	40✔
449	if ($endOfStatement !== false && $variableToken < $endOfStatement) {	40✔
450	// Don't throw the same error multiple times for multi-property declarations.
451	// Also skip over any other constructor promoted properties.
452	continue;	40✔
453	}
454
455	try {
456	$properties = Variables::getMemberProperties($phpcsFile, $variableToken);	40✔
457	} catch (ValueError $e) {	40✔
458	/*
459	* This must be constructor property promotion.
460	* Ignore for now and skip over any other promoted properties, these will be handled
461	* via the function token for the constructor.
462	*/
463	$deepestOpen = Parentheses::getLastOpener($phpcsFile, $variableToken);	40✔
464	if ($deepestOpen !== false	40✔
465	&& $stackPtr < $deepestOpen	40✔
466	&& Parentheses::isOwnerIn($phpcsFile, $deepestOpen, \T_FUNCTION)	40✔
467	&& isset($tokens[$deepestOpen]['parenthesis_closer'])	40✔
468	) {
469	$endOfStatement = $tokens[$deepestOpen]['parenthesis_closer'];	40✔
470	}
471
472	continue;	40✔
473	}
474
475	if ($properties['type'] === '') {	40✔
476	continue;	40✔
477	}
478
479	$this->checkTypeDeclaration($phpcsFile, $properties['type_token'], $properties['type']);	40✔
480
481	$endOfStatement = $phpcsFile->findNext([\T_SEMICOLON, \T_CLOSE_TAG], ($variableToken + 1));	40✔
482	}
483	}	20✔
484
485
486	/**
487	* Processes this test for when a function token is encountered.
488	*
489	* - Detect new interfaces when used as a parameter type hint.
490	* - Detect new interfaces when used as a return type hint.
491	*
492	* @since 7.1.4
493	*
494	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
495	* @param int $stackPtr The position of the current token in
496	* the stack passed in $tokens.
497	*
498	* @return void
499	*/
500	private function processFunctionToken(File $phpcsFile, $stackPtr)	40✔
501	{
502	/*
503	* Check parameter type declarations.
504	*/
505	$parameters = FunctionDeclarations::getParameters($phpcsFile, $stackPtr);	40✔
506	if (empty($parameters) === false && \is_array($parameters) === true) {	40✔
507	foreach ($parameters as $param) {	40✔
508	if ($param['type_hint'] === '') {	40✔
509	continue;	40✔
510	}
511
512	$this->checkTypeDeclaration($phpcsFile, $param['type_hint_token'], $param['type_hint']);	40✔
513	}
514	}
515
516	/*
517	* Check return type declarations.
518	*/
519	$properties = FunctionDeclarations::getProperties($phpcsFile, $stackPtr);	40✔
520	if ($properties['return_type'] === '') {	40✔
521	return;	40✔
522	}
523
524	$this->checkTypeDeclaration($phpcsFile, $properties['return_type_token'], $properties['return_type']);	40✔
525	}	20✔
526
527
528	/**
529	* Processes a type declaration.
530	*
531	* @since 10.0.0
532	*
533	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
534	* @param int $stackPtr The position of the current token in
535	* the stack passed in $tokens.
536	* @param string $typeHint The type declaration.
537	*
538	* @return void
539	*/
540	private function checkTypeDeclaration($phpcsFile, $stackPtr, $typeHint)	40✔
541	{
542	$types = TypeString::filterOOTypes(TypeString::toArray($typeHint));	40✔
543
544	if (empty($types) === true) {	40✔
545	return;	40✔
546	}
547
548	foreach ($types as $type) {	40✔
549	// Strip off potential (global) namespace indication.
550	$type = \ltrim($type, '\\');	40✔
551
552	if ($type === '') {	40✔
UNCOV 553	continue;	×
554	}
555
556	$typeLc = \strtolower($type);	40✔
557	if (isset($this->newInterfaces[$typeLc]) === false) {	40✔
558	continue;	40✔
559	}
560
561	$itemInfo = [	20✔
562	'name' => $type,	40✔
563	'nameLc' => $typeLc,	40✔
564	];	20✔
565	$this->handleFeature($phpcsFile, $stackPtr, $itemInfo);	40✔
566	}
567	}	20✔
568
569
570	/**
571	* Processes this test for when a catch token is encountered.
572	*
573	* - Detect interfaces (Throwable) when used in a catch statement.
574	*
575	* @since 10.0.0
576	*
577	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
578	* @param int $stackPtr The position of the current token in
579	* the stack passed in $tokens.
580	*
581	* @return void
582	*/
583	private function processCatchToken(File $phpcsFile, $stackPtr)	44✔
584	{
585	$exceptions = ControlStructures::getCaughtExceptions($phpcsFile, $stackPtr);	44✔
586	if (empty($exceptions) === true) {	44✔
587	return;	44✔
588	}
589
590	foreach ($exceptions as $exception) {	40✔
591	// Strip off potential (global) namespace indication.
592	$name = \ltrim($exception['type'], '\\');	40✔
593	$nameLC = \strtolower($name);	40✔
594
595	if (isset($this->newInterfaces[$nameLC]) === true) {	40✔
596	$itemInfo = [	20✔
597	'name' => $name,	40✔
598	'nameLc' => $nameLC,	40✔
599	];	20✔
600	$this->handleFeature($phpcsFile, $exception['type_token'], $itemInfo);	40✔
601	}
602	}
603	}	20✔
604
605	/**
606	* Processes this test for when a use token is encountered.
607	*
608	* - Save imported declarations for later use.
609	*
610	* @since 10.0.0
611	*
612	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
613	* @param int $stackPtr The position of the current token in
614	* the stack passed in $tokens.
615	*
616	* @return void
617	*/
618	private function processUseToken(File $phpcsFile, $stackPtr)	40✔
619	{
620	if (UseStatements::isImportUse($phpcsFile, $stackPtr) === false) {	40✔
621	return;	×
622	}
623
624	$splitUseStatement = UseStatements::splitImportUseStatement($phpcsFile, $stackPtr);	40✔
625
626	foreach ($splitUseStatement['name'] as $name => $fullyQualifiedName) {	40✔
627	$lowerFullyQualifiedName = \strtolower($fullyQualifiedName);	40✔
628
629	// If the imported declaration is imported from the internal namespace it will not be excluded.
630	if (isset($this->newInterfaces[$lowerFullyQualifiedName])) {	40✔
631	continue;	40✔
632	}
633
634	$this->importedDeclaration[\strtolower($name)] = true;	4✔
635	}
636	}	20✔
637
638	/**
639	* Handle the retrieval of relevant information and - if necessary - throwing of an
640	* error for a matched item.
641	*
642	* @since 10.0.0
643	*
644	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
645	* @param int $stackPtr The position of the relevant token in
646	* the stack.
647	* @param array $itemInfo Base information about the item.
648	*
649	* @return void
650	*/
651	protected function handleFeature(File $phpcsFile, $stackPtr, array $itemInfo)	40✔
652	{
653	if (isset($this->importedDeclaration[$itemInfo['nameLc']])) {	40✔
654	return;	4✔
655	}
656
657	$itemArray = $this->newInterfaces[$itemInfo['nameLc']];	40✔
658	$versionInfo = $this->getVersionInfo($itemArray);	40✔
659
660	if (empty($versionInfo['not_in_version'])	40✔
661	\|\| ScannedCode::shouldRunOnOrBelow($versionInfo['not_in_version']) === false	40✔
662	) {
663	return;	36✔
664	}
665
666	$this->addError($phpcsFile, $stackPtr, $itemInfo, $versionInfo);	36✔
667	}	18✔
668
669
670	/**
671	* Generates the error for this item.
672	*
673	* @since 10.0.0
674	*
675	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file being scanned.
676	* @param int $stackPtr The position of the relevant token in
677	* the stack.
678	* @param array $itemInfo Base information about the item.
679	* @param string[] $versionInfo Array with detail (version) information
680	* relevant to the item.
681	*
682	* @return void
683	*/
684	protected function addError(File $phpcsFile, $stackPtr, array $itemInfo, array $versionInfo)	36✔
685	{
686	// Overrule the default message template.
687	$this->msgTemplate = 'The built-in interface %s is not present in PHP version %s or earlier';	36✔
688
689	$msgInfo = $this->getMessageInfo($itemInfo['name'], $itemInfo['nameLc'], $versionInfo);	36✔
690
691	$phpcsFile->addError($msgInfo['message'], $stackPtr, $msgInfo['errorcode'], $msgInfo['data']);	36✔
692	}	18✔
693	}

PHPCompatibility / PHPCompatibility / 19798982662

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous