Skip to content

Commit aaa1b64

Browse files
tymondesignsclaude
andcommitted
docs: fill gaps in documentation
- Add error handling section to quickstart covering JsonRepairException - Add smart/curly quote and invalid escape sequence examples to repair-examples - Add missing log messages to the logging page (comments, trailing comma, smart quotes, doubled delimiter, incomplete string removal) - Clarify what composer check runs in the installation dev setup steps - Simplify the ensureAscii example to use a less noisy key name Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 7787548 commit aaa1b64

5 files changed

Lines changed: 51 additions & 9 deletions

File tree

docs/json-repair/configuration.mdx

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,12 @@ When `true` (default), non-ASCII characters are escaped. When `false`, Unicode i
1212
use function Cortex\JsonRepair\json_repair;
1313

1414
// ensureAscii: true (default) - escapes Unicode
15-
json_repair("{'test_中国人_ascii':'统一码'}", ensureAscii: true);
16-
// {"test_中国人_ascii":"\u7edf\u4e00\u7801"}
15+
json_repair("{'city':'上海'}", ensureAscii: true);
16+
// {"city":"\u4e0a\u6d77"}
1717

1818
// ensureAscii: false - preserves Unicode
19-
json_repair("{'test_中国人_ascii':'统一码'}", ensureAscii: false);
20-
// {"test_中国人_ascii":"统一码"}
19+
json_repair("{'city':'上海'}", ensureAscii: false);
20+
// {"city":"上海"}
2121
```
2222

2323
## omitEmptyValues

docs/json-repair/installation.mdx

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ If you're contributing to the package or want to run tests:
4040
```
4141
</Step>
4242
<Step title="Run Tests and Code Quality Tools">
43+
Runs tests, static analysis (PHPStan), coding standards (ECS), and type coverage:
4344
```bash
4445
composer check
4546
```

docs/json-repair/logging.mdx

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -39,15 +39,22 @@ Valid JSON produces a single log entry:
3939
When repairs occur, you'll see messages such as:
4040

4141
- `Starting JSON repair`
42-
- `Adding missing closing quote for unclosed string`
43-
- `Adding missing closing bracket/brace`
42+
- `Extracted JSON from markdown code block`
43+
- `Removed comments from JSON`
44+
- `Removing single-line comment`
45+
- `Removing multi-line comment`
4446
- `Converting single-quoted key to double quotes`
45-
- `Normalizing boolean/null value` (with context: `from: 'True', to: 'true'`)
47+
- `Converting smart/curly quote to standard double quote`
48+
- `Found doubled quote delimiter pattern, normalizing key`
4649
- `Adding quotes around unquoted key`
4750
- `Found unquoted string value, adding quotes`
48-
- `Inserting missing comma`
4951
- `Inserting missing colon after key`
50-
- `Extracted JSON from markdown code block`
52+
- `Inserting missing comma`
53+
- `Removing trailing comma`
54+
- `Normalizing boolean/null value` (with context: `from: 'True', to: 'true'`)
55+
- `Adding missing closing quote for unclosed string`
56+
- `Removing incomplete string value (omitIncompleteStrings enabled)`
57+
- `Adding missing closing bracket/brace`
5158
- `Removing key with missing value (omitEmptyValues enabled)`
5259

5360
Log entries include `position` and `context` with `>>>` markers showing where the repair occurred.

docs/json-repair/quickstart.mdx

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,23 @@ $data = $repairer->decode();
4040
// ['key' => 'value']
4141
```
4242

43+
## Error Handling
44+
45+
`repair()` throws `JsonRepairException` if the input cannot be repaired into valid JSON:
46+
47+
```php
48+
use Cortex\JsonRepair\JsonRepairer;
49+
use Cortex\JsonRepair\Exceptions\JsonRepairException;
50+
51+
try {
52+
$repaired = (new JsonRepairer($input))->repair();
53+
} catch (JsonRepairException $e) {
54+
// input could not be repaired into valid JSON
55+
}
56+
```
57+
58+
The helper functions `json_repair()` and `json_repair_decode()` propagate the same exception.
59+
4360
## Next Steps
4461

4562
- See [Repair Examples](/json-repair/repair-examples) for what gets fixed

docs/json-repair/repair-examples.mdx

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,30 @@ json_repair("{'key': 'string', \"key4\": unquoted}");
1919
// {"key": "string", "key4": "unquoted"}
2020
```
2121

22+
Typographic (smart/curly) quotes are normalised to standard double quotes:
23+
24+
```php
25+
json_repair('{"key": "value"}');
26+
// {"key": "value"}
27+
28+
json_repair("{'key': 'value'}");
29+
// {"key": "value"}
30+
```
31+
2232
Quotes inside string values are escaped:
2333

2434
```php
2535
json_repair('{"key": "v"alu"e"}');
2636
// {"key": "v\"alu\"e"}
2737
```
2838

39+
Invalid escape sequences are double-escaped so the output stays valid:
40+
41+
```php
42+
json_repair('{"key": "foo\qbar"}');
43+
// {"key": "foo\\qbar"}
44+
```
45+
2946
## Commas and Colons
3047

3148
Trailing commas are removed; missing commas and colons are inserted.

0 commit comments

Comments
 (0)