1: <?php
2: /**
3: * Text Helper
4: *
5: * Text manipulations: Highlight, excerpt, truncate, strip of links, convert email addresses to mailto: links...
6: *
7: * CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
8: * Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
9: *
10: * Licensed under The MIT License
11: * For full copyright and license information, please see the LICENSE.txt
12: * Redistributions of files must retain the above copyright notice.
13: *
14: * @copyright Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
15: * @link http://cakephp.org CakePHP(tm) Project
16: * @package Cake.View.Helper
17: * @since CakePHP(tm) v 0.10.0.1076
18: * @license http://www.opensource.org/licenses/mit-license.php MIT License
19: */
20:
21: App::uses('AppHelper', 'View/Helper');
22: App::uses('Hash', 'Utility');
23:
24: /**
25: * Text helper library.
26: *
27: * Text manipulations: Highlight, excerpt, truncate, strip of links, convert email addresses to mailto: links...
28: *
29: * @package Cake.View.Helper
30: * @property HtmlHelper $Html
31: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/text.html
32: * @see String
33: */
34: class TextHelper extends AppHelper {
35:
36: /**
37: * helpers
38: *
39: * @var array
40: */
41: public $helpers = array('Html');
42:
43: /**
44: * An array of md5sums and their contents.
45: * Used when inserting links into text.
46: *
47: * @var array
48: */
49: protected $_placeholders = array();
50:
51: /**
52: * String utility instance
53: *
54: * @var stdClass
55: */
56: protected $_engine;
57:
58: /**
59: * Constructor
60: *
61: * ### Settings:
62: *
63: * - `engine` Class name to use to replace String functionality.
64: * The class needs to be placed in the `Utility` directory.
65: *
66: * @param View $View the view object the helper is attached to.
67: * @param array $settings Settings array Settings array
68: * @throws CakeException when the engine class could not be found.
69: */
70: public function __construct(View $View, $settings = array()) {
71: $settings = Hash::merge(array('engine' => 'String'), $settings);
72: parent::__construct($View, $settings);
73: list($plugin, $engineClass) = pluginSplit($settings['engine'], true);
74: App::uses($engineClass, $plugin . 'Utility');
75: if (class_exists($engineClass)) {
76: $this->_engine = new $engineClass($settings);
77: } else {
78: throw new CakeException(__d('cake_dev', '%s could not be found', $engineClass));
79: }
80: }
81:
82: /**
83: * Call methods from String utility class
84: *
85: * @param string $method Method to call.
86: * @param array $params Parameters to pass to method.
87: * @return mixed Whatever is returned by called method, or false on failure
88: */
89: public function __call($method, $params) {
90: return call_user_func_array(array($this->_engine, $method), $params);
91: }
92:
93: /**
94: * Adds links (<a href=....) to a given text, by finding text that begins with
95: * strings like http:// and ftp://.
96: *
97: * ### Options
98: *
99: * - `escape` Control HTML escaping of input. Defaults to true.
100: *
101: * @param string $text Text
102: * @param array $options Array of HTML options, and options listed above.
103: * @return string The text with links
104: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/text.html#TextHelper::autoLinkUrls
105: */
106: public function autoLinkUrls($text, $options = array()) {
107: $this->_placeholders = array();
108: $options += array('escape' => true);
109:
110: $pattern = '#(?<!href="|src="|">)((?:https?|ftp|nntp)://[\p{L}0-9.\-_:]+(?:[/?][^\s<]*)?)#ui';
111: $text = preg_replace_callback(
112: $pattern,
113: array(&$this, '_insertPlaceHolder'),
114: $text
115: );
116: $text = preg_replace_callback(
117: '#(?<!href="|">)(?<!\b[[:punct:]])(?<!http://|https://|ftp://|nntp://)www.[^\n\%\ <]+[^<\n\%\,\.\ <](?<!\))#i',
118: array(&$this, '_insertPlaceHolder'),
119: $text
120: );
121: if ($options['escape']) {
122: $text = h($text);
123: }
124: return $this->_linkUrls($text, $options);
125: }
126:
127: /**
128: * Saves the placeholder for a string, for later use. This gets around double
129: * escaping content in URL's.
130: *
131: * @param array $matches An array of regexp matches.
132: * @return string Replaced values.
133: */
134: protected function _insertPlaceHolder($matches) {
135: $key = md5($matches[0]);
136: $this->_placeholders[$key] = $matches[0];
137: return $key;
138: }
139:
140: /**
141: * Replace placeholders with links.
142: *
143: * @param string $text The text to operate on.
144: * @param array $htmlOptions The options for the generated links.
145: * @return string The text with links inserted.
146: */
147: protected function _linkUrls($text, $htmlOptions) {
148: $replace = array();
149: foreach ($this->_placeholders as $hash => $url) {
150: $link = $url;
151: if (!preg_match('#^[a-z]+\://#', $url)) {
152: $url = 'http://' . $url;
153: }
154: $replace[$hash] = $this->Html->link($link, $url, $htmlOptions);
155: }
156: return strtr($text, $replace);
157: }
158:
159: /**
160: * Links email addresses
161: *
162: * @param string $text The text to operate on
163: * @param array $options An array of options to use for the HTML.
164: * @return string
165: * @see TextHelper::autoLinkEmails()
166: */
167: protected function _linkEmails($text, $options) {
168: $replace = array();
169: foreach ($this->_placeholders as $hash => $url) {
170: $replace[$hash] = $this->Html->link($url, 'mailto:' . $url, $options);
171: }
172: return strtr($text, $replace);
173: }
174:
175: /**
176: * Adds email links (<a href="mailto:....) to a given text.
177: *
178: * ### Options
179: *
180: * - `escape` Control HTML escaping of input. Defaults to true.
181: *
182: * @param string $text Text
183: * @param array $options Array of HTML options, and options listed above.
184: * @return string The text with links
185: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/text.html#TextHelper::autoLinkEmails
186: */
187: public function autoLinkEmails($text, $options = array()) {
188: $options += array('escape' => true);
189: $this->_placeholders = array();
190:
191: $atom = '[\p{L}0-9!#$%&\'*+\/=?^_`{|}~-]';
192: $text = preg_replace_callback(
193: '/(?<=\s|^|\(|\>|\;)(' . $atom . '*(?:\.' . $atom . '+)*@[\p{L}0-9-]+(?:\.[\p{L}0-9-]+)+)/ui',
194: array(&$this, '_insertPlaceholder'),
195: $text
196: );
197: if ($options['escape']) {
198: $text = h($text);
199: }
200: return $this->_linkEmails($text, $options);
201: }
202:
203: /**
204: * Convert all links and email addresses to HTML links.
205: *
206: * ### Options
207: *
208: * - `escape` Control HTML escaping of input. Defaults to true.
209: *
210: * @param string $text Text
211: * @param array $options Array of HTML options, and options listed above.
212: * @return string The text with links
213: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/text.html#TextHelper::autoLink
214: */
215: public function autoLink($text, $options = array()) {
216: $text = $this->autoLinkUrls($text, $options);
217: return $this->autoLinkEmails($text, array_merge($options, array('escape' => false)));
218: }
219:
220: /**
221: * Highlights a given phrase in a text. You can specify any expression in highlighter that
222: * may include the \1 expression to include the $phrase found.
223: *
224: * @param string $text Text to search the phrase in
225: * @param string $phrase The phrase that will be searched
226: * @param array $options An array of html attributes and options.
227: * @return string The highlighted text
228: * @see String::highlight()
229: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/text.html#TextHelper::highlight
230: */
231: public function highlight($text, $phrase, $options = array()) {
232: return $this->_engine->highlight($text, $phrase, $options);
233: }
234:
235: /**
236: * Formats paragraphs around given text for all line breaks
237: * <br /> added for single line return
238: * <p> added for double line return
239: *
240: * @param string $text Text
241: * @return string The text with proper <p> and <br /> tags
242: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/text.html#TextHelper::autoParagraph
243: */
244: public function autoParagraph($text) {
245: if (trim($text) !== '') {
246: $text = preg_replace('|<br[^>]*>\s*<br[^>]*>|i', "\n\n", $text . "\n");
247: $text = preg_replace("/\n\n+/", "\n\n", str_replace(array("\r\n", "\r"), "\n", $text));
248: $texts = preg_split('/\n\s*\n/', $text, -1, PREG_SPLIT_NO_EMPTY);
249: $text = '';
250: foreach ($texts as $txt) {
251: $text .= '<p>' . nl2br(trim($txt, "\n")) . "</p>\n";
252: }
253: $text = preg_replace('|<p>\s*</p>|', '', $text);
254: }
255: return $text;
256: }
257:
258: /**
259: * Strips given text of all links (<a href=....)
260: *
261: * @param string $text Text
262: * @return string The text without links
263: * @see String::stripLinks()
264: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/text.html#TextHelper::stripLinks
265: */
266: public function stripLinks($text) {
267: return $this->_engine->stripLinks($text);
268: }
269:
270: /**
271: * Truncates text.
272: *
273: * Cuts a string to the length of $length and replaces the last characters
274: * with the ellipsis if the text is longer than length.
275: *
276: * ### Options:
277: *
278: * - `ellipsis` Will be used as Ending and appended to the trimmed string (`ending` is deprecated)
279: * - `exact` If false, $text will not be cut mid-word
280: * - `html` If true, HTML tags would be handled correctly
281: *
282: * @param string $text String to truncate.
283: * @param int $length Length of returned string, including ellipsis.
284: * @param array $options An array of html attributes and options.
285: * @return string Trimmed string.
286: * @see String::truncate()
287: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/text.html#TextHelper::truncate
288: */
289: public function truncate($text, $length = 100, $options = array()) {
290: return $this->_engine->truncate($text, $length, $options);
291: }
292:
293: /**
294: * Truncates text starting from the end.
295: *
296: * Cuts a string to the length of $length and replaces the first characters
297: * with the ellipsis if the text is longer than length.
298: *
299: * ### Options:
300: *
301: * - `ellipsis` Will be used as Beginning and prepended to the trimmed string
302: * - `exact` If false, $text will not be cut mid-word
303: *
304: * @param string $text String to truncate.
305: * @param int $length Length of returned string, including ellipsis.
306: * @param array $options An array of html attributes and options.
307: * @return string Trimmed string.
308: * @see String::tail()
309: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/text.html#TextHelper::tail
310: */
311: public function tail($text, $length = 100, $options = array()) {
312: return $this->_engine->tail($text, $length, $options);
313: }
314:
315: /**
316: * Extracts an excerpt from the text surrounding the phrase with a number of characters on each side
317: * determined by radius.
318: *
319: * @param string $text String to search the phrase in
320: * @param string $phrase Phrase that will be searched for
321: * @param int $radius The amount of characters that will be returned on each side of the founded phrase
322: * @param string $ending Ending that will be appended
323: * @return string Modified string
324: * @see String::excerpt()
325: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/text.html#TextHelper::excerpt
326: */
327: public function excerpt($text, $phrase, $radius = 100, $ending = '...') {
328: return $this->_engine->excerpt($text, $phrase, $radius, $ending);
329: }
330:
331: /**
332: * Creates a comma separated list where the last two items are joined with 'and', forming natural English
333: *
334: * @param array $list The list to be joined
335: * @param string $and The word used to join the last and second last items together with. Defaults to 'and'
336: * @param string $separator The separator used to join all the other items together. Defaults to ', '
337: * @return string The glued together string.
338: * @see String::toList()
339: * @link http://book.cakephp.org/2.0/en/core-libraries/helpers/text.html#TextHelper::toList
340: */
341: public function toList($list, $and = 'and', $separator = ', ') {
342: return $this->_engine->toList($list, $and, $separator);
343: }
344:
345: }
346: