PHPackages                             d-skora/simple-sorted-linked-list - 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. [Utility & Helpers](/categories/utility)
4. /
5. d-skora/simple-sorted-linked-list

ActiveLibrary[Utility & Helpers](/categories/utility)

d-skora/simple-sorted-linked-list
=================================

A type-safe sorted linked list for PHP 8.2+, with stable scalar typing, custom sort order, and mutation-safe iteration.

1.0.0(today)00MITPHPPHP ^8.2

Since Jul 28Pushed todayCompare

[ Source](https://github.com/d-skora/simple-sorted-linked-list)[ Packagist](https://packagist.org/packages/d-skora/simple-sorted-linked-list)[ RSS](/packages/d-skora-simple-sorted-linked-list/feed)WikiDiscussions main Synced today

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

Simple Sorted Linked List
=========================

[](#simple-sorted-linked-list)

[![PHP](https://camo.githubusercontent.com/187240af044d09d5b14a1d9d9ebdf3f7a993e4c7bc09bdb46b4ba661a891bf5b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d626c7565)](https://camo.githubusercontent.com/187240af044d09d5b14a1d9d9ebdf3f7a993e4c7bc09bdb46b4ba661a891bf5b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d626c7565)[![License](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)](https://camo.githubusercontent.com/f8df3091bbe1149f398a5369b2c39e896766f9f6efba3477c63e9b4aa940ef14/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d677265656e)

A type-safe sorted singly linked list for PHP 8.2+. Items are kept in sorted order at all times, with stable scalar typing (a list of `int` stays a list of `int`), a pluggable sort order, and an iterator that remains safe even when the list is mutated during `foreach`.

---

Features
--------

[](#features)

- **Always sorted** — items are inserted in the correct position, not sorted on read
- **Stable scalar typing** — once the first item is inserted, the list accepts only the same scalar type (`int` or `string`); mixing types throws immediately
- **Ascending, descending, or custom order** — pass any comparator callable
- **Mutation-safe iteration** — you can `remove()`, `removeAll()`, or `clear()`inside a `foreach` without corrupting the iterator
- **Rich query API** — `first()`, `last()`, `at(int $index)`, `contains()`, `countOccurrences()`, `toArray()`
- **Functional helpers** — `copy()`, `filter()`, `merge()`
- **Zero runtime dependencies** — only `php: ^8.2`

---

Installation
------------

[](#installation)

```
composer require d-skora/simple-sorted-linked-list
```

---

Quick start
-----------

[](#quick-start)

### Ascending list of integers

[](#ascending-list-of-integers)

```
use SimpleSortedLinkedList\LinkedList\SortedLinkedList;
use SimpleSortedLinkedList\LinkedList\SortOrder;

$list = SortedLinkedList::create([3, 1, 4, 1, 5, 9, 2], SortOrder::ascending());

$list->toArray(); // [1, 1, 2, 3, 4, 5, 9]
$list->first();   // 1
$list->last();    // 9
$list->at(2);     // 2
$list->count();   // 7
```

### Descending list of strings

[](#descending-list-of-strings)

```
$list = SortedLinkedList::create(['banana', 'apple', 'cherry'], SortOrder::descending());

$list->toArray(); // ['cherry', 'banana', 'apple']
```

### Custom comparator

[](#custom-comparator)

```
// Sort integers by absolute value, ascending
$order = SortOrder::custom(static fn (int|string $a, int|string $b): int => abs((int)$a)  abs((int)$b));

$list = SortedLinkedList::create([-3, 1, -2], $order);
$list->toArray(); // [1, -2, -3]
```

### Factory

[](#factory)

```
use SimpleSortedLinkedList\LinkedList\SortedLinkedListFactory;

$list = SortedLinkedListFactory::create([5, 3, 1], SortOrder::ascending());
```

### Inserting and removing

[](#inserting-and-removing)

```
$list = SortedLinkedList::create([2, 1, 1, 3], SortOrder::ascending());

$list->insert(2);           // [1, 1, 2, 2, 3]
$list->remove(2);           // [1, 1, 2, 3]       — first occurrence only
$list->removeAll(1);        // [2, 3]

$list->insert(1);           // [1, 2, 3]
$list->insert(1);           // [1, 1, 2, 3]
$list->remove(1);           // [1, 2, 3]          — first occurrence only
```

### Filter and merge

[](#filter-and-merge)

```
$list = SortedLinkedList::create([1, 2, 3, 4, 5], SortOrder::ascending());

$evens = $list->filter(static fn (int|string $v): bool => (int)$v % 2 === 0);
$evens->toArray(); // [2, 4]

$other = SortedLinkedList::create([10, 20], SortOrder::ascending());
$merged = $list->merge($other);
$merged->toArray(); // [1, 2, 3, 4, 5, 10, 20]
```

### Safe mutation during foreach

[](#safe-mutation-during-foreach)

```
$list = SortedLinkedList::create([1, 2, 3, 4, 5], SortOrder::ascending());

foreach ($list as $value) {
    if ($value % 2 === 0) {
        $list->remove($value); // safe — iterator skips removed nodes
    }
}

$list->toArray(); // [1, 3, 5]
```

---

API reference
-------------

[](#api-reference)

MethodDescription`SortedLinkedList::create(iterable, SortOrder)`Static factory`insert(int|string)`Insert preserving order`remove(int|string): bool`Remove first occurrence`removeAll(int|string): bool`Remove all occurrences`first(): int|string`Head value (throws on empty)`last(): int|string`Tail value (throws on empty)`at(int): int|string`Value at zero-based index`contains(int|string): bool`Membership check`countOccurrences(int|string): int`Count of a specific value`count(): int`Total item count (`Countable`)`toArray(): array`Snapshot as array`clear()`Empty the list`copy()`Independent copy`filter(callable): self`New filtered list`merge(SortedLinkedListInterface): self`New merged list`getIterator()``foreach`-compatible iterator### Sort orders

[](#sort-orders)

FactoryBehaviour`SortOrder::ascending()`Natural ascending (integers by value, strings alphabetically)`SortOrder::descending()`Natural descending`SortOrder::custom(callable)`Comparator `fn(a, b): int` — same contract as `usort`### Exceptions

[](#exceptions)

ExceptionThrown when`InvalidArgumentException`Wrong scalar type inserted, or merging incompatible lists`UnderflowException``first()` / `last()` on empty list, or `current()` on exhausted iterator`OutOfBoundsException``at()` with out-of-range index`RuntimeException`Custom comparator returns a non-int, or comparator is not set---

Development
-----------

[](#development)

```
# Install dependencies
composer install

# Run tests
composer test

# Run tests with coverage (requires Xdebug)
XDEBUG_MODE=coverage composer test

# Static analysis (PHPStan level max + strict rules)
composer phpstan

# Check PSR-12 compliance
composer phpcs

# Auto-fix PSR-12 violations
composer phpcbf
```

---

License
-------

[](#license)

MIT © Daniel Skora

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance100

Actively maintained with recent releases

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity45

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

Unknown

Total

1

Last Release

0d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/4640851?v=4)[Daniel Skóra](/maintainers/d-skora)[@d-skora](https://github.com/d-skora)

---

Top Contributors

[![d-skora](https://avatars.githubusercontent.com/u/4640851?v=4)](https://github.com/d-skora "d-skora (1 commits)")

---

Tags

collectionlinked listtype-safesorteddata structure

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/d-skora-simple-sorted-linked-list/health.svg)

```
[![Health](https://phpackages.com/badges/d-skora-simple-sorted-linked-list/health.svg)](https://phpackages.com/packages/d-skora-simple-sorted-linked-list)
```

###  Alternatives

[chdemko/sorted-collections

Sorted Collections for PHP >= 8.4

222.7M3](/packages/chdemko-sorted-collections)[lorisleiva/lody

Load files and classes as lazy collections in Laravel.

957.9M15](/packages/lorisleiva-lody)[gamez/typed-collection

Type-safe collections based on Laravel Collections

45362.9k](/packages/gamez-typed-collection)

PHPackages © 2026

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