haspadar/primus

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

v0.2.0 2025-11-08 19: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

📦 About

Primus is a library of immutable value objects that wrap primitive types like string, int, bool, and array.

Instead of passing around loose values, you use small, self-contained wrappers like:

• Lowered, Trimmed, Sub (strings)
• Yes, No, IsEmpty, IsEmail, IsUuid, LogicEnvelope (logic)
• Mapped, SequenceOf (collections)

Each class encapsulates one behavior and can be composed with others to form robust, intention-revealing objects.

🧠 Philosophy

• ❌ No null, static, or shared state in the public API
• ✅ One object = one responsibility
• ✅ Final classes, immutability by default
• ✅ Composition over inheritance
• ✅ Behavior and data live together

Inspired by Elegant Objects and cactoos.

✨ Example

$text = new Sub(
    new Lowered(
        new Trimmed("  Hello, world!  ")
    ),
    5
);

echo $text->value(); // "hello"

Each wrapper adds one behavior:

• Trimmed removes whitespace
• TruncatedRight shortens the string

All wrappers implement the same interface and can be freely composed.

🧱 Modules

• Text — Trimmed, Uppered, Lowered, Sub, WithoutTags, LengthOfText, Abbreviated, TextOf
• Logic — Yes, No, ThrowsIf, IsEmpty, IsEmail, IsUuid, LogicEnvelope
• Iterable — Sequence, SequenceOf, Mapped, Filtered
• Number — (coming soon) Positive, NonZero, Rounded, etc.

🧪 Quality & CI

Every push and pull request is checked via GitHub Actions:

• ✅ Static analysis with PHPStan (level 9) and Psalm (level 8)
• ✅ Type coverage report via Shepherd
• ✅ Code style check with PHP-CS-Fixer (only changed files)
• ✅ Unit tests with PHPUnit
• ✅ Code coverage via Codecov
• ✅ Mutation testing with Infection
• ✅ Composer validation, platform checks, security audit
• ✅ Automatic refactoring via Rector

🧩 Static Analysis Rules

Primus enforces Elegant Objects design principles using
haspadar/psalm-eo-rules — a custom Psalm plugin that forbids:

• static methods and properties
• null, isset(), and empty()
• non-readonly mutable state
• traits and inheritance misuse

These checks guarantee immutability and strict object boundaries across all modules.

📥 Installation

composer require haspadar/primus

Requires PHP 8.2

📄 License

MIT