docs: update documentation and add comprehensive examples

- Add comprehensive_example.php demonstrating all library features
- Update README.md with new features and development tools
- Update CHANGELOG.md to version 2.0.0 with breaking changes
- Document algebraic data types, Laravel integration, and benchmarks
- Add migration guide for breaking changes
- Include examples for all major features and use cases

Author: nejc

CHANGELOG.md

@@ -1,7 +1,77 @@
 # Changelog
 
-All notable changes to `php-datatypes` will be documented in this file
+All notable changes to `php-datatypes` will be documented in this file.
 
-## 1.0.0 - 201X-XX-XX
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-- initial release
+## [2.0.0] - 2024-12-19
+
+### Added
+- PHP 8.4 compatibility and CI testing
+- PHPStan static analysis configuration (level 9)
+- `Dictionary::toArray()`, `isEmpty()`, and `getAll()` methods
+- Benchmark suite for performance testing
+- `Option<T>` type for nullable values
+- `Result<T, E>` type for error handling
+- Mutation testing with Infection
+- Laravel integration (validation rules, service provider)
+- PHPStorm metadata for better IDE support
+- Comprehensive example demonstrating all features
+
+### Changed
+- **BREAKING:** All concrete datatype classes are now `final` to prevent inheritance issues
+- **BREAKING:** All methods now have explicit return types for better type safety
+- **BREAKING:** All Laravel validation rules and casts are now `final`
+- Updated minimum PHP version requirement to ^8.4
+- Enhanced CI workflow to test PHP 8.4
+- Improved code quality with static analysis
+- Enhanced parameter type declarations throughout the codebase
+
+### Fixed
+- Missing serialization methods in Dictionary class
+- Missing return types in various methods
+- Parameter type declarations for better type safety
+
+### Migration Guide
+
+If you were extending any datatype classes, you'll need to use composition instead:
+
+**Before (v1.x):**
+```php
+class MyCustomInt8 extends Int8 {
+    // custom implementation
+}
+```
+
+**After (v2.0):**
+```php
+class MyCustomInt8 {
+    private Int8 $int8;
+    
+    public function __construct(int $value) {
+        $this->int8 = new Int8($value);
+    }
+    
+    public function getValue(): int {
+        return $this->int8->getValue();
+    }
+    
+    // delegate other methods as needed
+}
+```
+
+## [1.0.0] - 2024-12-19
+
+### Added
+- Initial release with comprehensive type system
+- Scalar types: Int8, Int16, Int32, Int64, Int128, UInt8, UInt16, UInt32, UInt64, UInt128
+- Floating point types: Float32, Float64
+- Boolean, Char, and Byte types
+- Composite types: Arrays, Structs, Unions, Lists, Dictionaries
+- String types: AsciiString, Utf8String, EmailString, and 20+ specialized string types
+- Vector types: Vec2, Vec3, Vec4
+- Serialization support: JSON, XML, Binary
+- Comprehensive test suite (592 tests, 1042 assertions)
+- Helper functions for all types
+- Type-safe operations with overflow/underflow protection

README.md

@@ -42,9 +42,13 @@ PHP Datatypes is designed to address the challenges of modern PHP development, w
 ## Features
 - **Strict Scalar Types:** Signed/unsigned integers (Int8, UInt8, etc.), floating points (Float32, Float64), booleans, chars, and bytes
 - **Composite Types:** Structs, arrays, unions, lists, dictionaries, and more
+- **Algebraic Data Types:** Option<T> for nullable values, Result<T, E> for error handling
 - **Type-safe Operations:** Arithmetic, validation, and conversion with built-in safeguards
-- **Serialization:** Easy conversion to/from array, JSON, and XML
-- **Laravel Integration:** Ready for use in modern PHP frameworks
+- **Serialization:** Easy conversion to/from array, JSON, XML, and binary formats
+- **Laravel Integration:** Validation rules, Eloquent casts, form requests, and service provider
+- **Performance Benchmarks:** Built-in benchmarking suite to compare with native PHP types
+- **Static Analysis:** PHPStan level 9 configuration for maximum code quality
+- **Mutation Testing:** Infection configuration for comprehensive test coverage
 - **Extensible:** Easily define your own types and validation rules
 
 ## Installation
