Parentheses.php
No OneTemporary
Actions

Size

18 KB

Referenced Files

None

Subscribers

None

Parentheses.php
View Options

	<?php
	/**
	* PHPCSUtils, utility functions and classes for PHP_CodeSniffer sniff developers.
	*
	* @package PHPCSUtils
	* @copyright 2019-2020 PHPCSUtils Contributors
	* @license https://opensource.org/licenses/LGPL-3.0 LGPL3
	* @link https://github.com/PHPCSStandards/PHPCSUtils
	*/

	namespace PHPCSUtils\Utils;

	use PHP_CodeSniffer\Files\File;
	use PHP_CodeSniffer\Util\Tokens;

	/**
	* Utility functions for use when examining parenthesis tokens and arbitrary tokens wrapped
	* in parentheses.
	*
	* In contrast to PHPCS natively, `isset()`, `unset()`, `empty()`, `exit()`, `die()` and `eval()`
	* will be considered parentheses owners by the functions in this class.
	*
	* @since 1.0.0
	*/
	final class Parentheses
	{

	/**
	* Extra tokens which should be considered parentheses owners.
	*
	* - `T_ISSET`, `T_UNSET`, `T_EMPTY`, `T_EXIT` and `T_EVAL` are not PHPCS native parentheses
	* owners, but are considered such for the purposes of this class.
	* Also see {@link https://github.com/squizlabs/PHP_CodeSniffer/issues/3118 PHPCS#3118}.
	*
	* @since 1.0.0
	*
	* @var array<int\|string, int\|string>
	*/
	private static $extraParenthesesOwners = [
	\T_ISSET => \T_ISSET,
	\T_UNSET => \T_UNSET,
	\T_EMPTY => \T_EMPTY,
	\T_EXIT => \T_EXIT,
	\T_EVAL => \T_EVAL,
	];

	/**
	* Get the stack pointer to the parentheses owner of an open/close parenthesis.
	*
	* @since 1.0.0
	*
	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
	* @param int $stackPtr The position of `T_OPEN/CLOSE_PARENTHESIS` token.
	*
	* @return int\|false Integer stack pointer to the parentheses owner; or `FALSE` if the
	* parenthesis does not have a (direct) owner or if the token passed
	* was not a parenthesis.
	*/
	public static function getOwner(File $phpcsFile, $stackPtr)
	{
	$tokens = $phpcsFile->getTokens();

	if (isset($tokens[$stackPtr]['parenthesis_owner'])) {
	return $tokens[$stackPtr]['parenthesis_owner'];
	}

	/*
	* As the 'parenthesis_owner' index is only set on parentheses, we didn't need to do any
	* input validation before, but now we do.
	*/
	if (isset($tokens[$stackPtr]) === false
	\|\| ($tokens[$stackPtr]['code'] !== \T_OPEN_PARENTHESIS
	&& $tokens[$stackPtr]['code'] !== \T_CLOSE_PARENTHESIS)
	) {
	return false;
	}

	if ($tokens[$stackPtr]['code'] === \T_CLOSE_PARENTHESIS) {
	$stackPtr = $tokens[$stackPtr]['parenthesis_opener'];
	}

	$prevNonEmpty = $phpcsFile->findPrevious(Tokens::$emptyTokens, ($stackPtr - 1), null, true);
	if ($prevNonEmpty !== false
	&& isset(self::$extraParenthesesOwners[$tokens[$prevNonEmpty]['code']]) === true
	) {
	return $prevNonEmpty;
	}

	return false;
	}

	/**
	* Check whether the parenthesis owner of an open/close parenthesis is within a limited
	* set of valid owners.
	*
	* @since 1.0.0
	*
	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
	* @param int $stackPtr The position of `T_OPEN/CLOSE_PARENTHESIS` token.
	* @param int\|string\|array<int\|string> $validOwners Array of token constants for the owners
	* which should be considered valid.
	*
	* @return bool `TRUE` if the owner is within the list of `$validOwners`; `FALSE` if not and
	* if the parenthesis does not have a (direct) owner.
	*/
	public static function isOwnerIn(File $phpcsFile, $stackPtr, $validOwners)
	{
	$owner = self::getOwner($phpcsFile, $stackPtr);
	if ($owner === false) {
	return false;
	}

	$tokens = $phpcsFile->getTokens();
	$validOwners = (array) $validOwners;

	return \in_array($tokens[$owner]['code'], $validOwners, true);
	}

	/**
	* Check whether the passed token is nested within parentheses owned by one of the valid owners.
	*
	* @since 1.0.0
	*
	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
	* @param int $stackPtr The position of the token we are checking.
	* @param int\|string\|array<int\|string> $validOwners Array of token constants for the owners
	* which should be considered valid.
	*
	* @return bool
	*/
	public static function hasOwner(File $phpcsFile, $stackPtr, $validOwners)
	{
	return (self::nestedParensWalker($phpcsFile, $stackPtr, $validOwners) !== false);
	}

	/**
	* Retrieve the stack pointer to the parentheses opener of the first (outer) set of parentheses
	* an arbitrary token is wrapped in.
	*
	* If the optional `$validOwners` parameter is passed, the stack pointer to the opener to
	* the first set of parentheses, which has an owner which is in the list of valid owners,
	* will be returned. This may be a nested set of parentheses.
	*
	* @since 1.0.0
	*
	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
	* @param int $stackPtr The position of the token we are checking.
	* @param int\|string\|array<int\|string> $validOwners Array of token constants for the owners
	* which should be considered valid.
	*
	* @return int\|false Integer stack pointer to the parentheses opener; or `FALSE` if the token
	* does not have parentheses owned by any of the valid owners or if
	* the token is not nested in parentheses at all.
	*/
	public static function getFirstOpener(File $phpcsFile, $stackPtr, $validOwners = [])
	{
	return self::nestedParensWalker($phpcsFile, $stackPtr, $validOwners, false);
	}

	/**
	* Retrieve the stack pointer to the parentheses closer of the first (outer) set of parentheses
	* an arbitrary token is wrapped in.
	*
	* If the optional `$validOwners` parameter is passed, the stack pointer to the closer to
	* the first set of parentheses, which has an owner which is in the list of valid owners,
	* will be returned. This may be a nested set of parentheses.
	*
	* @since 1.0.0
	*
	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
	* @param int $stackPtr The position of the token we are checking.
	* @param int\|string\|array<int\|string> $validOwners Array of token constants for the owners
	* which should be considered valid.
	*
	* @return int\|false Integer stack pointer to the parentheses closer; or `FALSE` if the token
	* does not have parentheses owned by any of the valid owners or if
	* the token is not nested in parentheses at all.
	*/
	public static function getFirstCloser(File $phpcsFile, $stackPtr, $validOwners = [])
	{
	$opener = self::getFirstOpener($phpcsFile, $stackPtr, $validOwners);
	$tokens = $phpcsFile->getTokens();
	if ($opener !== false && isset($tokens[$opener]['parenthesis_closer']) === true) {
	return $tokens[$opener]['parenthesis_closer'];
	}

	return false;
	}

	/**
	* Retrieve the stack pointer to the parentheses owner of the first (outer) set of parentheses
	* an arbitrary token is wrapped in.
	*
	* If the optional `$validOwners` parameter is passed, the stack pointer to the owner of
	* the first set of parentheses, which has an owner which is in the list of valid owners,
	* will be returned. This may be a nested set of parentheses.
	*
	* @since 1.0.0
	*
	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
	* @param int $stackPtr The position of the token we are checking.
	* @param int\|string\|array<int\|string> $validOwners Array of token constants for the owners
	* which should be considered valid.
	*
	* @return int\|false Integer stack pointer to the parentheses owner; or `FALSE` if the token
	* does not have parentheses owned by any of the valid owners or if
	* the token is not nested in parentheses at all.
	*/
	public static function getFirstOwner(File $phpcsFile, $stackPtr, $validOwners = [])
	{
	$opener = self::getFirstOpener($phpcsFile, $stackPtr, $validOwners);
	if ($opener !== false) {
	return self::getOwner($phpcsFile, $opener);
	}

	return false;
	}

	/**
	* Retrieve the stack pointer to the parentheses opener of the last (inner) set of parentheses
	* an arbitrary token is wrapped in.
	*
	* If the optional `$validOwners` parameter is passed, the stack pointer to the opener to
	* the last set of parentheses, which has an owner which is in the list of valid owners,
	* will be returned. This may be a set of parentheses higher up.
	*
	* @since 1.0.0
	*
	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
	* @param int $stackPtr The position of the token we are checking.
	* @param int\|string\|array<int\|string> $validOwners Array of token constants for the owners
	* which should be considered valid.
	*
	* @return int\|false Integer stack pointer to the parentheses opener; or `FALSE` if the token
	* does not have parentheses owned by any of the valid owners or if
	* the token is not nested in parentheses at all.
	*/
	public static function getLastOpener(File $phpcsFile, $stackPtr, $validOwners = [])
	{
	return self::nestedParensWalker($phpcsFile, $stackPtr, $validOwners, true);
	}

	/**
	* Retrieve the stack pointer to the parentheses closer of the last (inner) set of parentheses
	* an arbitrary token is wrapped in.
	*
	* If the optional `$validOwners` parameter is passed, the stack pointer to the closer to
	* the last set of parentheses, which has an owner which is in the list of valid owners,
	* will be returned. This may be a set of parentheses higher up.
	*
	* @since 1.0.0
	*
	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
	* @param int $stackPtr The position of the token we are checking.
	* @param int\|string\|array<int\|string> $validOwners Array of token constants for the owners
	* which should be considered valid.
	*
	* @return int\|false Integer stack pointer to the parentheses closer; or `FALSE` if the token
	* does not have parentheses owned by any of the valid owners or if
	* the token is not nested in parentheses at all.
	*/
	public static function getLastCloser(File $phpcsFile, $stackPtr, $validOwners = [])
	{
	$opener = self::getLastOpener($phpcsFile, $stackPtr, $validOwners);
	$tokens = $phpcsFile->getTokens();
	if ($opener !== false && isset($tokens[$opener]['parenthesis_closer']) === true) {
	return $tokens[$opener]['parenthesis_closer'];
	}

	return false;
	}

	/**
	* Retrieve the stack pointer to the parentheses owner of the last (inner) set of parentheses
	* an arbitrary token is wrapped in.
	*
	* If the optional `$validOwners` parameter is passed, the stack pointer to the owner of
	* the last set of parentheses, which has an owner which is in the list of valid owners,
	* will be returned. This may be a set of parentheses higher up.
	*
	* @since 1.0.0
	*
	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
	* @param int $stackPtr The position of the token we are checking.
	* @param int\|string\|array<int\|string> $validOwners Array of token constants for the owners
	* which should be considered valid.
	*
	* @return int\|false Integer stack pointer to the parentheses owner; or `FALSE` if the token
	* does not have parentheses owned by any of the valid owners or if
	* the token is not nested in parentheses at all.
	*/
	public static function getLastOwner(File $phpcsFile, $stackPtr, $validOwners = [])
	{
	$opener = self::getLastOpener($phpcsFile, $stackPtr, $validOwners);
	if ($opener !== false) {
	return self::getOwner($phpcsFile, $opener);
	}

	return false;
	}

	/**
	* Check whether the owner of the outermost wrapping set of parentheses of an arbitrary token
	* is within a limited set of acceptable token types.
	*
	* @since 1.0.0
	*
	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
	* @param int $stackPtr The position in the stack of the
	* token to verify.
	* @param int\|string\|array<int\|string> $validOwners Array of token constants for the owners
	* which should be considered valid.
	*
	* @return int\|false Integer stack pointer to the valid parentheses owner; or `FALSE` if
	* the token was not wrapped in parentheses or if the outermost set
	* of parentheses in which the token is wrapped does not have an owner
	* within the set of owners considered valid.
	*/
	public static function firstOwnerIn(File $phpcsFile, $stackPtr, $validOwners)
	{
	$opener = self::getFirstOpener($phpcsFile, $stackPtr);

	if ($opener !== false && self::isOwnerIn($phpcsFile, $opener, $validOwners) === true) {
	return self::getOwner($phpcsFile, $opener);
	}

	return false;
	}

	/**
	* Check whether the owner of the innermost wrapping set of parentheses of an arbitrary token
	* is within a limited set of acceptable token types.
	*
	* @since 1.0.0
	*
	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
	* @param int $stackPtr The position in the stack of the
	* token to verify.
	* @param int\|string\|array<int\|string> $validOwners Array of token constants for the owners
	* which should be considered valid.
	*
	* @return int\|false Integer stack pointer to the valid parentheses owner; or `FALSE` if
	* the token was not wrapped in parentheses or if the innermost set
	* of parentheses in which the token is wrapped does not have an owner
	* within the set of owners considered valid.
	*/
	public static function lastOwnerIn(File $phpcsFile, $stackPtr, $validOwners)
	{
	$opener = self::getLastOpener($phpcsFile, $stackPtr);

	if ($opener !== false && self::isOwnerIn($phpcsFile, $opener, $validOwners) === true) {
	return self::getOwner($phpcsFile, $opener);
	}

	return false;
	}

	/**
	* Helper method. Retrieve the position of a parentheses opener for an arbitrary passed token.
	*
	* If no `$validOwners` are specified, the opener to the first set of parentheses surrounding
	* the token - or if `$reverse = true`, the last set of parentheses - will be returned.
	*
	* @since 1.0.0
	*
	* @param \PHP_CodeSniffer\Files\File $phpcsFile The file where this token was found.
	* @param int $stackPtr The position of the token we are checking.
	* @param int\|string\|array<int\|string> $validOwners Optional. Array of token constants for the owners
	* which should be considered valid.
	* @param bool $reverse Optional. Whether to search for the first/outermost
	* (`false`) or the last/innermost (`true`) set of
	* parentheses with the specified owner(s).
	*
	* @return int\|false Integer stack pointer to the parentheses opener; or `FALSE` if the token
	* does not have parentheses owned by any of the valid owners or if
	* the token is not nested in parentheses at all.
	*/
	private static function nestedParensWalker(File $phpcsFile, $stackPtr, $validOwners = [], $reverse = false)
	{
	$tokens = $phpcsFile->getTokens();

	// Check for the existence of the token.
	if (isset($tokens[$stackPtr]) === false) {
	return false;
	}

	// Make sure the token is nested in parenthesis.
	if (empty($tokens[$stackPtr]['nested_parenthesis']) === true) {
	return false;
	}

	$validOwners = (array) $validOwners;
	$parentheses = $tokens[$stackPtr]['nested_parenthesis'];

	if (empty($validOwners) === true) {
	// No owners specified, just return the first/last parentheses opener.
	if ($reverse === true) {
	\end($parentheses);
	} else {
	\reset($parentheses);
	}

	return \key($parentheses);
	}

	if ($reverse === true) {
	$parentheses = \array_reverse($parentheses, true);
	}

	foreach ($parentheses as $opener => $closer) {
	if (self::isOwnerIn($phpcsFile, $opener, $validOwners) === true) {
	// We found a token with a valid owner.
	return $opener;
	}
	}

	return false;
	}
	}

File Metadata

Mime Type: text/x-php
Expires: Sat, Oct 3, 23:01 (1 w, 5 d ago)
Storage Engine: local-disk
Storage Format: Raw Data
Storage Handle: e9/8e/a47b8f5bc386aba94b80dae256d1
Default Alt Text: Parentheses.php (18 KB)

Parentheses.phpNo OneTemporaryActions

Parentheses.phpView Options

File Metadata

Event Timeline

Parentheses.php
No OneTemporary
Actions

Parentheses.php
View Options