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

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 Contao\CoreBundle\Util\SimpleTokenParser;
  14. use Patchwork\Utf8;
  15. use Webmozart\PathUtil\Path;
  17. /**
  18.  * Provides string manipulation methods
  19.  *
  20.  * Usage:
  21.  *
  22.  *     $short = StringUtil::substr($str, 32);
  23.  *     $html  = StringUtil::substrHtml($str, 32);
  24.  *     $xhtml = StringUtil::toXhtml($html5);
  25.  *
  26.  * @author Leo Feyer <https://github.com/leofeyer>
  27.  */
  28. class StringUtil
  29. {
  30.     /**
  31.      * Shorten a string to a given number of characters
  32.      *
  33.      * The function preserves words, so the result might be a bit shorter or
  34.      * longer than the number of characters given. It strips all tags.
  35.      *
  36.      * @param string  $strString        The string to shorten
  37.      * @param integer $intNumberOfChars The target number of characters
  38.      * @param string  $strEllipsis      An optional ellipsis to append to the shortened string
  39.      *
  40.      * @return string The shortened string
  41.      */
  42.     public static function substr($strString, $intNumberOfChars, $strEllipsis=' …')
  43.     {
  44.         $strString = preg_replace('/[\t\n\r]+/', ' ', $strString);
  45.         $strString = strip_tags($strString);
  47.         if (Utf8::strlen($strString) <= $intNumberOfChars)
  48.         {
  49.             return $strString;
  50.         }
  52.         $intCharCount = 0;
  53.         $arrWords = array();
  54.         $arrChunks = preg_split('/\s+/', $strString);
  55.         $blnAddEllipsis = false;
  57.         foreach ($arrChunks as $strChunk)
  58.         {
  59.             $intCharCount += Utf8::strlen(static::decodeEntities($strChunk));
  61.             if ($intCharCount++ <= $intNumberOfChars)
  62.             {
  63.                 $arrWords[] = $strChunk;
  64.                 continue;
  65.             }
  67.             // If the first word is longer than $intNumberOfChars already, shorten it
  68.             // with Utf8::substr() so the method does not return an empty string.
  69.             if (empty($arrWords))
  70.             {
  71.                 $arrWords[] = Utf8::substr($strChunk, 0, $intNumberOfChars);
  72.             }
  74.             if ($strEllipsis !== false)
  75.             {
  76.                 $blnAddEllipsis = true;
  77.             }
  79.             break;
  80.         }
  82.         // Deprecated since Contao 4.0, to be removed in Contao 5.0
  83.         if ($strEllipsis === true)
  84.         {
  85.             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.');
  87.             $strEllipsis = ' …';
  88.         }
  90.         return implode(' ', $arrWords) . ($blnAddEllipsis ? $strEllipsis : '');
  91.     }
  93.     /**
  94.      * Shorten a HTML string to a given number of characters
  95.      *
  96.      * The function preserves words, so the result might be a bit shorter or
  97.      * longer than the number of characters given. It preserves allowed tags.
  98.      *
  99.      * @param string  $strString        The string to shorten
  100.      * @param integer $intNumberOfChars The target number of characters
  101.      *
  102.      * @return string The shortened HTML string
  103.      */
  104.     public static function substrHtml($strString, $intNumberOfChars)
  105.     {
  106.         $strReturn = '';
  107.         $intCharCount = 0;
  108.         $arrOpenTags = array();
  109.         $arrTagBuffer = array();
  110.         $arrEmptyTags = array('area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr');
  112.         $strString = preg_replace('/[\t\n\r]+/', ' ', $strString);
  113.         $strString = strip_tags($strString, Config::get('allowedTags'));
  114.         $strString = preg_replace('/ +/', ' ', $strString);
  116.         // Seperate tags and text
  117.         $arrChunks = preg_split('/(<[^>]+>)/', $strString, -1, PREG_SPLIT_DELIM_CAPTURE|PREG_SPLIT_NO_EMPTY);
  119.         for ($i=0, $c=\count($arrChunks); $i<$c; $i++)
  120.         {
  121.             // Buffer tags to include them later
  122.             if (preg_match('/<([^>]+)>/', $arrChunks[$i]))
  123.             {
  124.                 $arrTagBuffer[] = $arrChunks[$i];
  125.                 continue;
  126.             }
  128.             $buffer = $arrChunks[$i];
  130.             // Get the substring of the current text
  131.             if (!$arrChunks[$i] = static::substr($arrChunks[$i], ($intNumberOfChars - $intCharCount), false))
  132.             {
  133.                 break;
  134.             }
  136.             $blnModified = ($buffer !== $arrChunks[$i]);
  137.             $intCharCount += Utf8::strlen(static::decodeEntities($arrChunks[$i]));
  139.             if ($intCharCount <= $intNumberOfChars)
  140.             {
  141.                 foreach ($arrTagBuffer as $strTag)
  142.                 {
  143.                     $strTagName = strtolower(trim($strTag));
  145.                     // Extract the tag name (see #5669)
  146.                     if (($pos = strpos($strTagName, ' ')) !== false)
  147.                     {
  148.                         $strTagName = substr($strTagName, 1, $pos - 1);
  149.                     }
  150.                     else
  151.                     {
  152.                         $strTagName = substr($strTagName, 1, -1);
  153.                     }
  155.                     // Skip empty tags
  156.                     if (\in_array($strTagName, $arrEmptyTags))
  157.                     {
  158.                         continue;
  159.                     }
  161.                     // Store opening tags in the open_tags array
  162.                     if (strncmp($strTagName, '/', 1) !== 0)
  163.                     {
  164.                         if ($i<$c || !empty($arrChunks[$i]))
  165.                         {
  166.                             $arrOpenTags[] = $strTagName;
  167.                         }
  169.                         continue;
  170.                     }
  172.                     // Closing tags will be removed from the "open tags" array
  173.                     if ($i<$c || !empty($arrChunks[$i]))
  174.                     {
  175.                         $arrOpenTags = array_values($arrOpenTags);
  177.                         for ($j=\count($arrOpenTags)-1; $j>=0; $j--)
  178.                         {
  179.                             if ($strTagName == '/' . $arrOpenTags[$j])
  180.                             {
  181.                                 unset($arrOpenTags[$j]);
  182.                                 break;
  183.                             }
  184.                         }
  185.                     }
  186.                 }
  188.                 // If the current chunk contains text, add tags and text to the return string
  189.                 if ($i<$c || \strlen($arrChunks[$i]))
  190.                 {
  191.                     $strReturn .= implode('', $arrTagBuffer) . $arrChunks[$i];
  192.                 }
  194.                 // Stop after the first shortened chunk (see #7311)
  195.                 if ($blnModified)
  196.                 {
  197.                     break;
  198.                 }
  200.                 $arrTagBuffer = array();
  201.                 continue;
  202.             }
  204.             break;
  205.         }
  207.         // Close all remaining open tags
  208.         krsort($arrOpenTags);
  210.         foreach ($arrOpenTags as $strTag)
  211.         {
  212.             $strReturn .= '</' . $strTag . '>';
  213.         }
  215.         return trim($strReturn);
  216.     }
  218.     /**
  219.      * Decode all entities
  220.      *
  221.      * @param mixed   $strString     The string to decode
  222.      * @param integer $strQuoteStyle The quote style (defaults to ENT_QUOTES)
  223.      * @param string  $strCharset    An optional charset
  224.      *
  225.      * @return string The decoded string
  226.      */
  227.     public static function decodeEntities($strString, $strQuoteStyle=ENT_QUOTES, $strCharset=null)
  228.     {
  229.         if ((string) $strString === '')
  230.         {
  231.             return '';
  232.         }
  234.         if ($strCharset === null)
  235.         {
  236.             $strCharset = 'UTF-8';
  237.         }
  239.         $strString = preg_replace('/(&#*\w+)[\x00-\x20]+;/i', '$1;', $strString);
  240.         $strString = preg_replace('/(&#x*)([0-9a-f]+);/i', '$1$2;', $strString);
  242.         return html_entity_decode($strString, $strQuoteStyle, $strCharset);
  243.     }
  245.     /**
  246.      * Restore basic entities
  247.      *
  248.      * @param string $strBuffer The string with the tags to be replaced
  249.      *
  250.      * @return string The string with the original entities
  251.      */
  252.     public static function restoreBasicEntities($strBuffer)
  253.     {
  254.         return str_replace(array('[&]', '[&amp;]', '[lt]', '[gt]', '[nbsp]', '[-]'), array('&amp;', '&amp;', '&lt;', '&gt;', '&nbsp;', '&shy;'), $strBuffer);
  255.     }
  257.     /**
  258.      * Generate an alias from a string
  259.      *
  260.      * @param string $strString The string
  261.      *
  262.      * @return string The alias
  263.      */
  264.     public static function generateAlias($strString)
  265.     {
  266.         $strString = static::decodeEntities($strString);
  267.         $strString = static::restoreBasicEntities($strString);
  268.         $strString = static::standardize(strip_tags($strString));
  270.         // Remove the prefix if the alias is not numeric (see #707)
  271.         if (strncmp($strString, 'id-', 3) === 0 && !is_numeric($strSubstr = substr($strString, 3)))
  272.         {
  273.             $strString = $strSubstr;
  274.         }
  276.         return $strString;
  277.     }
  279.     /**
  280.      * Prepare a slug
  281.      *
  282.      * @param string $strSlug The slug
  283.      *
  284.      * @return string
  285.      */
  286.     public static function prepareSlug($strSlug)
  287.     {
  288.         $strSlug = static::stripInsertTags($strSlug);
  289.         $strSlug = static::restoreBasicEntities($strSlug);
  290.         $strSlug = static::decodeEntities($strSlug);
  292.         return $strSlug;
  293.     }
  295.     /**
  296.      * Censor a single word or an array of words within a string
  297.      *
  298.      * @param string $strString  The string to censor
  299.      * @param mixed  $varWords   A string or array or words to replace
  300.      * @param string $strReplace An optional replacement string
  301.      *
  302.      * @return string The cleaned string
  303.      */
  304.     public static function censor($strString, $varWords, $strReplace='')
  305.     {
  306.         foreach ((array) $varWords as $strWord)
  307.         {
  308.             $strString = preg_replace('/\b(' . str_replace('\*', '\w*?', preg_quote($strWord, '/')) . ')\b/i', $strReplace, $strString);
  309.         }
  311.         return $strString;
  312.     }
  314.     /**
  315.      * Encode all e-mail addresses within a string
  316.      *
  317.      * @param string $strString The string to encode
  318.      *
  319.      * @return string The encoded string
  320.      */
  321.     public static function encodeEmail($strString)
  322.     {
  323.         if (strpos($strString, '@') === false)
  324.         {
  325.             return $strString;
  326.         }
  328.         $arrEmails = static::extractEmail($strString, Config::get('allowedTags'));
  330.         foreach ($arrEmails as $strEmail)
  331.         {
  332.             $strEncoded = '';
  333.             $arrCharacters = Utf8::str_split($strEmail);
  335.             foreach ($arrCharacters as $index => $strCharacter)
  336.             {
  337.                 $strEncoded .= sprintf(($index % 2) ? '&#x%X;' : '&#%s;', Utf8::ord($strCharacter));
  338.             }
  340.             $strString = str_replace($strEmail, $strEncoded, $strString);
  341.         }
  343.         return str_replace('mailto:', '&#109;&#97;&#105;&#108;&#116;&#111;&#58;', $strString);
  344.     }
  346.     /**
  347.      * Extract all e-mail addresses from a string
  348.      *
  349.      * @param string $strString      The string
  350.      * @param string $strAllowedTags A list of allowed HTML tags
  351.      *
  352.      * @return array The e-mail addresses
  353.      */
  354.     public static function extractEmail($strString, $strAllowedTags='')
  355.     {
  356.         $arrEmails = array();
  358.         if (strpos($strString, '@') === false)
  359.         {
  360.             return $arrEmails;
  361.         }
  363.         // Find all mailto: addresses
  364.         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);
  366.         foreach ($matches[0] as &$strEmail)
  367.         {
  368.             $strEmail = str_replace('mailto:', '', $strEmail);
  370.             if (Validator::isEmail($strEmail))
  371.             {
  372.                 $arrEmails[] = $strEmail;
  373.             }
  374.         }
  376.         unset($strEmail);
  378.         // Encode opening arrow brackets (see #3998)
  379.         $strString = preg_replace_callback('@</?([^\s<>/]*)@', static function ($matches) use ($strAllowedTags)
  380.         {
  381.             if (!$matches[1] || stripos($strAllowedTags, '<' . strtolower($matches[1]) . '>') === false)
  382.             {
  383.                 $matches[0] = str_replace('<', '&lt;', $matches[0]);
  384.             }
  386.             return $matches[0];
  387.         }, $strString);
  389.         // Find all addresses in the plain text
  390.         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);
  392.         foreach ($matches[0] as &$strEmail)
  393.         {
  394.             $strEmail = str_replace('&lt;', '<', $strEmail);
  396.             if (Validator::isEmail($strEmail))
  397.             {
  398.                 $arrEmails[] = $strEmail;
  399.             }
  400.         }
  402.         return array_unique($arrEmails);
  403.     }
  405.     /**
  406.      * Split a friendly-name e-mail address and return name and e-mail as array
  407.      *
  408.      * @param string $strEmail A friendly-name e-mail address
  409.      *
  410.      * @return array An array with name and e-mail address
  411.      */
  412.     public static function splitFriendlyEmail($strEmail)
  413.     {
  414.         if (strpos($strEmail, '<') !== false)
  415.         {
  416.             return array_map('trim', explode(' <', str_replace('>', '', $strEmail)));
  417.         }
  419.         if (strpos($strEmail, '[') !== false)
  420.         {
  421.             return array_map('trim', explode(' [', str_replace(']', '', $strEmail)));
  422.         }
  424.         return array('', $strEmail);
  425.     }
  427.     /**
  428.      * Wrap words after a particular number of characers
  429.      *
  430.      * @param string  $strString The string to wrap
  431.      * @param integer $strLength The number of characters to wrap after
  432.      * @param string  $strBreak  An optional break character
  433.      *
  434.      * @return string The wrapped string
  435.      */
  436.     public static function wordWrap($strString, $strLength=75, $strBreak="\n")
  437.     {
  438.         return wordwrap($strString, $strLength, $strBreak);
  439.     }
  441.     /**
  442.      * Highlight a phrase within a string
  443.      *
  444.      * @param string $strString     The string
  445.      * @param string $strPhrase     The phrase to highlight
  446.      * @param string $strOpeningTag The opening tag (defaults to <strong>)
  447.      * @param string $strClosingTag The closing tag (defaults to </strong>)
  448.      *
  449.      * @return string The highlighted string
  450.      */
  451.     public static function highlight($strString, $strPhrase, $strOpeningTag='<strong>', $strClosingTag='</strong>')
  452.     {
  453.         if (!$strString || !$strPhrase)
  454.         {
  455.             return $strString;
  456.         }
  458.         return preg_replace('/(' . preg_quote($strPhrase, '/') . ')/i', $strOpeningTag . '\\1' . $strClosingTag, $strString);
  459.     }
  461.     /**
  462.      * Split a string of comma separated values
  463.      *
  464.      * @param string $strString    The string to split
  465.      * @param string $strDelimiter An optional delimiter
  466.      *
  467.      * @return array The string chunks
  468.      */
  469.     public static function splitCsv($strString, $strDelimiter=',')
  470.     {
  471.         $arrValues = preg_split('/' . $strDelimiter . '(?=(?:[^"]*"[^"]*")*(?![^"]*"))/', $strString);
  473.         foreach ($arrValues as $k=>$v)
  474.         {
  475.             $arrValues[$k] = trim($v, ' "');
  476.         }
  478.         return $arrValues;
  479.     }
  481.     /**
  482.      * Convert a string to XHTML
  483.      *
  484.      * @param string $strString The HTML5 string
  485.      *
  486.      * @return string The XHTML string
  487.      */
  488.     public static function toXhtml($strString)
  489.     {
  490.         $arrPregReplace = array
  491.         (
  492.             '/<(br|hr|img)([^>]*)>/i' => '<$1$2 />', // Close stand-alone tags
  493.             '/ border="[^"]*"/'       => ''          // Remove deprecated attributes
  494.         );
  496.         $arrStrReplace = array
  497.         (
  498.             '/ />'             => ' />',        // Fix incorrectly closed tags
  499.             '<b>'              => '<strong>',   // Replace <b> with <strong>
  500.             '</b>'             => '</strong>',
  501.             '<i>'              => '<em>',       // Replace <i> with <em>
  502.             '</i>'             => '</em>',
  503.             '<u>'              => '<span style="text-decoration:underline">',
  504.             '</u>'             => '</span>',
  505.             ' target="_self"'  => '',
  506.             ' target="_blank"' => ' onclick="return !window.open(this.href)"'
  507.         );
  509.         $strString = preg_replace(array_keys($arrPregReplace), $arrPregReplace, $strString);
  510.         $strString = str_ireplace(array_keys($arrStrReplace), $arrStrReplace, $strString);
  512.         return $strString;
  513.     }
  515.     /**
  516.      * Convert a string to HTML5
  517.      *
  518.      * @param string $strString The XHTML string
  519.      *
  520.      * @return string The HTML5 string
  521.      */
  522.     public static function toHtml5($strString)
  523.     {
  524.         $arrPregReplace = array
  525.         (
  526.             '/<(br|hr|img)([^>]*) \/>/i'                  => '<$1$2>',             // Close stand-alone tags
  527.             '/ (cellpadding|cellspacing|border)="[^"]*"/' => '',                   // Remove deprecated attributes
  528.             '/ rel="lightbox(\[([^\]]+)\])?"/'            => ' data-lightbox="$2"' // see #4073
  529.         );
  531.         $arrStrReplace = array
  532.         (
  533.             '<u>'                                              => '<span style="text-decoration:underline">',
  534.             '</u>'                                             => '</span>',
  535.             ' target="_self"'                                  => '',
  536.             ' onclick="window.open(this.href); return false"'  => ' target="_blank"',
  537.             ' onclick="window.open(this.href);return false"'   => ' target="_blank"',
  538.             ' onclick="window.open(this.href); return false;"' => ' target="_blank"'
  539.         );
  541.         $strString = preg_replace(array_keys($arrPregReplace), $arrPregReplace, $strString);
  542.         $strString = str_ireplace(array_keys($arrStrReplace), $arrStrReplace, $strString);
  544.         return $strString;
  545.     }
  547.     /**
  548.      * Parse simple tokens
  549.      *
  550.      * @param string $strString    The string to be parsed
  551.      * @param array  $arrData      The replacement data
  552.      * @param array  $blnAllowHtml Whether HTML should be decoded inside conditions
  553.      *
  554.      * @return string The converted string
  555.      *
  556.      * @throws \RuntimeException         If $strString cannot be parsed
  557.      * @throws \InvalidArgumentException If there are incorrectly formatted if-tags
  558.      *
  559.      * @deprecated Deprecated since Contao 4.10, to be removed in Contao 5.
  560.      *             Use the SimpleTokenParser::class service instead.
  561.      */
  562.     public static function parseSimpleTokens($strString, $arrData, $blnAllowHtml = true)
  563.     {
  564.         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 "SimpleTokenParser::class" service instead.');
  566.         return System::getContainer()->get(SimpleTokenParser::class)->parse($strString, $arrData, $blnAllowHtml);
  567.     }
  569.     /**
  570.      * Convert a UUID string to binary data
  571.      *
  572.      * @param string $uuid The UUID string
  573.      *
  574.      * @return string The binary data
  575.      */
  576.     public static function uuidToBin($uuid)
  577.     {
  578.         return hex2bin(str_replace('-', '', $uuid));
  579.     }
  581.     /**
  582.      * Get a UUID string from binary data
  583.      *
  584.      * @param string $data The binary data
  585.      *
  586.      * @return string The UUID string
  587.      */
  588.     public static function binToUuid($data)
  589.     {
  590.         return implode('-', unpack('H8time_low/H4time_mid/H4time_high/H4clock_seq/H12node', $data));
  591.     }
  593.     /**
  594.      * Convert file paths inside "src" attributes to insert tags
  595.      *
  596.      * @param string $data The markup string
  597.      *
  598.      * @return string The markup with file paths converted to insert tags
  599.      */
  600.     public static function srcToInsertTag($data)
  601.     {
  602.         $return = '';
  603.         $paths = preg_split('/((src|href)="([^"]+)")/i', $data, -1, PREG_SPLIT_DELIM_CAPTURE);
  605.         for ($i=0, $c=\count($paths); $i<$c; $i+=4)
  606.         {
  607.             $return .= $paths[$i];
  609.             if (!isset($paths[$i+1]))
  610.             {
  611.                 continue;
  612.             }
  614.             $file = FilesModel::findByPath($paths[$i+3]);
  616.             if ($file !== null)
  617.             {
  618.                 $return .= $paths[$i+2] . '="{{file::' . static::binToUuid($file->uuid) . '}}"';
  619.             }
  620.             else
  621.             {
  622.                 $return .= $paths[$i+2] . '="' . $paths[$i+3] . '"';
  623.             }
  624.         }
  626.         return $return;
  627.     }
  629.     /**
  630.      * Convert insert tags inside "src" attributes to file paths
  631.      *
  632.      * @param string $data The markup string
  633.      *
  634.      * @return string The markup with insert tags converted to file paths
  635.      */
  636.     public static function insertTagToSrc($data)
  637.     {
  638.         $return = '';
  639.         $paths = preg_split('/((src|href)="([^"]*){{file::([^"}|]+)[^"}]*}}")/i', $data, -1, PREG_SPLIT_DELIM_CAPTURE);
  641.         for ($i=0, $c=\count($paths); $i<$c; $i+=5)
  642.         {
  643.             $return .= $paths[$i];
  645.             if (!isset($paths[$i+1]))
  646.             {
  647.                 continue;
  648.             }
  650.             $file = FilesModel::findByUuid($paths[$i+4]);
  652.             if ($file !== null)
  653.             {
  654.                 $return .= $paths[$i+2] . '="' . $paths[$i+3] . $file->path . '"';
  655.             }
  656.             else
  657.             {
  658.                 $return .= $paths[$i+2] . '="' . $paths[$i+3] . $paths[$i+4] . '"';
  659.             }
  660.         }
  662.         return $return;
  663.     }
  665.     /**
  666.      * Sanitize a file name
  667.      *
  668.      * @param string $strName The file name
  669.      *
  670.      * @return string The sanitized file name
  671.      */
  672.     public static function sanitizeFileName($strName)
  673.     {
  674.         // Remove invisible control characters and unused code points
  675.         $strName = preg_replace('/[\pC]/u', '', $strName);
  677.         if ($strName === null)
  678.         {
  679.             throw new \InvalidArgumentException('The file name could not be sanitzied');
  680.         }
  682.         // Remove special characters not supported on e.g. Windows
  683.         $strName = str_replace(array('\\', '/', ':', '*', '?', '"', '<', '>', '|'), '-', $strName);
  685.         return $strName;
  686.     }
  688.     /**
  689.      * Resolve a flagged URL such as assets/js/core.js|static|10184084
  690.      *
  691.      * @param string $url The URL
  692.      *
  693.      * @return \stdClass The options object
  694.      */
  695.     public static function resolveFlaggedUrl(&$url)
  696.     {
  697.         $options = new \stdClass();
  699.         // Defaults
  700.         $options->static = false;
  701.         $options->media  = null;
  702.         $options->mtime  = null;
  703.         $options->async  = false;
  705.         $chunks = explode('|', $url);
  707.         // Remove the flags from the URL
  708.         $url = $chunks[0];
  710.         for ($i=1, $c=\count($chunks); $i<$c; $i++)
  711.         {
  712.             if (empty($chunks[$i]))
  713.             {
  714.                 continue;
  715.             }
  717.             switch ($chunks[$i])
  718.             {
  719.                 case 'static':
  720.                     $options->static = true;
  721.                     break;
  723.                 case 'async':
  724.                     $options->async = true;
  725.                     break;
  727.                 case is_numeric($chunks[$i]):
  728.                     $options->mtime = $chunks[$i];
  729.                     break;
  731.                 default:
  732.                     $options->media = $chunks[$i];
  733.                     break;
  734.             }
  735.         }
  737.         return $options;
  738.     }
  740.     /**
  741.      * Convert the character encoding
  742.      *
  743.      * @param string $str  The input string
  744.      * @param string $to   The target character set
  745.      * @param string $from An optional source character set
  746.      *
  747.      * @return string The converted string
  748.      */
  749.     public static function convertEncoding($str, $to, $from=null)
  750.     {
  751.         if ($str !== null && !is_scalar($str) && !(\is_object($str) && method_exists($str, '__toString')))
  752.         {
  753.             @trigger_error('Passing a non-stringable argument to StringUtil::convertEncoding() has been deprecated an will no longer work in Contao 5.0.', E_USER_DEPRECATED);
  755.             return '';
  756.         }
  758.         $str = (string) $str;
  760.         if ('' === $str)
  761.         {
  762.             return $str;
  763.         }
  765.         if (!$from)
  766.         {
  767.             $from = mb_detect_encoding($str, 'ASCII,ISO-2022-JP,UTF-8,EUC-JP,ISO-8859-1');
  768.         }
  770.         if ($from == $to)
  771.         {
  772.             return $str;
  773.         }
  775.         if ($from == 'UTF-8' && $to == 'ISO-8859-1')
  776.         {
  777.             return utf8_decode($str);
  778.         }
  780.         if ($from == 'ISO-8859-1' && $to == 'UTF-8')
  781.         {
  782.             return utf8_encode($str);
  783.         }
  785.         return mb_convert_encoding($str, $to, $from);
  786.     }
  788.     /**
  789.      * Convert special characters to HTML entities preventing double conversions
  790.      *
  791.      * @param string  $strString          The input string
  792.      * @param boolean $blnStripInsertTags True to strip insert tags
  793.      * @param boolean $blnDoubleEncode    True to encode existing html entities
  794.      *
  795.      * @return string The converted string
  796.      */
  797.     public static function specialchars($strString, $blnStripInsertTags=false, $blnDoubleEncode=false)
  798.     {
  799.         if ($blnStripInsertTags)
  800.         {
  801.             $strString = static::stripInsertTags($strString);
  802.         }
  804.         return htmlspecialchars((string) $strString, ENT_QUOTES, $GLOBALS['TL_CONFIG']['characterSet'] ?? 'UTF-8', $blnDoubleEncode);
  805.     }
  807.     /**
  808.      * Encodes specialchars and nested insert tags for attributes
  809.      *
  810.      * @param string  $strString          The input string
  811.      * @param boolean $blnStripInsertTags True to strip insert tags
  812.      * @param boolean $blnDoubleEncode    True to encode existing html entities
  813.      *
  814.      * @return string The converted string
  815.      */
  816.     public static function specialcharsAttribute($strString, $blnStripInsertTags=false, $blnDoubleEncode=false)
  817.     {
  818.         $strString = self::specialchars($strString, $blnStripInsertTags, $blnDoubleEncode);
  820.         // Improve compatibility with JSON in attributes if no insert tags are present
  821.         if ($strString === self::stripInsertTags($strString))
  822.         {
  823.             $strString = str_replace('}}', '&#125;&#125;', $strString);
  824.         }
  826.         // Encode insert tags too
  827.         $strString = preg_replace('/(?:\|attr)?}}/', '|attr}}', $strString);
  828.         $strString = str_replace('|urlattr|attr}}', '|urlattr}}', $strString);
  830.         // Encode all remaining single closing curly braces
  831.         $strString = preg_replace_callback(
  832.             '/}}?/',
  833.             static function ($match)
  834.             {
  835.                 return \strlen($match[0]) === 2 ? $match[0] : '&#125;';
  836.             },
  837.             $strString
  838.         );
  840.         return $strString;
  841.     }
  843.     /**
  844.      * Encodes disallowed protocols and specialchars for URL attributes
  845.      *
  846.      * @param string  $strString          The input string
  847.      * @param boolean $blnStripInsertTags True to strip insert tags
  848.      * @param boolean $blnDoubleEncode    True to encode existing html entities
  849.      *
  850.      * @return string The converted string
  851.      */
  852.     public static function specialcharsUrl($strString, $blnStripInsertTags=false, $blnDoubleEncode=false)
  853.     {
  854.         $strString = self::specialchars($strString, $blnStripInsertTags, $blnDoubleEncode);
  856.         // Encode insert tags too
  857.         $strString = preg_replace('/(?:\|urlattr|\|attr)?}}/', '|urlattr}}', $strString);
  859.         // Encode all remaining single closing curly braces
  860.         $strString = preg_replace_callback(
  861.             '/}}?/',
  862.             static function ($match)
  863.             {
  864.                 return \strlen($match[0]) === 2 ? $match[0] : '&#125;';
  865.             },
  866.             $strString
  867.         );
  869.         $colonRegEx = '('
  870.             . ':'                 // Plain text colon
  871.             . '|'                 // OR
  872.             . '&colon;'           // Named entity
  873.             . '|'                 // OR
  874.             . '&#(?:'             // Start of entity
  875.                 . 'x0*+3a'        // Hex number 3A
  876.                 . '(?![0-9a-f])'  // Must not be followed by another hex digit
  877.                 . '|'             // OR
  878.                 . '0*+58'         // Decimal number 58
  879.                 . '(?![0-9])'     // Must not be followed by another digit
  880.             . ');?'               // Optional semicolon
  881.         . ')i';
  883.         // URL-encode colon to prevent disallowed protocols
  884.         if (
  885.             !preg_match('@^(?:https?|ftp|mailto|tel|data):@i', self::decodeEntities($strString))
  886.             && preg_match($colonRegEx, self::stripInsertTags($strString))
  887.         ) {
  888.             $strString = preg_replace($colonRegEx, '%3A', $strString);
  889.         }
  891.         return $strString;
  892.     }
  894.     /**
  895.      * Remove Contao insert tags from a string
  896.      *
  897.      * @param string $strString The input string
  898.      *
  899.      * @return string The converted string
  900.      */
  901.     public static function stripInsertTags($strString)
  902.     {
  903.         $count = 0;
  905.         do
  906.         {
  907.             $strString = preg_replace('/{{[^{}]*}}/', '', $strString, -1, $count);
  908.         } while ($count > 0);
  910.         return $strString;
  911.     }
  913.     /**
  914.      * Standardize a parameter (strip special characters and convert spaces)
  915.      *
  916.      * @param string  $strString            The input string
  917.      * @param boolean $blnPreserveUppercase True to preserver uppercase characters
  918.      *
  919.      * @return string The converted string
  920.      */
  921.     public static function standardize($strString, $blnPreserveUppercase=false)
  922.     {
  923.         $arrSearch = array('/[^\pN\pL \.\&\/_-]+/u', '/[ \.\&\/-]+/');
  924.         $arrReplace = array('', '-');
  926.         $strString = html_entity_decode($strString, ENT_QUOTES, $GLOBALS['TL_CONFIG']['characterSet'] ?? 'UTF-8');
  927.         $strString = static::stripInsertTags($strString);
  928.         $strString = preg_replace($arrSearch, $arrReplace, $strString);
  930.         if (is_numeric(substr($strString, 0, 1)))
  931.         {
  932.             $strString = 'id-' . $strString;
  933.         }
  935.         if (!$blnPreserveUppercase)
  936.         {
  937.             $strString = Utf8::strtolower($strString);
  938.         }
  940.         return trim($strString, '-');
  941.     }
  943.     /**
  944.      * Return an unserialized array or the argument
  945.      *
  946.      * @param mixed   $varValue      The serialized string
  947.      * @param boolean $blnForceArray True to always return an array
  948.      *
  949.      * @return mixed The unserialized array or the unprocessed input value
  950.      */
  951.     public static function deserialize($varValue, $blnForceArray=false)
  952.     {
  953.         // Already an array
  954.         if (\is_array($varValue))
  955.         {
  956.             return $varValue;
  957.         }
  959.         // Null
  960.         if ($varValue === null)
  961.         {
  962.             return $blnForceArray ? array() : null;
  963.         }
  965.         // Not a string
  966.         if (!\is_string($varValue))
  967.         {
  968.             return $blnForceArray ? array($varValue) : $varValue;
  969.         }
  971.         // Empty string
  972.         if (trim($varValue) === '')
  973.         {
  974.             return $blnForceArray ? array() : '';
  975.         }
  977.         // Not a serialized array (see #1486)
  978.         if (strncmp($varValue, 'a:', 2) !== 0)
  979.         {
  980.             return $blnForceArray ? array($varValue) : $varValue;
  981.         }
  983.         // Potentially including an object (see #6724)
  984.         if (preg_match('/[OoC]:\+?[0-9]+:"/', $varValue))
  985.         {
  986.             trigger_error('StringUtil::deserialize() does not allow serialized objects', E_USER_WARNING);
  988.             return $blnForceArray ? array($varValue) : $varValue;
  989.         }
  991.         $varUnserialized = @unserialize($varValue, array('allowed_classes' => false));
  993.         if (\is_array($varUnserialized))
  994.         {
  995.             $varValue = $varUnserialized;
  996.         }
  997.         elseif ($blnForceArray)
  998.         {
  999.             $varValue = array($varValue);
  1000.         }
  1002.         return $varValue;
  1003.     }
  1005.     /**
  1006.      * Split a string into fragments, remove whitespace and return fragments as array
  1007.      *
  1008.      * @param string $strPattern The split pattern
  1009.      * @param string $strString  The input string
  1010.      *
  1011.      * @return array The fragments array
  1012.      */
  1013.     public static function trimsplit($strPattern, $strString)
  1014.     {
  1015.         // Split
  1016.         if (\strlen($strPattern) == 1)
  1017.         {
  1018.             $arrFragments = array_map('trim', explode($strPattern, $strString));
  1019.         }
  1020.         else
  1021.         {
  1022.             $arrFragments = array_map('trim', preg_split('/' . $strPattern . '/ui', $strString));
  1023.         }
  1025.         // Empty array
  1026.         if (\count($arrFragments) < 2 && !\strlen($arrFragments[0]))
  1027.         {
  1028.             $arrFragments = array();
  1029.         }
  1031.         return $arrFragments;
  1032.     }
  1034.     /**
  1035.      * Strip the Contao root dir from the given absolute path
  1036.      *
  1037.      * @param string $path
  1038.      *
  1039.      * @return string
  1040.      *
  1041.      * @throws \InvalidArgumentException
  1042.      */
  1043.     public static function stripRootDir($path)
  1044.     {
  1045.         // Compare normalized version of the paths
  1046.         $projectDir = Path::normalize(System::getContainer()->getParameter('kernel.project_dir'));
  1047.         $normalizedPath = Path::normalize($path);
  1048.         $length = \strlen($projectDir);
  1050.         if (strncmp($normalizedPath, $projectDir, $length) !== 0 || \strlen($normalizedPath) <= $length || $normalizedPath[$length] !== '/')
  1051.         {
  1052.             throw new \InvalidArgumentException(sprintf('Path "%s" is not inside the Contao root dir "%s"', $path, $projectDir));
  1053.         }
  1055.         return (string) substr($path, $length + 1);
  1056.     }
  1058.     /**
  1059.      * Convert all ampersands into their HTML entity (default) or unencoded value
  1060.      *
  1061.      * @param string  $strString
  1062.      * @param boolean $blnEncode
  1063.      *
  1064.      * @return string
  1065.      */
  1066.     public static function ampersand($strString, $blnEncode=true): string
  1067.     {
  1068.         return preg_replace('/&(amp;)?/i', ($blnEncode ? '&amp;' : '&'), $strString);
  1069.     }
  1071.     /**
  1072.      * Convert an input-encoded string back to the raw UTF-8 value it originated from
  1073.      *
  1074.      * It handles all Contao input encoding specifics like basic entities and encoded entities.
  1075.      */
  1076.     public static function revertInputEncoding(string $strValue): string
  1077.     {
  1078.         $strValue = static::restoreBasicEntities($strValue);
  1079.         $strValue = static::decodeEntities($strValue);
  1081.         // Ensure valid UTF-8
  1082.         if (preg_match('//u', $strValue) !== 1)
  1083.         {
  1084.             $substituteCharacter = mb_substitute_character();
  1085.             mb_substitute_character(0xFFFD);
  1087.             $strValue = mb_convert_encoding($strValue, 'UTF-8', 'UTF-8');
  1089.             mb_substitute_character($substituteCharacter);
  1090.         }
  1092.         return $strValue;
  1093.     }
  1095.     /**
  1096.      * Convert an input-encoded string to plain text UTF-8
  1097.      *
  1098.      * Strips or replaces insert tags, strips HTML tags, decodes entities, escapes insert tag braces.
  1099.      *
  1100.      * @see StringUtil::revertInputEncoding()
  1101.      *
  1102.      * @param bool $blnRemoveInsertTags True to remove insert tags instead of replacing them
  1103.      */
  1104.     public static function inputEncodedToPlainText(string $strValue, bool $blnRemoveInsertTags = false): string
  1105.     {
  1106.         if ($blnRemoveInsertTags)
  1107.         {
  1108.             $strValue = static::stripInsertTags($strValue);
  1109.         }
  1110.         else
  1111.         {
  1112.             $strValue = Controller::replaceInsertTags($strValue, false);
  1113.         }
  1115.         $strValue = strip_tags($strValue);
  1116.         $strValue = static::revertInputEncoding($strValue);
  1117.         $strValue = str_replace(array('{{', '}}'), array('[{]', '[}]'), $strValue);
  1119.         return $strValue;
  1120.     }
  1122.     /**
  1123.      * Convert an HTML string to plain text with normalized white space
  1124.      *
  1125.      * It handles all Contao input encoding specifics like insert tags, basic
  1126.      * entities and encoded entities and is meant to be used with content from
  1127.      * fields that have the allowHtml flag enabled.
  1128.      *
  1129.      * @see StringUtil::inputEncodedToPlainText()
  1130.      *
  1131.      * @param bool $blnRemoveInsertTags True to remove insert tags instead of replacing them
  1132.      */
  1133.     public static function htmlToPlainText(string $strValue, bool $blnRemoveInsertTags = false): string
  1134.     {
  1135.         if (!$blnRemoveInsertTags)
  1136.         {
  1137.             $strValue = Controller::replaceInsertTags($strValue, false);
  1138.         }
  1140.         // Add new lines before and after block level elements
  1141.         $strValue = preg_replace(
  1142.             array('/[\r\n]+/', '/<\/?(?:br|blockquote|div|dl|figcaption|figure|footer|h\d|header|hr|li|p|pre|tr)\b/i'),
  1143.             array(' ', "\n$0"),
  1144.             $strValue
  1145.         );
  1147.         $strValue = static::inputEncodedToPlainText($strValue, true);
  1149.         // Remove duplicate line breaks and spaces
  1150.         $strValue = trim(preg_replace(array('/[^\S\n]+/', '/\s*\n\s*/'), array(' ', "\n"), $strValue));
  1152.         return $strValue;
  1153.     }
  1154. }
  1156. class_alias(StringUtil::class, 'StringUtil');