Skip to content

Commit 132274a

Browse files
jfcherngjfcherng
committed
docs: add UPGRADING_v7.md and CHANGELOG_v7.md
Signed-off-by: Jack Cherng <jfcherng@gmail.com>
1 parent c2732ad commit 132274a

3 files changed

Lines changed: 170 additions & 53 deletions

File tree

‎CHANGELOG/CHANGELOG_v7.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
11
## v7.0.0
22

3-
TBD
3+
There is no new features in this major release.
4+
The main focus is to modernize the codebase and improve type safety.
5+
6+
- The minimum supported PHP version is now **8.3**.
7+
- Introduce `DifferOptions` value object.
8+
- Introduce `RendererOptions` value object.

‎README.md‎

Lines changed: 47 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,8 @@ include __DIR__ . '/vendor/autoload.php';
5858
use Jfcherng\Diff\Differ;
5959
use Jfcherng\Diff\DiffHelper;
6060
use Jfcherng\Diff\Factory\RendererFactory;
61+
use Jfcherng\Diff\Options\DifferOptions;
62+
use Jfcherng\Diff\Options\RendererOptions;
6163
use Jfcherng\Diff\Renderer\RendererConstant;
6264

6365
$oldFile = __DIR__ . '/example/old_file.txt';
@@ -71,69 +73,62 @@ $new = 'And this is the new one.';
7173
// HTML renderers: Combined, Inline, JsonHtml, SideBySide
7274
$rendererName = 'Unified';
7375

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,
76+
// the Differ options
77+
$differOptions = new DifferOptions(
78+
// show how many neighbor lines; Differ::CONTEXT_ALL shows the whole file
79+
context: 3,
7980
// ignore case difference
80-
'ignoreCase' => false,
81+
ignoreCase: false,
8182
// ignore line ending difference
82-
'ignoreLineEnding' => false,
83+
ignoreLineEnding: false,
8384
// 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 = [
85+
ignoreWhitespace: false,
86+
// if the input sequence is too long, give up (especially for char-level diff)
87+
lengthLimit: 2000,
88+
// when inputs are identical, render the whole content rather than an empty result
89+
fullContextIfIdentical: false,
90+
);
91+
92+
// the renderer options
93+
$rendererOptions = new RendererOptions(
9394
// how detailed the rendered HTML in-line diff is? (none, line, word, char)
94-
'detailLevel' => 'line',
95+
detailLevel: 'line',
9596
// renderer language: eng, cht, chs, jpn, ...
9697
// or an array which has the same keys with a language file
9798
// check the "Custom Language" section in the readme for more advanced usage
98-
'language' => 'eng',
99+
language: 'eng',
99100
// show line numbers in HTML renderers
100-
'lineNumbers' => true,
101+
lineNumbers: true,
101102
// show a separator between different diff hunks in HTML renderers
102-
'separateBlock' => true,
103+
separateBlock: true,
103104
// 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,
105+
showHeader: true,
106+
// render spaces/tabs as <span class="ch sp"> </span> tags (visualised via CSS)
107+
spaceToHtmlTag: false,
108+
// convert consecutive spaces to &nbsp; in HTML output
109+
spacesToNbsp: false,
108110
// 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-
];
111+
tabSize: 4,
112+
// Combined renderer: merge replace-blocks whose changed ratio is at or below this threshold (0–1)
113+
mergeThreshold: 0.8,
114+
// Unified/Context renderers CLI colorization:
115+
// RendererConstant::CLI_COLOR_AUTO = colorize if possible (default)
116+
// RendererConstant::CLI_COLOR_ENABLE = force colorize
117+
// RendererConstant::CLI_COLOR_DISABLE = force no color
118+
cliColorization: RendererConstant::CLI_COLOR_AUTO,
119+
// JSON renderer: emit op tags as human-readable strings instead of ints
120+
outputTagAsString: false,
121+
// JSON renderer: flags passed to json_encode()
122+
// see https://www.php.net/manual/en/function.json-encode.php
123+
jsonEncodeFlags: \JSON_UNESCAPED_SLASHES | \JSON_UNESCAPED_UNICODE,
124+
// word-level diff: adjacent segments joined by these characters are merged into one
125+
// e.g. "<del>good</del>-<del>looking</del>" → "<del>good-looking</del>"
126+
wordGlues: ['-', ' '],
127+
// return this string verbatim when the two inputs are identical; null = renderer default
128+
resultForIdenticals: null,
129+
// extra CSS classes added to the diff container <div> in HTML renderers
130+
wrapperClasses: ['diff-wrapper'],
131+
);
137132

