vendor/contao/core-bundle/src/Resources/contao/library/Contao/StringUtil.php line 253

Open in your IDE?
  1. <?php
  3. /*
  4.  * This file is part of Contao.
  5.  *
  6.  * (c) Leo Feyer
  7.  *
  8.  * @license LGPL-3.0-or-later
  9.  */
  11. namespace Contao;
  13. use Symfony\Component\Filesystem\Path;
  15. /**
  16.  * Provides string manipulation methods
  17.  *
  18.  * Usage:
  19.  *
  20.  *     $short = StringUtil::substr($str, 32);
  21.  *     $html  = StringUtil::substrHtml($str, 32);
  22.  *     $decoded = StringUtil::decodeEntities($str);
  23.  */
  24. class StringUtil
  25. {
  26.     /**
  27.      * Shorten a string to a given number of characters
  28.      *
  29.      * The function preserves words, so the result might be a bit shorter or
  30.      * longer than the number of characters given. It strips all tags.
  31.      *
  32.      * @param string  $strString        The string to shorten
  33.      * @param integer $intNumberOfChars The target number of characters
  34.      * @param string  $strEllipsis      An optional ellipsis to append to the shortened string
  35.      *
  36.      * @return string The shortened string
  37.      */
  38.     public static function substr($strString, $intNumberOfChars, $strEllipsis=' …')
  39.     {
  40.         $strString = preg_replace('/[\t\n\r]+/', ' ', $strString);
  41.         $strString = strip_tags($strString);
  43.         if (mb_strlen($strString) <= $intNumberOfChars)
  44.         {
  45.             return $strString;
  46.         }
  48.         $intCharCount = 0;
  49.         $arrWords = array();
  50.         $arrChunks = preg_split('/\s+/', $strString);
  52.         foreach ($arrChunks as $strChunk)
  53.         {
  54.             $intCharCount += mb_strlen(static::decodeEntities($strChunk));
  56.             if ($intCharCount++ <= $intNumberOfChars)
  57.             {
  58.                 $arrWords[] = $strChunk;
  59.                 continue;
  60.             }
  62.             // If the first word is longer than $intNumberOfChars already, shorten it
  63.             // with mb_substr() so the method does not return an empty string.
  64.             if (empty($arrWords))
  65.             {
  66.                 $arrWords[] = mb_substr($strChunk, 0, $intNumberOfChars);
  67.             }
  69.             break;
  70.         }
  72.         if ($strEllipsis === false)
  73.         {
  74.             trigger_deprecation('contao/core-bundle', '4.0', 'Passing "false" as third argument to "Contao\StringUtil::substr()" has been deprecated and will no longer work in Contao 5.0. Pass an empty string instead.');
  75.             $strEllipsis = '';
  76.         }
  78.         // Deprecated since Contao 4.0, to be removed in Contao 5.0
  79.         if ($strEllipsis === true)
  80.         {
  81.             trigger_deprecation('contao/core-bundle', '4.0', 'Passing "true" as third argument to "Contao\StringUtil::substr()" has been deprecated and will no longer work in Contao 5.0. Pass the ellipsis string instead.');
  82.             $strEllipsis = ' …';
  83.         }
  85.         return implode(' ', $arrWords) . $strEllipsis;
  86.     }
  88.     /**
  89.      * Shorten an HTML string to a given number of characters
  90.      *
  91.      * The function preserves words, so the result might be a bit shorter or
  92.      * longer than the number of characters given. It preserves allowed tags.
  93.      *
  94.      * @param string  $strString        The string to shorten
  95.      * @param integer $intNumberOfChars The target number of characters
  96.      *
  97.      * @return string The shortened HTML string
  98.      */
  99.     public static function substrHtml($strString, $intNumberOfChars)
  100.     {
  101.         $strReturn = '';
  102.         $intCharCount = 0;
  103.         $arrOpenTags = array();
  104.         $arrTagBuffer = array();
  105.         $arrEmptyTags = array('area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr');
  107.         $strString = preg_replace('/[\t\n\r]+/', ' ', $strString);
  108.         $strString = strip_tags($strString, Config::get('allowedTags'));
  109.         $strString = preg_replace('/ +/', ' ', $strString);
  111.         // Separate tags and text
  112.         $arrChunks = preg_split('/(<[^>]+>)/', $strString, -1, PREG_SPLIT_DELIM_CAPTURE|PREG_SPLIT_NO_EMPTY);
  114.         for ($i=0, $c=\count($arrChunks); $i<$c; $i++)
  115.         {
  116.             // Buffer tags to include them later
  117.             if (preg_match('/<([^>]+)>/', $arrChunks[$i]))
  118.             {
  119.                 $arrTagBuffer[] = $arrChunks[$i];
  120.                 continue;
  121.             }
  123.             $buffer = $arrChunks[$i];
  125.             // Get the substring of the current text
  126.             if (!$arrChunks[$i] = static::substr($arrChunks[$i], ($intNumberOfChars - $intCharCount), false))
  127.             {
  128.                 break;
  129.             }
  131.             $blnModified = ($buffer !== $arrChunks[$i]);
  132.             $intCharCount += mb_strlen(static::decodeEntities($arrChunks[$i]));
  134.             if ($intCharCount <= $intNumberOfChars)
  135.             {
  136.                 foreach ($arrTagBuffer as $strTag)
  137.                 {
  138.                     $strTagName = strtolower(trim($strTag));
  140.                     // Extract the tag name (see #5669)
  141.                     if (($pos = strpos($strTagName, ' ')) !== false)
  142.                     {
  143.                         $strTagName = substr($strTagName, 1, $pos - 1);
  144.                     }
  145.                     else
  146.                     {
  147.                         $strTagName = substr($strTagName, 1, -1);
  148.                     }
  150.                     // Skip empty tags
  151.                     if (\in_array($strTagName, $arrEmptyTags))
  152.                     {
  153.                         continue;
  154.                     }
  156.                     // Store opening tags in the open_tags array
  157.                     if (strncmp($strTagName, '/', 1) !== 0)
  158.                     {
  159.                         if ($i<$c || !empty($arrChunks[$i]))
  160.                         {
  161.                             $arrOpenTags[] = $strTagName;
  162.                         }
  164.                         continue;
  165.                     }
  167.                     // Closing tags will be removed from the "open tags" array
  168.                     if ($i<$c || !empty($arrChunks[$i]))
  169.                     {
  170.                         $arrOpenTags = array_values($arrOpenTags);
  172.                         for ($j=\count($arrOpenTags)-1; $j>=0; $j--)
  173.                         {
  174.                             if ($strTagName == '/' . $arrOpenTags[$j])
  175.                             {
  176.                                 unset($arrOpenTags[$j]);
  177.                                 break;
  178.                             }
  179.                         }
  180.                     }
  181.                 }
  183.                 // If the current chunk contains text, add tags and text to the return string
  184.                 if ($i<$c || \strlen($arrChunks[$i]))
  185.                 {
  186.                     $strReturn .= implode('', $arrTagBuffer) . $arrChunks[$i];
  187.                 }
  189.                 // Stop after the first shortened chunk (see #7311)
  190.                 if ($blnModified)
  191.                 {
  192.                     break;
  193.                 }
  195.                 $arrTagBuffer = array();
  196.                 continue;
  197.             }
  199.             break;
  200.         }
  202.         // Close all remaining open tags
  203.         krsort($arrOpenTags);
  205.         foreach ($arrOpenTags as $strTag)
  206.         {
  207.             $strReturn .= '</' . $strTag . '>';
  208.         }
  210.         return trim($strReturn);
  211.     }
  213.     /**
  214.      * Decode all entities
  215.      *
  216.      * @param mixed   $strString     The string to decode
  217.      * @param integer $strQuoteStyle The quote style (defaults to ENT_QUOTES)
  218.      * @param string  $strCharset    An optional charset
  219.      *
  220.      * @return string The decoded string
  221.      */
  222.     public static function decodeEntities($strString, $strQuoteStyle=ENT_QUOTES, $strCharset=null)
  223.     {
  224.         if ((string) $strString === '')
  225.         {
  226.             return '';
  227.         }
  229.         if ($strCharset === null)
  230.         {
  231.             $strCharset = 'UTF-8';
  232.         }
  233.         else
  234.         {
  235.             trigger_deprecation('contao/core-bundle', '4.13', 'Passing a charset to StringUtil::decodeEntities() has been deprecated and will no longer work in Contao 5.0. Always use UTF-8 instead.');
  236.         }
  238.         $strString = preg_replace('/(&#*\w+)[\x00-\x20]+;/i', '$1;', $strString);
  239.         $strString = preg_replace('/(&#x*)([0-9a-f]+);/i', '$1$2;', $strString);
  241.         return html_entity_decode($strString, $strQuoteStyle | ENT_SUBSTITUTE | ENT_HTML5, $strCharset);
  242.     }
  244.     /**
  245.      * Restore basic entities
  246.      *
  247.      * @param string|array $strBuffer The string with the tags to be replaced
  248.      *
  249.      * @return string|array The string with the original entities
  250.      */
  251.     public static function restoreBasicEntities($strBuffer)
  252.     {
  253.         return str_replace(array('[&]', '[&amp;]', '[lt]', '[gt]', '[nbsp]', '[-]'), array('&amp;', '&amp;', '&lt;', '&gt;', '&nbsp;', '&shy;'), $strBuffer);
  254.     }
  256.     /**
  257.      * Generate an alias from a string
  258.      *
  259.      * @param string $strString The string
  260.      *
  261.      * @return string The alias
  262.      */
  263.     public static function generateAlias($strString)
  264.     {
  265.         $strString = static::decodeEntities($strString);
  266.         $strString = static::restoreBasicEntities($strString);
  267.         $strString = static::standardize(strip_tags($strString));
  269.         // Remove the prefix if the alias is not numeric (see #707)
  270.         if (strncmp($strString, 'id-', 3) === 0 && !is_numeric($strSubstr = substr($strString, 3)))
  271.         {
  272.             $strString = $strSubstr;
  273.         }
  275.         return $strString;
  276.     }
  278.     /**
  279.      * Prepare a slug
  280.      *
  281.      * @param string $strSlug The slug
  282.      *
  283.      * @return string
  284.      */
  285.     public static function prepareSlug($strSlug)
  286.     {
  287.         $strSlug = static::stripInsertTags($strSlug);
  288.         $strSlug = static::restoreBasicEntities($strSlug);
  289.         $strSlug = static::decodeEntities($strSlug);
  291.         return $strSlug;
  292.     }
  294.     /**
  295.      * Censor a single word or an array of words within a string
  296.      *
  297.      * @param string $strString  The string to censor
  298.      * @param mixed  $varWords   A string or array or words to replace
  299.      * @param string $strReplace An optional replacement string
  300.      *
  301.      * @return string The cleaned string
  302.      */
  303.     public static function censor($strString, $varWords, $strReplace='')
  304.     {
  305.         foreach ((array) $varWords as $strWord)
  306.         {
  307.             $strString = preg_replace('/\b(' . str_replace('\*', '\w*?', preg_quote($strWord, '/')) . ')\b/i', $strReplace, $strString);
  308.         }
  310.         return $strString;
  311.     }
  313.     /**
  314.      * Encode all e-mail addresses within a string
  315.      *
  316.      * @param string $strString The string to encode
  317.      *
  318.      * @return string The encoded string
  319.      */
  320.     public static function encodeEmail($strString)
  321.     {
  322.         if (strpos($strString, '@') === false)
  323.         {
  324.             return $strString;
  325.         }
  327.         $arrEmails = static::extractEmail($strString, Config::get('allowedTags'));
  329.         foreach ($arrEmails as $strEmail)
  330.         {
  331.             $strEncoded = '';
  332.             $arrCharacters = mb_str_split($strEmail);
  334.             foreach ($arrCharacters as $index => $strCharacter)
  335.             {
  336.                 $strEncoded .= sprintf(($index % 2) ? '&#x%X;' : '&#%s;', mb_ord($strCharacter));
  337.             }
  339.             $strString = str_replace($strEmail, $strEncoded, $strString);
  340.         }
  342.         return str_replace('mailto:', '&#109;&#97;&#105;&#108;&#116;&#111;&#58;', $strString);
  343.     }
  345.     /**
  346.      * Extract all e-mail addresses from a string
  347.      *
  348.      * @param string $strString      The string
  349.      * @param string $strAllowedTags A list of allowed HTML tags
  350.      *
  351.      * @return array The e-mail addresses
  352.      */
  353.     public static function extractEmail($strString, $strAllowedTags='')
  354.     {
  355.         $arrEmails = array();
  357.         if (strpos($strString, '@') === false)
  358.         {
  359.             return $arrEmails;
  360.         }
  362.         // Find all mailto: addresses
  363.         preg_match_all('/mailto:(?:[^\x00-\x20\x22\x40\x7F]{1,64}+|\x22[^\x00-\x1F\x7F]{1,64}?\x22)@(?:\[(?:IPv)?[a-f0-9.:]{1,47}]|[\w.-]{1,252}\.[a-z]{2,63}\b)/u', $strString, $matches);
  365.         foreach ($matches[0] as &$strEmail)
  366.         {
  367.             $strEmail = str_replace('mailto:', '', $strEmail);
  369.             if (Validator::isEmail($strEmail))
  370.             {
  371.                 $arrEmails[] = $strEmail;
  372.             }
  373.         }
  375.         unset($strEmail);
  377.         // Encode opening arrow brackets (see #3998)
  378.         $strString = preg_replace_callback('@</?([^\s<>/]*)@', static function ($matches) use ($strAllowedTags)
  379.         {
  380.             if (!$matches[1] || stripos($strAllowedTags, '<' . strtolower($matches[1]) . '>') === false)
  381.             {
  382.                 $matches[0] = str_replace('<', '&lt;', $matches[0]);
  383.             }
  385.             return $matches[0];
  386.         }, $strString);
  388.         // Find all addresses in the plain text
  389.         preg_match_all('/(?:[^\x00-\x20\x22\x40\x7F]{1,64}|\x22[^\x00-\x1F\x7F]{1,64}?\x22)@(?:\[(?:IPv)?[a-f0-9.:]{1,47}]|[\w.-]{1,252}\.[a-z]{2,63}\b)/u', strip_tags($strString), $matches);
  391.         foreach ($matches[0] as &$strEmail)
  392.         {
  393.             $strEmail = str_replace('&lt;', '<', $strEmail);
  395.             if (Validator::isEmail($strEmail))
  396.             {
  397.                 $arrEmails[] = $strEmail;
  398.             }
  399.         }
  401.         return array_unique($arrEmails);
  402.     }
  404.     /**
  405.      * Split a friendly-name e-mail address and return name and e-mail as array
  406.      *
  407.      * @param string $strEmail A friendly-name e-mail address
  408.      *
  409.      * @return array An array with name and e-mail address
  410.      */
  411.     public static function splitFriendlyEmail($strEmail)
  412.     {
  413.         if (strpos($strEmail, '<') !== false)
  414.         {
  415.             return array_map('trim', explode(' <', str_replace('>', '', $strEmail)));
  416.         }
  418.         if (strpos($strEmail, '[') !== false)
  419.         {
  420.             return array_map('trim', explode(' [', str_replace(']', '', $strEmail)));
  421.         }
  423.         return array('', $strEmail);
  424.     }
  426.     /**
  427.      * Wrap words after a particular number of characers
  428.      *
  429.      * @param string  $strString The string to wrap
  430.      * @param integer $strLength The number of characters to wrap after
  431.      * @param string  $strBreak  An optional break character
  432.      *
  433.      * @return string The wrapped string
  434.      */
  435.     public static function wordWrap($strString, $strLength=75, $strBreak="\n")
  436.     {
  437.         return wordwrap($strString, $strLength, $strBreak);
  438.     }
  440.     /**
  441.      * Highlight a phrase within a string
  442.      *
  443.      * @param string $strString     The string
  444.      * @param string $strPhrase     The phrase to highlight
  445.      * @param string $strOpeningTag The opening tag (defaults to <strong>)
  446.      * @param string $strClosingTag The closing tag (defaults to </strong>)
  447.      *
  448.      * @return string The highlighted string
  449.      */
  450.     public static function highlight($strString, $strPhrase, $strOpeningTag='<strong>', $strClosingTag='</strong>')
  451.     {
  452.         if (!$strString || !$strPhrase)
  453.         {
  454.             return $strString;
  455.         }
  457.         return preg_replace('/(' . preg_quote($strPhrase, '/') . ')/i', $strOpeningTag . '\\1' . $strClosingTag, $strString);
  458.     }
  460.     /**
  461.      * Split a string of comma separated values
  462.      *
  463.      * @param string $strString    The string to split
  464.      * @param string $strDelimiter An optional delimiter
  465.      *
  466.      * @return array The string chunks
  467.      */
  468.     public static function splitCsv($strString, $strDelimiter=',')
  469.     {
  470.         $arrValues = preg_split('/' . $strDelimiter . '(?=(?:[^"]*"[^"]*")*(?![^"]*"))/', $strString);
  472.         foreach ($arrValues as $k=>$v)
  473.         {
  474.             $arrValues[$k] = trim($v, ' "');
  475.         }
  477.         return $arrValues;
  478.     }
  480.     /**
  481.      * Convert a string to XHTML
  482.      *
  483.      * @param string $strString The HTML5 string
  484.      *
  485.      * @return string The XHTML string
  486.      *
  487.      * @deprecated Deprecated since Contao 4.9, to be removed in Contao 5.0
  488.      */
  489.     public static function toXhtml($strString)
  490.     {
  491.         trigger_deprecation('contao/core-bundle', '4.9', 'The "StringUtil::toXhtml()" method has been deprecated and will no longer work in Contao 5.0.');
  493.         $arrPregReplace = array
  494.         (
  495.             '/<(br|hr|img)([^>]*)>/i' => '<$1$2 />', // Close stand-alone tags
  496.             '/ border="[^"]*"/'       => ''          // Remove deprecated attributes
  497.         );
  499.         $arrStrReplace = array
  500.         (
  501.             '/ />'             => ' />',        // Fix incorrectly closed tags
  502.             '<b>'              => '<strong>',   // Replace <b> with <strong>
  503.             '</b>'             => '</strong>',
  504.             '<i>'              => '<em>',       // Replace <i> with <em>
  505.             '</i>'             => '</em>',
  506.             '<u>'              => '<span style="text-decoration:underline">',
  507.             '</u>'             => '</span>',
  508.             ' target="_self"'  => '',
  509.             ' target="_blank"' => ' onclick="return !window.open(this.href)"'
  510.         );
  512.         $strString = preg_replace(array_keys($arrPregReplace), $arrPregReplace, $strString);
  513.         $strString = str_ireplace(array_keys($arrStrReplace), $arrStrReplace, $strString);
  515.         return $strString;
  516.     }
  518.     /**
  519.      * Convert a string to HTML5
  520.      *
  521.      * @param string $strString The XHTML string
  522.      *
  523.      * @return string The HTML5 string
  524.      *
  525.      * @deprecated Deprecated since Contao 4.13, to be removed in Contao 5.0
  526.      */
  527.     public static function toHtml5($strString)
  528.     {
  529.         trigger_deprecation('contao/core-bundle', '4.13', 'The "StringUtil::toHtml5()" method has been deprecated and will no longer work in Contao 5.0.');
  531.         $arrPregReplace = array
  532.         (
  533.             '/<(br|hr|img)([^>]*) \/>/i'                  => '<$1$2>',             // Close stand-alone tags
  534.             '/ (cellpadding|cellspacing|border)="[^"]*"/' => '',                   // Remove deprecated attributes
  535.             '/ rel="lightbox(\[([^\]]+)\])?"/'            => ' data-lightbox="$2"' // see #4073
  536.         );
  538.         $arrStrReplace = array
  539.         (
  540.             '<u>'                                              => '<span style="text-decoration:underline">',
  541.             '</u>'                                             => '</span>',
  542.             ' target="_self"'                                  => '',
  543.             ' onclick="window.open(this.href); return false"'  => ' target="_blank"',
  544.             ' onclick="window.open(this.href);return false"'   => ' target="_blank"',
  545.             ' onclick="window.open(this.href); return false;"' => ' target="_blank"'
  546.         );
  548.         $strString = preg_replace(array_keys($arrPregReplace), $arrPregReplace, $strString);
  549.         $strString = str_ireplace(array_keys($arrStrReplace), $arrStrReplace, $strString);
  551.         return $strString;
  552.     }
  554.     /**
  555.      * Parse simple tokens
  556.      *
  557.      * @param string $strString    The string to be parsed
  558.      * @param array  $arrData      The replacement data
  559.      * @param array  $blnAllowHtml Whether HTML should be decoded inside conditions
  560.      *
  561.      * @return string The converted string
  562.      *
  563.      * @throws \RuntimeException         If $strString cannot be parsed
  564.      * @throws \InvalidArgumentException If there are incorrectly formatted if-tags
  565.      *
  566.      * @deprecated Deprecated since Contao 4.10, to be removed in Contao 5.
  567.      *             Use the contao.string.simple_token_parser service instead.
  568.      */
  569.     public static function parseSimpleTokens($strString, $arrData, $blnAllowHtml = true)
  570.     {
  571.         trigger_deprecation('contao/core-bundle', '4.10', 'Using "Contao\StringUtil::parseSimpleTokens()" has been deprecated and will no longer work in Contao 5.0. Use the "contao.string.simple_token_parser" service instead.');
  573.         return System::getContainer()->get('contao.string.simple_token_parser')->parse($strString, $arrData, $blnAllowHtml);
  574.     }
  576.     /**
  577.      * Convert a UUID string to binary data
  578.      *
  579.      * @param string $uuid The UUID string
  580.      *
  581.      * @return string The binary data
  582.      */
  583.     public static function uuidToBin($uuid)
  584.     {
  585.         return hex2bin(str_replace('-', '', $uuid));
  586.     }
  588.     /**
  589.      * Get a UUID string from binary data
  590.      *
  591.      * @param string $data The binary data
  592.      *
  593.      * @return string The UUID string
  594.      */
  595.     public static function binToUuid($data)
  596.     {
  597.         return implode('-', unpack('H8time_low/H4time_mid/H4time_high/H4clock_seq/H12node', $data));
  598.     }
  600.     /**
  601.      * Encode a string with Crockford’s Base32 (0123456789ABCDEFGHJKMNPQRSTVWXYZ)
  602.      *
  603.      * @see StringUtil::decodeBase32()
  604.      */
  605.     public static function encodeBase32(string $bytes): string
  606.     {
  607.         $result = array();
  609.         foreach (str_split($bytes, 5) as $chunk)
  610.         {
  611.             $result[] = substr(
  612.                 str_pad(
  613.                     strtr(
  614.                         base_convert(bin2hex(str_pad($chunk, 5, "\0")), 16, 32),
  615.                         'ijklmnopqrstuv',
  616.                         'jkmnpqrstvwxyz', // Crockford's Base32
  617.                     ),
  618.                     8,
  619.                     '0',
  620.                     STR_PAD_LEFT,
  621.                 ),
  622.                 0,
  623.                 (int) ceil(\strlen($chunk) * 8 / 5),
  624.             );
  625.         }
  627.         return strtoupper(implode('', $result));
  628.     }
  630.     /**
  631.      * Decode a Crockford’s Base32 encoded string
  632.      *
  633.      * Uppercase and lowercase letters are supported. Letters O and o are
  634.      * interpreted as 0. Letters I, i, L and l are interpreted as 1.
  635.      *
  636.      * @see StringUtil::encodeBase32()
  637.      */
  638.     public static function decodeBase32(string $base32String): string
  639.     {
  640.         if (1 !== preg_match('/^[0-9a-tv-z]*$/i', $base32String))
  641.         {
  642.             throw new \InvalidArgumentException('Base32 string must only consist of digits and letters except "U"');
  643.         }
  645.         $result = array();
  647.         foreach (str_split($base32String, 8) as $chunk)
  648.         {
  649.             $result[] = substr(
  650.                 hex2bin(
  651.                     str_pad(
  652.                         base_convert(
  653.                             strtr(
  654.                                 str_pad(strtolower($chunk), 8, '0'),
  655.                                 'oiljkmnpqrstvwxyz', // Crockford's Base32
  656.                                 '011ijklmnopqrstuv',
  657.                             ),
  658.                             32,
  659.                             16,
  660.                         ),
  661.                         10,
  662.                         '0',
  663.                         STR_PAD_LEFT,
  664.                     ),
  665.                 ),
  666.                 0,
  667.                 (int) floor(\strlen($chunk) * 5 / 8),
  668.             );
  669.         }
  671.         return implode('', $result);
  672.     }
  674.     /**
  675.      * Convert file paths inside "src" attributes to insert tags
  676.      *
  677.      * @param string $data The markup string
  678.      *
  679.      * @return string The markup with file paths converted to insert tags
  680.      */
  681.     public static function srcToInsertTag($data)
  682.     {
  683.         $return = '';
  684.         $paths = preg_split('/((src|href)="([^"]+)")/i', $data, -1, PREG_SPLIT_DELIM_CAPTURE);
  686.         for ($i=0, $c=\count($paths); $i<$c; $i+=4)
  687.         {
  688.             $return .= $paths[$i];
  690.             if (!isset($paths[$i+1]))
  691.             {
  692.                 continue;
  693.             }
  695.             $file = FilesModel::findByPath($paths[$i+3]);
  697.             if ($file !== null)
  698.             {
  699.                 $return .= $paths[$i+2] . '="{{file::' . static::binToUuid($file->uuid) . '|urlattr}}"';
  700.             }
  701.             else
  702.             {
  703.                 $return .= $paths[$i+2] . '="' . $paths[$i+3] . '"';
  704.             }
  705.         }
  707.         return $return;
  708.     }
  710.     /**
  711.      * Convert insert tags inside "src" attributes to file paths
  712.      *
  713.      * @param string $data The markup string
  714.      *
  715.      * @return string The markup with insert tags converted to file paths
  716.      */
  717.     public static function insertTagToSrc($data)
  718.     {
  719.         $paths = preg_split('/((src|href)="([^"]*){{file::([^"}|]+)[^"}]*}}")/i', $data, -1, PREG_SPLIT_DELIM_CAPTURE);
  721.         if (!$paths)
  722.         {
  723.             return $data;
  724.         }
  726.         $return = '';
  728.         for ($i=0, $c=\count($paths); $i<$c; $i+=5)
  729.         {
  730.             $return .= $paths[$i];
  732.             if (!isset($paths[$i+1]))
  733.             {
  734.                 continue;
  735.             }
  737.             $file = FilesModel::findByUuid($paths[$i+4]);
  739.             if ($file !== null)
  740.             {
  741.                 $return .= $paths[$i+2] . '="' . $paths[$i+3] . $file->path . '"';
  742.             }
  743.             else
  744.             {
  745.                 $return .= $paths[$i+1];
  746.             }
  747.         }
  749.         return $return;
  750.     }
  752.     /**
  753.      * Sanitize a file name
  754.      *
  755.      * @param string $strName The file name
  756.      *
  757.      * @return string The sanitized file name
  758.      */
  759.     public static function sanitizeFileName($strName)
  760.     {
  761.         // Remove invisible control characters and unused code points
  762.         $strName = preg_replace('/[\pC]/u', '', $strName);
  764.         if ($strName === null)
  765.         {
  766.             throw new \InvalidArgumentException('The file name could not be sanitzied');
  767.         }
  769.         // Remove special characters not supported on e.g. Windows
  770.         return str_replace(array('\\', '/', ':', '*', '?', '"', '<', '>', '|'), '-', $strName);
  771.     }
  773.     /**
  774.      * Resolve a flagged URL such as assets/js/core.js|static|10184084
  775.      *
  776.      * @param string $url The URL
  777.      *
  778.      * @return \stdClass The options object
  779.      */
  780.     public static function resolveFlaggedUrl(&$url)
  781.     {
  782.         $options = new \stdClass();
  784.         // Defaults
  785.         $options->static = false;
  786.         $options->media  = null;
  787.         $options->mtime  = null;
  788.         $options->async  = false;
  790.         $chunks = explode('|', $url);
  792.         // Remove the flags from the URL
  793.         $url = $chunks[0];
  795.         for ($i=1, $c=\count($chunks); $i<$c; $i++)
  796.         {
  797.             if (empty($chunks[$i]))
  798.             {
  799.                 continue;
  800.             }
  802.             switch ($chunks[$i])
  803.             {
  804.                 case 'static':
  805.                     $options->static = true;
  806.                     break;
  808.                 case 'async':
  809.                     $options->async = true;
  810.                     break;
  812.                 case is_numeric($chunks[$i]):
  813.                     $options->mtime = $chunks[$i];
  814.                     break;
  816.                 default:
  817.                     $options->media = $chunks[$i];
  818.                     break;
  819.             }
  820.         }
  822.         return $options;
  823.     }
  825.     /**
  826.      * Convert the character encoding
  827.      *
  828.      * @param string $str  The input string
  829.      * @param string $to   The target character set
  830.      * @param string $from An optional source character set
  831.      *
  832.      * @return string The converted string
  833.      */
  834.     public static function convertEncoding($str, $to, $from=null)
  835.     {
  836.         if ($str !== null && !\is_scalar($str) && !(\is_object($str) && method_exists($str, '__toString')))
  837.         {
  838.             trigger_deprecation('contao/core-bundle', '4.9', 'Passing a non-stringable argument to StringUtil::convertEncoding() has been deprecated an will no longer work in Contao 5.0.');
  840.             return '';
  841.         }
  843.         $str = (string) $str;
  845.         if ('' === $str)
  846.         {
  847.             return $str;
  848.         }
  850.         if (!$from)
  851.         {
  852.             $from = mb_detect_encoding($str, 'ASCII,ISO-2022-JP,UTF-8,EUC-JP,ISO-8859-1');
  853.         }
  855.         if ($from == $to)
  856.         {
  857.             return $str;
  858.         }
  860.         return mb_convert_encoding($str, $to, $from);
  861.     }
  863.     /**
  864.      * Convert special characters to HTML entities preventing double conversions
  865.      *
  866.      * @param string  $strString          The input string
  867.      * @param boolean $blnStripInsertTags True to strip insert tags
  868.      * @param boolean $blnDoubleEncode    True to encode existing html entities
  869.      *
  870.      * @return string The converted string
  871.      */
  872.     public static function specialchars($strString, $blnStripInsertTags=false, $blnDoubleEncode=false)
  873.     {
  874.         if ($blnStripInsertTags)
  875.         {
  876.             $strString = static::stripInsertTags($strString);
  877.         }
  879.         return htmlspecialchars((string) $strString, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML5, $GLOBALS['TL_CONFIG']['characterSet'] ?? 'UTF-8', $blnDoubleEncode);
  880.     }
  882.     /**
  883.      * Encodes specialchars and nested insert tags for attributes
  884.      *
  885.      * @param string  $strString          The input string
  886.      * @param boolean $blnStripInsertTags True to strip insert tags
  887.      * @param boolean $blnDoubleEncode    True to encode existing html entities
  888.      *
  889.      * @return string The converted string
  890.      */
  891.     public static function specialcharsAttribute($strString, $blnStripInsertTags=false, $blnDoubleEncode=false)
  892.     {
  893.         $strString = self::specialchars($strString, $blnStripInsertTags, $blnDoubleEncode);
  895.         // Improve compatibility with JSON in attributes if no insert tags are present
  896.         if ($strString === self::stripInsertTags($strString))
  897.         {
  898.             $strString = str_replace('}}', '&#125;&#125;', $strString);
  899.         }
  901.         // Encode insert tags too
  902.         $strString = preg_replace('/(?:\|attr)?}}/', '|attr}}', $strString);
  903.         $strString = str_replace('|urlattr|attr}}', '|urlattr}}', $strString);
  905.         // Encode all remaining single closing curly braces
  906.         return preg_replace_callback('/}}?/', static fn ($match) => \strlen($match[0]) === 2 ? $match[0] : '&#125;', $strString);
  907.     }
  909.     /**
  910.      * Encodes disallowed protocols and specialchars for URL attributes
  911.      *
  912.      * @param string  $strString          The input string
  913.      * @param boolean $blnStripInsertTags True to strip insert tags
  914.      * @param boolean $blnDoubleEncode    True to encode existing html entities
  915.      *
  916.      * @return string The converted string
  917.      */
  918.     public static function specialcharsUrl($strString, $blnStripInsertTags=false, $blnDoubleEncode=false)
  919.     {
  920.         $strString = self::specialchars($strString, $blnStripInsertTags, $blnDoubleEncode);
  922.         // Encode insert tags too
  923.         $strString = preg_replace('/(?:\|urlattr|\|attr)?}}/', '|urlattr}}', $strString);
  925.         // Encode all remaining single closing curly braces
  926.         $strString = preg_replace_callback('/}}?/', static fn ($match) => \strlen($match[0]) === 2 ? $match[0] : '&#125;', $strString);
  928.         $colonRegEx = '('
  929.             . ':'                 // Plain text colon
  930.             . '|'                 // OR
  931.             . '&colon;'           // Named entity
  932.             . '|'                 // OR
  933.             . '&#(?:'             // Start of entity
  934.                 . 'x0*+3a'        // Hex number 3A
  935.                 . '(?![0-9a-f])'  // Must not be followed by another hex digit
  936.                 . '|'             // OR
  937.                 . '0*+58'         // Decimal number 58
  938.                 . '(?![0-9])'     // Must not be followed by another digit
  939.             . ');?'               // Optional semicolon
  940.         . ')i';
  942.         $arrAllowedUrlProtocols = System::getContainer()->getParameter('contao.sanitizer.allowed_url_protocols');
  944.         // URL-encode colon to prevent disallowed protocols
  945.         if (
  946.             !preg_match('(^(?:' . implode('|', array_map('preg_quote', $arrAllowedUrlProtocols)) . '):)i', self::decodeEntities($strString))
  947.             && preg_match($colonRegEx, self::stripInsertTags($strString))
  948.         ) {
  949.             $arrChunks = preg_split('/({{[^{}]*}})/', $strString, -1, PREG_SPLIT_DELIM_CAPTURE);
  950.             $strString = '';
  952.             foreach ($arrChunks as $index => $strChunk)
  953.             {
  954.                 $strString .= ($index % 2) ? $strChunk : preg_replace($colonRegEx, '%3A', $strChunk);
  955.             }
  956.         }
  958.         return $strString;
  959.     }
  961.     /**
  962.      * Remove Contao insert tags from a string
  963.      *
  964.      * @param string $strString The input string
  965.      *
  966.      * @return string The converted string
  967.      */
  968.     public static function stripInsertTags($strString)
  969.     {
  970.         $count = 0;
  972.         do
  973.         {
  974.             $strString = preg_replace('/{{[^{}]*}}/', '', $strString, -1, $count);
  975.         }
  976.         while ($count > 0);
  978.         return $strString;
  979.     }
  981.     /**
  982.      * Standardize a parameter (strip special characters and convert spaces)
  983.      *
  984.      * @param string  $strString            The input string
  985.      * @param boolean $blnPreserveUppercase True to preserver uppercase characters
  986.      *
  987.      * @return string The converted string
  988.      */
  989.     public static function standardize($strString, $blnPreserveUppercase=false)
  990.     {
  991.         $arrSearch = array('/[^\pN\pL \.\&\/_-]+/u', '/[ \.\&\/-]+/');
  992.         $arrReplace = array('', '-');
  994.         $strString = html_entity_decode($strString, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML5, $GLOBALS['TL_CONFIG']['characterSet'] ?? 'UTF-8');
  995.         $strString = static::stripInsertTags($strString);
  996.         $strString = preg_replace($arrSearch, $arrReplace, $strString);
  998.         if (is_numeric(substr($strString, 0, 1)))
  999.         {
  1000.             $strString = 'id-' . $strString;
  1001.         }
  1003.         if (!$blnPreserveUppercase)
  1004.         {
  1005.             $strString = mb_strtolower($strString);
  1006.         }
  1008.         return trim($strString, '-');
  1009.     }
  1011.     /**
  1012.      * Return an unserialized array or the argument
  1013.      *
  1014.      * @param mixed   $varValue      The serialized string
  1015.      * @param boolean $blnForceArray True to always return an array
  1016.      *
  1017.      * @return mixed The unserialized array or the unprocessed input value
  1018.      */
  1019.     public static function deserialize($varValue, $blnForceArray=false)
  1020.     {
  1021.         // Already an array
  1022.         if (\is_array($varValue))
  1023.         {
  1024.             return $varValue;
  1025.         }
  1027.         // Null
  1028.         if ($varValue === null)
  1029.         {
  1030.             return $blnForceArray ? array() : null;
  1031.         }
  1033.         // Not a string
  1034.         if (!\is_string($varValue))
  1035.         {
  1036.             return $blnForceArray ? array($varValue) : $varValue;
  1037.         }
  1039.         // Empty string
  1040.         if (trim($varValue) === '')
  1041.         {
  1042.             return $blnForceArray ? array() : '';
  1043.         }
  1045.         // Not a serialized array (see #1486)
  1046.         if (strncmp($varValue, 'a:', 2) !== 0)
  1047.         {
  1048.             return $blnForceArray ? array($varValue) : $varValue;
  1049.         }
  1051.         // Potentially including an object (see #6724)
  1052.         if (preg_match('/[OoC]:\+?[0-9]+:"/', $varValue))
  1053.         {
  1054.             trigger_error('StringUtil::deserialize() does not allow serialized objects', E_USER_WARNING);
  1056.             return $blnForceArray ? array($varValue) : $varValue;
  1057.         }
  1059.         $varUnserialized = @unserialize($varValue, array('allowed_classes' => false));
  1061.         if (\is_array($varUnserialized))
  1062.         {
  1063.             $varValue = $varUnserialized;
  1064.         }
  1065.         elseif ($blnForceArray)
  1066.         {
  1067.             $varValue = array($varValue);
  1068.         }
  1070.         return $varValue;
  1071.     }
  1073.     /**
  1074.      * Split a string into fragments, remove whitespace and return fragments as array
  1075.      *
  1076.      * @param string $strPattern The split pattern
  1077.      * @param string $strString  The input string
  1078.      *
  1079.      * @return array The fragments array
  1080.      */
  1081.     public static function trimsplit($strPattern, $strString)
  1082.     {
  1083.         // Split
  1084.         if (\strlen($strPattern) == 1)
  1085.         {
  1086.             $arrFragments = array_map('trim', explode($strPattern, $strString));
  1087.         }
  1088.         else
  1089.         {
  1090.             $arrFragments = array_map('trim', preg_split('/' . $strPattern . '/ui', $strString));
  1091.         }
  1093.         // Empty array
  1094.         if (\count($arrFragments) < 2 && !\strlen($arrFragments[0]))
  1095.         {
  1096.             $arrFragments = array();
  1097.         }
  1099.         return $arrFragments;
  1100.     }
  1102.     /**
  1103.      * Strip the Contao root dir from the given absolute path
  1104.      *
  1105.      * @param string $path
  1106.      *
  1107.      * @return string
  1108.      *
  1109.      * @throws \InvalidArgumentException
  1110.      */
  1111.     public static function stripRootDir($path)
  1112.     {
  1113.         // Compare normalized version of the paths
  1114.         $projectDir = Path::normalize(System::getContainer()->getParameter('kernel.project_dir'));
  1115.         $normalizedPath = Path::normalize($path);
  1116.         $length = \strlen($projectDir);
  1118.         if (strncmp($normalizedPath, $projectDir, $length) !== 0 || \strlen($normalizedPath) <= $length || $normalizedPath[$length] !== '/')
  1119.         {
  1120.             throw new \InvalidArgumentException(sprintf('Path "%s" is not inside the Contao root dir "%s"', $path, $projectDir));
  1121.         }
  1123.         return (string) substr($path, $length + 1);
  1124.     }
  1126.     /**
  1127.      * Convert all ampersands into their HTML entity (default) or unencoded value
  1128.      *
  1129.      * @param string  $strString
  1130.      * @param boolean $blnEncode
  1131.      *
  1132.      * @return string
  1133.      */
  1134.     public static function ampersand($strString, $blnEncode=true): string
  1135.     {
  1136.         return preg_replace('/&(amp;)?/i', ($blnEncode ? '&amp;' : '&'), $strString);
  1137.     }
  1139.     /**
  1140.      * Convert an input-encoded string back to the raw UTF-8 value it originated from
  1141.      *
  1142.      * It handles all Contao input encoding specifics like basic entities and encoded entities.
  1143.      */
  1144.     public static function revertInputEncoding(string $strValue): string
  1145.     {
  1146.         $strValue = static::restoreBasicEntities($strValue);
  1147.         $strValue = static::decodeEntities($strValue);
  1149.         // Ensure valid UTF-8
  1150.         if (preg_match('//u', $strValue) !== 1)
  1151.         {
  1152.             $substituteCharacter = mb_substitute_character();
  1153.             mb_substitute_character(0xFFFD);
  1155.             $strValue = mb_convert_encoding($strValue, 'UTF-8', 'UTF-8');
  1157.             mb_substitute_character($substituteCharacter);
  1158.         }
  1160.         return $strValue;
  1161.     }
  1163.     /**
  1164.      * Convert an input-encoded string to plain text UTF-8
  1165.      *
  1166.      * Strips or replaces insert tags, strips HTML tags, decodes entities, escapes insert tag braces.
  1167.      *
  1168.      * @param bool $blnRemoveInsertTags True to remove insert tags instead of replacing them
  1169.      *
  1170.      * @deprecated Deprecated since Contao 4.13, to be removed in Contao 5;
  1171.      *             use the Contao\CoreBundle\String\HtmlDecoder service instead
  1172.      */
  1173.     public static function inputEncodedToPlainText(string $strValue, bool $blnRemoveInsertTags = false): string
  1174.     {
  1175.         trigger_deprecation('contao/core-bundle', '4.13', 'Using "StringUtil::inputEncodedToPlainText()" has been deprecated and will no longer work in Contao 5.0. Use the "Contao\CoreBundle\String\HtmlDecoder" service instead.');
  1177.         return System::getContainer()->get('contao.string.html_decoder')->inputEncodedToPlainText($strValue, $blnRemoveInsertTags);
  1178.     }
  1180.     /**
  1181.      * Convert an HTML string to plain text with normalized white space
  1182.      *
  1183.      * It handles all Contao input encoding specifics like insert tags, basic
  1184.      * entities and encoded entities and is meant to be used with content from
  1185.      * fields that have the allowHtml flag enabled.
  1186.      *
  1187.      * @param bool $blnRemoveInsertTags True to remove insert tags instead of replacing them
  1188.      *
  1189.      * @deprecated Deprecated since Contao 4.13, to be removed in Contao 5;
  1190.      *             use the Contao\CoreBundle\String\HtmlDecoder service instead
  1191.      */
  1192.     public static function htmlToPlainText(string $strValue, bool $blnRemoveInsertTags = false): string
  1193.     {
  1194.         trigger_deprecation('contao/core-bundle', '4.13', 'Using "StringUtil::htmlToPlainText()" has been deprecated and will no longer work in Contao 5.0. Use the "Contao\CoreBundle\String\HtmlDecoder" service instead.');
  1196.         return System::getContainer()->get('contao.string.html_decoder')->htmlToPlainText($strValue, $blnRemoveInsertTags);
  1197.     }
  1199.     /**
  1200.      * @param float|int $number
  1201.      */
  1202.     public static function numberToString($number, ?int $precision = null): string
  1203.     {
  1204.         if (\is_int($number))
  1205.         {
  1206.             if (null === $precision)
  1207.             {
  1208.                 return (string) $number;
  1209.             }
  1211.             $number = (float) $number;
  1212.         }
  1214.         if (!\is_float($number))
  1215.         {
  1216.             throw new \TypeError(sprintf('Argument 1 passed to %s() must be of the type int|float, %s given', __METHOD__, get_debug_type($number)));
  1217.         }
  1219.         if ($precision === null)
  1220.         {
  1221.             $precision = (int) \ini_get('precision');
  1222.         }
  1224.         // Special value from PHP ini
  1225.         if ($precision === -1)
  1226.         {
  1227.             $precision = 14;
  1228.         }
  1230.         if ($precision <= 1)
  1231.         {
  1232.             throw new \InvalidArgumentException(sprintf('Precision must be greater than 1, "%s" given.', $precision));
  1233.         }
  1235.         if (!preg_match('/^(-?)(\d)\.(\d+)e([+-]\d+)$/', sprintf('%.' . ($precision - 1) . 'e', $number), $match))
  1236.         {
  1237.             throw new \InvalidArgumentException(sprintf('Unable to convert "%s" into a string representation.', $number));
  1238.         }
  1240.         $significantDigits = rtrim($match[2] . $match[3], '0');
  1241.         $shiftBy = (int) $match[4] + 1;
  1243.         $signPart = $match[1];
  1244.         $wholePart = substr(str_pad($significantDigits, $shiftBy, '0'), 0, max(0, $shiftBy)) ?: '0';
  1245.         $decimalPart = str_repeat('0', max(0, -$shiftBy)) . substr($significantDigits, max(0, $shiftBy));
  1247.         return rtrim("$signPart$wholePart.$decimalPart", '.');
  1248.     }
  1249. }
  1251. class_alias(StringUtil::class, 'StringUtil');