PHPackages                             fasano/lib-primitives - 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. fasano/lib-primitives

ActiveLibrary

fasano/lib-primitives
=====================

v1.0.0(9mo ago)013MITPHPPHP >=8.4

Since Aug 21Pushed 8mo agoCompare

[ Source](https://github.com/n-fasano/lib-primitives)[ Packagist](https://packagist.org/packages/fasano/lib-primitives)[ RSS](/packages/fasano-lib-primitives/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

PrimitivesLib
=============

[](#primitiveslib)

A PHP library that defines an implicit interface for domain primitives and provides utilities to detect them, along with metadata and reflection features.

What are Domain Primitives?
---------------------------

[](#what-are-domain-primitives)

Domain primitives are simple value objects that wrap primitive scalar types (string, int, float, etc.) with domain-specific validation and meaning. They help prevent primitive obsession and make your code more expressive and type-safe.

For example, instead of passing around raw strings for email addresses:

```
function sendEmail(string $email) // Requires checks
```

You can use domain primitives:

```
function sendEmail(Email $email)  // Trusted input
```

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

[](#installation)

```
composer require fasano/lib-primitives
```

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

[](#requirements)

- Tested with PHP 8.4 only.

Domain Primitive Interface
--------------------------

[](#domain-primitive-interface)

This library works with classes that follow a specific implicit interface:

1. **Single public property** named `value` of a builtin PHP type
2. **Constructor** that accepts the value as the first parameter named `value`
3. **Validation** logic in the constructor (optional but recommended)

### Example Domain Primitive

[](#example-domain-primitive)

```
readonly class Email
{
    public function __construct(public string $value)
    {
        if (false === filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidArgumentException(sprintf('%s is not a valid email', $value));
        }
    }
}
```

### With Metadata Attributes

[](#with-metadata-attributes)

You can enhance your primitives with metadata using the provided attributes:

```
use Fasano\PrimitivesLib\Metadata\Attribute\Name;
use Fasano\PrimitivesLib\Metadata\Attribute\Example;
use Fasano\PrimitivesLib\Metadata\Attribute\Description;

#[Name('Email Address')]
#[Example('user@example.com')]
#[Description('A valid email address for user communication')]
readonly class Email
{
    public function __construct(public string $value)
    {
        if (false === filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidArgumentException(sprintf('%s is not a valid email', $value));
        }
    }
}
```

### Using StringPrimitive Base Class

[](#using-stringprimitive-base-class)

For string-based primitives, a base class is provided that can be used for inspiration:

```
use Fasano\PrimitivesLib\StringPrimitive;

readonly class ProductCode extends StringPrimitive
{
    public static function check(string $value): bool
    {
        return preg_match('/^[A-Z]{2}-\d{4}$/', $value) === 1;
    }
}

// Usage
$code = new ProductCode('AB-1234'); // Valid
$code = new ProductCode('invalid'); // Throws InvalidArgumentException
```

Examples
--------

[](#examples)

```
use Fasano\PrimitivesLib\Primitives;

$isPrimitive = Primitives::isPrimitive(Email::class);    // true
$isPrimitive = Primitives::isPrimitive(stdClass::class); // false
```

```
$metadata = Primitives::getMetadata(Email::class);

echo $metadata->name;        // "Email Address"
echo $metadata->example;     // "user@example.com"
echo $metadata->description; // "A valid email address for user communication"
echo $metadata->type;        // "string"
echo $metadata->fqcn;        // "MyApp\Domain\User\Property\Email"
```

```
$email = new Email('user@example.com');
$value = Primitives::valueOf($email); // "user@example.com"
```

```
$email = Primitives::create(Email::class, 'user@example.com');
// Equivalent to: new Email('user@example.com')
```

```
$email1 = new Email('user@example.com');
$email2 = new Email('user@example.com');
$email3 = new Email('other@example.com');

Primitives::equals($email1, $email2); // true
Primitives::equals($email1, $email3); // false
```

Error Handling
--------------

[](#error-handling)

The library throws `InvalidArgumentException` when trying to use a non-primitive class with any of the utility methods.

License
-------

[](#license)

This project is licensed under the MIT License.

###  Health Score

33

—

LowBetter than 75% of packages

Maintenance59

Moderate activity, may be stable

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity53

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

271d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/16bb6f7b889777bcd3237bbddd90a3707306fc1803da0bd10c3710086b8702a4?d=identicon)[nfasano](/maintainers/nfasano)

---

Top Contributors

[![n-fasano](https://avatars.githubusercontent.com/u/46872160?v=4)](https://github.com/n-fasano "n-fasano (10 commits)")

---

Tags

dddRich Domain

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/fasano-lib-primitives/health.svg)

```
[![Health](https://phpackages.com/badges/fasano-lib-primitives/health.svg)](https://phpackages.com/packages/fasano-lib-primitives)
```

###  Alternatives

[broadway/broadway

Infrastructure and testing helpers for creating CQRS and event sourced applications.

1.5k2.0M53](/packages/broadway-broadway)[prooph/event-store

Event Store v8

5471.5M40](/packages/prooph-event-store)[prooph/service-bus

PHP Enterprise Service Bus Implementation supporting CQRS and DDD

4421.4M32](/packages/prooph-service-bus)[ecotone/ecotone

Supporting you in building DDD, CQRS, Event Sourcing applications with ease.

558549.8k17](/packages/ecotone-ecotone)[prooph/event-sourcing

PHP EventSourcing library

267808.5k18](/packages/prooph-event-sourcing)[jpkleemans/attribute-events

🔥 Fire events on attribute changes of your Eloquent model

332484.7k1](/packages/jpkleemans-attribute-events)

PHPackages © 2026

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