PHPackages                             raigu/ordered-lists-sync - 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. raigu/ordered-lists-sync

ActiveLibrary

raigu/ordered-lists-sync
========================

Library for synchronizing ordered data with the minimum of insert and delete operations.

v0.3.2(2mo ago)19MITPHPPHP ^7.4|^8.0CI passing

Since Aug 21Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/raigu/ordered-lists-sync)[ Packagist](https://packagist.org/packages/raigu/ordered-lists-sync)[ RSS](/packages/raigu-ordered-lists-sync/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (3)Dependencies (1)Versions (13)Used By (0)

[![Latest Stable Version](https://camo.githubusercontent.com/ce6dfa9966301bb30bf01ac88491bf1c72d77d9b923a0a00b27121499febcb24/687474703a2f2f706f7365722e707567782e6f72672f72616967752f6f7264657265642d6c697374732d73796e632f762f737461626c65)](https://packagist.org/packages/raigu/ordered-lists-sync)[![build](https://github.com/raigu/ordered-lists-sync/workflows/build/badge.svg)](https://github.com/raigu/ordered-data-sync/actions)[![codecov](https://camo.githubusercontent.com/8ce07e933c81386e32c4af0b2067799057cb8aae95e7dd078e035eaa73887a58/68747470733a2f2f636f6465636f762e696f2f67682f72616967752f6f7264657265642d6c697374732d73796e632f6272616e63682f6d61696e2f67726170682f62616467652e7376673f746f6b656e3d34334230583935435a33)](https://codecov.io/gh/raigu/ordered-data-sync)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/a1748eb017163e1e6748d42ca1c5b801177a1e4d68a10db1ef8fd1d87f30cd73/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f72616967752f6f7264657265642d6c697374732d73796e632f6261646765732f7175616c6974792d73636f72652e706e673f623d6d61696e)](https://scrutinizer-ci.com/g/raigu/ordered-lists-sync/?branch=main)[![License: MIT](https://camo.githubusercontent.com/08cef40a9105b6526ca22088bc514fbfdbc9aac1ddbf8d4e6c750e3a88a44dca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e737667)](LICENSE)[![Dependents](https://camo.githubusercontent.com/c8fc2f8244a125aefd32415e5ddeca11beef9fe2753c4d70829cc636e68f70d6/687474703a2f2f706f7365722e707567782e6f72672f72616967752f6f7264657265642d6c697374732d73796e632f646570656e64656e7473)](https://packagist.org/packages/raigu/ordered-lists-sync)

Library for synchronizing ordered data with the minimum of insert and delete operations.

Optimized for large datasets. Suitable for keeping in sync internal data with outside source. See [demos](./demo).

Compatibility
=============

[](#compatibility)

- PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4, 8.5

Installations
=============

[](#installations)

```
$ composer require raigu/ordered-lists-sync
```

Usage
=====

[](#usage)

`\Raigu\OrderedListsSynchronization\Synchronization` compares source and target lists. It detects which elements have been added or removed in source compared to the target and calls corresponding callback.

The source and target must be of type `Iterator`.

```
$synchronization = new \Raigu\OrderedListsSynchronization\Synchronization();
$synchronization(
    $source = new ArrayIterator(['A', 'B', 'D']),
    $target = new ArrayIterator(['B', 'C', 'D']),
    $add = function ($element) { echo "ADD: {$element}\n"; },
    $remove = function ($element) { echo "REMOVE: {$element}\n"; }
);
```

Output:

```
ADD: A
REMOVE: C

```

Use Cases
=========

[](#use-cases)

Sample use cases with demo code:

- Keeping a relational database table in sync with another ( demo: [./demo/database\_tables.php](./demo/database_tables.php))
- Keeping local data in sync with data available in internet ( demo: [./demo/internet\_to\_database.php](./demo/internet_to_database.php))
- Syncing entities identified by unique id and having several attributes (demo: [./demo/sync\_entities.php](./demo/sync_entities.php))

Design
======

[](#design)

The `\Raigu\OrderedListsSynchronization\Synchronization` has only one purpose. Therefore, it is [designed](https://www.php.net/manual/en/language.oop5.magic.php#object.invoke) so the instance will be a function, no method is exposed. It is an object because it allows extending it in future (for example adding logging).

Using `Iterator` type for source and target has several advantages.

First, you can create your own iterators as separate components which are easier to develop and test.

Secondly, more complex problems can be solved. Specially if there are memory constraints.
You can make source or target as [generator](https://www.php.net/manual/en/language.generators.overview.php), as an instance implementing [Iterate](https://www.php.net/manual/en/class.iterator.php)or [IteratorAggregate](https://www.php.net/manual/en/class.iteratoraggregate.php) interface or use [Sandard PHP Library (SPL) iterators](https://www.php.net/manual/en/spl.iterators.php).

Thirdly, it allows creating components which do not do any job in constructor. This is convenient when using dependency injection or declarative programming.

Development
===========

[](#development)

Setting up
----------

[](#setting-up)

```
$ git clone git@github.com:raigu/ordered-lists-sync.git
$ cd ordered-lists-sync
$ composer install
```

Testing
-------

[](#testing)

```
$ composer test
$ composer coverage
```

Algorithm
=========

[](#algorithm)

Algorithm works same way like we use dictionary. If all words are ordered, then we know exactly where some word should be. If we have two dictionaries and start to compare them word by word from start, then we can detect added or removed words.

Example (`V` denotes current position of the iterator):

```
        V
Source: A, B, D
        V
Target: B, C, D

```

A < B => if source is before target, then this means that value is missing in target. If there would be an A in target, then it should be here before B. But it is not. Therefore, it is missing and should be added. Add A and move source cursor:

```
           V
Source: A, B, D
        V
Target: B, C, D

```

B = B => if the source and target are equal, then they are sync. Move both cursors.

```
              V
Source: A, B, D
           V
Target: B, C, D

```

D > C => if source is after the target, then this means that value has been removed from source. Therefore, remove C and move the cursor forward:

```
              V
Source: A, B, D
              V
Target: B, C, D

```

D = D => they are in sync. Move both cursors.

###  Health Score

40

—

FairBetter than 88% of packages

Maintenance82

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 96.3% 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 ~182 days

Recently: every ~410 days

Total

10

Last Release

89d ago

PHP version history (2 changes)v0.1.0-alphaPHP >=7.4

v0.3.1PHP ^7.4|^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/82bf3ac844b3984ae4f9965188829da1729ca1e86abd92151406d15896c021b9?d=identicon)[raigu](/maintainers/raigu)

---

Top Contributors

[![raigu](https://avatars.githubusercontent.com/u/3442567?v=4)](https://github.com/raigu "raigu (52 commits)")[![claude](https://avatars.githubusercontent.com/u/81847?v=4)](https://github.com/claude "claude (2 commits)")

---

Tags

datalistsorderingsyncsyncrhonizationupdate

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/raigu-ordered-lists-sync/health.svg)

```
[![Health](https://phpackages.com/badges/raigu-ordered-lists-sync/health.svg)](https://phpackages.com/packages/raigu-ordered-lists-sync)
```

PHPackages © 2026

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