georgii-web/php-typed-values

Typed value objects library for common php data types.

v3.12.8 2026-04-06 18:00 UTC

Requires

• php: >=8.4

Requires (Dev)

• friendsofphp/php-cs-fixer: ^v3.94
• pestphp/pest: ^v3.8
• pestphp/pest-plugin-type-coverage: ^v3.6
• phpunit/phpunit: ^11.5
• rector/rector: ^2.3
• vimeo/psalm: ^6.16

Suggests

• ext-bcmath: Optionally required for Decimal type.

MIT

• GeorgII

README

PHP Typed Values

Typed value objects for PHP. Build precise, immutable, and validated data for DTOs, Value Objects, and Entities.

Install

• Use V3 for PHP 8.4:

composer require georgii-web/php-typed-values:^3

• Use V2 for PHP >=8.2 & <8.4:

composer require georgii-web/php-typed-values:^2

• Use V1 for PHP 7.4:

composer require georgii-web/php-typed-values:^1

Why

• Strong typing for scalars with runtime validation
• Immutable and self‑documenting values
• Safer constructors for your DTOs/VOs/Entities
• Great fit for static analysis
• Safe type conversion, no silent errors

Quick start

Use existing typed values

use PhpTypedValues\Integer\IntegerPositive;

$id = IntegerPositive::fromString('123');

Instead of spreading validation across an application

$id = (int) '123';
if ($id <= 0) {
    throw new InvalidArgumentException('Invalid ID');
}

Create an alias (in your domain)

use PhpTypedValues\Integer\IntegerPositive;

readonly class Id extends IntegerPositive {}

Id::fromInt(123);

Create composite objects

final readonly class Profile
{
    public function __construct(
        private IntegerPositive $id,
        private StringUsername $username,
        private FloatPositive|Undefined $rating,
    ) {}
}

Undefined

Prefer using the Undefined type over null to maintain consistency and improve type safety within the codebase.

Other usage examples docs/USAGE.md

Key features

• Idempotent conversion on fromString() > toString(): "1" > 1 > "1"
• Static analysis friendly
• Strict types
• Validation on construction; no invalid state
• Immutable, readonly objects
• No external runtime dependencies
• Easy to extend with your own types and composites
• Heavily tested

Performance note

• Objects vs Scalars:
  • ~2.3× slower for large arrays of objects
  • ~1.5× higher memory usage
• Use value objects for domain boundaries, validation, and clarity
• Use raw scalars in hot loops or large data processing paths

Documentation

• Development guide: docs/DEVELOP.md
• More usage examples in tests/Unit

Types structure

Types
├── ArrayType
│   ├── ArrayEmpty
│   ├── ArrayNonEmpty
│   ├── ArrayOfObjects
│   └── ArrayUndefined
├── Bool
│   ├── Alias
│   │   └── BooleanType
│   ├── BoolStandard
│   ├── FalseStandard
│   └── TrueStandard
├── DateTime
│   ├── DateTimeAtom
│   ├── DateTimeRFC3339
│   ├── DateTimeRFC3339Extended
│   ├── DateTimeW3C
│   ├── MariaDb
│   │   └── DateTimeSql
│   └── Timestamp
│       ├── TimestampMicroseconds
│       ├── TimestampMilliseconds
│       └── TimestampSeconds
├── Decimal
│   ├── Alias
│   │   └── Decimal
│   ├── DecimalNegative
│   ├── DecimalNonNegative
│   ├── DecimalPositive
│   ├── DecimalStandard
│   └── Specific
│       └── DecimalMoney
├── Float
│   ├── Alias
│   │   ├── DoubleType
│   │   └── FloatType
│   ├── FloatNegative
│   ├── FloatNonNegative
│   ├── FloatPositive
│   └── FloatStandard
├── Integer
│   ├── Alias
│   │   └── IntegerType
│   ├── IntegerNegative
│   ├── IntegerNonNegative
│   ├── IntegerPositive
│   ├── IntegerStandard
│   ├── MariaDb
│   │   ├── IntegerBig
│   │   ├── IntegerBigUnsigned
│   │   ├── IntegerMedium
│   │   ├── IntegerMediumUnsigned
│   │   ├── IntegerNormal
│   │   ├── IntegerNormalUnsigned
│   │   ├── IntegerSmall
│   │   ├── IntegerSmallUnsigned
│   │   ├── IntegerTiny
│   │   └── IntegerTinyUnsigned
│   └── Specific
│       ├── IntegerAge
│       ├── IntegerDayOfMonth
│       ├── IntegerHour
│       ├── IntegerHttpStatusCode
│       ├── IntegerMinute
│       ├── IntegerMonth
│       ├── IntegerPercent
│       ├── IntegerPort
│       ├── IntegerSecond
│       ├── IntegerWeekDay
│       └── IntegerYear
├── String
│   ├── Alias
│   │   └── StringType
│   ├── MariaDb
│   │   ├── StringLongText
│   │   ├── StringMediumText
│   │   ├── StringText
│   │   ├── StringTinyText
│   │   └── StringVarChar255
│   ├── Specific
│   │   ├── StringCountryCode
│   │   ├── StringCurrencyCode
│   │   ├── StringDomain
│   │   ├── StringEmail
│   │   ├── StringFileName
│   │   ├── StringHex
│   │   ├── StringIban
│   │   ├── StringIpV4
│   │   ├── StringIpV6
│   │   ├── StringJson
│   │   ├── StringJwt
│   │   ├── StringLanguageCode
│   │   ├── StringLocaleCode
│   │   ├── StringMacAddress
│   │   ├── StringMd5
│   │   ├── StringMimeType
│   │   ├── StringPath
│   │   ├── StringPhoneE164
│   │   ├── StringSemVer
│   │   ├── StringSha256
│   │   ├── StringSha512
│   │   ├── StringSlug
│   │   ├── StringUrl
│   │   ├── StringUrlPath
│   │   ├── StringUsername
│   │   ├── StringUuidV4
│   │   └── StringUuidV7
│   ├── StringEmpty
│   ├── StringNonBlank
│   ├── StringNonEmpty
│   └── StringStandard
└── Undefined
    ├── Alias
    │   └── Undefined
    └── UndefinedStandard

License

MIT