├── LICENSE-MIT
├── Readme.md
├── unittest.php
└── truncateHTML.php
/LICENSE-MIT:
--------------------------------------------------------------------------------
1 | The MIT License (MIT)
2 | Copyright (c) 2018 Jean-Louis Grall, contributors
3 |
4 | Permission is hereby granted, free of charge, to any person
5 | obtaining a copy of this software and associated documentation
6 | files (the "Software"), to deal in the Software without
7 | restriction, including without limitation the rights to use,
8 | copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the
10 | Software is furnished to do so, subject to the following
11 | conditions:
12 |
13 | The above copyright notice and this permission notice shall be
14 | included in all copies or substantial portions of the Software.
15 |
16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
18 | OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19 | NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
20 | HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
21 | WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
22 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
23 | OTHER DEALINGS IN THE SOFTWARE.
24 |
--------------------------------------------------------------------------------
/Readme.md:
--------------------------------------------------------------------------------
1 | # truncateHTML
2 |
3 | A PHP function that truncates (shortens) a given HTML5 string to a max number of characters.
4 |
5 | __Example:__ truncate after 6 characters including the ellipsis:
6 | `
A red ball.
` __=>__ `
A red…
`
7 |
8 | Compatible with PHP 5.6 and 7+
9 | Uses the _mbstring_ PHP extension for UTF-8.
10 | More than 240 unit tests (see or run: [unittest.php](unittest.php))
11 |
12 | _The function is in [truncateHTML.php](truncateHTML.php), you can just copy/paste it to your project._
13 |
14 |
15 | ## Features:
16 |
17 | - Quickly truncate most common HTML5 sources without using a full HTML parser (which is ~100x slower).
18 | - Configurable ellipsis: `…`, `...`, `More`, etc.
19 | - Can include the length of the ellipsis in the truncated result.
20 | - Supports self-closing tags like: ``, ``, ``
21 | - Collapsing spaces: sequences of multiple spaces are counted only once (including ` `, ` ` and a few others)
22 | - Don't count characters in invisible elements like: ``, `
Hi
More text.");
53 | // => "
Hi…
"
54 |
55 | // Collapsing multiple spaces:
56 | truncateHTML(6, "A \n\t long space!");
57 | // => "A \n\t long…"
58 |
59 | // Tag mismatch: truncates before the error:
60 | truncateHTML(99, "Clickhere");
61 | // => "Click…"
62 | ```
63 |
64 |
65 | ## API:
66 |
67 | __`string truncateHTML(int $maxLength, string $html, array $options = [])`__
68 |
69 | - `$maxLength`: the returned HTML will contain at most $maxLength countable characters.
70 | If negative, remove $maxLength countable characters from the end of the $html.
71 | - `$html`: the input HTML string that will be truncated.
72 | - `$options`: (optional) an array of options:
73 |
74 | |Options (with default value)|Descriptions|
75 | |---|---|
76 | |`'ellipsis'=>'…'` (or: `'ellipsis'=>'...'`)|The ellipsis that will be included. Can be an empty string, can contain HTML tags. (`'…'` is the horizontal ellipsis character, ie. `'...'` as a single unicode character) (If not using UTF-8 mode, the default value will be `'...'` instead of `'…'`)|
77 | |`'includeEllipsisLength'=>true`|Whether to include the length of the ellipsis in the length of the truncated result.|
78 | |`'wholeWord'=>true`|When truncating, don't cut in the middle of a word. Instead cut at the end of the last word.|
79 | |`'cutWord'=>18`|When `wholeWord` is enabled, allows to cut long words after `cutWord` characters (Set to `0` or `false` to disable)|
80 | |`'utf8'=>true`|Use UTF-8 mode. You should always use [UTF-8](https://en.wikipedia.org/wiki/UTF-8) though. If `utf8` is `false`, only ASCII-compatible single-byte encodings (such as [Latin-1](https://en.wikipedia.org/wiki/ISO/IEC_8859-1)) are supported. For other encodings, use [mb_convert_encoding](https://secure.php.net/manual/en/function.mb-convert-encoding.php) to convert to UTF-8 and back. (If UTF-8 is disabled, the default ellipsis will be `'...'` instead of `'…'`)|
81 |
82 |
83 | ## Limitations:
84 |
85 | XHTML: probably works in most cases, but is untested.
86 |
87 | __Not supported:__
88 | - __Malformed HTML__, badly nested tags, missing closing tags: it doesn't try to guess the correct fix (for this you would need a full HTML parser).
89 | _Note: when meeting an unexpected closing tag: it always truncates before the closing tag (see the examples)._
90 | - Uncommon HTML code like:
91 | - [HTML tags inside an HTML Tag attribute](https://stackoverflow.com/questions/4699276/can-data-attribute-contain-html-tags): ``
92 | - The string __``__ inside ``. For this you would need a full HTML parser, or a JavaScript parser. (Other tags are ok, but don't have a closing tag `` in a JavaScript string or comment)
93 | - The string __``__ inside ``. For this you would need a full HTML parser, or a CSS parser. (Other tags are ok, but don't have a closing tag `` in a CSS comment)
94 | - XML
95 | - CDATA ([deprecated in HTML5](https://developer.mozilla.org/en-US/docs/Web/API/CDATASection))
96 |
97 | _If you find more, please open an [issue](https://github.com/jlgrall/truncateHTML/issues)._
98 |
99 | ## History (changelog)
100 |
101 | - __v1.0.1__ _(9 Feb. 2018)_:
102 | - Fix multibyte characters in regex
103 | - Add parameter types verifications
104 | - __v1.0__ _(5 Feb. 2018)_:
105 | - Initial version
106 | - _Inspired by:_
107 | - _[StackOverflow: Truncate text containing HTML, ignoring tags](https://stackoverflow.com/questions/1193500/truncate-text-containing-html-ignoring-tags/1193598#1193598)_
108 | - _[truncate() from CakePHP](https://github.com/cakephp/cakephp/blob/master/src/Utility/Text.php)_
--------------------------------------------------------------------------------
/unittest.php:
--------------------------------------------------------------------------------
1 | ..."): sets the input html string.
7 | - input(['option' => 'value']): sets or modifies an option that is used for the $options parameter.
8 | - t($maxLength, "Expected output"): tests the output of truncateHTML() with the expected output, using the given $maxLength and the previously set input html and the $options parameter.
9 | - sub(['option' => 'value'], function() {...}): sets the given options for inside the function.
10 | */
11 |
12 | sub([
13 | 'ellipsis' => "…",
14 | 'includeEllipsisLength' => false,
15 | 'wholeWord' => false,
16 | 'cutWord' => 3,
17 | 'utf8' => true,
18 | ], function() {
19 |
20 | /* TEST: empty html */
21 | input("");
22 | t(-1, "");
23 | t( 0, "");
24 | t( 1, "");
25 |
26 |
27 | /* TEST: basic html */
28 | input("a");
29 | t(-1, "…");
30 | t( 0, "…");
31 | t( 1, "a");
32 | t( 2, "a");
33 |
34 | input("12 456789");
35 | t(-2, "12 4567…");
36 | t(-1, "12 45678…");
37 | t( 0, "…");
38 | t( 1, "1…");
39 | t( 2, "12…");
40 | t( 3, "12 …");
41 | t( 8, "12 45678…");
42 | t( 9, "12 456789");
43 | t(10, "12 456789");
44 |
45 | /* TEST: HTML entities */
46 | input("1& +56789");
47 | t(-2, "1& +567…");
48 | t(-1, "1& +5678…");
49 | t( 0, "…");
50 | t( 1, "1…");
51 | t( 2, "1&…");
52 | t( 3, "1& …");
53 | t( 4, "1& +…");
54 | t( 8, "1& +5678…");
55 | t( 9, "1& +56789");
56 | t(10, "1& +56789");
57 |
58 | /* TEST: Multiple spaces */
59 | input("___");
60 | t(2, "__…");
61 | input(" \t\t ");
62 | t(-1, "…");
63 | t( 0, "…");
64 | t( 1, " \t\t ");
65 | t( 2, " \t\t ");
66 |
67 | input("1 3456");
68 | t(-1, "1 345…");
69 | t( 0, "…");
70 | t( 1, "1…");
71 | t( 2, "1 …");
72 | t( 3, "1 3…");
73 | t( 4, "1 34…");
74 |
75 | input("1 ");
76 | t(-1, "1…");
77 | t( 0, "…");
78 | t( 1, "1…");
79 | t( 2, "1 ");
80 |
81 | input(" 2");
82 | t(-1, " …");
83 | t( 0, "…");
84 | t( 1, " …");
85 | t( 2, " 2");
86 |
87 |
88 | /* TEST: Include ellipsis length */
89 | sub(['includeEllipsisLength' => true], function() {
90 |
91 | input(['ellipsis' => "…"]);
92 |
93 | input("");
94 | t( 0, "");
95 |
96 | input("12");
97 | t( 0, "…");
98 | t( 1, "…");
99 | t( 2, "12");
100 |
101 |
102 | input(['ellipsis' => "..."]);
103 |
104 | input("");
105 | t( 0, "");
106 |
107 | input("12");
108 | t( 0, "...");
109 | t( 1, "...");
110 | t( 2, "12");
111 |
112 | input("123");
113 | t( 0, "...");
114 | t( 1, "...");
115 | t( 2, "...");
116 | t( 3, "123");
117 | });
118 |
119 |
120 | /* TEST: Empty ellipsis */
121 | sub(['ellipsis' => ""], function() {
122 |
123 | input(['includeEllipsisLength' => false]);
124 |
125 | input("");
126 | t( 0, "");
127 | t( 1, "");
128 |
129 | input("abc");
130 | t( 0, "");
131 | t( 1, "a");
132 | t( 2, "ab");
133 | t( 3, "abc");
134 |
135 | input(['includeEllipsisLength' => true]);
136 |
137 | input("");
138 | t( 0, "");
139 | t( 1, "");
140 |
141 | input("abc");
142 | t( 0, "");
143 | t( 1, "a");
144 | t( 2, "ab");
145 | t( 3, "abc");
146 | });
147 |
148 |
149 | /* TEST: Whole word */
150 | sub(['wholeWord' => true], function() {
151 |
152 | input("12 45678");
153 | t( 0, "…");
154 | t( 1, "…");
155 | t( 2, "12…");
156 | t( 3, "12…");
157 | t( 4, "12…");
158 | t( 5, "12…");
159 | t( 6, "12 456…");
160 | t( 7, "12 4567…");
161 | t( 7, "12…", ['cutWord' => 0]);
162 | t( 7, "12…", ['cutWord' => false]);
163 |
164 | input("12 45678");
165 | t( 0, "…");
166 | t( 1, "…");
167 | t( 2, "12…");
168 | t( 3, "12…");
169 | t( 4, "12…");
170 | t( 5, "12…");
171 | t( 6, "12 456…");
172 | t( 7, "12 4567…");
173 |
174 | input("12
12");
271 | t( 0, "…");
272 | t( 1, "