StringUtils.php

Go to the documentation of this file.

<?php
 
namespace Wikimedia\StringUtils;
 
use ArrayIterator;
use InvalidArgumentException;
use Wikimedia\Assert\Assert;
use Wikimedia\UnpackFailedException;
 
class StringUtils {
    public static function isUtf8( $value ) {
        return mb_check_encoding( (string)$value, 'UTF-8' );
    }
 
    public static function delimiterExplode( $startDelim, $endDelim, $separator,
        $subject, $nested = false ) {
        $inputPos = 0;
        $lastPos = 0;
        $depth = 0;
        $encStart = preg_quote( $startDelim, '!' );
        $encEnd = preg_quote( $endDelim, '!' );
        $encSep = preg_quote( $separator, '!' );
        $len = strlen( $subject );
        $m = [];
        $exploded = [];
        while (
            $inputPos < $len &&
            preg_match(
                "!$encStart|$encEnd|$encSep!S", $subject, $m,
                PREG_OFFSET_CAPTURE, $inputPos
            )
        ) {
            $match = $m[0][0];
            $matchPos = $m[0][1];
            $inputPos = $matchPos + strlen( $match );
            if ( $match === $separator ) {
                if ( $depth === 0 ) {
                    $exploded[] = substr(
                        $subject, $lastPos, $matchPos - $lastPos
                    );
                    $lastPos = $inputPos;
                }
            } elseif ( $match === $startDelim ) {
                if ( $depth === 0 || $nested ) {
                    $depth++;
                }
            } else {
                $depth--;
            }
        }
        $exploded[] = substr( $subject, $lastPos );
        // This method could be rewritten in the future to avoid creating an
        // intermediate array, since the return type is just an iterator.
        return new ArrayIterator( $exploded );
    }
 
    public static function hungryDelimiterReplace( $startDelim, $endDelim, $replace, $subject ) {
        $segments = explode( $startDelim, $subject );
        $output = array_shift( $segments );
        foreach ( $segments as $s ) {
            $endDelimPos = strpos( $s, $endDelim );
            if ( $endDelimPos === false ) {
                $output .= $startDelim . $s;
            } else {
                $output .= $replace . substr( $s, $endDelimPos + strlen( $endDelim ) );
            }
        }
 
        return $output;
    }
 
    private static function delimiterReplaceCallback( $startDelim, $endDelim, $callback,
        $subject, $flags = ''
    ) {
        $inputPos = 0;
        $outputPos = 0;
        $contentPos = 0;
        $output = '';
        $foundStart = false;
        $encStart = preg_quote( $startDelim, '!' );
        $encEnd = preg_quote( $endDelim, '!' );
        $strcmp = !str_contains( $flags, 'i' ) ? 'strcmp' : 'strcasecmp';
        $endLength = strlen( $endDelim );
        $m = [];
 
        while ( $inputPos < strlen( $subject ) &&
            preg_match( "!($encStart)|($encEnd)!S$flags", $subject, $m, PREG_OFFSET_CAPTURE, $inputPos )
        ) {
            $tokenOffset = $m[0][1];
            if ( $m[1][0] != '' ) {
                if ( $foundStart &&
                    $strcmp( $endDelim, substr( $subject, $tokenOffset, $endLength ) ) == 0
                ) {
                    # An end match is present at the same location
                    $tokenType = 'end';
                    $tokenLength = $endLength;
                } else {
                    $tokenType = 'start';
                    $tokenLength = strlen( $m[0][0] );
                }
            } elseif ( $m[2][0] != '' ) {
                $tokenType = 'end';
                $tokenLength = strlen( $m[0][0] );
            } else {
                throw new InvalidArgumentException( 'Invalid delimiter given to ' . __METHOD__ );
            }
 
            if ( $tokenType == 'start' ) {
                # Only move the start position if we haven't already found a start
                # This means that START START END matches outer pair
                if ( !$foundStart ) {
                    # Found start
                    $inputPos = $tokenOffset + $tokenLength;
                    # Write out the non-matching section
                    $output .= substr( $subject, $outputPos, $tokenOffset - $outputPos );
                    $outputPos = $tokenOffset;
                    $contentPos = $inputPos;
                    $foundStart = true;
                } else {
                    # Move the input position past the *first character* of START,
                    # to protect against missing END when it overlaps with START
                    $inputPos = $tokenOffset + 1;
                }
            } elseif ( $tokenType == 'end' ) {
                if ( $foundStart ) {
                    # Found match
                    $output .= $callback( [
                        substr( $subject, $outputPos, $tokenOffset + $tokenLength - $outputPos ),
                        substr( $subject, $contentPos, $tokenOffset - $contentPos )
                    ] );
                    $foundStart = false;
                } else {
                    # Non-matching end, write it out
                    $output .= substr( $subject, $inputPos, $tokenOffset + $tokenLength - $outputPos );
                }
                $inputPos = $outputPos = $tokenOffset + $tokenLength;
            } else {
                throw new InvalidArgumentException( 'Invalid delimiter given to ' . __METHOD__ );
            }
        }
        if ( $outputPos < strlen( $subject ) ) {
            $output .= substr( $subject, $outputPos );
        }
 
        return $output;
    }
 
    public static function delimiterReplace(
        $startDelim, $endDelim, $replace, $subject, $flags = ''
    ) {
        return self::delimiterReplaceCallback(
            $startDelim, $endDelim,
            static function ( array $matches ) use ( $replace ) {
                return strtr( $replace, [ '$0' => $matches[0], '$1' => $matches[1] ] );
            },
            $subject, $flags
        );
    }
 
    public static function replaceMarkup( $search, $replace, $text ) {
        $placeholder = "\x00";
 
        // Remove placeholder instances
        $text = str_replace( $placeholder, '', $text );
 
        // Replace instances of the separator inside HTML-like tags with the placeholder
        $cleaned = self::delimiterReplaceCallback(
            '<', '>',
            static function ( array $matches ) use ( $search, $placeholder ) {
                return str_replace( $search, $placeholder, $matches[0] );
            },
            $text
        );
 
        // Explode, then put the replaced separators back in
        $cleaned = str_replace( $search, $replace, $cleaned );
        $text = str_replace( $placeholder, $search, $cleaned );
 
        return $text;
    }
 
    public static function isValidPCRERegex( $string ) {
        // @phan-suppress-next-line PhanParamSuspiciousOrder False positive
        return @preg_match( $string, '' ) !== false; // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged
    }
 
    public static function escapeRegexReplacement( $string ) {
        $string = str_replace( '\\', '\\\\', $string );
        return str_replace( '$', '\\$', $string );
    }
 
    public static function explode( $separator, $subject ) {
        if ( substr_count( $subject, $separator ) > 1000 ) {
            return new ExplodeIterator( $separator, $subject );
        } else {
            return new ArrayIterator( explode( $separator, $subject ) );
        }
    }
 
    public static function unpack( string $format, string $data, $length = false ): array {
        Assert::parameterType( [ 'integer', 'false' ], $length, '$length' );
        if ( $length !== false ) {
            $realLen = strlen( $data );
            if ( $realLen < $length ) {
                throw new UnpackFailedException( "Tried to unpack a "
                    . "string of length $realLen, but needed one "
                    . "of at least length $length."
                );
            }
        }
 
        // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged
        $result = @unpack( $format, $data );
 
        if ( $result === false ) {
            // If it cannot extract the packed data.
            throw new UnpackFailedException( "unpack could not unpack binary data" );
        }
        return $result;
    }
}
 
class_alias( StringUtils::class, 'StringUtils' );