@@ -134,6 +138,60 @@ $result = $int1->add($int2); // Performs addition
 echo $result->getValue(); // 80
 ```
 
+### Algebraic Data Types
+#### Option Type for Nullable Values
+```php
+use Nejcc\PhpDatatypes\Composite\Option;
+
+$someValue = Option::some("Hello");
+$noneValue = Option::none();
+
+$processed = $someValue
+    ->map(fn($value) => strtoupper($value))
+    ->unwrapOr("DEFAULT");
+
+echo $processed; // "HELLO"
+```
+
+#### Result Type for Error Handling
+```php
+use Nejcc\PhpDatatypes\Composite\Result;
+
+$result = Result::try(function () {
+    return new Int8(42);
+});
+
+if ($result->isOk()) {
+    echo $result->unwrap()->getValue(); // 42
+} else {
+    echo "Error: " . $result->unwrapErr();
+}
+```
+
+### Laravel Integration
+#### Validation Rules
+```php
+// In your form request
+public function rules(): array
+{
+    return [
+        'age' => ['required', 'int8'],
+        'user_id' => ['required', 'uint8'],
+        'balance' => ['required', 'float32'],
+    ];
+}
+```
+
+#### Eloquent Casts
+```php
+// In your model
+protected $casts = [
+    'age' => Int8Cast::class,
+    'user_id' => 'uint8',
+    'balance' => 'float32',
+];
+```
+
 ## Roadmap
 
 ```md
