Parsoid
A bidirectional parser between wikitext and HTML5
Parsoid\Utils\PHPUtils Class Reference

This file contains Parsoid-independent PHP helper functions. More...

Static Public Member Functions

static counterToBase64 (int $n)
 Convert a counter to a Base64 encoded string. More...
 
static getStartHRTime ()
 Return accurate system time. More...
 
static getHRTimeDifferential (float $previousTime)
 Return millisecond accurate system time differential. More...
 
static jsonEncode ( $o)
 json_encode wrapper function More...
 
static jsonDecode (string $str, bool $assoc=true)
 json_decode wrapper function More...
 
static jsSort (array &$a)
 Sort associative array keys the same way that JavaScript would; that is, natural order is preserved BUT integer indices are moved to the front of the array and sorted in order. More...
 
static makeSet (array $a)
 Convert array to associative array usable as a read-only Set. More...
 
static makeMap (array $a)
 PORT-FIXME: To be removed once all uses of this have disappeared Convert array to associative array usable as a key-value Map. More...
 
static lastItem (array $a)
 Helper to get last item of the array. More...
 
static pushArray (array &$dest, array $source)
 Append an array to an accumulator using the most efficient method available. More...
 
static safeSubstr (string $s, int $start, ?int $length=null, bool $checkEntireString=false)
 Return a substring, asserting that it is valid UTF-8. More...
 
static assertValidUTF8 (string $s)
 Helper for verifying a valid UTF-8 encoding. More...
 
static reStrip (string $re, ?string $newDelimiter=null)
 Helper for joining pieces of regular expressions together. More...
 
static encodeURIComponent (string $str)
 JS-compatible encodeURIComponent function FIXME: See T221147 (for a post-port update) More...
 
static coalesce (... $args)
 Simulate the JS || operator. More...
 
static arrayToObject ( $array)
 Convert an array to an object. More...
 
static sortArray (&$array)
 Sort keys in an array, recursively, for better reproducibility. More...
 

Detailed Description

This file contains Parsoid-independent PHP helper functions.

Over time, more functions can be migrated out of various other files here.

Member Function Documentation

◆ arrayToObject()

static Parsoid\Utils\PHPUtils::arrayToObject (   $array)
static

Convert an array to an object.

Workaround for https://bugs.php.net/bug.php?id=78379

PHP 7 introduced "efficient" casting of arrays to objects by taking a reference instead of duplicating the array. However, this was not properly accounted for in the garbage collector. The garbage collector would free the array while it was still referred to by live objects.

The workaround here is to manually duplicate the array. It's not necessary to do a deep copy since only the top-level array is referenced by the new object.

It's only necessary to call this for potentially shared arrays, such as compile-time constants. Arrays that have a reference count of 1 can be cast to objects in the usual way. For example, array literals containing variables are typically unshared.

Parameters
array$array
Returns

◆ assertValidUTF8()

static Parsoid\Utils\PHPUtils::assertValidUTF8 ( string  $s)
static

Helper for verifying a valid UTF-8 encoding.

Using safeSubstr() is a more efficient way of doing this check in most places, where you can assume that the original string was valid UTF-8. This function does a complete traversal of the string, in time proportional to the length of the string.

Parameters
string$sThe string to check.

◆ coalesce()

static Parsoid\Utils\PHPUtils::coalesce (   $args)
static

Simulate the JS || operator.

Parameters
mixed...$args
Returns
mixed

◆ counterToBase64()

static Parsoid\Utils\PHPUtils::counterToBase64 ( int  $n)
static

Convert a counter to a Base64 encoded string.

Padding is stripped. \,+ are replaced with _,- respectively. Warning: Max integer is 2^31 - 1 for bitwise operations.

Parameters
int$n
Returns
string

◆ encodeURIComponent()

static Parsoid\Utils\PHPUtils::encodeURIComponent ( string  $str)
static

JS-compatible encodeURIComponent function FIXME: See T221147 (for a post-port update)

Parameters
string$str
Returns
string

◆ getHRTimeDifferential()

static Parsoid\Utils\PHPUtils::getHRTimeDifferential ( float  $previousTime)
static

Return millisecond accurate system time differential.

Parameters
float$previousTime
Returns
float milliseconds

◆ getStartHRTime()

