PHPackages                             adambenovic/shipmonk-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. adambenovic/shipmonk-sorted-linked-list

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

adambenovic/shipmonk-sorted-linked-list
=======================================

A type-safe sorted linked list for PHP 8.4+ that holds either int or string values, maintaining sorted order on insertion.

1.0.0(3mo ago)02MITPHPPHP ^8.4

Since Feb 9Pushed 3mo agoCompare

[ Source](https://github.com/adambenovic/shipmonk-test)[ Packagist](https://packagist.org/packages/adambenovic/shipmonk-sorted-linked-list)[ RSS](/packages/adambenovic-shipmonk-sorted-linked-list/feed)WikiDiscussions main Synced 1mo ago

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

SortedLinkedList
================

[](#sortedlinkedlist)

A type-safe sorted linked list library for PHP 8.4+. Holds either `int` or `string` values (never both in the same instance) and maintains ascending order on every insertion.

Requirements
------------

[](#requirements)

- PHP 8.4 or higher

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

[](#installation)

```
composer require adambenovic/shipmonk-sorted-linked-list
```

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

[](#quick-start)

```
use AdamBenovic\SortedLinkedList\SortedLinkedList;

// Just insert values -- the type is detected automatically
$list = new SortedLinkedList();
$list->insert(42);
$list->insert(7);
$list->insert(15);

$list->toArray(); // [7, 15, 42]
$list->first();   // 7
$list->last();    // 42
```

Once the first value is inserted, the type is locked:

```
$list = new SortedLinkedList();
$list->insert(1);       // OK -- type locked to "integer"
$list->insert(2);       // OK
$list->insert('hello'); // throws TypeMismatchException
```

Creating Lists
--------------

[](#creating-lists)

```
use AdamBenovic\SortedLinkedList\SortedLinkedList;
use AdamBenovic\SortedLinkedList\ValueType;

// Auto-detect type from first insert
$list = new SortedLinkedList();

// Pre-declare the type (rejects wrong-type values even before first insert)
$ints = new SortedLinkedList(ValueType::Integer);
$strings = new SortedLinkedList(ValueType::String);

// Factory method -- creates a pre-populated sorted list
$list = SortedLinkedList::of(3, 1, 4, 1, 5);       // [1, 1, 3, 4, 5]
$list = SortedLinkedList::of('cherry', 'apple');     // ['apple', 'cherry']
```

### Typed Convenience Classes

[](#typed-convenience-classes)

For stricter static analysis, use the type-specific classes directly:

```
use AdamBenovic\SortedLinkedList\IntSortedLinkedList;
use AdamBenovic\SortedLinkedList\StringSortedLinkedList;

$ints = new IntSortedLinkedList();       // first() returns int
$strings = new StringSortedLinkedList(); // first() returns string
```

API
---

[](#api)

MethodDescriptionComplexity`insert($value): void`Add a value, maintaining sorted orderO(n)`remove($value): bool`Remove the first occurrenceO(n)`contains($value): bool`Check if a value existsO(n)`first(): int|string`Get the smallest (first) elementO(1)`last(): int|string`Get the largest (last) elementO(1)`toArray(): array`Get all values as a sorted arrayO(n)`isEmpty(): bool`Check if the list is emptyO(1)`clear(): void`Remove all elementsO(1)`count(): int`Get the number of elementsO(1)`filter(callable): static`Create a new filtered listO(n)`merge(self): static`Merge two lists into a new oneO(n+m)`getValueType(): ?ValueType`Get the detected/declared value typeO(1)### Counting and Iteration

[](#counting-and-iteration)

All list classes implement `Countable`, `IteratorAggregate`, `JsonSerializable`, and `Stringable`:

```
$list = SortedLinkedList::of(3, 1, 2);

count($list);             // 3
$list->size;              // 3 (read-only from outside)

foreach ($list as $value) {
    echo $value;          // 1, 2, 3
}

json_encode($list);       // [1,2,3]
echo $list;               // SortedLinkedList[1, 2, 3]
```

### Filtering

[](#filtering)

```
$list = SortedLinkedList::of(1, 2, 3, 4, 5);

$even = $list->filter(fn(int|string $v) => $v % 2 === 0);
$even->toArray(); // [2, 4]
```

### Merging

[](#merging)

Merges two sorted lists of the same type in O(n+m) time:

```
$a = SortedLinkedList::of('apple', 'cherry');
$b = SortedLinkedList::of('banana', 'date');

$merged = $a->merge($b);
$merged->toArray(); // ['apple', 'banana', 'cherry', 'date']
```

### Duplicates

[](#duplicates)

Duplicate values are allowed. `remove()` removes only the first occurrence:

```
$list = SortedLinkedList::of(5, 5, 5);

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

### String Sorting

[](#string-sorting)

`StringSortedLinkedList` and `SortedLinkedList` (when holding strings) use byte-level comparison (`strcmp`), which follows UTF-8 byte order rather than locale-aware collation. This means:

- Uppercase letters sort before lowercase (e.g., `"Banana"` before `"apple"`)
- Multi-byte characters (e.g., `"ä"`, `"ñ"`) sort after all ASCII characters

If you need locale-sensitive ordering, consider using PHP's `intl` extension (`Collator` class).

Exceptions
----------

[](#exceptions)

ExceptionParentWhen`TypeMismatchException``\InvalidArgumentException`Inserting a value of the wrong type`EmptyListException``\UnderflowException`Calling `first()` or `last()` on an empty list`\InvalidArgumentException`--Merging two lists of different typesArchitecture
------------

[](#architecture)

The library uses the **Template Method** pattern:

- `SortedLinkedListInterface` -- defines the public contract with `@template` generics
- `AbstractSortedLinkedList` -- implements the sorted insertion algorithm, delegates type validation and comparison to subclasses
- `SortedLinkedList` -- the primary entry point with auto-detection of value type
- `IntSortedLinkedList` / `StringSortedLinkedList` -- convenience classes with narrowed return types for `first()` and `last()`

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

[](#development)

```
# Install dependencies
composer install

# Run tests
vendor/bin/phpunit

# Run static analysis
vendor/bin/phpstan analyse

# Fix code style (PSR-12)
vendor/bin/php-cs-fixer fix
```

License
-------

[](#license)

MIT

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance82

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

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

92d ago

### Community

Maintainers

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

---

Tags

collectionlinked listsortedtypeddata structure

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/adambenovic-shipmonk-sorted-linked-list/health.svg)

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

###  Alternatives

[phpcollection/phpcollection

General-Purpose Collection Library for PHP

1.0k64.0M34](/packages/phpcollection-phpcollection)[league/period

Time range API for PHP

7335.4M21](/packages/league-period)[loophp/collection

A (memory) friendly, easy, lazy and modular collection class.

745663.8k13](/packages/loophp-collection)[chdemko/sorted-collections

Sorted Collections for PHP >= 8.2

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

Load files and classes as lazy collections in Laravel.

956.6M9](/packages/lorisleiva-lody)[gamez/typed-collection

Type-safe collections based on Laravel Collections

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

PHPackages © 2026

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