haspadar/primus

Primitive wrappers for PHP: strong typing for strings, ints, arrays, and more

v0.5.0 2025-11-19 18:55 UTC

Requires

• php: 8.2.*

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3
• haspadar/psalm-eo-rules: dev-main
• infection/infection: ^0.29.14
• nunomaduro/collision: ^8.0
• phpmetrics/phpmetrics: ^3.0
• phpstan/phpstan: ^2.0
• phpunit/phpunit: ^10.5
• rector/rector: ^2.0
• vimeo/psalm: ^6.13

MIT

README

Object‑Oriented PHP Primitives

Primus is a library of object‑oriented PHP primitives.
It provides common operations as small composable objects instead of functions.

Inspired by Elegant Objects and cactoos.

📦 Core Idea

Procedural PHP:

strtolower(trim(substr($s, 0, 5)));

Primus:

(new Sub(
    new Lowered(
        new Trimmed($s)
    ),
    5
))->value();

Each object represents exactly one operation.
Objects are immutable, final, and easy to combine.

🧭 Quick Reference

Procedural	Primus
trim($s)	new Trimmed($s)
strtolower($s)	new Lowered($s)
substr($s, 0, 5)	new Sub($s, 5)
strip_tags($s)	new WithoutTags($s)
strlen($s)	new LengthOfText($s)
array_map(fn, $a)	new Mapped($a, new FuncOf(fn))
array_filter($a, fn)	new Filtered($a, new PredicateOf(fn))

🧱 Modules

Text

Trimmed, Lowered, Uppered, Sub, WithoutTags, Abbreviated, LengthOfText, TextOf

Logic

Yes, No, IsEmpty, IsEmail, IsUuid, IsUrl, ThrowsIf, LogicEnvelope

Scalar

ScalarOf, ScalarEnvelope, EqualTo, GreaterThan, LessThan, Ternary, Sticky

Func

Func, FuncOf, FuncEnvelope, BiFunc, Proc, Predicate, StickyFunc, Repeated

Iterator

IteratorOf, Mapped, Filtered, Joined, NoNulls

Iterable

IterableOf, Mapped, Filtered, Joined, NoNulls

Numeric (WIP)

Positive, NonZero, Rounded

🧠 Design Principles

• No null

• No static

• No procedural helpers

• No mutable state

• Immutable objects

• Final classes

• One class = one behavior

• Composition over inheritance

🧪 Testing & Static Analysis

Primus includes:

• Custom PHPUnit constraints (HasIteratorValues, EqualsValue, …)
• Mutation testing (Infection)
• Static analysis:
  • PHPStan level 9
  • Psalm + haspadar/psalm-eo-rules

The Psalm rules enforce:

• No static
• No null
• No isset() / empty()
• All state must be readonly
• No traits or unnecessary inheritance

📥 Installation

composer require haspadar/primus

Requires PHP ≥ 8.2

📄 License

MIT