bylec/sortedlinkedlist

A type-safe sorted linked list for int or string values.

1.0.0 2026-03-21 10:12 UTC

Requires

• php: >=8.3

Requires (Dev)

• phpstan/phpstan: ^1.12
• phpunit/phpunit: ^11.0
• squizlabs/php_codesniffer: ^3.10

MIT

• data-structure
• sorted
• linked-list

README

A type-safe sorted linked list for PHP 8.3+.
Holds int or string values — but not both at the same time — and keeps them sorted on every insert.

Installation

composer require bylec/sortedlinkedlist

Quick start

use SortedLinkedList\Enum\SortOrder;
use SortedLinkedList\SortedLinkedList;

$list = new SortedLinkedList();
$list->insert(5);
$list->insert(2);
$list->insert(8);
$list->insert(1);
print_r($list->toArray()); // [1, 2, 5, 8]

$desc = new SortedLinkedList(SortOrder::DESCENDING);
$desc->insert(5);
$desc->insert(2);
$desc->insert(8);
$desc->insert(1);
print_r($desc->toArray()); // [8, 5, 2, 1]

$list = SortedLinkedList::fromArray([3, 1, 4, 1, 5], SortOrder::ASCENDING);
print_r($list->toArray()); // [1, 1, 3, 4, 5]

Constructor

new SortedLinkedList(SortOrder $order = SortOrder::ASCENDING)

Mutation

Method	Description
insert(int|string $value): void	Insert a value in sorted order
remove(int|string $value): void	Remove first occurrence; throws ValueNotFoundException if missing
clear(): void	Remove all values and reset the type lock

Query

Method	Description
contains(int|string $value): bool	Check whether a value exists
first(): int|string	First value in list order; throws EmptyListException
last(): int|string	Last value in list order; throws EmptyListException
toArray(): array	All values as a plain PHP array
count(): int	Number of elements — also works with count($list)
isEmpty(): bool	True when the list has no elements

Static factory

SortedLinkedList::fromArray(array $values, SortOrder $order = SortOrder::ASCENDING): self

Interfaces implemented

• Countable — use count($list)
• IteratorAggregate — use foreach ($list as $value)

Exceptions

All exceptions extend SortedLinkedListException extends \RuntimeException.

Exception	Thrown when
TypeMismatchException	A value of the wrong type is inserted or queried
ValueNotFoundException	remove() is called with a value not in the list
EmptyListException	first() or last() is called on an empty list

use SortedLinkedList\Exception\TypeMismatchException;

try {
    $list->insert('oops'); // list holds ints
} catch (TypeMismatchException $e) {
    echo $e->getMessage();
    // Type mismatch: list holds 'int' values, but 'string' was given.
}

Development

composer install

composer test     # run PHPUnit
composer stan     # run PHPStan (level max)
composer cs       # run PHP_CodeSniffer (PSR-12)
composer cs-fix   # auto-fix code style
composer check    # run all three

Project structure

src/
├── Enum/
│   └── SortOrder.php
├── Exception/
│   ├── SortedLinkedListException.php
│   ├── TypeMismatchException.php
│   ├── EmptyListException.php
│   └── ValueNotFoundException.php
├── Node.php
└── SortedLinkedList.php
tests/
└── SortedLinkedListTest.php