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

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, $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.         $return = '';
  720.         $paths = preg_split('/((src|href)="([^"]*){{file::([^"}|]+)[^"}]*}}")/i', $data, -1, PREG_SPLIT_DELIM_CAPTURE);
  722.         for ($i=0, $c=\count($paths); $i<$c; $i+=5)
  723.         {
  724.             $return .= $paths[$i];
  726.             if (!isset($paths[$i+1]))
  727.             {
  728.                 continue;
  729.             }
  731.             $file = FilesModel::findByUuid($paths[$i+4]);
  733.             if ($file !== null)
  734.             {
  735.                 $return .= $paths[$i+2] . '="' . $paths[$i+3] . $file->path . '"';
  736.             }
  737.             else
  738.             {
  739.                 $return .= $paths[$i+1];
  740.             }
  741.         }
  743.         return $return;
  744.     }
  746.     /**
  747.      * Sanitize a file name
  748.      *
  749.      * @param string $strName The file name
  750.      *
  751.      * @return string The sanitized file name
  752.      */
  753.     public static function sanitizeFileName($strName)
  754.     {
  755.         // Remove invisible control characters and unused code points
  756.         $strName = preg_replace('/[\pC]/u', '', $strName);
  758.         if ($strName === null)
  759.         {
  760.             throw new \InvalidArgumentException('The file name could not be sanitzied');
  761.         }
  763.         // Remove special characters not supported on e.g. Windows
  764.         return str_replace(array('\\', '/', ':', '*', '?', '"', '<', '>', '|'), '-', $strName);
  765.     }
  767.     /**
  768.      * Resolve a flagged URL such as assets/js/core.js|static|10184084
  769.      *
  770.      * @param string $url The URL
  771.      *
  772.      * @return \stdClass The options object
  773.      */
  774.     public static function resolveFlaggedUrl(&$url)
  775.     {
  776.         $options = new \stdClass();
  778.         // Defaults
  779.         $options->static = false;
  780.         $options->media  = null;
  781.         $options->mtime  = null;
  782.         $options->async  = false;
  784.         $chunks = explode('|', $url);
  786.         // Remove the flags from the URL
  787.         $url = $chunks[0];
  789.         for ($i=1, $c=\count($chunks); $i<$c; $i++)
  790.         {
  791.             if (empty($chunks[$i]))
  792.             {
  793.                 continue;
  794.             }
  796.             switch ($chunks[$i])
  797.             {
  798.                 case 'static':
  799.                     $options->static = true;
  800.                     break;
  802.                 case 'async':
  803.                     $options->async = true;
  804.                     break;
  806.                 case is_numeric($chunks[$i]):
  807.                     $options->mtime = $chunks[$i];
  808.                     break;
  810.                 default:
  811.                     $options->media = $chunks[$i];
  812.                     break;
  813.             }
  814.         }
  816.         return $options;
  817.     }
  819.     /**
  820.      * Convert the character encoding
  821.      *
  822.      * @param string $str  The input string
  823.      * @param string $to   The target character set
  824.      * @param string $from An optional source character set
  825.      *
  826.      * @return string The converted string
  827.      */
  828.     public static function convertEncoding($str, $to, $from=null)
  829.     {
  830.         if ($str !== null && !\is_scalar($str) && !(\is_object($str) && method_exists($str, '__toString')))
  831.         {
  832.             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.');
  834.             return '';
  835.         }
  837.         $str = (string) $str;
  839.         if ('' === $str)
  840.         {
  841.             return $str;
  842.         }
  844.         if (!$from)
  845.         {
  846.             $from = mb_detect_encoding($str, 'ASCII,ISO-2022-JP,UTF-8,EUC-JP,ISO-8859-1');
  847.         }
  849.         if ($from == $to)
  850.         {
  851.             return $str;
  852.         }
  854.         return mb_convert_encoding($str, $to, $from);
  855.     }
  857.     /**
  858.      * Convert special characters to HTML entities preventing double conversions
  859.      *
  860.      * @param string  $strString          The input string
  861.      * @param boolean $blnStripInsertTags True to strip insert tags
  862.      * @param boolean $blnDoubleEncode    True to encode existing html entities
  863.      *
  864.      * @return string The converted string
  865.      */
  866.     public static function specialchars($strString, $blnStripInsertTags=false, $blnDoubleEncode=false)
  867.     {
  868.         if ($blnStripInsertTags)
  869.         {
  870.             $strString = static::stripInsertTags($strString);
  871.         }
  873.         return htmlspecialchars((string) $strString, ENT_QUOTES, $GLOBALS['TL_CONFIG']['characterSet'] ?? 'UTF-8', $blnDoubleEncode);
  874.     }
  876.     /**
  877.      * Encodes specialchars and nested insert tags for attributes
  878.      *
  879.      * @param string  $strString          The input string
  880.      * @param boolean $blnStripInsertTags True to strip insert tags
  881.      * @param boolean $blnDoubleEncode    True to encode existing html entities
  882.      *
  883.      * @return string The converted string
  884.      */
  885.     public static function specialcharsAttribute($strString, $blnStripInsertTags=false, $blnDoubleEncode=false)
  886.     {
  887.         $strString = self::specialchars($strString, $blnStripInsertTags, $blnDoubleEncode);
  889.         // Improve compatibility with JSON in attributes if no insert tags are present
  890.         if ($strString === self::stripInsertTags($strString))
  891.         {
  892.             $strString = str_replace('}}', '&#125;&#125;', $strString);
  893.         }
  895.         // Encode insert tags too
  896.         $strString = preg_replace('/(?:\|attr)?}}/', '|attr}}', $strString);
  897.         $strString = str_replace('|urlattr|attr}}', '|urlattr}}', $strString);
  899.         // Encode all remaining single closing curly braces
  900.         return preg_replace_callback('/}}?/', static fn ($match) => \strlen($match[0]) === 2 ? $match[0] : '&#125;', $strString);
  901.     }
  903.     /**
  904.      * Encodes disallowed protocols and specialchars for URL attributes
  905.      *
  906.      * @param string  $strString          The input string
  907.      * @param boolean $blnStripInsertTags True to strip insert tags
  908.      * @param boolean $blnDoubleEncode    True to encode existing html entities
  909.      *
  910.      * @return string The converted string
  911.      */
  912.     public static function specialcharsUrl($strString, $blnStripInsertTags=false, $blnDoubleEncode=false)
  913.     {
  914.         $strString = self::specialchars($strString, $blnStripInsertTags, $blnDoubleEncode);
  916.         // Encode insert tags too
  917.         $strString = preg_replace('/(?:\|urlattr|\|attr)?}}/', '|urlattr}}', $strString);
  919.         // Encode all remaining single closing curly braces
  920.         $strString = preg_replace_callback('/}}?/', static fn ($match) => \strlen($match[0]) === 2 ? $match[0] : '&#125;', $strString);
  922.         $colonRegEx = '('
  923.             . ':'                 // Plain text colon
  924.             . '|'                 // OR
  925.             . '&colon;'           // Named entity
  926.             . '|'                 // OR
  927.             . '&#(?:'             // Start of entity
  928.                 . 'x0*+3a'        // Hex number 3A
  929.                 . '(?![0-9a-f])'  // Must not be followed by another hex digit
  930.                 . '|'             // OR
  931.                 . '0*+58'         // Decimal number 58
  932.                 . '(?![0-9])'     // Must not be followed by another digit
  933.             . ');?'               // Optional semicolon
  934.         . ')i';
  936.         $arrAllowedUrlProtocols = System::getContainer()->getParameter('contao.sanitizer.allowed_url_protocols');
  938.         // URL-encode colon to prevent disallowed protocols
  939.         if (
  940.             !preg_match('(^(?:' . implode('|', array_map('preg_quote', $arrAllowedUrlProtocols)) . '):)i', self::decodeEntities($strString))
  941.             && preg_match($colonRegEx, self::stripInsertTags($strString))
  942.         ) {
  943.             $strString = preg_replace($colonRegEx, '%3A', $strString);
  944.         }
  946.         return $strString;
  947.     }
  949.     /**
  950.      * Remove Contao insert tags from a string
  951.      *
  952.      * @param string $strString The input string
  953.      *
  954.      * @return string The converted string
  955.      */
  956.     public static function stripInsertTags($strString)
  957.     {
  958.         $count = 0;
  960.         do
  961.         {
  962.             $strString = preg_replace('/{{[^{}]*}}/', '', $strString, -1, $count);
  963.         }
  964.         while ($count > 0);
  966.         return $strString;
  967.     }
  969.     /**
  970.      * Standardize a parameter (strip special characters and convert spaces)
  971.      *
  972.      * @param string  $strString            The input string
  973.      * @param boolean $blnPreserveUppercase True to preserver uppercase characters
  974.      *
  975.      * @return string The converted string
  976.      */
  977.     public static function standardize($strString, $blnPreserveUppercase=false)
  978.     {
  979.         $arrSearch = array('/[^\pN\pL \.\&\/_-]+/u', '/[ \.\&\/-]+/');
  980.         $arrReplace = array('', '-');
  982.         $strString = html_entity_decode($strString, ENT_QUOTES, $GLOBALS['TL_CONFIG']['characterSet'] ?? 'UTF-8');
  983.         $strString = static::stripInsertTags($strString);
  984.         $strString = preg_replace($arrSearch, $arrReplace, $strString);
  986.         if (is_numeric(substr($strString, 0, 1)))
  987.         {
  988.             $strString = 'id-' . $strString;
  989.         }
  991.         if (!$blnPreserveUppercase)
  992.         {
  993.             $strString = mb_strtolower($strString);
  994.         }
  996.         return trim($strString, '-');
  997.     }
  999.     /**
  1000.      * Return an unserialized array or the argument
  1001.      *
  1002.      * @param mixed   $varValue      The serialized string
  1003.      * @param boolean $blnForceArray True to always return an array
  1004.      *
  1005.      * @return mixed The unserialized array or the unprocessed input value
  1006.      */
  1007.     public static function deserialize($varValue, $blnForceArray=false)
  1008.     {
  1009.         // Already an array
  1010.         if (\is_array($varValue))
  1011.         {
  1012.             return $varValue;
  1013.         }
  1015.         // Null
  1016.         if ($varValue === null)
  1017.         {
  1018.             return $blnForceArray ? array() : null;
  1019.         }
  1021.         // Not a string
  1022.         if (!\is_string($varValue))
  1023.         {
  1024.             return $blnForceArray ? array($varValue) : $varValue;
  1025.         }
  1027.         // Empty string
  1028.         if (trim($varValue) === '')
  1029.         {
  1030.             return $blnForceArray ? array() : '';
  1031.         }
  1033.         // Not a serialized array (see #1486)
  1034.         if (strncmp($varValue, 'a:', 2) !== 0)
  1035.         {
  1036.             return $blnForceArray ? array($varValue) : $varValue;
  1037.         }
  1039.         // Potentially including an object (see #6724)
  1040.         if (preg_match('/[OoC]:\+?[0-9]+:"/', $varValue))
  1041.         {
  1042.             trigger_error('StringUtil::deserialize() does not allow serialized objects', E_USER_WARNING);
  1044.             return $blnForceArray ? array($varValue) : $varValue;
  1045.         }
  1047.         $varUnserialized = @unserialize($varValue, array('allowed_classes' => false));
  1049.         if (\is_array($varUnserialized))
  1050.         {
  1051.             $varValue = $varUnserialized;
  1052.         }
  1053.         elseif ($blnForceArray)
  1054.         {
  1055.             $varValue = array($varValue);
  1056.         }
  1058.         return $varValue;
  1059.     }
  1061.     /**
  1062.      * Split a string into fragments, remove whitespace and return fragments as array
  1063.      *
  1064.      * @param string $strPattern The split pattern
  1065.      * @param string $strString  The input string
  1066.      *
  1067.      * @return array The fragments array
  1068.      */
  1069.     public static function trimsplit($strPattern, $strString)
  1070.     {
  1071.         // Split
  1072.         if (\strlen($strPattern) == 1)
  1073.         {
  1074.             $arrFragments = array_map('trim', explode($strPattern, $strString));
  1075.         }
  1076.         else
  1077.         {
  1078.             $arrFragments = array_map('trim', preg_split('/' . $strPattern . '/ui', $strString));
  1079.         }
  1081.         // Empty array
  1082.         if (\count($arrFragments) < 2 && !\strlen($arrFragments[0]))
  1083.         {
  1084.             $arrFragments = array();
  1085.         }
  1087.         return $arrFragments;
  1088.     }
  1090.     /**
  1091.      * Strip the Contao root dir from the given absolute path
  1092.      *
  1093.      * @param string $path
  1094.      *
  1095.      * @return string
  1096.      *
  1097.      * @throws \InvalidArgumentException
  1098.      */
  1099.     public static function stripRootDir($path)
  1100.     {
  1101.         // Compare normalized version of the paths
  1102.         $projectDir = Path::normalize(System::getContainer()->getParameter('kernel.project_dir'));
  1103.         $normalizedPath = Path::normalize($path);
  1104.         $length = \strlen($projectDir);
  1106.         if (strncmp($normalizedPath, $projectDir, $length) !== 0 || \strlen($normalizedPath) <= $length || $normalizedPath[$length] !== '/')
  1107.         {
  1108.             throw new \InvalidArgumentException(sprintf('Path "%s" is not inside the Contao root dir "%s"', $path, $projectDir));
  1109.         }
  1111.         return (string) substr($path, $length + 1);
  1112.     }
  1114.     /**
  1115.      * Convert all ampersands into their HTML entity (default) or unencoded value
  1116.      *
  1117.      * @param string  $strString
  1118.      * @param boolean $blnEncode
  1119.      *
  1120.      * @return string
  1121.      */
  1122.     public static function ampersand($strString, $blnEncode=true): string
  1123.     {
  1124.         return preg_replace('/&(amp;)?/i', ($blnEncode ? '&amp;' : '&'), $strString);
  1125.     }
  1127.     /**
  1128.      * Convert an input-encoded string back to the raw UTF-8 value it originated from
  1129.      *
  1130.      * It handles all Contao input encoding specifics like basic entities and encoded entities.
  1131.      */
  1132.     public static function revertInputEncoding(string $strValue): string
  1133.     {
  1134.         $strValue = static::restoreBasicEntities($strValue);
  1135.         $strValue = static::decodeEntities($strValue);
  1137.         // Ensure valid UTF-8
  1138.         if (preg_match('//u', $strValue) !== 1)
  1139.         {
  1140.             $substituteCharacter = mb_substitute_character();
  1141.             mb_substitute_character(0xFFFD);
  1143.             $strValue = mb_convert_encoding($strValue, 'UTF-8', 'UTF-8');
  1145.             mb_substitute_character($substituteCharacter);
  1146.         }
  1148.         return $strValue;
  1149.     }
  1151.     /**
  1152.      * Convert an input-encoded string to plain text UTF-8
  1153.      *
  1154.      * Strips or replaces insert tags, strips HTML tags, decodes entities, escapes insert tag braces.
  1155.      *
  1156.      * @param bool $blnRemoveInsertTags True to remove insert tags instead of replacing them
  1157.      *
  1158.      * @deprecated Deprecated since Contao 4.13, to be removed in Contao 5;
  1159.      *             use the Contao\CoreBundle\String\HtmlDecoder service instead
  1160.      */
  1161.     public static function inputEncodedToPlainText(string $strValue, bool $blnRemoveInsertTags = false): string
  1162.     {
  1163.         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.');
  1165.         return System::getContainer()->get('contao.string.html_decoder')->inputEncodedToPlainText($strValue, $blnRemoveInsertTags);
  1166.     }
  1168.     /**
  1169.      * Convert an HTML string to plain text with normalized white space
  1170.      *
  1171.      * It handles all Contao input encoding specifics like insert tags, basic
  1172.      * entities and encoded entities and is meant to be used with content from
  1173.      * fields that have the allowHtml flag enabled.
  1174.      *
  1175.      * @param bool $blnRemoveInsertTags True to remove insert tags instead of replacing them
  1176.      *
  1177.      * @deprecated Deprecated since Contao 4.13, to be removed in Contao 5;
  1178.      *             use the Contao\CoreBundle\String\HtmlDecoder service instead
  1179.      */
  1180.     public static function htmlToPlainText(string $strValue, bool $blnRemoveInsertTags = false): string
  1181.     {
  1182.         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.');
  1184.         return System::getContainer()->get('contao.string.html_decoder')->htmlToPlainText($strValue, $blnRemoveInsertTags);
  1185.     }
  1187.     /**
  1188.      * @param float|int $number
  1189.      */
  1190.     public static function numberToString($number, int $precision = null): string
  1191.     {
  1192.         if (\is_int($number))
  1193.         {
  1194.             if (null === $precision)
  1195.             {
  1196.                 return (string) $number;
  1197.             }
  1199.             $number = (float) $number;
  1200.         }
  1202.         if (!\is_float($number))
  1203.         {
  1204.             throw new \TypeError(sprintf('Argument 1 passed to %s() must be of the type int|float, %s given', __METHOD__, get_debug_type($number)));
  1205.         }
  1207.         if ($precision === null)
  1208.         {
  1209.             $precision = (int) \ini_get('precision');
  1210.         }
  1212.         // Special value from PHP ini
  1213.         if ($precision === -1)
  1214.         {
  1215.             $precision = 14;
  1216.         }
  1218.         if ($precision <= 1)
  1219.         {
  1220.             throw new \InvalidArgumentException(sprintf('Precision must be greater than 1, "%s" given.', $precision));
  1221.         }
  1223.         if (!preg_match('/^(-?)(\d)\.(\d+)e([+-]\d+)$/', sprintf('%.' . ($precision - 1) . 'e', $number), $match))
  1224.         {
  1225.             throw new \InvalidArgumentException(sprintf('Unable to convert "%s" into a string representation.', $number));
  1226.         }
  1228.         $significantDigits = rtrim($match[2] . $match[3], '0');
  1229.         $shiftBy = (int) $match[4] + 1;
  1231.         $signPart = $match[1];
  1232.         $wholePart = substr(str_pad($significantDigits, $shiftBy, '0'), 0, max(0, $shiftBy)) ?: '0';
  1233.         $decimalPart = str_repeat('0', max(0, -$shiftBy)) . substr($significantDigits, max(0, $shiftBy));
  1235.         return rtrim("$signPart$wholePart.$decimalPart", '.');
  1236.     }
  1237. }
  1239. class_alias(StringUtil::class, 'StringUtil');