README

Composite Entity is a PHP 8.1+ lightweight class designed for efficient and intelligent data handling. It specializes in the serialization and deserialization of data, making it highly beneficial for database management.

Features

• Converts database rows to strictly typed objects and vice versa.
• Streamlines database interactions.

Overview:

• Requirements
• Installation
• Quick example
• Advanced usage

Requirements

• PHP 8.1 or higher.

Installation

Install using Composer::

$ composer require compositephp/entity

Supported column types:

Composite Entity supports a wide range of data types:

• Basic types: String, Integer, Float, Bool, Array.
• Complex types: Object (stdClass), DateTime/DateTimeImmutable, Enum.
• Advanced types: Entity, Entity Lists or Maps, Collections (e.g., Doctrine Collection), Custom classes implementing Composite\DB\Entity\CastableInterface.

Quick example

use Composite\Entity\AbstractEntity;

class User extends AbstractEntity
{
    public function __construct(
        public readonly int $id,
        public string $email,
        public ?string $name = null,
        public bool $is_test = false,
        public array $languages = [],
        public Status $status = Status::ACTIVE,
        public readonly \DateTimeImmutable $created_at = new \DateTimeImmutable(),
    ) {}
}

enum Status
{
    case ACTIVE;
    case BLOCKED;
}

Example of serialization:

$user = new User(
    id: 123,
    email: 'john@example.com',
    name: 'John',
    is_test: false,
    languages: ['en', 'fr'],
    status: Status::BLOCKED,
);

var_export($user->toArray());

//will output
array (
  'id' => 123,
  'email' => 'user@example.com',
  'name' => 'John',
  'is_test' => false,
  'languages' => '["en","fr"]',
  'status' => 'BLOCKED',
  'created_at' => '2022-01-01 11:22:33.000000',
)

You can also deserialize (hydrate) entity from array:

$user = User::fromArray([
  'id' => 123,
  'email' => 'user@example.com',
  'name' => 'John',
  'is_test' => false,
  'languages' => '["en","fr"]',
  'status' => 'BLOCKED',
  'created_at' => '2022-01-01 11:22:33.000000',
]);

And that's it. No need for special getters or setters, no additional "behaviours" or extra layers of code. Composite Entity handles everything automatically, ensuring seamless data casting.

Advanced usage

Custom Hydration

For tailored performance, implement your own hydrator:

1. Create a class implementing Composite\Entity\HydratorInterface.
2. Add Composite\Entity\Attributes\Hydrator attribute to your entity class.

Useful Attributes

• Composite\Entity\Attributes\SkipSerialization

  Exclude properties from hydration.

• Composite\Entity\Attributes\ListOf

  Define lists of entities within a property.

  Example:

  use Composite\Entity\AbstractEntity;
  use Composite\Entity\Attributes\ListOf;
  
  class User extends AbstractEntity
  {
      public readonly int $id;
      
      public function __construct(
          public string $name,
          #[ListOf(Setting::class)]
          public array $settings = [],
      ) {}
  }
  
  class Setting extends AbstractEntity
  {
      public function __construct(
          public readonly string $name,
          public bool $isActive,
      ) {}
  }

License:

MIT License (MIT). Please see LICENSE for more information. Maintained by Composite PHP.