README

A powerful, zero-dependency PHP library for building immutable, serializable objects with validation and mapping capabilities. Perfect for DTOs, Value Objects, API responses, and domain modeling.

🪶 Pebble - Lightweight Immutable Snapshots

Pebble is a lightweight alternative to Granite for defensive, immutable snapshots without validation overhead — ideal for caching, Eloquent snapshots, and fast comparisons. Nested arrays, userland objects, and dates are copied so later source mutations cannot change the snapshot.

$snapshot = Pebble::from($eloquentModel);

$snapshot->name;           // Magic __get
$snapshot['email'];        // ArrayAccess
$snapshot->equals($other); // O(1) fingerprint comparison

📖 Read Pebble Documentation

✨ Features

Immutable Objects — Read-only DTOs and Value Objects, thread-safe by design
Flexible from() Method — Create from arrays, JSON, named parameters, other Granite objects, or mix them
Comprehensive Validation — 30+ built-in rules including Carbon date validation (Age, Future, Past, BusinessDay...)
ObjectMapper — Convention-based property mapping between objects with custom transformations
Smart Serialization — Custom property names, naming conventions, hidden fields, Carbon date formats
Object Comparison — Deep equality with equals(), detailed diffs with differs()
Performance Optimized — Conservative fast path for simple DTOs, deep immutable WeakMap caching, direct property access

🚀 Quick Start

Installation

composer require diego-ninja/granite

Basic Usage

use Ninja\Granite\Granite;
use Ninja\Granite\Validation\Attributes\Required;
use Ninja\Granite\Validation\Attributes\Email;
use Ninja\Granite\Validation\Attributes\Min;
use Ninja\Granite\Serialization\Attributes\Hidden;

final readonly class User extends Granite
{
    public function __construct(
        #[Required]
        #[Min(2)]
        public string $name,

        #[Required]
        #[Email]
        public string $email,

        #[Hidden]
        public ?string $password = null,
    ) {}
}

// Create from array
$user = User::from(['name' => 'John Doe', 'email' => 'john@example.com', 'password' => 'secret']);

// Create from named parameters
$user = User::from(name: 'John Doe', email: 'john@example.com');

// Immutable updates
$updated = $user->with(['name' => 'Jane Doe']);

// Serialization (password hidden automatically)
$json = $user->json();   // {"name":"John Doe","email":"john@example.com"}
$array = $user->array();

📖 Documentation

Core Concepts

Enhanced from() Method — Multiple invocation patterns for flexible object creation
Validation — Comprehensive validation system with 30+ built-in rules including Carbon
Serialization — Control how objects are converted to/from arrays and JSON with Carbon support
Object Comparison — Deep equality checks and difference detection
ObjectMapper — Powerful object-to-object mapping with conventions
Pebble — Lightweight immutable snapshots with fingerprinting
Advanced Usage — Patterns for complex applications
API Reference — Complete API documentation

Guides

Migration Guide — Migrate from arrays, stdClass, Doctrine, Laravel
Troubleshooting — Common issues and solutions

📈 Performance & Benchmarks

Granite uses a multi-layer fast path system that detects simple DTOs at class-load time and bypasses the full hydration pipeline (reflection, metadata, type conversion) entirely. For objects that qualify, the overhead vs plain PHP constructors is minimal.

Benchmark Results

Measured on PHP 8.5.10 with OPcache CLI enabled, using the median of 7 repetitions with 100,000 operations each:

Scenario	µs/op	Improvement
Plain PHP constructor	0.147	control
`Granite::from(array)`	0.284	—
`Granite::from(JSON)`	1.019	6.11x faster
`Granite::from(object)`	1.000	5.59x faster
`Granite::from(Granite)`	0.898	7.50x faster
Array-property DTO hydration	0.201	11.69x faster
Validated DTO hydration	4.691	1.96x faster
Cached `array()`	0.040	22.58x faster
Cached nested `array()`	0.040	31.56x faster
General array serialization	1.175	1.39x faster
ObjectMapper to plain object	1.869	1.11x faster
ObjectMapper to Granite	1.550	1.14x faster

Improvements compare the same benchmark against the pre-optimization baseline. Full samples and methodology are recorded in the performance optimization plan.

How it works

Granite's performance comes from three layers of optimization:

Capability-specific fast paths (ClassProfile) — Hydration, serialization, and comparison are evaluated independently. Exact array properties can use constructor hydration while still using recursive general serialization.
WeakMap caching — array() and json() results are read before repeating graph analysis and are cached only for deeply immutable graphs. Runtime serialization configuration invalidates cached values.
Compiled metadata — Reflection objects, validation attributes, validators, class date providers, and property transformers are reused across operations.

Classes that need conversion or custom naming use the general pipeline, with cached metadata and early exits for scalar values.

Running the Benchmarks

php benchmarks/GraniteBench.php
composer bench:objects
composer bench:objects -- --json --iterations=100000 --repetitions=7

⚠️ Deprecation Notice

GraniteDTO was already deprecated before v2.0.0, and GraniteVO is deprecated as of v2.0.0, in favor of the unified Granite base class. Both still extend Granite for backward compatibility but will be removed in v3.0.0.

// ❌ Deprecated — use Granite instead
final readonly class User extends GraniteVO { }
// ✅
final readonly class User extends Granite { }

🔧 Requirements

PHP 8.3+ — Takes advantage of modern PHP features
No dependencies — Zero external dependencies for maximum compatibility

📦 Installation

composer require diego-ninja/granite

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

📄 License

This package is open-sourced software licensed under the MIT license.

🙏 Credits

This project is developed and maintained by 🥷 Diego Rin in his free time.

If you find this project useful, please consider:

⭐ Starring the repository
🐛 Reporting bugs and issues
💡 Suggesting new features
🔧 Contributing code improvements

Made with ❤️ for the PHP community

diego-ninja / granite

Package info

Security

Statistics