PHPCSUtils

TextStrings
in package

Utility functions for working with text string tokens.

Tags
since
1.0.0
since
1.0.0-alpha4

Dropped support for PHPCS < 3.7.1.

Table of Contents

START_OF_EMBED  = '`(?<!\\\\)(\\\\{2})*(\\{\\$|\\$\\{|\\$(?=[a-zA-Z_\\x7f-\\xff]))`'
Regex to match the start of an embedded variable/expression.
TYPE1_EMBED_AFTER_DOLLAR  = '`(?P<varname>[a-zA-Z_\\x7f-\\xff][a-zA-Z0-9_\\x7f-\\xff]*)(?:\\??->(?P>varname)|\\[[^\\]\'"\\s]+\\])?`'
Regex to match a "type 1" - directly embedded - variable without the dollar sign.
getCompleteTextString()  : string
Get the complete contents of a - potentially multi-line - text string.
getEmbeds()  : array<int, string>
Get the embedded variables/expressions from an arbitrary string.
getEndOfCompleteTextString()  : int
Get the stack pointer to the end of a - potentially multi-line - text string.
getStripEmbeds()  : array<string, mixed>
Split an arbitrary text string into embedded variables/expressions and remaining text.
stripEmbeds()  : string
Strip embedded variables/expressions from an arbitrary string.
stripQuotes()  : string
Strip text delimiter quotes from an arbitrary text string.

Constants

START_OF_EMBED

Regex to match the start of an embedded variable/expression.

public string START_OF_EMBED = '`(?<!\\\\)(\\\\{2})*(\\{\\$|\\$\\{|\\$(?=[a-zA-Z_\\x7f-\\xff]))`'

Prevents matching escaped variables/expressions.

TYPE1_EMBED_AFTER_DOLLAR

Regex to match a "type 1" - directly embedded - variable without the dollar sign.

public string TYPE1_EMBED_AFTER_DOLLAR = '`(?P<varname>[a-zA-Z_\\x7f-\\xff][a-zA-Z0-9_\\x7f-\\xff]*)(?:\\??->(?P>varname)|\\[[^\\]\'"\\s]+\\])?`'

Allows for array access and property access in as far as supported (single level).

Methods

getCompleteTextString()

Get the complete contents of a - potentially multi-line - text string.

public static getCompleteTextString(File $phpcsFile, int $stackPtr[, bool $stripQuotes = true ]) : string

PHPCS tokenizes multi-line text strings with a single token for each line. This method can be used to retrieve the text string as it would be received and processed in PHP itself.

This method is particularly useful for sniffs which examine the contents of text strings, where the content matching might result in false positives/false negatives if the text were to be examined line by line.

Parameters
$phpcsFile : File

The file where this token was found.

$stackPtr : int

Pointer to the first text string token of a - potentially multi-line - text string or to a Nowdoc/Heredoc opener.

$stripQuotes : bool = true

Optional. Whether to strip text delimiter quotes off the resulting text string. Defaults to true.

Tags
since
1.0.0
throws
RuntimeException

If the specified position is not a valid text string token.

throws
RuntimeException

If the specified token is not the first token in a text string.

Return values
string

The contents of the complete text string.

getEmbeds()

Get the embedded variables/expressions from an arbitrary string.

public static getEmbeds(string $text) : array<int, string>

Note: this function gets the complete variables/expressions as they are embedded, i.e. including potential curly brace wrappers, array access, method calls etc.

Parameters
$text : string

The contents of a T_DOUBLE_QUOTED_STRING or T_HEREDOC token.

Tags
since
1.0.0-alpha4
Return values
array<int, string>

Array of encountered variable names/expressions with the offset at which the variable/expression was found in the string, as the key.

getEndOfCompleteTextString()

Get the stack pointer to the end of a - potentially multi-line - text string.

public static getEndOfCompleteTextString(File $phpcsFile, int $stackPtr) : int
Parameters
$phpcsFile : File

The file where this token was found.

$stackPtr : int

Pointer to the first text string token of a - potentially multi-line - text string or to a Nowdoc/Heredoc opener.

Tags
see
TextStrings::getCompleteTextString()

Retrieve the contents of a complete - potentially multi-line - text string.

since
1.0.0-alpha4
throws
RuntimeException

If the specified position is not a valid text string token.

throws
RuntimeException

If the specified token is not the first token in a text string.

Return values
int

Stack pointer to the last token in the text string.

getStripEmbeds()

Split an arbitrary text string into embedded variables/expressions and remaining text.

public static getStripEmbeds(string $text) : array<string, mixed>

PHP contains four types of embedding syntaxes:

  1. Directly embedding variables ("$foo");
  2. Braces outside the variable ("{$foo}");
  3. Braces after the dollar sign ("${foo}");
  4. Variable variables ("${expr}", equivalent to (string) ${expr}).

Type 3 and 4 are deprecated as of PHP 8.2 and will be removed in PHP 9.0.

This method handles all types of embeds, including recognition of whether an embed is escaped or not.

Parameters
$text : string

The contents of a T_DOUBLE_QUOTED_STRING or T_HEREDOC token.

Tags
link

PHP Manual on string parsing

link

PHP RFC on deprecating select string interpolation syntaxes

since
1.0.0-alpha4
Return values
array<string, mixed>

Array containing two values:

  1. An array containing a string representation of each embed encountered. The keys in this array are the integer offset within the original string where the embed was found.
  2. The textual contents, embeds stripped out of it. The format of the array return value is:
array(
  'embeds'    => array<int, string>,
  'remaining' => string,
)

stripEmbeds()

Strip embedded variables/expressions from an arbitrary string.

public static stripEmbeds(string $text) : string
Parameters
$text : string

The contents of a T_DOUBLE_QUOTED_STRING or T_HEREDOC token.

Tags
since
1.0.0-alpha4
Return values
string

String without variables/expressions in it.

stripQuotes()

Strip text delimiter quotes from an arbitrary text string.

public static stripQuotes(string $textString) : string

Intended for use with the "content" of a T_CONSTANT_ENCAPSED_STRING / T_DOUBLE_QUOTED_STRING.

  • Prevents stripping mis-matched quotes.
  • Prevents stripping quotes from the textual content of the text string.
Parameters
$textString : string

The raw text string.

Tags
since
1.0.0
Return values
string

Text string without quotes around it.

Search results