static Parsoid\Utils\PHPUtils::getStartHRTime ( )
static

Return accurate system time.

Returns
float time in seconds since Jan 1 1970 GMT accurate to the microsecond

◆ jsonDecode()

static Parsoid\Utils\PHPUtils::jsonDecode ( string  $str,
bool  $assoc = true 
)
static

json_decode wrapper function

Parameters
string$strString to decode into the json object
bool$assocControls whether to parse as an an associative array - defaults to true
Returns
mixed

◆ jsonEncode()

static Parsoid\Utils\PHPUtils::jsonEncode (   $o)
static

json_encode wrapper function

  • unscapes slashes and unicode
Parameters
mixed$o
Returns
string

◆ jsSort()

static Parsoid\Utils\PHPUtils::jsSort ( array &  $a)
static

Sort associative array keys the same way that JavaScript would; that is, natural order is preserved BUT integer indices are moved to the front of the array and sorted in order.

See also
https://2ality.com/2015/10/property-traversal-order-es6.html
Parameters
array&$aArray to sort.

◆ lastItem()

static Parsoid\Utils\PHPUtils::lastItem ( array  $a)
static

Helper to get last item of the array.

Parameters
mixed[]$a
Returns
mixed

◆ makeMap()

static Parsoid\Utils\PHPUtils::makeMap ( array  $a)
static

PORT-FIXME: To be removed once all uses of this have disappeared Convert array to associative array usable as a key-value Map.

Instead of

$var = PHPUtils::makeMap( [
    [ 'key1', 'value1' ],
    [ 'key2', 'value2' ],
] );

just do

$var = [
    'key1' => 'value1',
    'key2' => 'value2',
];

Unlike JS objects, PHP's associative arrays already preserve order.

Parameters
array$a
Returns
array

◆ makeSet()

static Parsoid\Utils\PHPUtils::makeSet ( array  $a)
static

Convert array to associative array usable as a read-only Set.

Parameters
array$a
Returns
array

◆ pushArray()

static Parsoid\Utils\PHPUtils::pushArray ( array &  $dest,
array  $source 
)
static

Append an array to an accumulator using the most efficient method available.

Makes sure that accumulation is O(n).

Parameters
array&$destDestination array
array$sourceArray to merge

◆ reStrip()

static Parsoid\Utils\PHPUtils::reStrip ( string  $re,
?string  $newDelimiter = null 
)
static

Helper for joining pieces of regular expressions together.

This safely strips delimiters from regular expression strings, while ensuring that the result is safely escaped for the new delimiter you plan to use (see the $delimiter argument to preg_quote). Note that using a meta-character for the new delimiter can lead to unexpected results; for example, if you use ! then escaping (?!foo) will break the regular expression.

Parameters
string$reThe regular expression to strip
string | null$newDelimiterOptional delimiter which will be used when recomposing this stripped regular expression into a new regular expression.
Returns
string The regular expression without delimiters or flags

◆ safeSubstr()

static Parsoid\Utils\PHPUtils::safeSubstr ( string  $s,
int  $start,
?int  $length = null,
bool  $checkEntireString = false 
)
static

Return a substring, asserting that it is valid UTF-8.

By default we assume the full string was valid UTF-8, which allows us to look at the first and last bytes to make this check. You can check the entire string if you are feeling paranoid; it will take O(N) time (where N is the length of the substring) but so does the substring operation.

If the substring would start beyond the end of the string or end before the start of the string, then this function will return the empty string (as would JavaScript); note that the native substr would return false in this case.

Using this helper instead of native substr is useful during the PHP port to verify that we don't break up Unicode codepoints by the switch from JavaScript UCS-2 offsets to PHP UTF-8 byte offsets.

Parameters
string$sThe (sub)string to check
int$startThe starting offset (in bytes). If negative, the offset is counted from the end of the string.
int | null$length(optional) The maximum length of the returned string. If negative, the end position is counted from the end of the string.
bool$checkEntireStringWhether to do a slower verification of the entire string, not just the edges. Defaults to false.
Returns
string The checked substring

◆ sortArray()

static Parsoid\Utils\PHPUtils::sortArray ( $array)
static

Sort keys in an array, recursively, for better reproducibility.

(This is especially useful before serializing as JSON.)

Parameters
mixed&$array

The documentation for this class was generated from the following file: