PHPackages                             bumpcore/json-patch - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. bumpcore/json-patch

ActiveLibrary[Parsing & Serialization](/categories/parsing)

bumpcore/json-patch
===================

RFC 6902 JSON Patch and RFC 7396 JSON Merge Patch implementation for PHP.

v0.1.1(2w ago)08MITPHPPHP ^8.3CI passing

Since May 21Pushed 2w agoCompare

[ Source](https://github.com/bumpcore/json-patch)[ Packagist](https://packagist.org/packages/bumpcore/json-patch)[ RSS](/packages/bumpcore-json-patch/feed)WikiDiscussions 0.x Synced 1w ago

READMEChangelog (2)Dependencies (4)Versions (4)Used By (0)

BumpCore JSON Patch
===================

[](#bumpcore-json-patch)

BumpCore JSON Patch is a dependency-free PHP package for working with JSON change documents. It supports RFC 6902 JSON Patch, RFC 7396 JSON Merge Patch, and RFC 6901 JSON Pointer.

Use it when you need to apply HTTP PATCH payloads, generate deterministic patch documents, address values inside JSON-like PHP data, or expose precise patch errors to API clients.

Table Of Contents
-----------------

[](#table-of-contents)

- [Version Table](#version-table)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Choosing a Patch Format](#choosing-a-patch-format)
- [JSON Patch](#json-patch)
    - [Applying JSON Patch Documents](#applying-json-patch-documents)
    - [Generating JSON Patch Documents](#generating-json-patch-documents)
    - [Supported Operations](#supported-operations)
- [JSON Merge Patch](#json-merge-patch)
- [JSON Pointer](#json-pointer)
- [JSON Values in PHP](#json-values-in-php)
- [Exceptions](#exceptions)
- [Testing](#testing)
- [Contribution](#contribution)
- [Changelog](#changelog)
- [Credits](#credits)
- [License](#license)

Version Table
-------------

[](#version-table)

BumpCore JSON PatchPHP0.x^8.3Installation
------------

[](#installation)

Install the package with Composer:

```
composer require bumpcore/json-patch
```

Quick Start
-----------

[](#quick-start)

```
use BumpCore\JsonPatch\JsonPatch;

$document = ['foo' => ['bar', 'baz']];

$result = JsonPatch::apply($document, [
    ['op' => 'add', 'path' => '/foo/1', 'value' => 'qux'],
]);

// ['foo' => ['bar', 'qux', 'baz']]
```

For JSON string input and output:

```
use BumpCore\JsonPatch\JsonPatch;

$json = JsonPatch::applyJson(
    '{"foo":["bar","baz"]}',
    '[{"op":"add","path":"/foo/1","value":"qux"}]',
);

// {"foo":["bar","qux","baz"]}
```

Choosing a Patch Format
-----------------------

[](#choosing-a-patch-format)

This package supports two patch formats because they solve different problems.

Use **JSON Patch** when you need explicit operations:

```
[
  {"op": "replace", "path": "/title", "value": "Hello!"},
  {"op": "remove", "path": "/author/familyName"}
]
```

Use **JSON Merge Patch** when the patch should look like the document shape:

```
{
  "title": "Hello!",
  "author": {
    "familyName": null
  }
}
```

JSON Patch can update individual array elements. JSON Merge Patch replaces arrays as whole values and uses `null` object members as removals.

JSON Patch
----------

[](#json-patch)

`JsonPatch` implements RFC 6902.

### Applying JSON Patch Documents

[](#applying-json-patch-documents)

```
use BumpCore\JsonPatch\JsonPatch;

$document = [
    'title' => 'Goodbye!',
    'tags' => ['example', 'sample'],
];

$patched = JsonPatch::apply($document, [
    ['op' => 'replace', 'path' => '/title', 'value' => 'Hello!'],
    ['op' => 'remove', 'path' => '/tags/1'],
    ['op' => 'add', 'path' => '/published', 'value' => true],
]);

// [
//     'title' => 'Hello!',
//     'tags' => ['example'],
//     'published' => true,
// ]
```

Patch application does not mutate the input document. It stops at the first failing operation, as RFC 6902 requires.

### Generating JSON Patch Documents

[](#generating-json-patch-documents)

```
use BumpCore\JsonPatch\JsonPatch;

$source = ['name' => 'old', 'tags' => ['stable']];
$target = ['name' => 'new', 'tags' => ['stable', 'fast']];

$patch = JsonPatch::diff($source, $target);

// [
//     ['op' => 'replace', 'path' => '/name', 'value' => 'new'],
//     ['op' => 'add', 'path' => '/tags/-', 'value' => 'fast'],
// ]
```

`JsonPatch::diff()` generates readable `add`, `remove`, and `replace`operations. It intentionally does not infer `move` or `copy` operations because those require heuristic choices and can make generated patches harder to review.

For JSON text input and output:

```
use BumpCore\JsonPatch\JsonPatch;

$patchJson = JsonPatch::diffJson(
    '{"name":"old"}',
    '{"name":"new","enabled":true}',
);

// [{"op":"add","path":"/enabled","value":true},{"op":"replace","path":"/name","value":"new"}]
```

### Supported Operations

[](#supported-operations)

- `add`
- `remove`
- `replace`
- `move`
- `copy`
- `test`

The package exposes the RFC media type:

```
JsonPatch::MEDIA_TYPE; // application/json-patch+json
```

JSON Merge Patch
----------------

[](#json-merge-patch)

`JsonMergePatch` implements RFC 7396.

```
use BumpCore\JsonPatch\JsonMergePatch;

$document = [
    'title' => 'Goodbye!',
    'author' => [
        'givenName' => 'John',
        'familyName' => 'Doe',
    ],
    'tags' => ['example', 'sample'],
];

$patched = JsonMergePatch::apply($document, [
    'title' => 'Hello!',
    'author' => [
        'familyName' => null,
    ],
    'tags' => ['example'],
]);

// [
//     'title' => 'Hello!',
//     'author' => ['givenName' => 'John'],
//     'tags' => ['example'],
// ]
```

Merge Patch rules are intentionally simple:

- Object members are added or replaced.
- Object members set to `null` are removed.
- Arrays are replaced as whole values.
- Non-object patches replace the whole target document.

For JSON text input and output:

```
use BumpCore\JsonPatch\JsonMergePatch;

$json = JsonMergePatch::applyJson(
    '{"a":"b","c":{"d":"e","f":"g"}}',
    '{"a":"z","c":{"f":null}}',
);

// {"a":"z","c":{"d":"e"}}
```

The package exposes the RFC media type:

```
JsonMergePatch::MEDIA_TYPE; // application/merge-patch+json
```

JSON Pointer
------------

[](#json-pointer)

`JsonPointer` implements RFC 6901 pointer parsing and escaping.

```
use BumpCore\JsonPatch\JsonPointer;

$pointer = JsonPointer::fromString('/foo/~01');

$pointer->tokens(); // ['foo', '~1']
JsonPointer::escapeToken('a/b~c'); // a~1b~0c
JsonPointer::unescapeToken('a~1b~0c'); // a/b~c
```

Pointer helpers can also read and return modified copies of JSON-like values:

```
use BumpCore\JsonPatch\JsonPointer;

$document = ['items' => [['name' => 'Old']]];

JsonPointer::get($document, '/items/0/name'); // Old
JsonPointer::has($document, '/items/0/name'); // true

$updated = JsonPointer::set($document, '/items/0/name', 'New');
$removed = JsonPointer::remove($updated, '/items/0');
```

The helper methods do not mutate the original document.

JSON Values in PHP
------------------

[](#json-values-in-php)

The PHP-value APIs accept JSON-like PHP data:

- PHP lists are treated as JSON arrays.
- `stdClass` objects are treated as JSON objects.
- Non-list PHP arrays are treated as JSON objects for ergonomic PHP usage.
- Non-finite floats and non-JSON PHP values are rejected.

When exact JSON shape matters, especially empty objects or numeric object member names, use the JSON string helpers:

```
use BumpCore\JsonPatch\JsonPatch;

$json = JsonPatch::applyJson(
    '{"child":{}}',
    '[{"op":"add","path":"/child/0","value":"kept as an object member"}]',
);

// {"child":{"0":"kept as an object member"}}
```

Exceptions
----------

[](#exceptions)

All package-specific failures extend:

```
BumpCore\JsonPatch\Exception\JsonPatchException
```

More specific exceptions are available:

- `InvalidPatchException`
- `JsonPointerException`
- `TestFailedException`

Patch operation failures expose context when it is available:

```
$exception->operationIndex(); // 0
$exception->operation(); // remove
$exception->path(); // /items/0
$exception->from(); // /source for move/copy failures
```

Testing
-------

[](#testing)

Install development dependencies:

```
composer install
```

Run the test suite:

```
composer test
```

Run static analysis:

```
composer analyse
```

Check code style:

```
composer cs:check
```

Run the 100% coverage gate:

```
composer test:coverage
```

The test suite includes the active upstream `json-patch/json-patch-tests`fixtures. Coverage requires PCOV, Xdebug, or phpdbg.

Contribution
------------

[](#contribution)

Contributions are welcome. If you find a bug or have a suggestion for improvement, please open an issue or create a pull request.

Please include tests for behavioral changes and run the quality checks before submitting a pull request:

```
composer cs:check
composer analyse
composer test
```

Changelog
---------

[](#changelog)

See [CHANGELOG.md](CHANGELOG.md) for version history.

Credits
-------

[](#credits)

- [Abdulkadir Cemiloglu](https://github.com/megastive19)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE) for more information.

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance96

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity40

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

19d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e7ebacfe6cf6f4fea420c0a71271bb8ad18734bce868f06d49ac96cd30471654?d=identicon)[megasteve19](/maintainers/megasteve19)

---

Top Contributors

[![megasteve19](https://avatars.githubusercontent.com/u/32229751?v=4)](https://github.com/megasteve19 "megasteve19 (12 commits)")

---

Tags

json-mergejson-patchphpjsonjson pointerjson patchJSON merge patch

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/bumpcore-json-patch/health.svg)

```
[![Health](https://phpackages.com/badges/bumpcore-json-patch/health.svg)](https://phpackages.com/packages/bumpcore-json-patch)
```

###  Alternatives

[justinrainbow/json-schema

A library to validate a json schema.

3.7k328.4M734](/packages/justinrainbow-json-schema)[mtdowling/jmespath.php

Declaratively specify how to extract elements from a JSON document

2.0k493.5M159](/packages/mtdowling-jmespathphp)[jms/serializer

Library for (de-)serializing data of any complexity; supports XML, and JSON.

2.3k139.8M905](/packages/jms-serializer)[jms/serializer-bundle

Allows you to easily serialize, and deserialize data of any complexity

1.9k91.4M662](/packages/jms-serializer-bundle)[php-jsonpointer/php-jsonpointer

Implementation of JSON Pointer (http://tools.ietf.org/html/rfc6901)

9316.3M14](/packages/php-jsonpointer-php-jsonpointer)[colinodell/json5

UTF-8 compatible JSON5 parser for PHP

30424.1M51](/packages/colinodell-json5)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)