138133
// one-line simply compare two files
139134
$result = DiffHelper::calculateFiles($oldFile, $newFile, $rendererName, $differOptions, $rendererOptions);

‎UPGRADING/UPGRADING_v7.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
## Upgrading to v7
2+
3+
### PHP version requirement raised to 8.3
4+
5+
The minimum supported PHP version is now **8.3**.
6+
7+
### [BREAKING CHANGE] `DifferOptions` value object
8+
9+
Differ options are now represented by `Jfcherng\Diff\Options\DifferOptions` instead of a plain associative array.
10+
This change makes it easier to be statically analyzed.
11+
12+
**Before (v6):**
13+
14+
```php
15+
<?php
16+
17+
$differ = new Differ($old, $new, [
18+
'context' => 3,
19+
'ignoreCase' => false,
20+
'ignoreLineEnding' => false,
21+
'ignoreWhitespace' => false,
22+
'lengthLimit' => 2000,
23+
'fullContextIfIdentical' => false,
24+
]);
25+
```
26+
27+
**After (v7):**
28+
29+
```php
30+
<?php
31+
32+
use Jfcherng\Diff\Options\DifferOptions;
33+
34+
$differ = new Differ($old, $new, new DifferOptions(
35+
context: 3,
36+
ignoreCase: false,
37+
ignoreLineEnding: false,
38+
ignoreWhitespace: false,
39+
lengthLimit: 2000,
40+
fullContextIfIdentical: false,
41+
));
42+
```
43+
44+
`Differ::__construct()`, `DiffHelper::calculate()`, and
45+
`DiffHelper::calculateFiles()` still accept a plain array for backward
46+
compatibility — it is converted to `DifferOptions` internally via
47+
`DifferOptions::fromArray()`. Passing a typed object is now preferred.
48+
49+
The public property `Differ::$options` is now of type `DifferOptions`
50+
instead of `array`.
51+
52+
### [BREAKING CHANGE] `RendererOptions` value object
53+
54+
It's similar to `DifferOptions`.
55+
56+
Renderer options are now represented by `Jfcherng\Diff\Options\RendererOptions` instead of a plain associative array.
57+
58+
**Before (v6):**
59+
60+
```php
61+
<?php
62+
63+
$renderer = RendererFactory::make('Inline', [
64+
'detailLevel' => 'line',
65+
'language' => 'eng',
66+
'lineNumbers' => true,
67+
'separateBlock' => true,
68+
'showHeader' => true,
69+
'spacesToNbsp' => false,
70+
'tabSize' => 4,
71+
'mergeThreshold' => 0.8,
72+
'cliColorization' => RendererConstant::CLI_COLOR_AUTO,
73+
'outputTagAsString' => false,
74+
'jsonEncodeFlags' => JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE,
75+
'wordGlues' => ['-', ' '],
76+
'resultForIdenticals' => null,
77+
'wrapperClasses' => ['diff-wrapper'],
78+
]);
79+
```
80+
81+
**After (v7):**
82+
83+
```php
84+
<?php
85+
86+
use Jfcherng\Diff\Options\RendererOptions;
87+
88+
$renderer = RendererFactory::make('Inline', new RendererOptions(
89+
detailLevel: 'line',
90+
language: 'eng',
91+
lineNumbers: true,
92+
separateBlock: true,
93+
showHeader: true,
94+
spaceToHtmlTag: false,
95+
spacesToNbsp: false,
96+
tabSize: 4,
97+
mergeThreshold: 0.8,
98+
cliColorization: RendererConstant::CLI_COLOR_AUTO,
99+
outputTagAsString: false,
100+
jsonEncodeFlags: JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE,
101+
wordGlues: ['-', ' '],
102+
resultForIdenticals: null,
103+
wrapperClasses: ['diff-wrapper'],
104+
));
105+
```
106+
107+
`RendererFactory::make()` and `AbstractRenderer::setOptions()` still accept
108+
a plain array for backward compatibility — it is converted via
109+
`RendererOptions::fromArray()` internally. Passing a typed object is preferred.
110+
111+
### `jfcherng/php-sequence-matcher` bumped to v5
112+
113+
The `SequenceMatcher::setOptions()` method now requires a `Jfcherng\Diff\SequenceMatcherOptions` object instead of an array.
114+
This only affects code that instantiates or configures `SequenceMatcher` directly.
115+
Users interacting solely through `Differ` or `DiffHelper` are not affected.
116+
117+
`DifferOptions` exposes a `toSequenceMatcherOptions()` helper to convert between the two types.

0 commit comments

Comments
 (0)