1610 lines
57 KiB
PHP
1610 lines
57 KiB
PHP
<?php namespace ProcessWire;
|
||
|
||
/**
|
||
* ProcessWire Text Tools
|
||
*
|
||
* #pw-summary Specific text and markup tools for ProcessWire $sanitizer and elsewhere.
|
||
*
|
||
* ProcessWire 3.x, Copyright 2020 by Ryan Cramer
|
||
* https://processwire.com
|
||
*
|
||
* @since 3.0.101
|
||
*
|
||
* @method array wordAlternates($word, array $options = array()) Protected method for hooking purposes only #pw-hooker #pw-internal
|
||
* @method string wordStem($word) Protected method for hooking purposes only #pw-hooker #pw-internal
|
||
*
|
||
*/
|
||
|
||
class WireTextTools extends Wire {
|
||
|
||
/**
|
||
* mbstring support?
|
||
*
|
||
* @var bool
|
||
*
|
||
*/
|
||
protected $mb;
|
||
|
||
/**
|
||
* Construct
|
||
*
|
||
*/
|
||
public function __construct() {
|
||
$this->mb = function_exists("mb_internal_encoding");
|
||
parent::__construct();
|
||
}
|
||
|
||
/**
|
||
* Convert HTML markup to readable text
|
||
*
|
||
* Like PHP’s strip_tags but with some small improvements in HTML-to-text conversion that
|
||
* improves the readability of the text.
|
||
*
|
||
* In 3.0.197+ inner content of script, style and object tags is now removed, rather than just the tags.
|
||
* To revert this behavior or to remove content of additional tags, see the `clearTags` option.
|
||
*
|
||
* Note that this method differs from the `Sanitizer::markupToText()` method in that this method is newer,
|
||
* more powerful and has more options. But the two methods differ in how they perform markup-to-text
|
||
* conversion so you may want to review and try both to determine which one better suits your needs.
|
||
*
|
||
* @param string $str String to convert to text
|
||
* @param array $options
|
||
* - `keepTags` (array): Tag names to keep in returned value, i.e. [ "em", "strong" ]. (default=none)
|
||
* - `clearTags` (array): Tags that should also have their content cleared. (default=[ "script", "style", "object" ]) Since 3.0.197
|
||
* - `splitBlocks` (string): String to split paragraph and header elements. (default="\n\n")
|
||
* - `convertEntities` (bool): Convert HTML entities to plain text equivalents? (default=true)
|
||
* - `listItemPrefix` (string): Prefix for converted list item `<li>` elements. (default='• ')
|
||
* - `linksToUrls` (bool): Convert links to `(url)` rather than removing? (default=true) Since 3.0.132
|
||
* - `linksToMarkdown` (bool): Convert links to `[text](url)` rather than removing? (default=false) Since 3.0.197
|
||
* - `uppercaseHeadlines` (bool): Convert headline tags to uppercase? (default=false) Since 3.0.132
|
||
* - `underlineHeadlines` (bool): Underline headlines with "=" or "-"? (default=true) Since 3.0.132
|
||
* - `collapseSpaces` (bool): Collapse extra/redundant extra spaces to single space? (default=true) Since 3.0.132
|
||
* - `replacements` (array): Associative array of strings to manually replace. (default=[' ' => ' '])
|
||
* @return string
|
||
* @see Sanitizer::markupToText()
|
||
*
|
||
*/
|
||
public function markupToText($str, array $options = array()) {
|
||
|
||
$sanitizer = $this->wire()->sanitizer;
|
||
|
||
$defaults = array(
|
||
'keepTags' => array(),
|
||
'clearTags' => array('script', 'style', 'object'),
|
||
'linksToUrls' => true, // convert links to just URL rather than removing entirely
|
||
'linksToMarkdown' => false, // convert links to Markdown style links
|
||
'splitBlocks' => "\n\n",
|
||
'uppercaseHeadlines' => false,
|
||
'underlineHeadlines' => true,
|
||
'convertEntities' => true,
|
||
'listItemPrefix' => '• ',
|
||
'preIndent' => '', // indent for text within a <pre>
|
||
'collapseSpaces' => true,
|
||
'replacements' => array(
|
||
' ' => ' '
|
||
),
|
||
'finishReplacements' => array(), // replacements applied at very end (internal)
|
||
);
|
||
|
||
$str = (string) $str;
|
||
if(!strlen($str)) return '';
|
||
|
||
// merge options using arrays
|
||
foreach(array('replacements') as $key) {
|
||
if(!isset($options[$key])) continue;
|
||
$options[$key] = array_merge($defaults[$key], $options[$key]);
|
||
}
|
||
|
||
$options = array_merge($defaults, $options);
|
||
|
||
if(strpos($str, '>') !== false) {
|
||
|
||
// strip out everything up to and including </head>, if present
|
||
if(strpos($str, '</head>') !== false) list(, $str) = explode('</head>', $str);
|
||
|
||
// ensure tags are separated by whitespace
|
||
$str = str_replace('><', '> <', $str);
|
||
|
||
// normalize newlines
|
||
if(strpos($str, "\r") !== false) {
|
||
$str = str_replace(array("\r\n", "\r"), "\n", $str);
|
||
}
|
||
|
||
// normalize tabs to spaces
|
||
if(strpos($str, "\t") !== false) {
|
||
$str = str_replace("\t", " ", $str);
|
||
}
|
||
|
||
// ensure paragraphs and headers are followed by two newlines
|
||
if(stripos($str, '</p') || stripos($str, '</h') || stripos($str, '</li') || stripos($str, '</bl') || stripos($str, '</div')) {
|
||
$str = preg_replace('!(</?(?:p|h\d|ul|ol|pre|blockquote|div)>)!i', '$1' . $options['splitBlocks'], $str);
|
||
}
|
||
|
||
// ensure list items are on their own line and prefixed with a bullet
|
||
if(stripos($str, '<li') !== false) {
|
||
$prefix = in_array('li', $options['keepTags']) ? '' : $options['listItemPrefix'];
|
||
$str = preg_replace('![\s\r\n]+<li[^>]*>[\s\r\n]*!i', "\n<li>$prefix", $str);
|
||
if($prefix) {
|
||
$options['replacements']["\n$prefix "] = "\n$prefix"; // prevent extra space
|
||
$prefix = trim($prefix);
|
||
$options['finishReplacements']["\n$prefix\n$prefix"] = ""; // prevent blank items
|
||
$options['finishReplacements']["\n$prefix\n"] = "";
|
||
|
||
}
|
||
}
|
||
|
||
// convert <br> tags to be just a single newline
|
||
if(stripos($str, '<br') !== false) {
|
||
$str = str_replace(array('<br>', '<br/>', '<br />', '</li>'), "<br>\n", $str);
|
||
while(stripos($str, "\n<br>") !== false) $str = str_replace("\n<br>", "<br>", $str);
|
||
while(stripos($str, "<br>\n\n") !== false) $str = str_replace("<br>\n\n", "<br>\n", $str);
|
||
}
|
||
|
||
// make headlines more prominent with underlines or uppercase
|
||
if(($options['uppercaseHeadlines'] || $options['underlineHeadlines']) && stripos($str, '<h') !== false) {
|
||
$topHtag = '';
|
||
if($options['underlineHeadlines']) {
|
||
// determine which is the top level headline tag
|
||
for($n = 1; $n <= 6; $n++) {
|
||
if(stripos($str, "<h$n") === false) continue;
|
||
$topHtag = "h$n";
|
||
break;
|
||
}
|
||
}
|
||
if(preg_match_all('!<(h[123456])[^>]*>(.+?)</\1>!is', $str, $matches)) {
|
||
foreach($matches[2] as $key => $headline) {
|
||
$fullMatch = $matches[0][$key];
|
||
$tagName = strtolower($matches[1][$key]);
|
||
$underline = '';
|
||
//$headline = trim($headline);
|
||
if($options['underlineHeadlines']) {
|
||
$char = $tagName === $topHtag ? '=' : '-';
|
||
$underline = "\n" . str_repeat($char, $this->strlen(trim(strip_tags($headline))));
|
||
}
|
||
if($options['uppercaseHeadlines']) $headline = strtoupper($headline);
|
||
$str = str_replace($fullMatch, "\n\n<$tagName>$headline</$tagName>$underline", $str);
|
||
}
|
||
}
|
||
}
|
||
|
||
// convert "<a href='url'>text</a>" tags to "text (url)"
|
||
if(($options['linksToUrls'] || $options['linksToMarkdown']) && stripos($str, '<a ') !== false) {
|
||
if(preg_match_all('!<a\s[^<>]*href=([^\s>]+)[^<>]*>(.+?)</a>!is', $str, $matches)) {
|
||
$links = array();
|
||
foreach($matches[0] as $key => $fullMatch) {
|
||
$href = trim($matches[1][$key], '"\'');
|
||
if(strpos($href, '#') === 0) continue; // do not convert jumplinks
|
||
$anchorText = trim($matches[2][$key]);
|
||
$links[$fullMatch] = "[$anchorText]($href)";
|
||
}
|
||
if(count($links)) {
|
||
$str = str_replace(array_keys($links), array_values($links), $str);
|
||
}
|
||
unset($links);
|
||
}
|
||
}
|
||
|
||
// indent within <pre>...</pre> sections
|
||
if(strlen($options['preIndent']) && strpos($str, '<pre') !== false) {
|
||
if(preg_match_all('!<pre(?:>|\s[^>]*>)(.+?)</pre>!is', $str, $matches)) {
|
||
foreach($matches[0] as $key => $fullMatch) {
|
||
$lines = explode("\n", $matches[1][$key]);
|
||
foreach($lines as $k => $line) {
|
||
$lines[$k] = ':preIndent:' . rtrim($line);
|
||
}
|
||
$str = str_replace($fullMatch, implode("\n", $lines), $str);
|
||
$options['finishReplacements'][':preIndent:'] = $options['preIndent'];
|
||
unset($lines);
|
||
}
|
||
}
|
||
}
|
||
|
||
// strip tags AND their contents for specified tags
|
||
foreach($options['clearTags'] as $s) {
|
||
$s = strtolower($s);
|
||
if(stripos($str, "<$s") === false) continue;
|
||
$str = str_ireplace(array("<$s", "</$s"), array("<$s", "</$s"), $str); // adjust case
|
||
$parts = explode("<$s", $str);
|
||
foreach($parts as $key => $part) {
|
||
if(strpos($part, "</$s>") === false) {
|
||
if($key > 0) unset($parts[$key]); // remove nested inner content
|
||
} else {
|
||
$endparts = explode("</$s>", $part);
|
||
$parts[$key] = array_pop($endparts); // convert to content after last </s>
|
||
}
|
||
}
|
||
$str = implode("", $parts);
|
||
unset($parts, $endparts, $s);
|
||
}
|
||
}
|
||
|
||
// strip tags
|
||
if(count($options['keepTags'])) {
|
||
// some tags will be allowed to remain
|
||
$keepTags = '';
|
||
foreach($options['keepTags'] as $tag) {
|
||
$keepTags .= "<" . trim($tag, "<>") . ">";
|
||
}
|
||
$str = strip_tags($str, $keepTags);
|
||
|
||
} else {
|
||
// not allowing any tags
|
||
$str = strip_tags($str);
|
||
// if any possible tag characters remain, drop them now
|
||
$str = str_replace(array('<', '>'), ' ', $str);
|
||
}
|
||
|
||
// apply any other replacements
|
||
foreach($options['replacements'] as $find => $replace) {
|
||
$str = str_ireplace($find, $replace, $str);
|
||
}
|
||
|
||
// convert entities to plain text equivalents
|
||
if($options['convertEntities'] && strpos($str, '&') !== false) {
|
||
$str = $sanitizer->unentities($str);
|
||
}
|
||
|
||
// collapse any redundant/extra whitespace
|
||
if($options['collapseSpaces']) {
|
||
while(strpos($str, ' ') !== false) $str = str_replace(' ', ' ', $str);
|
||
}
|
||
|
||
// normalize newlines and whitespace around newlines
|
||
while(strpos($str, " \n") !== false) $str = str_replace(" \n", "\n", $str);
|
||
while(strpos($str, "\n ") !== false) $str = str_replace("\n ", "\n", $str);
|
||
while(strpos($str, "\n\n\n") !== false) $str = str_replace("\n\n\n", "\n\n", $str);
|
||
|
||
if(strpos($str, '](')) {
|
||
// contains links
|
||
if(strpos($str, '[](') !== false || strpos($str, '[ ](') !== false) {
|
||
// remove links that lack anchor text
|
||
$str = preg_replace('!\[\s*\]\([^)]*\)!', '', $str);
|
||
}
|
||
if($options['linksToUrls']) {
|
||
// convert markdown style "[text](url)" to "text (url)"
|
||
if(!$options['linksToMarkdown']) $str = preg_replace('!\[\s*(.+?)\]\(!', '$1 (', $str);
|
||
}
|
||
}
|
||
|
||
if(count($options['finishReplacements'])) {
|
||
$str = str_replace(array_keys($options['finishReplacements']), array_values($options['finishReplacements']), $str);
|
||
}
|
||
|
||
return trim($str);
|
||
}
|
||
|
||
/**
|
||
* Remove (or close) unclosed HTML tags from given string
|
||
*
|
||
* Remove unclosed tags:
|
||
* ---------------------
|
||
* At present, if it finds an unclosed tag, it removes all tags of the same kind.
|
||
* This is in order to keep the function fast, by delegating what it can to strip_tags().
|
||
* This is sufficient for our internal use here, but may not be ideal for all situations.
|
||
*
|
||
* Fix/close unclosed tags:
|
||
* ------------------------
|
||
* When the remove option is false, it will attempt to close unclosed tags rather than
|
||
* remove them. It doesn't know exactly where they should be closed, so it appends the
|
||
* close tags to the end of the string.
|
||
*
|
||
* @param string $str
|
||
* @param bool $remove Remove unclosed tags? If false, it will attempt to close them instead. (default=true)
|
||
* @param array $options
|
||
* - `ignoreTags` (array): Tags that can be ignored because they close themselves. (default=per HTML spec)
|
||
* @return string
|
||
*
|
||
*/
|
||
public function fixUnclosedTags($str, $remove = true, $options = array()) {
|
||
|
||
$defaults = array(
|
||
'ignoreTags' => array(
|
||
'area','base','br','col','command','embed','hr','img','input',
|
||
'keygen','link','menuitem','meta','param','source','track','wbr',
|
||
),
|
||
);
|
||
|
||
if(isset($options['ignoreTags'])) {
|
||
// merge user specified ignoreTags with our defaults so that both are used
|
||
$options['ignoreTags'] = array_merge($defaults['ignoreTags'], $options['ignoreTags']);
|
||
}
|
||
|
||
$options = array_merge($defaults, $options);
|
||
$tags = array();
|
||
$unclosed = array();
|
||
|
||
$n1 = substr_count($str, '>');
|
||
$n2 = substr_count($str, '</');
|
||
|
||
if($n1) $n1 = $n1 / 2;
|
||
|
||
// if the quantity of ">" is equal to double the quantity of "</" then early exit
|
||
if($n1 === $n2) return $str;
|
||
|
||
// now check for string possibly ending with a partial tag, and remove if present
|
||
$n1 = strrpos($str, '<');
|
||
$n2 = strrpos($str, '>');
|
||
if($n1 > $n2) {
|
||
// string might end with a partial tag, i.e. "<span"
|
||
$test = substr($str, $n1 + 1, 1); // i.e. "s" from "<span", or "<" is last char in the string
|
||
if(ctype_alpha($test) || $test === false || $test === '') {
|
||
// going to assume this is a tag, so trucate
|
||
$str = substr($str, 0, $n1 - 1);
|
||
}
|
||
}
|
||
|
||
// find all open tags
|
||
if(!preg_match_all('!<([a-z]+[a-z0-9]*)(>|\s*/>|\s[^>]+>)!i', $str, $matches)) return $str;
|
||
|
||
foreach($matches[1] as $key => $tag) {
|
||
if(strpos($matches[2][$key], '/>') !== false) continue; // ignore self closing tags
|
||
if(in_array(strtolower($tag), $options['ignoreTags'])) continue;
|
||
$tags[$tag] = $tag;
|
||
}
|
||
|
||
// count appearances of found tags
|
||
foreach($tags as $tag) {
|
||
// count number of open tags of this type
|
||
$openQty = substr_count($str, "<$tag>") + substr_count($str, "<$tag ");
|
||
// count number of closing tags of this type
|
||
$closeQty = substr_count($str, "</$tag>");
|
||
// if quantities do not match, mark tag for deletion
|
||
if($openQty !== $closeQty) {
|
||
unset($tags[$tag]);
|
||
$unclosed[] = $tag;
|
||
}
|
||
}
|
||
|
||
|
||
if(count($unclosed)) {
|
||
if($remove) {
|
||
// strip all tags except those where open/close quantity matched
|
||
$keepTags = count($tags) ? '<' . implode('><', $tags) . '>' : '';
|
||
$str = strip_tags($str, $keepTags);
|
||
} else {
|
||
foreach($unclosed as $tag) {
|
||
$str .= "</$tag>";
|
||
}
|
||
}
|
||
}
|
||
|
||
return $str;
|
||
}
|
||
|
||
/**
|
||
* Collapse string to plain text that all exists on a single long line without destroying words/punctuation.
|
||
*
|
||
* @param string $str String to collapse
|
||
* @param array $options
|
||
* - `stripTags` (bool): Strip markup tags? (default=true)
|
||
* - `keepTags` (array): Array of tag names to keep, if stripTags==true. (default=[])
|
||
* - `collapseLinesWith` (string): String to collapse newlines with. (default=' ')
|
||
* - `linksToUrls` (bool): Convert links to "(url)" rather than removing entirely? (default=false) Since 3.0.132
|
||
* - `endBlocksWith` (string): Character or string to insert to identify paragraph/header separation (default='')
|
||
* - `convertEntities` (bool): Convert entity-encoded characters to text? (default=true)
|
||
* @return string
|
||
*
|
||
*/
|
||
public function collapse($str, array $options = array()) {
|
||
|
||
$defaults = array(
|
||
'stripTags' => true,
|
||
'keepTags' => array(),
|
||
'collapseLinesWith' => ' ',
|
||
'endBlocksWith' => '',
|
||
'convertEntities' => true,
|
||
'linksToUrls' => false,
|
||
);
|
||
|
||
$options = array_merge($defaults, $options);
|
||
|
||
if($options['stripTags']) {
|
||
$str = $this->markupToText($str, array(
|
||
'underlineHeadlines' => false,
|
||
'uppercaseHeadlines' => false,
|
||
'convertEntities' => $options['convertEntities'],
|
||
'linksToUrls' => $options['linksToUrls'],
|
||
'keepTags' => $options['keepTags'],
|
||
));
|
||
if(!strlen($str)) return $str;
|
||
}
|
||
|
||
// character that we collapse lines with
|
||
$r = $options['collapseLinesWith'];
|
||
|
||
// convert any tabs to space
|
||
if(strpos($str, "\t") !== false) {
|
||
$str = str_replace("\t", " ", $str);
|
||
}
|
||
|
||
// convert CRs to LFs
|
||
if(strpos($str, "\r") !== false) {
|
||
$str = str_replace(array("\r\n", "\r"), "\n", $str);
|
||
}
|
||
|
||
// collapse whitespace that appears before or after newlines
|
||
while(strpos($str, " \n") !== false) $str = str_replace(" \n", "\n", $str);
|
||
while(strpos($str, "\n ") !== false) $str = str_replace("\n ", "\n", $str);
|
||
|
||
// convert redundant LFs to no more than double LFs
|
||
while(strpos($str, "\n\n\n") !== false) {
|
||
$str = str_replace("\n\n\n", "\n\n", $str);
|
||
}
|
||
|
||
// add character to indicate blocks, when asked for
|
||
if(!empty($options['endBlocksWith'])) {
|
||
$str = str_replace("\n\n", "$options[endBlocksWith]\n\n", $str);
|
||
}
|
||
|
||
// replace all types of newlines
|
||
$str = str_replace(array("\r\n", "\r", "\n\n", "\n"), $r, $str);
|
||
|
||
// while there are consecutives of our collapse string, reduce them to one
|
||
while(strpos($str, "$r$r") !== false) {
|
||
$str = str_replace("$r$r", $r, $str);
|
||
}
|
||
|
||
if($r !== $defaults['collapseLinesWith']) {
|
||
// replacement of whitespace with something other than another single whitespace
|
||
// so collapse consecutive spaces to one space, since this would not be already done
|
||
while(strpos($str, " ") !== false) {
|
||
$str = str_replace(" ", " ", $str);
|
||
}
|
||
// use space rather than replacement char when left side already ends with punctuation
|
||
foreach($this->getPunctuationChars() as $c) {
|
||
if(strpos($str, "$c$r")) $str = str_replace("$c$r", "$c ", $str);
|
||
}
|
||
}
|
||
|
||
return trim($str);
|
||
}
|
||
|
||
/**
|
||
* Truncate string to given maximum length without breaking words
|
||
*
|
||
* This method can truncate between words, sentences, punctuation or blocks (like paragraphs).
|
||
* See the `type` option for details on how it should truncate. By default it truncates between
|
||
* words. Description of types:
|
||
*
|
||
* - word: truncate to closest word.
|
||
* - punctuation: truncate to closest punctuation within sentence.
|
||
* - sentence: truncate to closest sentence.
|
||
* - block: truncate to closest block of text (like a paragraph or headline).
|
||
*
|
||
* Note that if your specified `type` is something other than “word”, and it cannot be matched
|
||
* within the maxLength, then it will attempt a different type. For instance, if you specify
|
||
* “sentence” as the type, and it cannot match a sentence, it will try to match to “punctuation”
|
||
* instead. If it cannot match that, then it will attempt “word”.
|
||
*
|
||
* HTML will be stripped from returned string. If you want to keep some tags use the `keepTags` or `keepFormatTags`
|
||
* options to specify what tags are allowed to remain. The `keepFormatTags` option that, when true, will make it
|
||
* retain all HTML inline text formatting tags.
|
||
*
|
||
* ~~~~~~~
|
||
* // Truncate string to closest word within 150 characters
|
||
* $s = $sanitizer->truncate($str, 150);
|
||
*
|
||
* // Truncate string to closest sentence within 300 characters
|
||
* $s = $sanitizer->truncate($str, 300, 'sentence');
|
||
*
|
||
* // Truncate with options
|
||
* $s = $sanitizer->truncate($str, [
|
||
* 'type' => 'punctuation',
|
||
* 'maxLength' => 300,
|
||
* 'visible' => true,
|
||
* 'more' => '…'
|
||
* ]);
|
||
* ~~~~~~~
|
||
*
|
||
* @param string $str String to truncate
|
||
* @param int|array $maxLength Maximum length of returned string, or specify $options array here.
|
||
* @param array|string $options Options array, or specify `type` option (string).
|
||
* - `type` (string): Preferred truncation type of word, punctuation, sentence, or block. (default='word')
|
||
* This is a “preferred type”, not an absolute one, because it will adjust to match what it can within your maxLength.
|
||
* - `maxLength` (int): Max characters for truncation, used only if $options array substituted for $maxLength argument.
|
||
* - `maximize` (bool): Include as much as possible within specified type and max-length? (default=true)
|
||
* If you specify false for the maximize option, it will truncate to first word, puncutation, sentence or block.
|
||
* - `visible` (bool): When true, invisible text (markup, entities, etc.) does not count towards string length. (default=false)
|
||
* - `trim` (string): Characters to trim from returned string. (default=',;/ ')
|
||
* - `noTrim` (string): Never trim these from end of returned string. (default=')]>}”»')
|
||
* - `more` (string): Append this to truncated strings that do not end with sentence punctuation. (default='…')
|
||
* - `keepTags` (array): HTML tags that should be kept in returned string. (default=[])
|
||
* - `keepFormatTags` (bool): Keep HTML text-formatting tags? Simpler alternative to keepTags option. (default=false)
|
||
* - `collapseLinesWith` (string): String to collapse lines with where the first is not punctuated. (default=' … ')
|
||
* - `convertEntities` (bool): Convert HTML entities to non-entity characters? (default=false)
|
||
* - `noEndSentence` (string): Strings that sentence may not end with, space-separated values (default='Mr. Mrs. …')
|
||
* @return string
|
||
*
|
||
*/
|
||
function truncate($str, $maxLength, $options = array()) {
|
||
|
||
if(!strlen($str)) return '';
|
||
|
||
$ent = __(true, 'entityEncode', false);
|
||
|
||
$defaults = array(
|
||
'type' => 'word', // word, punctuation, sentence, or block
|
||
'maximize' => true, // include as much as possible within the type and maxLength (false=include as little as possible)
|
||
'visible' => false, // when true, invisible text (markup, entities, etc.) does not count towards string length. (default=false)
|
||
'trim' => $this->_(',;/') . ' ', // Trim these characters from the end of the returned string
|
||
'noTrim' => $this->_(')]>}”»'), // Never trim these characters from end of returned string
|
||
'more' => '…', // Append to truncated strings that do not end with sentence punctuation
|
||
'stripTags' => true, // strip HTML tags? (currently required, see keepTags to keep some)
|
||
'keepTags' => array(), // if strip HTML tags is true, optional array of tag names you want to keep
|
||
'keepFormatTags' => false, // alternative to keepTags: keep just inline text format tags like strong, em, etc.
|
||
'collapseWhitespace' => true, // collapsed whitespace (currently required)
|
||
'collapseLinesWith' => ' ' . $this->_('…') . ' ', // String placed between joined lines (like from paragraphs)
|
||
'convertEntities' => false, // convert entity encoded characters to non-entity equivalents? (default=false)
|
||
'noEndSentence' => $this->_('Mr. Mrs. Ms. Dr. Hon. PhD. i.e. e.g.'), // When in sentence type, words that do not end the sentence (space-separated)
|
||
);
|
||
|
||
if($ent) __(true, 'entityEncode', $ent);
|
||
|
||
if(is_string($options) && ctype_alpha($options)) {
|
||
$defaults['type'] = $options;
|
||
$options = array();
|
||
}
|
||
|
||
if(is_array($maxLength)) {
|
||
$options = $maxLength;
|
||
if(!isset($options['maxLength'])) $options['maxLength'] = 0;
|
||
$maxLength = $options['maxLength'];
|
||
} else if(is_string($maxLength) && ctype_alpha($maxLength)) {
|
||
$options['type'] = $maxLength;
|
||
$maxLength = isset($options['maxLength']) ? $options['maxLength'] : $this->strlen($str);
|
||
}
|
||
|
||
if(!$maxLength) $maxLength = 255;
|
||
$options = array_merge($defaults, $options);
|
||
$type = $options['type'];
|
||
$str = trim($str);
|
||
$blockEndChar = '¶';
|
||
$tests = array();
|
||
$punctuationChars = $this->getPunctuationChars();
|
||
$endSentenceChars = $this->getPunctuationChars(true);
|
||
$endSentenceChars[] = ':';
|
||
|
||
if($options['keepFormatTags']) {
|
||
$options['keepTags'] = array_merge($options['keepTags'], array(
|
||
'abbr','acronym','b','big','cite','code','em','i','kbd', 'q','samp','small','span','strong','sub','sup','time','var',
|
||
));
|
||
}
|
||
|
||
if($type === 'block') {
|
||
if($this->strpos($str, $blockEndChar) !== false) $str = str_replace($blockEndChar, ' ', $str);
|
||
$options['endBlocksWith'] = $blockEndChar;
|
||
}
|
||
|
||
// collapse whitespace and strip tags
|
||
$str = $this->collapse($str, $options);
|
||
|
||
if(trim($options['collapseLinesWith']) && $this->strpos($str, $options['collapseLinesWith'])) {
|
||
// if lines are collapsed with something other than whitespace, avoid using that string
|
||
// when the line already ends with sentence punctuation
|
||
foreach($endSentenceChars as $c) {
|
||
$str = str_replace("$c$options[collapseLinesWith]", "$c ", $str);
|
||
}
|
||
}
|
||
|
||
// if anything above reduced the length of the string enough, return it now
|
||
if($this->strlen($str) <= $maxLength) return $str;
|
||
|
||
// get string at maximum possible length
|
||
if($options['visible']) {
|
||
// adjust for only visible length
|
||
$_str = $str;
|
||
$str = $this->substr($str, 0, $maxLength);
|
||
$len = $this->getVisibleLength($str);
|
||
if($len < $maxLength) {
|
||
$maxLength += ($maxLength - $len);
|
||
$str = $this->substr($_str, 0, $maxLength);
|
||
}
|
||
unset($_str);
|
||
} else {
|
||
$str = $this->substr($str, 0, $maxLength);
|
||
}
|
||
|
||
// match to closest blocks, like paragraph(s)
|
||
if($type === 'block') {
|
||
$pos = $options['maximize'] ? $this->strrpos($str, $blockEndChar) : $this->strpos($str, $blockEndChar);
|
||
if($pos === false) {
|
||
$type = 'sentence';
|
||
} else {
|
||
$tests[] = $pos;
|
||
$options['trim'] .= $blockEndChar;
|
||
}
|
||
}
|
||
|
||
// find sentences closest to end
|
||
if($type === 'sentence') {
|
||
$this->truncateSentenceTests($str, $tests, $endSentenceChars, $options);
|
||
if(!count($tests)) $type = 'punctuation';
|
||
}
|
||
|
||
// find punctuation closes to end of string
|
||
if($type === 'punctuation') {
|
||
foreach($punctuationChars as $find) {
|
||
$pos = $options['maximize'] ? $this->strrpos($str, $find) : $this->strpos($str, $find);
|
||
if($pos) $tests[] = $pos;
|
||
}
|
||
if(!count($tests)) $type = 'word';
|
||
}
|
||
|
||
// find whitespace and last word closest to end of string
|
||
if($type === 'word' || !count($tests)) {
|
||
$pos = $options['maximize'] ? $this->strrpos($str, ' ') : $this->strpos($str, ' ');
|
||
if($pos) $tests[] = $pos;
|
||
}
|
||
|
||
if(count($tests)) {
|
||
// we found somewhere to truncate, so truncate at the longest one possible
|
||
if($options['maximize']) {
|
||
sort($tests);
|
||
} else {
|
||
rsort($tests);
|
||
}
|
||
|
||
// process our tests
|
||
do {
|
||
$pos = array_pop($tests);
|
||
$result = trim($this->substr($str, 0, $pos + 1));
|
||
$lastChar = $this->substr($result, -1);
|
||
$result = $this->rtrim($result, $options['trim']);
|
||
|
||
if($type === 'sentence' || $type === 'block') {
|
||
// good to go with result as is
|
||
} else if(in_array($lastChar, $endSentenceChars)) {
|
||
// good, end with sentence ending punctuation
|
||
} else if(in_array($lastChar, $punctuationChars)) {
|
||
$trims = ' ';
|
||
foreach($punctuationChars as $c) {
|
||
if($this->strpos($options['noTrim'], $c) !== false) continue;
|
||
if(in_array($c, $endSentenceChars)) continue;
|
||
$trims .= $c;
|
||
}
|
||
$result = $this->rtrim($result, $trims) . $options['more'];
|
||
} else {
|
||
$result .= $options['more'];
|
||
}
|
||
|
||
} while(!strlen($result) && count($tests));
|
||
|
||
// make sure we didn't break any HTML tags as a result of truncation
|
||
if(strlen($result) && count($options['keepTags']) && strpos($result, '<') !== false) {
|
||
$result = $this->fixUnclosedTags($result);
|
||
}
|
||
} else {
|
||
// if we didn't find any place to truncate, just return exact truncated string
|
||
$result = $this->trim($str, $options['trim']) . $options['more'];
|
||
}
|
||
|
||
if(strlen($options['more'])) {
|
||
// remove any duplicated more strings
|
||
$more = $options['more'];
|
||
while(strpos($result, "$more$more") !== false) {
|
||
$result = str_replace("$more$more", "$more", $result);
|
||
}
|
||
}
|
||
|
||
return $result;
|
||
}
|
||
|
||
/**
|
||
* Helper to truncate() method, generate tests/positions for where sentences end
|
||
*
|
||
* @param string $str
|
||
* @param array $tests Tests to append found positions to
|
||
* @param array $endSentenceChars
|
||
* @param array $options Options provided to truncate method
|
||
*
|
||
*/
|
||
protected function truncateSentenceTests($str, array &$tests, array $endSentenceChars, array $options) {
|
||
|
||
$chars = $endSentenceChars;
|
||
$thisStr = $str;
|
||
$nextStr = '';
|
||
$nextOffset = 0;
|
||
$offset = 0; // offset used for maximize==false mode only
|
||
$n = 0;
|
||
|
||
// regex matches specified words, plus digits or single letters followed by period
|
||
$noEndRegex = '!\b(' . str_replace(' ', '|', preg_quote($options['noEndSentence'])) . '|\d+\.|\w\.)$!';
|
||
|
||
do {
|
||
|
||
if($nextStr) {
|
||
$offset = $nextOffset;
|
||
$thisStr = $nextStr;
|
||
$nextStr = '';
|
||
$chars = array('.');
|
||
}
|
||
|
||
foreach($chars as $find) {
|
||
|
||
$pos = $options['maximize'] ? $this->strrpos($thisStr, "$find ") : $this->strpos($thisStr, "$find ", $offset);
|
||
|
||
if(!$pos) continue;
|
||
|
||
if($find === '.') {
|
||
$testStr = $this->substr($thisStr, 0, $pos + 1);
|
||
if(preg_match($noEndRegex, $testStr, $matches)) {
|
||
// ends with a disallowed word, next time try to match with a shorter string
|
||
if($options['maximize']) {
|
||
$nextStr = $this->substr($testStr, 0, $this->strlen($testStr) - $this->strlen($matches[1]) - 1);
|
||
} else {
|
||
$nextOffset = $this->strlen($testStr);
|
||
}
|
||
continue;
|
||
}
|
||
}
|
||
|
||
$tests[] = $pos;
|
||
}
|
||
|
||
} while(strlen($nextStr) && ++$n < 3);
|
||
}
|
||
|
||
/**
|
||
* Return visible length of string, which is length not counting markup or entities
|
||
*
|
||
* @param string $str
|
||
* @return int
|
||
*
|
||
*/
|
||
public function getVisibleLength($str) {
|
||
if(strpos($str, '>')) {
|
||
$str = strip_tags($str);
|
||
}
|
||
if(strpos($str, '&') !== false && strpos($str, ';')) {
|
||
$str = html_entity_decode($str, ENT_QUOTES, 'UTF-8');
|
||
}
|
||
return $this->strlen($str);
|
||
}
|
||
|
||
/**
|
||
* Get array of punctuation characters
|
||
*
|
||
* @param bool $sentence Get only sentence-ending punctuation
|
||
* @return array
|
||
*
|
||
*/
|
||
public function getPunctuationChars($sentence = false) {
|
||
$ent = __(true, 'entityEncode', false);
|
||
if($sentence) {
|
||
$s = $this->_('. ? !'); // Sentence ending punctuation characters (must be space-separated)
|
||
} else {
|
||
$s = $this->_(', : . ? ! “ ” „ " – -- ( ) [ ] { } « »'); // All punctuation characters (must be space-separated)
|
||
}
|
||
if($ent) __(true, 'entityEncode', $ent);
|
||
return explode(' ', $s);
|
||
}
|
||
|
||
/**
|
||
* Get alternate words for given word
|
||
*
|
||
* This method does not do anything unless an implementation is provided by a module (or something else)
|
||
* hooking the protected `WireTextTools::wordAlternates($word, $options)` method. Implementation should
|
||
* populate $event->return with any or all of the following (as available):
|
||
*
|
||
* - Word plural(s)
|
||
* - Word singular(s)
|
||
* - Word Lemmas
|
||
* - Word Synonyms
|
||
* - Anything else applicable to current $user->language
|
||
*
|
||
* See the protected WireTextTools::wordAlternates() method for hook instructions and an example.
|
||
*
|
||
* @param string $word
|
||
* @param array $options
|
||
* - `operator` (string): Operator being used, if applicable (default='')
|
||
* - `minLength` (int): Minimum word length to return in alternates (default=2)
|
||
* - `lowercase` (bool): Convert words to lowercase, if not already (default=false)
|
||
* @return array
|
||
* @since 3.0.162
|
||
* @see WireTextTools::getWordStem()
|
||
*
|
||
*/
|
||
public function getWordAlternates($word, array $options = array()) {
|
||
|
||
if(!$this->hasHook('wordAlternates()')) return array();
|
||
|
||
$defaults = array(
|
||
'operator' => '',
|
||
'minLength' => 2,
|
||
'lowercase' => false,
|
||
);
|
||
|
||
$options = array_merge($defaults, $options);
|
||
$word = $this->trim($word);
|
||
$words = array();
|
||
$wordLow = $this->strtolower($word);
|
||
|
||
if($options['lowercase']) $word = $wordLow;
|
||
if(empty($word)) return array();
|
||
|
||
$alternates = $this->wordAlternates($word, $options);
|
||
if(!count($alternates)) return array();
|
||
|
||
// if original word appears in return value, remove it
|
||
$key = array_search($word, $alternates);
|
||
if($key !== false) unset($alternates[$key]);
|
||
|
||
// populate $words, removing any invalid or duplicate values
|
||
foreach($alternates as $w) {
|
||
if(!is_string($w)) continue;
|
||
$w = $this->trim($w);
|
||
$wLow = $this->strtolower($w);
|
||
if($wLow === $wordLow) continue; // dup of original word
|
||
if($options['lowercase']) $w = $wLow; // use lowercase
|
||
if($this->strlen($w) < $options['minLength']) continue; // too short
|
||
if(isset($words[$wLow])) continue; // already have it
|
||
$words[$wLow] = $w;
|
||
}
|
||
|
||
return array_values($words);
|
||
}
|
||
|
||
/**
|
||
* Hookable method to return alternate words for given word
|
||
*
|
||
* This hookable method is separate from the public getWordAlternates() method so that
|
||
* we can provide predictable and already-populated $options to whatever is hooking this, as
|
||
* as provide some additional QA with the return value from modules/hooks.
|
||
*
|
||
* It is fine if the return value contains duplicates, the original word, or too-short words,
|
||
* as the calling getWordAlternates() takes care of those before returning words to user.
|
||
* Basically, hooks can ignore the `$options` argument, unless they need to know the `operator`,
|
||
* which may or may not be provided by the caller.
|
||
*
|
||
* In hook implementation, avoid deleting what’s already present in $event->return just in
|
||
* case multiple hooks are adding words.
|
||
*
|
||
* ~~~~~
|
||
* // Contrived example of how to implement
|
||
* $wire->addHookAfter('WireTextTools::wordAlternates', function(HookEvent $event) {
|
||
* $word = $event->arguments(0); // string: word requested alternates for
|
||
* $words = $event->return; // array: existing return value
|
||
*
|
||
* $cats = [ 'cat', 'cats', 'kitty', 'feline', 'felines' ];
|
||
* $dogs = [ 'dog', 'dogs', 'doggy', 'canine', 'canines' ];
|
||
*
|
||
* if(in_array($word, $cats)) {
|
||
* $words = array_merge($words, $cats);
|
||
* } else if(in_array($word, $dogs)) {
|
||
* $words = array_merge($words, $dogs);
|
||
* }
|
||
*
|
||
* $event->return = $words;
|
||
* });
|
||
*
|
||
* // Test it out
|
||
* $words = $sanitizer->getTextTools()->getWordAlternates('cat');
|
||
* echo implode(', ', $words); // outputs: cats, kitty, kitten, feline, felines
|
||
* ~~~~~
|
||
*
|
||
* #pw-hooker
|
||
*
|
||
* @param string $word
|
||
* @param array $options
|
||
* - `operator` (string): Operator being used, if applicable (default='')
|
||
* @return array
|
||
* @since 3.0.162
|
||
*
|
||
*/
|
||
protected function ___wordAlternates($word, array $options) {
|
||
if($word && $options) {} // ignore
|
||
$alternates = array();
|
||
return $alternates;
|
||
}
|
||
|
||
/**
|
||
* Find and return all {placeholder} tags found in given string
|
||
*
|
||
* @param string $str String that might contain field {tags}
|
||
* @param array $options
|
||
* - `has` (bool): Specify true to only return true or false if it has tags (default=false).
|
||
* - `tagOpen` (string): The required opening tag character(s), default is '{'
|
||
* - `tagClose` (string): The required closing tag character(s), default is '}'
|
||
* @return array|bool
|
||
* @since 3.0.126
|
||
*
|
||
*/
|
||
public function findPlaceholders($str, array $options = array()) {
|
||
|
||
$defaults = array(
|
||
'has' => false,
|
||
'tagOpen' => '{',
|
||
'tagClose' => '}',
|
||
);
|
||
|
||
$options = array_merge($defaults, $options);
|
||
$tags = array();
|
||
$pos1 = strpos($str, $options['tagOpen']);
|
||
|
||
if($pos1 === false) return $options['has'] ? false : $tags;
|
||
|
||
if(strlen($options['tagClose'])) {
|
||
$pos2 = strpos($str, $options['tagClose']);
|
||
if($pos2 === false) return $options['has'] ? false : $tags;
|
||
}
|
||
|
||
$regex = '/' . preg_quote($options['tagOpen']) . '([-_.|a-zA-Z0-9]+)' . preg_quote($options['tagClose']) . '/';
|
||
if($options['has']) return (bool) preg_match($regex, $str);
|
||
if(!preg_match_all($regex, $str, $matches)) return $tags;
|
||
|
||
foreach($matches[0] as $key => $tag) {
|
||
$name = $matches[1][$key];
|
||
$tags[$name] = $tag;
|
||
}
|
||
|
||
return $tags;
|
||
}
|
||
|
||
/**
|
||
* Does the string have any {placeholder} tags in it?
|
||
*
|
||
* @param string $str
|
||
* @param array $options
|
||
* - `tagOpen` (string): The required opening tag character(s), default is '{'
|
||
* - `tagClose` (string): The required closing tag character(s), default is '}'
|
||
* @return bool
|
||
* @since 3.0.126
|
||
*
|
||
*/
|
||
public function hasPlaceholders($str, array $options = array()) {
|
||
$options['has'] = true;
|
||
return $this->findPlaceholders($str, $options);
|
||
}
|
||
|
||
/**
|
||
* Given a string ($str) and values ($vars), populate placeholder “{tags}” in the string with the values
|
||
*
|
||
* - The `$vars` should be an associative array of `[ 'tag' => 'value' ]`.
|
||
* - The `$vars` may also be an object, in which case values will be pulled as properties of the object.
|
||
*
|
||
* By default, tags are specified in the format: {first_name} where first_name is the name of the
|
||
* variable to pull from $vars, `{` is the opening tag character, and `}` is the closing tag char.
|
||
*
|
||
* The tag parser can also handle subfields and OR tags, if `$vars` is an object that supports that.
|
||
* For instance `{products.title}` is a subfield, and `{first_name|title|name}` is an OR tag.
|
||
*
|
||
* ~~~~~
|
||
* $vars = [ 'foo' => 'FOO!', 'bar' => 'BAR!' ];
|
||
* $str = 'This is a test: {foo}, and this is another test: {bar}';
|
||
* echo $sanitizer->getTextTools()->populatePlaceholders($str, $vars);
|
||
* // outputs: This is a test: FOO!, and this is another test: BAR!
|
||
* ~~~~~
|
||
*
|
||
* @param string $str The string to operate on (where the {tags} might be found)
|
||
* @param WireData|object|array $vars Object or associative array to pull replacement values from.
|
||
* @param array $options Array of optional changes to default behavior, including:
|
||
* - `tagOpen` (string): The required opening tag character(s), default is '{'
|
||
* - `tagClose` (string): The optional closing tag character(s), default is '}'
|
||
* - `recursive` (bool): If replacement value contains tags, populate those too? (default=false)
|
||
* - `removeNullTags` (bool): If a tag resolves to a NULL, remove it? If false, tag will remain. (default=true)
|
||
* - `entityEncode` (bool): Entity encode the values pulled from $vars? (default=false)
|
||
* - `entityDecode` (bool): Entity decode the values pulled from $vars? (default=false)
|
||
* - `allowMarkup` (bool): Allow markup to appear in populated variables? (default=true)
|
||
* @return string String with tags populated.
|
||
* @since 3.0.126 Use wirePopulateStringTags() function for older versions
|
||
*
|
||
*/
|
||
public function populatePlaceholders($str, $vars, array $options = array()) {
|
||
|
||
$defaults = array(
|
||
'tagOpen' => '{', // opening tag (required)
|
||
'tagClose' => '}', // closing tag (optional)
|
||
'recursive' => false, // if replacement value contains tags, populate those too?
|
||
'removeNullTags' => true, // if a tag value resolves to a NULL, remove it? If false, tag will be left in tact.
|
||
'entityEncode' => false, // entity encode values pulled from $vars?
|
||
'entityDecode' => false, // entity decode values pulled from $vars?
|
||
'allowMarkup' => true, // allow markup to appear in populated variables?
|
||
);
|
||
|
||
$options = array_merge($defaults, $options);
|
||
$optionsNoRecursive = $options['recursive'] ? array_merge($options, array('recursive' => false)) : $options;
|
||
$replacements = array();
|
||
$tags = $this->findPlaceholders($str, $options);
|
||
|
||
// create a list of replacements by finding replacement values in $vars
|
||
foreach($tags as $fieldName => $tag) {
|
||
|
||
if(isset($replacements[$tag])) continue; // if already found, do not do it again
|
||
$fieldValue = null;
|
||
|
||
if(is_object($vars)) {
|
||
if($vars instanceof Page) {
|
||
$fieldValue = $options['allowMarkup'] ? $vars->getMarkup($fieldName) : $vars->getText($fieldName);
|
||
} else if($vars instanceof WireData) {
|
||
$fieldValue = $vars->get($fieldName);
|
||
} else {
|
||
$fieldValue = $vars->$fieldName;
|
||
}
|
||
} else if(is_array($vars)) {
|
||
$fieldValue = isset($vars[$fieldName]) ? $vars[$fieldName] : null;
|
||
}
|
||
|
||
// if value resolves to null and we are not removing null tags, then do not add to replacements
|
||
if($fieldValue === null && !$options['removeNullTags']) continue;
|
||
|
||
$fieldValue = (string) $fieldValue;
|
||
|
||
if(!$options['allowMarkup'] && strpos($fieldValue, '<') !== false) $fieldValue = strip_tags($fieldValue);
|
||
if($options['entityEncode']) $fieldValue = htmlentities($fieldValue, ENT_QUOTES, 'UTF-8', false);
|
||
if($options['entityDecode']) $fieldValue = html_entity_decode($fieldValue, ENT_QUOTES, 'UTF-8');
|
||
|
||
if($options['recursive'] && strpos($fieldValue, $options['tagOpen']) !== false) {
|
||
$fieldValue = $this->populatePlaceholders($fieldValue, $vars, $optionsNoRecursive);
|
||
}
|
||
|
||
$replacements[$tag] = $fieldValue;
|
||
}
|
||
|
||
// replace the tags
|
||
if(count($tags)) {
|
||
$str = str_replace(array_keys($replacements), array_values($replacements), $str);
|
||
}
|
||
|
||
return $str;
|
||
}
|
||
|
||
/**
|
||
* Populate placeholders in string with sanitizers applied to populated values
|
||
*
|
||
* These placeholders accept one or more sanitizer names as part `{placeholder}` in the format `{placeholder:sanitizers}`,
|
||
* where `placeholder` is the name of a variable accessible from `$data` argument and `sanitizers` is the name of a
|
||
* sanitizer method or a CSV string of sanitizer methods. Placeholders with any whitespace are ignored.
|
||
*
|
||
* #pw-internal
|
||
*
|
||
* ~~~~~
|
||
* $tools = $sanitizer->getTextTools();
|
||
* $data = [ 'name' => 'John <Bob> Smith', 'age' => 46.5 ];
|
||
*
|
||
* $str = "My name is {name:camelCase}, my age is {age:int}";
|
||
* echo $tools->placeholderSanitizers($str, $data); // outputs: My name is johnBobSmith, my age is 46
|
||
*
|
||
* $str = "My name is {name:removeWhitespace,entities}, my age is {age:float}";
|
||
* echo $tools->placeholderSanitizers($str, $data); // outputs: My name is John<Bob>Smith, my age is 46.5
|
||
*
|
||
* $str = "My name is {name:text,word}, my age is {age:digits}";
|
||
* echo $tools->placeholderSanitizers($str, $data); // outputs: My name is John, my age is 465
|
||
* ~~~~~
|
||
*
|
||
* @param string $str
|
||
* @param array|WireData|WireInputData
|
||
* @param array $options
|
||
* @return string
|
||
* @throws WireException
|
||
* @since 3.0.178
|
||
* @todo currently 'protected' for later use
|
||
*
|
||
*/
|
||
protected function placeholderSanitizers($str, $data, array $options = array()) {
|
||
|
||
|
||
$defaults = array(
|
||
'tagOpen' => '{',
|
||
'tagClose' => '}',
|
||
'sanitizersBefore' => array('string'), // sanitizers to apply before requested ones
|
||
'sanitizersAfter' => array(), // sanitizers to apply after requested ones
|
||
'sanitizersDefault' => array('text'), // defaults if only {var} is presented without {var:sanitizer}
|
||
);
|
||
|
||
|
||
$options = array_merge($defaults, $options);
|
||
$sanitizer = $this->wire()->sanitizer;
|
||
$dataIsArray = is_array($data);
|
||
$replacements = array();
|
||
$parts = array();
|
||
|
||
if(strpos($str, $options['tagOpen']) === false || !strpos($str, $options['tagClose'])) return $str;
|
||
|
||
if(!is_array($data) && !$data instanceof WireData && !$data instanceof WireInputData) {
|
||
throw new WireException('$data argument must be associative array, WireData or WireInputData');
|
||
}
|
||
|
||
list($tagOpen, $tagClose) = array(preg_quote($options['tagOpen']), preg_quote($options['tagClose']));
|
||
|
||
$regex = '/OPEN([-_.a-z0-9]+)(:[_,a-z0-9]+CLOSE|CLOSE)/i';
|
||
$regex = str_replace(array('OPEN', 'CLOSE'), array($tagOpen, $tagClose), $regex);
|
||
if(!preg_match_all($regex, $str, $matches)) return $str;
|
||
|
||
foreach($matches[0] as $key => $placeholder) {
|
||
$varName = $matches[1][$key];
|
||
$sanitizers = trim($matches[2][$key], ':}');
|
||
$sanitizers = strlen($sanitizers) ? explode(',', $sanitizers) : array();
|
||
if(!count($sanitizers)) $sanitizers = $options['sanitizersDefault'];
|
||
if($dataIsArray) {
|
||
/** @var array $data */
|
||
$value = isset($data[$varName]) ? $data[$varName] : null;
|
||
} else {
|
||
/** @var WireData|WireInputData $data */
|
||
$value = $data->get($varName);
|
||
}
|
||
$n = 0;
|
||
foreach(array($options['sanitizersBefore'], $sanitizers, $options['sanitizersAfter']) as $methods) {
|
||
foreach($methods as $method) {
|
||
if(!$sanitizer->methodExists($method)) throw new WireException("Unknown sanitizer method: $method");
|
||
$value = $sanitizer->sanitize($value, $method);
|
||
$n++;
|
||
}
|
||
}
|
||
if(!$n) $value = $placeholder;
|
||
$replacements[] = array($placeholder, $value);
|
||
}
|
||
|
||
// piece it back together manually so values in $data cannot introduce more placeholders
|
||
foreach($replacements as $item) {
|
||
list($placeholder, $value) = $item;
|
||
list($before, $after) = explode($placeholder, $str, 2);
|
||
$parts[] = $before . $value;
|
||
$str = $after;
|
||
}
|
||
|
||
return implode('', $parts) . $str;
|
||
}
|
||
|
||
/**
|
||
* Populate placeholders with optional sanitizers in a selector string
|
||
*
|
||
* #pw-internal
|
||
*
|
||
* @param string $selectorString
|
||
* @param array|WireData|WireInputData
|
||
* @param array $options
|
||
* @return string
|
||
* @throws WireException
|
||
* @since 3.0.178
|
||
* @todo currently 'protected' for later use
|
||
*
|
||
*/
|
||
protected function placeholderSelector($selectorString, $data, array $options = array()) {
|
||
if(!isset($options['sanitizersBefore'])) $options['sanitizersBefore'] = array();
|
||
if(!isset($options['sanitizersAfter'])) $options['sanitizersAfter'] = array();
|
||
$options['sanitizersBefore'][] = 'text';
|
||
$options['sanitizersAfter'][] = 'selectorValue';
|
||
return $this->placeholderSanitizers($selectorString, $data, $options);
|
||
}
|
||
|
||
/**
|
||
* Given two arrays, return array of the changes with 'ins' and 'del' keys
|
||
*
|
||
* Based upon Paul Butler’s Simple Diff Algorithm v0.1 © 2007 (zlib/libpng) https://paulbutler.org
|
||
*
|
||
* @param array $oldArray
|
||
* @param array $newArray
|
||
* @return array
|
||
* @since 3.0.144
|
||
*
|
||
*/
|
||
protected function diffArray(array $oldArray, array $newArray) {
|
||
|
||
$matrix = array();
|
||
$maxLen = 0;
|
||
$oldMax = 0;
|
||
$newMax = 0;
|
||
|
||
foreach($oldArray as $oldKey => $oldValue){
|
||
|
||
$newKeys = array_keys($newArray, $oldValue);
|
||
|
||
foreach($newKeys as $newKey) {
|
||
$len = 1;
|
||
if(isset($matrix[$oldKey - 1][$newKey - 1])) {
|
||
$len = $matrix[$oldKey - 1][$newKey - 1] + 1;
|
||
}
|
||
$matrix[$oldKey][$newKey] = $len;
|
||
|
||
if($len > $maxLen) {
|
||
$maxLen = $len;
|
||
$oldMax = $oldKey + 1 - $maxLen;
|
||
$newMax = $newKey + 1 - $maxLen;
|
||
}
|
||
}
|
||
}
|
||
|
||
if($maxLen == 0) {
|
||
$result = array(
|
||
array('del' => $oldArray, 'ins' => $newArray)
|
||
);
|
||
|
||
} else {
|
||
$result = array_merge(
|
||
$this->diffArray(
|
||
array_slice($oldArray, 0, $oldMax),
|
||
array_slice($newArray, 0, $newMax)
|
||
),
|
||
array_slice($newArray, $newMax, $maxLen),
|
||
$this->diffArray(
|
||
array_slice($oldArray, $oldMax + $maxLen),
|
||
array_slice($newArray, $newMax + $maxLen)
|
||
)
|
||
);
|
||
}
|
||
|
||
return $result;
|
||
}
|
||
|
||
/**
|
||
* Given two strings ($old and $new) return a diff string in HTML markup
|
||
*
|
||
* @param string $old Old string value
|
||
* @param string $new New string value
|
||
* @param array $options Options to modify behavior:
|
||
* - `ins` (string) Markup to use for diff insertions (default: `<ins>{out}</ins>`)
|
||
* - `del` (string) Markup to use for diff deletions (default: `<del>{out}</del>`)
|
||
* - `entityEncode` (bool): Entity encode values, other than added ins/del tags? (default=true)
|
||
* - `split` (string): Regex used to split strings for parts to diff (default=`\s+`)
|
||
* @return string
|
||
* @since 3.0.144
|
||
*
|
||
*/
|
||
public function diffMarkup($old, $new, array $options = array()) {
|
||
|
||
$defaults = array(
|
||
'ins' => "<ins>{out}</ins>",
|
||
'del' => "<del>{out}</del>",
|
||
'entityEncode' => true,
|
||
'split' => '\s+',
|
||
);
|
||
|
||
/** @var Sanitizer $sanitizer */
|
||
$sanitizer = $this->wire('sanitizer');
|
||
list($old, $new) = array("$old", "$new"); // enforce as string
|
||
$options = array_merge($defaults, $options);
|
||
$oldArray = preg_split("!($options[split])!", $old, 0, PREG_SPLIT_DELIM_CAPTURE);
|
||
$newArray = preg_split("!($options[split])!", $new, 0, PREG_SPLIT_DELIM_CAPTURE);
|
||
$diffArray = $this->diffArray($oldArray, $newArray);
|
||
list(,$delClose) = explode('{out}', $options['del'], 2);
|
||
list($insOpen,) = explode('{out}', $options['ins'], 2);
|
||
$out = '';
|
||
|
||
foreach($diffArray as $diff) {
|
||
if(is_array($diff)) {
|
||
foreach(array('del', 'ins') as $key) {
|
||
if(empty($diff[$key])) continue;
|
||
$diffStr = implode('', $diff[$key]);
|
||
if($options['entityEncode']) $diffStr = $sanitizer->entities1($diffStr);
|
||
$out .= str_replace('{out}', $diffStr, $options[$key]);
|
||
}
|
||
} else {
|
||
$out .= ($options['entityEncode'] ? $sanitizer->entities1($diff) : $diff);
|
||
}
|
||
}
|
||
|
||
if(strpos($out, "$delClose$insOpen")) {
|
||
// put a space between '</del><ins>' so that it is '</del> <ins>'
|
||
$out = str_replace("$delClose$insOpen", "$delClose $insOpen", $out);
|
||
}
|
||
|
||
return $out;
|
||
}
|
||
|
||
/**
|
||
* Find escaped characters in $str, replace them with a placeholder, and return the placeholders
|
||
*
|
||
* Usage
|
||
* ~~~~~
|
||
* // 1. Escape certain chars in a string that you want to survive some processing:
|
||
* $str = 'Hello \*world\* foo \"bar\" baz';
|
||
*
|
||
* // 2. Use this method to find escape chars and replace them temporarily:
|
||
* $a = $sanitizer->getTextTools()->findReplaceEscapeChars($str, [ '*', '"' ]);
|
||
*
|
||
* // 3. Process string with anything that you want NOT to see chars that were escaped:
|
||
* $str = some_function_that_processes_the_string($str);
|
||
*
|
||
* // 4. Do this to restore the escaped chars (restored without backslashes by default):
|
||
* $str = str_replace(array_keys($a), array_values($a), $str);
|
||
* ~~~~~
|
||
*
|
||
* @param string &$str String to find escape chars in, it will be modified directly (passed by reference)
|
||
* @param array $escapeChars Array of chars you want to escape i.e. [ '*', '[', ']', '(', ')', '`', '_', '\\', '"' ]
|
||
* @param array $options Options to modify behavior:
|
||
* - `escapePrefix` (string): Character used to escape another character (default is backslash).
|
||
* - `restoreEscape` (bool): Should returned array also include the escape prefix, so escapes are restored? (default=false)
|
||
* - `gluePrefix` (string): Prefix for placeholders we substitute for escaped characters (default='{ESC')
|
||
* - `glueSuffix` (string): Suffix for placeholders we substitute for escaped characters (default='}')
|
||
* - `unescapeUnknown` (bool): If we come across escaped char not in your $escapeChars list, unescape it? (default=false)
|
||
* - `removeUnknown` (bool): If we come across escaped char not in your $escapeChars list, remove the escape and char? (default=false)
|
||
* @return array Returns assoc array where keys are placeholders substituted in $str and values are escaped characters.
|
||
* @since 3.0.162
|
||
*
|
||
*/
|
||
public function findReplaceEscapeChars(&$str, array $escapeChars, array $options = array()) {
|
||
|
||
$defaults = array(
|
||
'escapePrefix' => '\\',
|
||
'restoreEscape' => false, // when restoring, also restore escape prefix?
|
||
'gluePrefix' => '{ESC',
|
||
'glueSuffix' => '}',
|
||
'unescapeUnknown' => false,
|
||
'removeUnknown' => false,
|
||
);
|
||
|
||
$options = array_merge($defaults, $options);
|
||
$escapePrefix = $options['escapePrefix'];
|
||
if(strpos($str, $escapePrefix) === false) return array();
|
||
$escapes = array();
|
||
$glueSuffix = $options['glueSuffix'];
|
||
$parts = explode($escapePrefix, $str);
|
||
$n = 0;
|
||
|
||
do {
|
||
$gluePrefix = $options['gluePrefix'] . $n;
|
||
} while($this->strpos($str, $gluePrefix) !== false && ++$n);
|
||
|
||
$str = array_shift($parts);
|
||
|
||
foreach($parts as $part) {
|
||
|
||
$len = $this->strlen($part);
|
||
$char = $len > 0 ? $this->substr($part, 0, 1) : ''; // char being escaped
|
||
$part = $len > 1 ? $this->substr($part, 1) : ''; // everything after it
|
||
$charKey = array_search($char, $escapeChars); // find placeholder (glue)
|
||
|
||
if($charKey !== false) {
|
||
// replace escaped char with placeholder ($glue)
|
||
$glue = $gluePrefix . $charKey . $glueSuffix;
|
||
$escapes[$glue] = $options['restoreEscape'] ? $escapePrefix . $char : $char;
|
||
$str .= $glue . $part;
|
||
} else if($options['unescapeUnknown']) {
|
||
// unescape unknown escape char
|
||
$str .= $char . $part;
|
||
} else if($options['removeUnknown']) {
|
||
// remove unknown escape char
|
||
$str .= $part;
|
||
} else {
|
||
// some other backslash that’s allowed, restore back as it was
|
||
$str .= $escapePrefix . $char . $part;
|
||
}
|
||
}
|
||
|
||
return $escapes;
|
||
}
|
||
|
||
/***********************************************************************************************************
|
||
* MULTIBYTE PHP STRING FUNCTIONS THAT FALLBACK WHEN MBSTRING NOT AVAILABLE
|
||
*
|
||
* These duplicate the equivalent PHP string methods and use exactly the same arguments
|
||
* and exhibit exactly the same behavior. The only difference is that these methods using
|
||
* the multibyte string versions when they are available, and fallback to the regular PHP
|
||
* string methods when not. Use these functions only when that behavior is okay.
|
||
*
|
||
*/
|
||
|
||
/**
|
||
* Get part of a string
|
||
*
|
||
* #pw-group-PHP-function-alternates
|
||
*
|
||
* @param string $str
|
||
* @param int $start
|
||
* @param int|null $length Max chars to use from str. If omitted or NULL, extract all characters to the end of the string.
|
||
* @return string
|
||
* @see https://www.php.net/manual/en/function.substr.php
|
||
*
|
||
*/
|
||
public function substr($str, $start, $length = null) {
|
||
return $this->mb ? mb_substr($str, $start, $length) : substr($str, $start, $length);
|
||
}
|
||
|
||
/**
|
||
* Find position of first occurrence of string in a string
|
||
*
|
||
* #pw-group-PHP-function-alternates
|
||
*
|
||
* @param string $haystack
|
||
* @param string $needle
|
||
* @param int $offset
|
||
* @return bool|false|int
|
||
* @see https://www.php.net/manual/en/function.strpos.php
|
||
*
|
||
*/
|
||
public function strpos($haystack, $needle, $offset = 0) {
|
||
return $this->mb ? mb_strpos($haystack, $needle, $offset) : strpos($haystack, $needle, $offset);
|
||
}
|
||
|
||
/**
|
||
* Find the position of the first occurrence of a case-insensitive substring in a string
|
||
*
|
||
* #pw-group-PHP-function-alternates
|
||
*
|
||
* @param string $haystack
|
||
* @param string $needle
|
||
* @param int $offset
|
||
* @return bool|false|int
|
||
* @see https://www.php.net/manual/en/function.stripos.php
|
||
*
|
||
*/
|
||
public function stripos($haystack, $needle, $offset = 0) {
|
||
return $this->mb ? mb_stripos($haystack, $needle, $offset) : stripos($haystack, $needle, $offset);
|
||
}
|
||
|
||
/**
|
||
* Find the position of the last occurrence of a substring in a string
|
||
*
|
||
* #pw-group-PHP-function-alternates
|
||
*
|
||
* @param string $haystack
|
||
* @param string $needle
|
||
* @param int $offset
|
||
* @return bool|false|int
|
||
* @see https://www.php.net/manual/en/function.strrpos.php
|
||
*
|
||
*/
|
||
public function strrpos($haystack, $needle, $offset = 0) {
|
||
return $this->mb ? mb_strrpos($haystack, $needle, $offset) : strrpos($haystack, $needle, $offset);
|
||
}
|
||
|
||
/**
|
||
* Find the position of the last occurrence of a case-insensitive substring in a string
|
||
*
|
||
* #pw-group-PHP-function-alternates
|
||
*
|
||
* @param string $haystack
|
||
* @param string $needle
|
||
* @param int $offset
|
||
* @return bool|false|int
|
||
* @see https://www.php.net/manual/en/function.strripos.php
|
||
*
|
||
*/
|
||
public function strripos($haystack, $needle, $offset = 0) {
|
||
return $this->mb ? mb_strripos($haystack, $needle, $offset) : strripos($haystack, $needle, $offset);
|
||
}
|
||
|
||
/**
|
||
* Get string length
|
||
*
|
||
* #pw-group-PHP-function-alternates
|
||
*
|
||
* @param string $str
|
||
* @return int
|
||
* @see https://www.php.net/manual/en/function.strlen.php
|
||
*
|
||
*/
|
||
public function strlen($str) {
|
||
return $this->mb ? mb_strlen($str) : strlen($str);
|
||
}
|
||
|
||
/**
|
||
* Make a string lowercase
|
||
*
|
||
* #pw-group-PHP-function-alternates
|
||
*
|
||
* @param string $str
|
||
* @return string
|
||
* @see https://www.php.net/manual/en/function.strtolower.php
|
||
*
|
||
*/
|
||
public function strtolower($str) {
|
||
return $this->mb ? mb_strtolower($str) : strtolower($str);
|
||
}
|
||
|
||
/**
|
||
* Make a string uppercase
|
||
*
|
||
* #pw-group-PHP-function-alternates
|
||
*
|
||
* @param string $str
|
||
* @return string
|
||
* @see https://www.php.net/manual/en/function.strtoupper.php
|
||
*
|
||
*/
|
||
public function strtoupper($str) {
|
||
return $this->mb ? mb_strtoupper($str) : strtoupper($str);
|
||
}
|
||
|
||
/**
|
||
* Count the number of substring occurrences
|
||
*
|
||
* #pw-group-PHP-function-alternates
|
||
*
|
||
* @param string $haystack
|
||
* @param string $needle
|
||
* @return int
|
||
* @see https://www.php.net/manual/en/function.substr-count.php
|
||
*
|
||
*/
|
||
public function substrCount($haystack, $needle) {
|
||
return $this->mb ? mb_substr_count($haystack, $needle) : substr_count($haystack, $needle);
|
||
}
|
||
|
||
/**
|
||
* Find the first occurrence of a string
|
||
*
|
||
* #pw-group-PHP-function-alternates
|
||
*
|
||
* @param string $haystack
|
||
* @param string $needle
|
||
* @param bool $beforeNeedle Return part of haystack before first occurrence of the needle? (default=false)
|
||
* @return false|string
|
||
* @see https://www.php.net/manual/en/function.strstr.php
|
||
*
|
||
*/
|
||
public function strstr($haystack, $needle, $beforeNeedle = false) {
|
||
return $this->mb ? mb_strstr($haystack, $needle, $beforeNeedle) : strstr($haystack, $needle, $beforeNeedle);
|
||
}
|
||
|
||
/**
|
||
* Find the first occurrence of a string (case insensitive)
|
||
*
|
||
* #pw-group-PHP-function-alternates
|
||
*
|
||
* @param string $haystack
|
||
* @param string $needle
|
||
* @param bool $beforeNeedle Return part of haystack before first occurrence of the needle? (default=false)
|
||
* @return false|string
|
||
* @see https://www.php.net/manual/en/function.stristr.php
|
||
*
|
||
*/
|
||
public function stristr($haystack, $needle, $beforeNeedle = false) {
|
||
return $this->mb ? mb_stristr($haystack, $needle, $beforeNeedle) : stristr($haystack, $needle, $beforeNeedle);
|
||
}
|
||
|
||
|
||
/**
|
||
* Find the last occurrence of a character in a string
|
||
*
|
||
* #pw-group-PHP-function-alternates
|
||
*
|
||
* @param string $haystack
|
||
* @param string $needle Only first given character used
|
||
* @return false|string
|
||
* @see https://www.php.net/manual/en/function.strrchr.php
|
||
*
|
||
*/
|
||
public function strrchr($haystack, $needle) {
|
||
return $this->mb ? mb_strrchr($haystack, $needle) : strrchr($haystack, $needle);
|
||
}
|
||
|
||
/**
|
||
* Strip whitespace (or other characters) from the beginning and end of a string
|
||
*
|
||
* #pw-group-PHP-function-alternates
|
||
*
|
||
* @param string $str
|
||
* @param string $chars Omit for default
|
||
* @return string
|
||
*
|
||
*/
|
||
public function trim($str, $chars = '') {
|
||
if(!$this->mb) return $chars === '' ? trim($str) : trim($str, $chars);
|
||
return $this->wire()->sanitizer->trim($str, $chars);
|
||
}
|
||
|
||
/**
|
||
* Strip whitespace (or other characters) from the beginning of string only (aka left trim)
|
||
*
|
||
* #pw-group-PHP-function-alternates
|
||
*
|
||
* @param string $str
|
||
* @param string $chars Omit for default
|
||
* @return string
|
||
* @since 3.0.168
|
||
*
|
||
*/
|
||
public function ltrim($str, $chars = '') {
|
||
if(!$this->mb) return $chars === '' ? ltrim($str) : ltrim($str, $chars);
|
||
return $this->wire()->sanitizer->trim($str, $chars, 'ltrim');
|
||
}
|
||
|
||
/**
|
||
* Strip whitespace (or other characters) from the end of string only (aka right trim)
|
||
*
|
||
* #pw-group-PHP-function-alternates
|
||
*
|
||
* @param string $str
|
||
* @param string $chars Omit for default
|
||
* @return string
|
||
* @since 3.0.168
|
||
*
|
||
*/
|
||
public function rtrim($str, $chars = '') {
|
||
if(!$this->mb) return $chars === '' ? rtrim($str) : rtrim($str, $chars);
|
||
return $this->wire()->sanitizer->trim($str, $chars, 'rtrim');
|
||
}
|
||
|
||
|
||
}
|