astral / php-serialize
An advanced PHP serialization tool leveraging attributes for flexible object-to-array and JSON conversion. Supports property aliases, type conversions, and nested object handling. Ideal for APIs, data persistence, and configuration management.
Requires
- php: ^8.1
- illuminate/support: ^6.0||^7.0||^8.0||^9.0||^10.0||^11.0||^12.0
- phpdocumentor/reflection: ^6.0
- phpdocumentor/reflection-docblock: ^5.5
- psr/simple-cache: ^3.0
Requires (Dev)
- fakerphp/faker: ^1.23
- friendsofphp/php-cs-fixer: ^3.0
- mockery/mockery: ^1.6
- pestphp/pest: ^2.30
- phpbench/phpbench: ^1.2
- phpstan/phpstan: ^2.0.2
This package is auto-updated.
Last update: 2025-06-27 09:27:09 UTC
README
Languages
php-serialize
php-serialize is a powerful attribute-based serialization library for PHP (requires PHP ≥ 8.1).
It allows you to map objects to arrays/JSON and automatically generate OpenAPI documentation based on the same attributes.
🚀 Unified solution for API data serialization and documentation generation.
✨ Features
- 🏷️ Property aliasing with
- 🔄 Automatic type casting (e.g.
DateTime ↔ string
) - 🔁 Deep object nesting support
- ❌ Skip/exclude fields with
- 🧩 Recursive DTO serialization
- 🧬 Auto-generate OpenAPI schema using object definitions
- ⚙️ Framework-agnostic — works with Laravel, Symfony, etc.
Quick Start
Installation
Install using Composer:
composer require astral/php-serialize
Basic Usage
use Astral\Serialize\Serialize; class User extends Serialize { public string $name, public int $age } // Create object from array $user = User::from([ 'name' => 'John Doe', 'age' => 30 ]); // Access object properties echo $user->name; // Output: John Doe echo $user->age; // Output: 30 // Convert to array $userArray = $user->toArray(); // $userArray contents: // [ // 'name' => 'John Doe', // 'age' => 30 // ]
Other Features
- Immutability: Read-only properties cannot be modified after construction
use Astral\Serialize\Serialize; class User extends Serialize { public function __construct( public readonly string $name, public readonly int $age ) {} } $user = User::from([ 'name' => 'John Doe', 'age' => 30 ]); try { $user->name = 'Jane Doe'; // Compile-time error: cannot modify read-only property } catch (Error $e) { echo "Read-only properties cannot be reassigned"; }
- Type-Safe Initialization
$user = User::from([ 'name' => 123, // Integer will be converted to string 'age' => '35' // String will be converted to integer ]); echo $user->name; // Output: "123" echo $user->age; // Output: 35
- Constructor Initialization
use Astral\Serialize\Serialize; class User extends Serialize { public function __construct( public readonly string $name, public readonly int $age ) { // Can add additional validation or processing logic in the constructor if (strlen($name) < 2) { throw new \InvalidArgumentException('Name is too short'); } } }
Auto Create OpenApi Doc
Creating Request
use Astral\Serialize\Serialize; class UserAddRequest extends Serialize { public string $name; public int $id; } class UserDetailRequest extends Serialize { public int $id; }
Creating Response
use Astral\Serialize\Serialize; class UserDto extends Serialize { public string $name, public int $id; }
Creating Controller
use Astral\Serialize\Serialize; use Astral\Serialize\OpenApi\Enum\MethodEnum; #[\Astral\Serialize\OpenApi\Annotations\Tag('User Module Management')] class UserController { #[\Astral\Serialize\OpenApi\Annotations\Summary('Create User')] #[\Astral\Serialize\OpenApi\Annotations\Route('/user/create')] #[\Astral\Serialize\OpenApi\Annotations\RequestBody(UserAddRequest::class)] #[\Astral\Serialize\OpenApi\Annotations\Response(UserDto::class)] public function create() { return new UserDto(); } #[\Astral\Serialize\OpenApi\Annotations\Summary('User Detail')] #[\Astral\Serialize\OpenApi\Annotations\Route(route:'/user/detail', method: MethodEnum::GET)] public function detail(UserDetailRequest $request): UserDto { return new UserDto(); } }
Starting the Service
Docker Deployment
Navigate to the project root directory first:
docker run -v $PWD/vendor/astral/php-serialize/src/OpenApi/Frankenphp/Caddyfile:/etc/frankenphp/Caddyfile -v $PWD:/app -p 8089:80 dunglas/frankenphp
Access http://127.0.0.1:8089/docs
to view the documentation.