@@ -193,13 +251,38 @@ Data Types
     └── Channel
 ```
 
-## Testing
+## Development Tools
 
+### Testing
 Run the test suite with:
 ```bash
 composer test
 ```
 
+### Static Analysis
+Run PHPStan for static analysis:
+```bash
+composer phpstan
+```
+
+### Mutation Testing
+Run Infection for mutation testing:
+```bash
+composer infection
+```
+
+### Performance Benchmarks
+Run performance benchmarks:
+```bash
+composer benchmark
+```
+
+### Code Style
+Run Laravel Pint for code formatting:
+```bash
+vendor/bin/pint
+```
+
 ## Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for details on recent changes.

examples/comprehensive_example.php

@@ -0,0 +1,173 @@
+<?php
+
+declare(strict_types=1);
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+use Nejcc\PhpDatatypes\Scalar\Integers\Signed\Int8;
+use Nejcc\PhpDatatypes\Scalar\Integers\Signed\Int32;
+use Nejcc\PhpDatatypes\Scalar\Integers\Unsigned\UInt8;
+use Nejcc\PhpDatatypes\Scalar\FloatingPoints\Float32;
+use Nejcc\PhpDatatypes\Composite\Option;
+use Nejcc\PhpDatatypes\Composite\Result;
+use Nejcc\PhpDatatypes\Composite\Dictionary;
+use Nejcc\PhpDatatypes\Composite\Struct\Struct;
+use Nejcc\PhpDatatypes\Composite\Union\UnionType;
+
+echo "=== PHP Datatypes Comprehensive Example ===\n\n";
+
+// 1. Scalar Types
+echo "1. Scalar Types:\n";
+echo "---------------\n";
+
+$int8 = new Int8(42);
+$int32 = new Int32(1000);
+$uint8 = new UInt8(200);
+$float32 = new Float32(3.14159);
+
+echo "Int8: " . $int8->getValue() . "\n";
+echo "Int32: " . $int32->getValue() . "\n";
+echo "UInt8: " . $uint8->getValue() . "\n";
+echo "Float32: " . $float32->getValue() . "\n\n";
+
+// 2. Arithmetic Operations
+echo "2. Arithmetic Operations:\n";
+echo "------------------------\n";
+
+$result = $int8->add(new Int8(10));
+echo "Int8(42) + Int8(10) = " . $result->getValue() . "\n";
+
+$result = $int32->multiply(new Int32(2));
+echo "Int32(1000) * Int32(2) = " . $result->getValue() . "\n\n";
+
+// 3. Option Type
+echo "3. Option Type:\n";
+echo "--------------\n";
+
+$someValue = Option::some("Hello World");
+$noneValue = Option::none();
+
+echo "Some value: " . $someValue . "\n";
+echo "None value: " . $noneValue . "\n";
+
+$processed = $someValue
+    ->map(fn($value) => strtoupper($value))
+    ->unwrapOr("DEFAULT");
+
+echo "Processed: " . $processed . "\n\n";
+
+// 4. Result Type
+echo "4. Result Type:\n";
+echo "--------------\n";
+
+$successResult = Result::ok("Operation successful");
+$errorResult = Result::err("Something went wrong");
+
+echo "Success: " . $successResult . "\n";
+echo "Error: " . $errorResult . "\n";
+
+$safeResult = Result::try(function () {
+    return new Int8(50);
+});
+
+if ($safeResult->isOk()) {
+    echo "Safe operation result: " . $safeResult->unwrap()->getValue() . "\n";
+} else {
+    echo "Safe operation failed: " . $safeResult->unwrapErr() . "\n";
+}
+
+echo "\n";
+
+// 5. Dictionary
+echo "5. Dictionary:\n";
+echo "-------------\n";
+
+$dict = new Dictionary([
+    'name' => 'John Doe',
+    'age' => 30,
+    'email' => 'john@example.com'
+]);
+
+echo "Dictionary size: " . $dict->size() . "\n";
+echo "Name: " . $dict->get('name') . "\n";
+echo "Keys: " . implode(', ', $dict->getKeys()) . "\n\n";
+
+// 6. Struct
+echo "6. Struct:\n";
+echo "----------\n";
+
+$userStruct = new Struct([
+    'id' => ['type' => 'int', 'nullable' => false],
+    'name' => ['type' => 'string', 'nullable' => false],
+    'email' => ['type' => 'string', 'nullable' => true],
+], [
+    'id' => 1,
+    'name' => 'Jane Doe',
+    'email' => 'jane@example.com'
+]);
+
+echo "User ID: " . $userStruct->get('id') . "\n";
+echo "User Name: " . $userStruct->get('name') . "\n";
+echo "User Email: " . $userStruct->get('email') . "\n\n";
+
+// 7. Union Type
+echo "7. Union Type:\n";
+echo "-------------\n";
+
+$union = new UnionType([
+    'string' => 'string',
+    'int' => 'int',
+    'float' => 'float'
+]);
+
+$union->setValue('string', 'Hello Union');
+echo "Union active type: " . $union->getActiveType() . "\n";
+echo "Union value: " . $union->getValue() . "\n";
+
+$union->setValue('int', 42);
+echo "Union active type: " . $union->getActiveType() . "\n";
+echo "Union value: " . $union->getValue() . "\n\n";
+
+// 8. Helper Functions
+echo "8. Helper Functions:\n";
+echo "-------------------\n";
+
+$int8Helper = int8(75);
+$uint8Helper = uint8(150);
+$float32Helper = float32(2.71828);
+$someHelper = some("Helper function");
+$okHelper = ok("Success");
+
+echo "Int8 helper: " . $int8Helper->getValue() . "\n";
+echo "UInt8 helper: " . $uint8Helper->getValue() . "\n";
+echo "Float32 helper: " . $float32Helper->getValue() . "\n";
+echo "Some helper: " . $someHelper . "\n";
+echo "Ok helper: " . $okHelper . "\n\n";
+
+// 9. Serialization
+echo "9. Serialization:\n";
+echo "----------------\n";
+
+$json = $userStruct->toJson();
+echo "Struct JSON: " . $json . "\n";
+
+$xml = $userStruct->toXml();
+echo "Struct XML: " . substr($xml, 0, 100) . "...\n\n";
+
+// 10. Error Handling
+echo "10. Error Handling:\n";
+echo "------------------\n";
+
+try {
+    $invalidInt8 = new Int8(1000); // This will throw OutOfRangeException
+} catch (\OutOfRangeException $e) {
+    echo "Caught OutOfRangeException: " . $e->getMessage() . "\n";
+}
+
+try {
+    $overflow = $int8->add(new Int8(100)); // This will throw OverflowException
+} catch (\OverflowException $e) {
+    echo "Caught OverflowException: " . $e->getMessage() . "\n";
+}
+
+echo "\n=== Example Complete ===\n";