{"id":18994040,"url":"https://github.com/swaggest/json-diff","last_synced_at":"2025-04-13T04:56:50.600Z","repository":{"id":45655476,"uuid":"105132705","full_name":"swaggest/json-diff","owner":"swaggest","description":"JSON diff/rearrange/patch/pointer library for PHP","archived":false,"fork":false,"pushed_at":"2025-03-10T08:22:32.000Z","size":188,"stargazers_count":227,"open_issues_count":7,"forks_count":31,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-06T02:01:43.630Z","etag":null,"topics":["diff","hacktoberfest","json"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swaggest.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-09-28T10:01:05.000Z","updated_at":"2025-03-13T11:41:00.000Z","dependencies_parsed_at":"2024-11-08T17:30:40.568Z","dependency_job_id":"d6a26bee-5514-44f3-aaa6-b2e846954880","html_url":"https://github.com/swaggest/json-diff","commit_stats":{"total_commits":86,"total_committers":16,"mean_commits":5.375,"dds":0.6395348837209303,"last_synced_commit":"f4e511708060ff7511a3743fab4aa484a062bcfb"},"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggest%2Fjson-diff","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggest%2Fjson-diff/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggest%2Fjson-diff/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swaggest%2Fjson-diff/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swaggest","download_url":"https://codeload.github.com/swaggest/json-diff/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248537142,"owners_count":21120709,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["diff","hacktoberfest","json"],"created_at":"2024-11-08T17:23:56.546Z","updated_at":"2025-04-13T04:56:50.558Z","avatar_url":"https://github.com/swaggest.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JSON diff/rearrange/patch/pointer library for PHP\n\nA PHP implementation for finding unordered diff between two `JSON` documents.\n\n[![Build Status](https://travis-ci.org/swaggest/json-diff.svg?branch=master)](https://travis-ci.org/swaggest/json-diff)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/swaggest/json-diff/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/swaggest/json-diff/?branch=master)\n[![Code Climate](https://codeclimate.com/github/swaggest/json-diff/badges/gpa.svg)](https://codeclimate.com/github/swaggest/json-diff)\n[![Code Coverage](https://scrutinizer-ci.com/g/swaggest/json-diff/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/swaggest/json-diff/code-structure/master/code-coverage)\n[![time tracker](https://wakatime.com/badge/github/swaggest/json-diff.svg)](https://wakatime.com/badge/github/swaggest/json-diff)\n\n\n## Purpose\n\n * To simplify changes review between two `JSON` files you can use a standard `diff` tool on rearranged pretty-printed `JSON`.\n * To detect breaking changes by analyzing removals and changes from original `JSON`.\n * To keep original order of object sets (for example `swagger.json` [parameters](https://swagger.io/docs/specification/describing-parameters/) list).\n * To [make](#getpatch) and [apply](#jsonpatch) JSON Patches, specified in [RFC 6902](https://datatracker.ietf.org/doc/html/rfc6902) from the IETF.\n * To [make](#getmergepatch) and [apply](#jsonmergepatch) JSON Merge Patches, specified in [RFC 7386](https://datatracker.ietf.org/doc/html/rfc7386) from the IETF.\n * To retrieve and modify data by [JSON Pointer](https://datatracker.ietf.org/doc/html/rfc6901).\n * To recursively replace by JSON value.\n\n## Installation\n\n### Library\n\n```bash\ngit clone https://github.com/swaggest/json-diff.git\n```\n\n### Composer\n\n[Install PHP Composer](https://getcomposer.org/doc/00-intro.md)\n\n```bash\ncomposer require swaggest/json-diff\n```\n\n## Library usage\n\n### `JsonDiff`\n\nCreate `JsonDiff` object from two values (`original` and `new`).\n\n```php\n$r = new JsonDiff(json_decode($originalJson), json_decode($newJson));\n```\n\nOn construction `JsonDiff` will build `rearranged` value of `new` recursively keeping `original` keys order where possible. \nKeys that are missing in `original` will be appended to the end of `rearranged` value in same order they had in `new` value.\n\nIf two values are arrays of objects, `JsonDiff` will try to find a common unique field in those objects and use it as criteria for rearranging. \nYou can enable this behaviour with `JsonDiff::REARRANGE_ARRAYS` option:\n```php\n$r = new JsonDiff(\n    json_decode($originalJson), \n    json_decode($newJson),\n    JsonDiff::REARRANGE_ARRAYS\n);\n```\n\nAvailable options:\n * `REARRANGE_ARRAYS` is an option to enable [arrays rearrangement](#arrays-rearrangement) to minimize the difference.\n * `STOP_ON_DIFF` is an option to improve performance by stopping comparison when a difference is found.\n * `JSON_URI_FRAGMENT_ID` is an option to use URI Fragment Identifier Representation (example: \"#/c%25d\"). If not set default JSON String Representation (example: \"/c%d\").\n * `SKIP_JSON_PATCH` is an option to improve performance by not building JsonPatch for this diff.\n * `SKIP_JSON_MERGE_PATCH` is an option to improve performance by not building JSON Merge Patch value for this diff.\n * `TOLERATE_ASSOCIATIVE_ARRAYS` is an option to allow associative arrays to mimic JSON objects (not recommended).\n * `COLLECT_MODIFIED_DIFF` is an option to enable [getModifiedDiff](#getmodifieddiff).\n\nOptions can be combined, e.g. `JsonDiff::REARRANGE_ARRAYS + JsonDiff::STOP_ON_DIFF`.\n\n#### `getDiffCnt`\nReturns total number of differences\n\n#### `getPatch`\nReturns [`JsonPatch`](#jsonpatch) of difference\n\n#### `getMergePatch`\nReturns [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7386) value of difference\n\n#### `getRearranged`\nReturns new value, rearranged with original order.\n\n#### `getRemoved`\nReturns removals as partial value of original.\n\n#### `getRemovedPaths`\nReturns list of `JSON` paths that were removed from original.\n\n#### `getRemovedCnt`\nReturns number of removals.\n\n#### `getAdded`\nReturns additions as partial value of new.\n\n#### `getAddedPaths`\nReturns list of `JSON` paths that were added to new.\n\n#### `getAddedCnt`\nReturns number of additions.\n\n#### `getModifiedOriginal`\nReturns modifications as partial value of original.\n\n#### `getModifiedNew`\nReturns modifications as partial value of new.\n\n#### `getModifiedDiff`\nReturns list of [`ModifiedPathDiff`](src/ModifiedPathDiff.php) containing paths with original and new values.\n\nNot collected by default, requires `JsonDiff::COLLECT_MODIFIED_DIFF` option.\n\n#### `getModifiedPaths`\nReturns list of `JSON` paths that were modified from original to new.\n\n#### `getModifiedCnt`\nReturns number of modifications.\n\n### `JsonPatch`\n\n#### `import`\nCreates `JsonPatch` instance from `JSON`-decoded data.\n\n#### `export`\nCreates patch data from `JsonPatch` object.\n\n#### `op`\nAdds operation to `JsonPatch`.\n\n#### `apply`\nApplies patch to `JSON`-decoded data.\n\n#### `setFlags`\nAlters default behavior.\n\nAvailable flags:\n\n* `JsonPatch::STRICT_MODE` Disallow converting empty array to object for key creation.\n* `JsonPatch::TOLERATE_ASSOCIATIVE_ARRAYS` Allow associative arrays to mimic JSON objects (not recommended).\n\n### `JsonPointer`\n\n#### `escapeSegment`\nEscapes path segment.\n\n#### `splitPath`\nCreates array of unescaped segments from `JSON Pointer` string.\n\n#### `buildPath`\nCreates `JSON Pointer` string from array of unescaped segments.\n\n#### `add`\nAdds value to data at path specified by segments.\n\n#### `get`\nGets value from data at path specified by segments.\n\n#### `getByPointer`\nGets value from data at path specified `JSON Pointer` string.\n\n#### `remove`\nRemoves value from data at path specified by segments.\n\n### `JsonMergePatch`\n\n#### `apply`\nApplies patch to `JSON`-decoded data.\n\n### `JsonValueReplace`\n\n#### `process`\nRecursively replaces all nodes equal to `search` value with `replace` value.\n\n## Example\n\n```php\n$originalJson = \u003c\u003c\u003c'JSON'\n{\n    \"key1\": [4, 1, 2, 3],\n    \"key2\": 2,\n    \"key3\": {\n        \"sub0\": 0,\n        \"sub1\": \"a\",\n        \"sub2\": \"b\"\n    },\n    \"key4\": [\n        {\"a\":1, \"b\":true, \"subs\": [{\"s\":1}, {\"s\":2}, {\"s\":3}]}, {\"a\":2, \"b\":false}, {\"a\":3}\n    ]\n}\nJSON;\n\n$newJson = \u003c\u003c\u003c'JSON'\n{\n    \"key5\": \"wat\",\n    \"key1\": [5, 1, 2, 3],\n    \"key4\": [\n        {\"c\":false, \"a\":2}, {\"a\":1, \"b\":true, \"subs\": [{\"s\":3, \"add\": true}, {\"s\":2}, {\"s\":1}]}, {\"c\":1, \"a\":3}\n    ],\n    \"key3\": {\n        \"sub3\": 0,\n        \"sub2\": false,\n        \"sub1\": \"c\"\n    }\n}\nJSON;\n\n$patchJson = \u003c\u003c\u003c'JSON'\n[\n    {\"value\":4,\"op\":\"test\",\"path\":\"/key1/0\"},\n    {\"value\":5,\"op\":\"replace\",\"path\":\"/key1/0\"},\n    \n    {\"op\":\"remove\",\"path\":\"/key2\"},\n    \n    {\"op\":\"remove\",\"path\":\"/key3/sub0\"},\n    \n    {\"value\":\"a\",\"op\":\"test\",\"path\":\"/key3/sub1\"},\n    {\"value\":\"c\",\"op\":\"replace\",\"path\":\"/key3/sub1\"},\n    \n    {\"value\":\"b\",\"op\":\"test\",\"path\":\"/key3/sub2\"},\n    {\"value\":false,\"op\":\"replace\",\"path\":\"/key3/sub2\"},\n    \n    {\"value\":0,\"op\":\"add\",\"path\":\"/key3/sub3\"},\n\n    {\"value\":true,\"op\":\"add\",\"path\":\"/key4/0/subs/2/add\"},\n    \n    {\"op\":\"remove\",\"path\":\"/key4/1/b\"},\n    \n    {\"value\":false,\"op\":\"add\",\"path\":\"/key4/1/c\"},\n    \n    {\"value\":1,\"op\":\"add\",\"path\":\"/key4/2/c\"},\n    \n    {\"value\":\"wat\",\"op\":\"add\",\"path\":\"/key5\"}\n]\nJSON;\n\n$diff = new JsonDiff(json_decode($originalJson), json_decode($newJson), JsonDiff::REARRANGE_ARRAYS);\n$this-\u003eassertEquals(json_decode($patchJson), $diff-\u003egetPatch()-\u003ejsonSerialize());\n\n$original = json_decode($originalJson);\n$patch = JsonPatch::import(json_decode($patchJson));\n$patch-\u003eapply($original);\n$this-\u003eassertEquals($diff-\u003egetRearranged(), $original);\n```\n\n## PHP Classes as JSON objects\n\nDue to magical methods and other restrictions PHP classes can not be reliably mapped to/from JSON objects.\nThere is support for objects of PHP classes in `JsonPointer` with limitations:\n* `null` is equal to non-existent\n\n## Arrays Rearrangement\n\nWhen `JsonDiff::REARRANGE_ARRAYS` option is enabled, array items are ordered to match the original array.\n\nIf arrays contain homogenous objects, and those objects have a common property with unique values, array is\nordered to match placement of items with same value of such property in the original array.\n\nExample:\noriginal\n```json\n[{\"name\": \"Alex\", \"height\": 180},{\"name\": \"Joe\", \"height\": 179},{\"name\": \"Jane\", \"height\": 165}]\n```\nvs new\n```json\n[{\"name\": \"Joe\", \"height\": 179},{\"name\": \"Jane\", \"height\": 168},{\"name\": \"Alex\", \"height\": 180}]\n```\nwould produce a patch:\n```json\n[{\"value\":165,\"op\":\"test\",\"path\":\"/2/height\"},{\"value\":168,\"op\":\"replace\",\"path\":\"/2/height\"}]\n```\n\nIf qualifying indexing property is not found, rearrangement is done based on items equality.\n\nExample:\noriginal\n```json\n{\"data\": [{\"A\": 1, \"C\": [1, 2, 3]}, {\"B\": 2}]}\n```\nvs new\n```json\n{\"data\": [{\"B\": 2}, {\"A\": 1, \"C\": [3, 2, 1]}]}\n```\nwould produce no difference.\n\n## CLI tool\n\nMoved to [`swaggest/json-cli`](https://github.com/swaggest/json-cli)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswaggest%2Fjson-diff","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswaggest%2Fjson-diff","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswaggest%2Fjson-diff/lists"}