Debian Codegraph @

vendor/jfcherng/php-diff/README.md

raw
1 # php-diff
2
3 [![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/jfcherng/php-diff/php.yml?branch=v6&style=flat-square)](https://github.com/jfcherng/php-diff/actions)
4 [![Codacy grade](https://img.shields.io/codacy/grade/5b7ab5ed613d48b99f12cd334f6489ff/v6?style=flat-square)](https://app.codacy.com/project/jfcherng/php-diff/dashboard)
5 [![Packagist](https://img.shields.io/packagist/dt/jfcherng/php-diff?style=flat-square)](https://packagist.org/packages/jfcherng/php-diff)
6 [![Packagist Version](https://img.shields.io/packagist/v/jfcherng/php-diff?style=flat-square)](https://packagist.org/packages/jfcherng/php-diff)
7 [![Project license](https://img.shields.io/github/license/jfcherng/php-diff?style=flat-square)](https://github.com/jfcherng/php-diff/blob/v6/LICENSE)
8 [![GitHub stars](https://img.shields.io/github/stars/jfcherng/php-diff?style=flat-square&logo=github)](https://github.com/jfcherng/php-diff/stargazers)
9 [![Donate to this project using Paypal](https://img.shields.io/badge/paypal-donate-blue.svg?style=flat-square&logo=paypal)](https://www.paypal.me/jfcherng/5usd)
10
11 A comprehensive library for generating diff between two strings.
12
13 ## Introduction
14
15 Generated diff can be rendered in all of the standard formats including:
16
17 **Text** renderers:
18
19 - Context
20 - Json (plain text)
21 - Unified
22
23 **HTML** renderers:
24
25 - Combined
26 - Inline
27 - Json (HTML)
28 - Side by Side
29
30 Note that for HTML rendered results, you have to add CSS for a better visualization.
31 You may modify one from `example/diff-table.css` or write your own from zero.
32
33 If you are okay with the default CSS, there is `\Jfcherng\Diff\DiffHelper::getStyleSheet()`
34 which can be used to get the content of the `example/diff-table.css`.
35
36 ## Requirements
37
38 ![php](https://img.shields.io/badge/php-%E2%89%A57.4.0-blue?style=flat-square)
39 ![ext-iconv](https://img.shields.io/badge/ext-iconv-brightgreen?style=flat-square)
40
41 ## Installation
42
43 This package is available on `Packagist` by the name of [jfcherng/php-diff](https://packagist.org/packages/jfcherng/php-diff).
44
45 ```bash
46 composer require jfcherng/php-diff
47 ```
48
49 ## Example
50
51 See files and readme in the [example/](https://github.com/jfcherng/php-diff/blob/v6/example) directory.
52
53 ```php
54 <?php
55
56 include __DIR__ . '/vendor/autoload.php';
57
58 use Jfcherng\Diff\Differ;
59 use Jfcherng\Diff\DiffHelper;
60 use Jfcherng\Diff\Factory\RendererFactory;
61 use Jfcherng\Diff\Renderer\RendererConstant;
62
63 $oldFile = __DIR__ . '/example/old_file.txt';
64 $newFile = __DIR__ . '/example/new_file.txt';
65
66 $old = 'This is the old string.';
67 $new = 'And this is the new one.';
68
69 // renderer class name:
70 // Text renderers: Context, JsonText, Unified
71 // HTML renderers: Combined, Inline, JsonHtml, SideBySide
72 $rendererName = 'Unified';
73
74 // the Diff class options
75 $differOptions = [
76 // show how many neighbor lines
77 // Differ::CONTEXT_ALL can be used to show the whole file
78 'context' => 3,
79 // ignore case difference
80 'ignoreCase' => false,
81 // ignore line ending difference
82 'ignoreLineEnding' => false,
83 // ignore whitespace difference
84 'ignoreWhitespace' => false,
85 // if the input sequence is too long, it will just gives up (especially for char-level diff)
86 'lengthLimit' => 2000,
87 // if truthy, when inputs are identical, the whole inputs will be rendered in the output
88 'fullContextIfIdentical' => false,
89 ];
90
91 // the renderer class options
92 $rendererOptions = [
93 // how detailed the rendered HTML in-line diff is? (none, line, word, char)
94 'detailLevel' => 'line',
95 // renderer language: eng, cht, chs, jpn, ...
96 // or an array which has the same keys with a language file
97 // check the "Custom Language" section in the readme for more advanced usage
98 'language' => 'eng',
99 // show line numbers in HTML renderers
100 'lineNumbers' => true,
101 // show a separator between different diff hunks in HTML renderers
102 'separateBlock' => true,
103 // show the (table) header
104 'showHeader' => true,
105 // the frontend HTML could use CSS "white-space: pre;" to visualize consecutive whitespaces
106 // but if you want to visualize them in the backend with "&nbsp;", you can set this to true
107 'spacesToNbsp' => false,
108 // HTML renderer tab width (negative = do not convert into spaces)
109 'tabSize' => 4,
110 // this option is currently only for the Combined renderer.
111 // it determines whether a replace-type block should be merged or not
112 // depending on the content changed ratio, which values between 0 and 1.
113 'mergeThreshold' => 0.8,
114 // this option is currently only for the Unified and the Context renderers.
115 // RendererConstant::CLI_COLOR_AUTO = colorize the output if possible (default)
116 // RendererConstant::CLI_COLOR_ENABLE = force to colorize the output
117 // RendererConstant::CLI_COLOR_DISABLE = force not to colorize the output
118 'cliColorization' => RendererConstant::CLI_COLOR_AUTO,
119 // this option is currently only for the Json renderer.
120 // internally, ops (tags) are all int type but this is not good for human reading.
121 // set this to "true" to convert them into string form before outputting.
122 'outputTagAsString' => false,
123 // this option is currently only for the Json renderer.
124 // it controls how the output JSON is formatted.
125 // see available options on https://www.php.net/manual/en/function.json-encode.php
126 'jsonEncodeFlags' => \JSON_UNESCAPED_SLASHES | \JSON_UNESCAPED_UNICODE,
127 // this option is currently effective when the "detailLevel" is "word"
128 // characters listed in this array can be used to make diff segments into a whole
129 // for example, making "<del>good</del>-<del>looking</del>" into "<del>good-looking</del>"
130 // this should bring better readability but set this to empty array if you do not want it
131 'wordGlues' => [' ', '-'],
132 // change this value to a string as the returned diff if the two input strings are identical
133 'resultForIdenticals' => null,
134 // extra HTML classes added to the DOM of the diff container
135 'wrapperClasses' => ['diff-wrapper'],
136 ];
137
138 // one-line simply compare two files
139 $result = DiffHelper::calculateFiles($oldFile, $newFile, $rendererName, $differOptions, $rendererOptions);
140 // one-line simply compare two strings
141 $result = DiffHelper::calculate($old, $new, $rendererName, $differOptions, $rendererOptions);
142 // or even shorter if you are happy with default options
143 $result = DiffHelper::calculate($old, $new, $rendererName);
144
145 // custom usage
146 $differ = new Differ(explode("\n", $old), explode("\n", $new), $differOptions);
147 $renderer = RendererFactory::make($rendererName, $rendererOptions); // or your own renderer object
148 $result = $renderer->render($differ);
149
150 // use the JSON result to render in HTML
151 $jsonResult = DiffHelper::calculate($old, $new, 'Json'); // may store the JSON result in your database
152 $htmlRenderer = RendererFactory::make('Inline', $rendererOptions);
153 $result = $htmlRenderer->renderArray(json_decode($jsonResult, true));
154 ```
155
156 ## Rendered Results
157
158 ### HTML Diff In-line Detailed Rendering
159
160 <table>
161 <tr>
162 <th>None-level</th>
163 <th>Line-level (Default)</th>
164 </tr>
165 <tr>
166 <td><img src="https://raw.githubusercontent.com/jfcherng/php-diff/v6/example/images/inline-none-level-diff.png"></td>
167 <td><img src="https://raw.githubusercontent.com/jfcherng/php-diff/v6/example/images/inline-line-level-diff.png"></td>
168 </tr>
169 <tr>
170 <th>Word-level</th>
171 <th>Char-level</th>
172 </tr>
173 <tr>
174 <td><img src="https://raw.githubusercontent.com/jfcherng/php-diff/v6/example/images/inline-word-level-diff.png"></td>
175 <td><img src="https://raw.githubusercontent.com/jfcherng/php-diff/v6/example/images/inline-char-level-diff.png"></td>
176 </tr>
177 </table>
178
179 ### Renderer: Inline
180
181 ```php
182 <?php $rendererOptions = ['detailLevel' => 'line'];
183 ```
184
185 ![Inline](https://raw.githubusercontent.com/jfcherng/php-diff/v6/example/images/inline-renderer.png)
186
187 ### Renderer: Side By Side
188
189 ```php
190 <?php $rendererOptions = ['detailLevel' => 'line'];
191 ```
192
193 ![Side By Side](https://raw.githubusercontent.com/jfcherng/php-diff/v6/example/images/side-by-side-renderer.png)
194
195 ### Renderer: Combined
196
197 ```php
198 <?php $rendererOptions = ['detailLevel' => 'word'];
199 ```
200
201 This renderer is suitable for articles and always has no line number information.
202
203 ![Combined](https://raw.githubusercontent.com/jfcherng/php-diff/v6/example/images/combined-renderer-word-level.png)
204
205 ### Renderer: Unified
206
207 About the `Unified` diff format: https://en.wikipedia.org/wiki/Diff#Unified_format
208
209 ```diff
210 @@ -1,3 +1,4 @@
211 -<p>Hello World!</p>
212 +<div>Hello World!</div>
213 ~~~~~~~~~~~~~~~~~~~
214 +Let's add a new line here.
215 X
216 @@ -7,6 +8,5 @@
217 N
218 -Do you know in Chinese, "金槍魚罐頭" means tuna can.
219 +Do you know in Japanese, "魚の缶詰" means fish can.
220 This is just a useless line.
221 G
222 -// remember to delete this line
223 Say hello to my neighbors.
224 ```
225
226 ### Renderer: Context
227
228 About the `Context` diff format: https://en.wikipedia.org/wiki/Diff#Context_format
229
230 <details><summary>Click to expand</summary>
231
232 ```diff
233 ***************
234 *** 1,3 ****
235 ! <p>Hello World!</p>
236 ~~~~~~~~~~~~~~~~~~~
237 X
238 --- 1,4 ----
239 ! <div>Hello World!</div>
240 ~~~~~~~~~~~~~~~~~~~
241 + Let's add a new line here.
242 X
243 ***************
244 *** 7,12 ****
245 N
246 ! Do you know in Chinese, "金槍魚罐頭" means tuna can.
247 This is just a useless line.
248 G
249 - // remember to delete this line
250 Say hello to my neighbors.
251 --- 8,12 ----
252 N
253 ! Do you know in Japanese, "魚の缶詰" means fish can.
254 This is just a useless line.
255 G
256 Say hello to my neighbors.
257 ```
258
259 </details>
260
261 ### Renderer: Text JSON
262
263 This renderer has no detailed diff.
264
265 <details><summary>Click to expand</summary>
266
267 ```json
268 [
269 [
270 {
271 "tag": "rep",
272 "old": {
273 "offset": 0,
274 "lines": ["<p>Hello World! Good-looking.</p>"]
275 },
276 "new": {
277 "offset": 0,
278 "lines": ["<div>Hello World! Bad-tempered.</div>"]
279 }
280 },
281 {
282 "tag": "eq",
283 "old": {
284 "offset": 1,
285 "lines": ["~~~~~~~~~~~~~~~~~~~"]
286 },
287 "new": {
288 "offset": 1,
289 "lines": ["~~~~~~~~~~~~~~~~~~~"]
290 }
291 },
292 {
293 "tag": "ins",
294 "old": {
295 "offset": 2,
296 "lines": []
297 },
298 "new": {
299 "offset": 2,
300 "lines": ["Let's add a new line here."]
301 }
302 },
303 {
304 "tag": "eq",
305 "old": {
306 "offset": 2,
307 "lines": ["X"]
308 },
309 "new": {
310 "offset": 3,
311 "lines": ["X"]
312 }
313 }
314 ],
315 [
316 {
317 "tag": "eq",
318 "old": {
319 "offset": 6,
320 "lines": ["N"]
321 },
322 "new": {
323 "offset": 7,
324 "lines": ["N"]
325 }
326 },
327 {
328 "tag": "rep",
329 "old": {
330 "offset": 7,
331 "lines": ["Do you know in Chinese, \"金槍魚罐頭\" means tuna can."]
332 },
333 "new": {
334 "offset": 8,
335 "lines": ["Do you know in Japanese, \"魚の缶詰\" means fish can."]
336 }
337 },
338 {
339 "tag": "eq",
340 "old": {
341 "offset": 8,
342 "lines": ["\t \tTab visualization test.", "G"]
343 },
344 "new": {
345 "offset": 9,
346 "lines": ["\t \tTab visualization test.", "G"]
347 }
348 },
349 {
350 "tag": "del",
351 "old": {
352 "offset": 10,
353 "lines": ["// remember to delete this line"]
354 },
355 "new": {
356 "offset": 11,
357 "lines": []
358 }
359 },
360 {
361 "tag": "eq",
362 "old": {
363 "offset": 11,
364 "lines": ["Say hello to my neighbors."]
365 },
366 "new": {
367 "offset": 11,
368 "lines": ["Say hello to my neighbors."]
369 }
370 }
371 ],
372 [
373 {
374 "tag": "eq",
375 "old": {
376 "offset": 14,
377 "lines": ["B"]
378 },
379 "new": {
380 "offset": 14,
381 "lines": ["B"]
382 }
383 },
384 {
385 "tag": "rep",
386 "old": {
387 "offset": 15,
388 "lines": ["Donec rutrum."]
389 },
390 "new": {
391 "offset": 15,
392 "lines": ["Donec rutrum test.", "There is a new inserted line."]
393 }
394 },
395 {
396 "tag": "eq",
397 "old": {
398 "offset": 16,
399 "lines": ["C"]
400 },
401 "new": {
402 "offset": 17,
403 "lines": ["C"]
404 }
405 },
406 {
407 "tag": "rep",
408 "old": {
409 "offset": 17,
410 "lines": ["Sed dictum lorem ipsum."]
411 },
412 "new": {
413 "offset": 18,
414 "lines": ["Sed dolor lorem ipsum hendrerit."]
415 }
416 },
417 {
418 "tag": "eq",
419 "old": {
420 "offset": 18,
421 "lines": [""]
422 },
423 "new": {
424 "offset": 19,
425 "lines": [""]
426 }
427 }
428 ]
429 ]
430 ```
431
432 </details>
433
434 ### Renderer: HTML JSON
435
436 For a `"tag": "rep" (8)` block, this renderer has HTML-style detailed diff.
437 If you don't need those detailed diff, consider using the `JsonText` renderer.
438
439 <details><summary>Click to expand</summary>
440
441 ```json
442 [
443 [
444 {
445 "tag": "rep",
446 "old": {
447 "offset": 0,
448 "lines": ["&lt;<del>p&gt;Hello World! Good-looking.&lt;/p</del>&gt;"]
449 },
450 "new": {
451 "offset": 0,
452 "lines": ["&lt;<ins>div&gt;Hello World! Bad-tempered.&lt;/div</ins>&gt;"]
453 }
454 },
455 {
456 "tag": "eq",
457 "old": {
458 "offset": 1,
459 "lines": ["~~~~~~~~~~~~~~~~~~~"]
460 },
461 "new": {
462 "offset": 1,
463 "lines": ["~~~~~~~~~~~~~~~~~~~"]
464 }
465 },
466 {
467 "tag": "ins",
468 "old": {
469 "offset": 2,
470 "lines": [""]
471 },
472 "new": {
473 "offset": 2,
474 "lines": ["Let's add a new line here."]
475 }
476 },
477 {
478 "tag": "eq",
479 "old": {
480 "offset": 2,
481 "lines": ["X"]
482 },
483 "new": {
484 "offset": 3,
485 "lines": ["X"]
486 }
487 }
488 ],
489 [
490 {
491 "tag": "eq",
492 "old": {
493 "offset": 6,
494 "lines": ["N"]
495 },
496 "new": {
497 "offset": 7,
498 "lines": ["N"]
499 }
500 },
501 {
502 "tag": "rep",
503 "old": {
504 "offset": 7,
505 "lines": ["Do you know in <del>Chinese, \"金槍魚罐頭\" means tuna</del> can."]
506 },
507 "new": {
508 "offset": 8,
509 "lines": ["Do you know in <ins>Japanese, \"魚の缶詰\" means fish</ins> can."]
510 }
511 },
512 {
513 "tag": "eq",
514 "old": {
515 "offset": 8,
516 "lines": ["\t \tTab visualization test.", "G"]
517 },
518 "new": {
519 "offset": 9,
520 "lines": ["\t \tTab visualization test.", "G"]
521 }
522 },
523 {
524 "tag": "del",
525 "old": {
526 "offset": 10,
527 "lines": ["// remember to delete this line"]
528 },
529 "new": {
530 "offset": 11,
531 "lines": [""]
532 }
533 },
534 {
535 "tag": "eq",
536 "old": {
537 "offset": 11,
538 "lines": ["Say hello to my neighbors."]
539 },
540 "new": {
541 "offset": 11,
542 "lines": ["Say hello to my neighbors."]
543 }
544 }
545 ],
546 [
547 {
548 "tag": "eq",
549 "old": {
550 "offset": 14,
551 "lines": ["B"]
552 },
553 "new": {
554 "offset": 14,
555 "lines": ["B"]
556 }
557 },
558 {
559 "tag": "rep",
560 "old": {
561 "offset": 15,
562 "lines": ["Donec rutrum."]
563 },
564 "new": {
565 "offset": 15,
566 "lines": ["Donec rutrum test.", "There is a new inserted line."]
567 }
568 },
569 {
570 "tag": "eq",
571 "old": {
572 "offset": 16,
573 "lines": ["C"]
574 },
575 "new": {
576 "offset": 17,
577 "lines": ["C"]
578 }
579 },
580 {
581 "tag": "rep",
582 "old": {
583 "offset": 17,
584 "lines": ["Sed d<del>ictum lorem ipsum</del>."]
585 },
586 "new": {
587 "offset": 18,
588 "lines": ["Sed d<ins>olor lorem ipsum hendrerit</ins>."]
589 }
590 },
591 {
592 "tag": "eq",
593 "old": {
594 "offset": 18,
595 "lines": [""]
596 },
597 "new": {
598 "offset": 19,
599 "lines": [""]
600 }
601 }
602 ]
603 ]
604 ```
605
606 </details>
607
608 ## Custom Language
609
610 ### Override an Existing Language
611
612 If you just want to override some translations of an existing language...
613
614 ```php
615 $rendererOptions = [
616 'language' => [
617 // use English as the base language
618 'eng',
619 // your custom overrides
620 [
621 // use "Diff" as the new value of the "differences" key
622 'differences' => 'Diff',
623 ],
624 // maybe more overrides if you somehow need them...
625 ],
626 ]
627 ```
628
629 ## Acknowledgment
630
631 This package is built on the top of [chrisboulton/php-diff](https://github.com/chrisboulton/php-diff) initially.
632 But the original repository looks like no longer maintained.
633 Here have been quite lots of rewrites and new features since then, hence I re-started this as a new package for better visibility.