Constructo

O serializador e deserializador definitivo para PHP

Constructo é uma poderosa biblioteca PHP que fornece capacidades avançadas de serialização e deserialização para objetos PHP. Ela permite conversão perfeita entre objetos e arrays/JSON, com suporte para estruturas aninhadas complexas, conversão de tipos, validação e formatação personalizada.

🚀 Funcionalidades

Conversão Bidirecional: Serialize objetos para arrays/JSON e deserialize de volta para objetos tipados
Segurança de Tipos: Suporte completo ao sistema de tipos do PHP 8.3+ incluindo union types, backed enums e propriedades readonly
Mapeamento Inteligente: Mapeamento automático de propriedades com conversão de snake_case para camelCase
Formatadores Personalizados: Sistema de formatação extensível para transformações de dados customizadas
Objetos Aninhados: Manipule hierarquias de objetos complexas e coleções perfeitamente
Tratamento de Erros: Relatório de erros abrangente com contexto detalhado
Validação: Validação integrada com suporte a atributos personalizados
Manipulação de Data/Hora: Análise e formatação inteligente de DateTime
Coleções: Suporte de primeira classe para coleções tipadas
Injeção de Dependência: Resolução automática de dependência para construção de objetos

📦 Instalação

Instale o Constructo via Composer:

composer require devitools/constructo

Requisitos

PHP 8.3 ou superior
ext-json

🔧 Início Rápido

Serialização simples e rápida

<?php
# ...
use Constructo\Core\Serialize\Builder;
use Constructo\Support\Set;
use Constructo\Type\Timestamp;

// Defina sua entidade informando os valores das propriedades no construtor
readonly class User
{
    public function __construct(
        public int $id,
        public string $name,
        public Timestamp $birthDate,
        public bool $isActive = true,
        public array $tags = [],
    ) {}
}

// Monte um set com os dados (de JSON, banco de dados, etc.)
$set = Set::createFrom([
    'id' => 1,
    'name' => 'João Silva',
    'birth_date' => '1981-08-13',
    'is_active' => true,
    'tags' => ['nice', 'welcome'],
]);

// Crie um novo builder e use-o para construir o objeto
$user = (new Builder())->build(User::class, $set);

echo "Usuário: \n";
echo sprintf("  ID: %s\n", $user->id);
echo sprintf("  Nome: %s\n", $user->name);
echo sprintf("  Ativo: %s\n", $user->isActive);
echo sprintf("  Tags: %s\n", implode(', ', $user->tags));
echo sprintf("  Data de Nascimento: %s\n", $user->birthDate->format('Y-m-d'));

Desserialização prática e direta

<?php

use Constructo\Core\Deserialize\Demolisher;

// Crie uma instância
$user = new User(1, 'João Silva', 'joao@exemplo.com', true, ['admin', 'usuario']);

// Serialize para objeto/array
$demolisher = new Demolisher();
$data = $demolisher->demolish($user);

echo json_encode($data);
// Saída: {"id":1,"name":"João Silva","email":"joao@exemplo.com","isActive":true,"tags":["admin","usuario"]}

📋 Uso Avançado do Builder

Formatadores Personalizados no Builder

Constructo suporta formatadores personalizados para transformação de dados durante a deserialização:

<?php

use Constructo\Core\Serialize\Builder;

// Formatador personalizado para arrays
class ArrayFormatter
{
    public function __invoke($value)
    {
        return is_string($value) ? json_decode($value, true) : $value;
    }
}

// Use com Builder
$builder = new Builder(formatters: [
    'array' => new ArrayFormatter(),
]);

$data = [
    'id' => 1,
    'name' => 'Maria Santos',
    'tags' => '["desenvolvedor", "php"]' // String JSON será convertida para array
];

$user = $builder->build(User::class, Set::createFrom($data));
echo implode(', ', $user->tags); // "desenvolvedor, php"

Objetos Aninhados Complexos com Builder

<?php

class Address extends Entity
{
    public function __construct(
        public readonly string $street,
        public readonly string $city,
        public readonly string $country
    ) {}
}

class User extends Entity
{
    public function __construct(
        public readonly int $id,
        public readonly string $name,
        public readonly Address $address,
        public readonly ?DateTime $createdAt = null
    ) {}
}

// Dados aninhados
$data = [
    'id' => 1,
    'name' => 'João Silva',
    'address' => [
        'street' => 'Rua Principal, 123',
        'city' => 'São Paulo',
        'country' => 'Brasil'
    ],
    'created_at' => '2023-01-15T10:30:00+00:00'
];

$builder = new Builder();
$user = $builder->build(User::class, Set::createFrom($data));

echo $user->address->city; // "São Paulo"
echo $user->createdAt->format('d/m/Y'); // "15/01/2023"

Suporte a Backed Enums com Builder

<?php

enum Status: string
{
    case ACTIVE = 'ativo';
    case INACTIVE = 'inativo';
    case PENDING = 'pendente';
}

class Order extends Entity
{
    public function __construct(
        public readonly int $id,
        public readonly Status $status,
        public readonly float $amount
    ) {}
}

$data = [
    'id' => 1,
    'status' => 'ativo',  // String será convertida para enum
    'amount' => 99.99
];

$builder = new Builder();
$order = $builder->build(Order::class, Set::createFrom($data));

echo $order->status->value; // "ativo"

Tratamento de Erros com Datum

Quando a deserialização falha, o Constructo fornece informações detalhadas de erro:

<?php

use Constructo\Support\Datum;
use Constructo\Exception\AdapterException;

try {
    $result = $builder->build(User::class, Set::createFrom($invalidData));
} catch (AdapterException $e) {
    // Crie um objeto Datum com detalhes do erro
    $datum = new Datum($e, $invalidData);
    
    $errorData = $datum->export();
    // Contém dados originais mais '@error' com detalhes da exceção
}

📋 Uso Avançado do Demolisher

Formatadores Personalizados no Demolisher

<?php

use Constructo\Core\Deserialize\Demolisher;

// Formatador de string personalizado
$stringFormatter = fn($value) => sprintf('[%s]', $value);

// Use com Demolisher
$demolisher = new Demolisher(formatters: [
    'string' => $stringFormatter,
]);

$user = new User(1, 'Ana Costa', 'ana@exemplo.com');
$data = $demolisher->demolish($user);

echo $data->name; // "[Ana Costa]"

Trabalhando com Coleções

<?php

use Constructo\Contract\Collectable;
use Constructo\Type\Collection;

class UserCollection extends Collection implements Collectable
{
    protected function getItemClass(): string
    {
        return User::class;
    }
}

// Serialize coleção
$collection = new UserCollection();
$collection->push($user1);
$collection->push($user2);

$demolisher = new Demolisher();
$arrayData = $demolisher->demolishCollection($collection);

🛠️ Funções Utilitárias

Constructo inclui várias funções utilitárias para operações comuns:

Helpers JSON

<?php

use function Constructo\Json\decode;
use function Constructo\Json\encode;

$array = decode('{"name":"João","age":30}');
$json = encode(['name' => 'João', 'age' => 30]);

Conversão de Tipos

<?php

use function Constructo\Cast\arrayify;
use function Constructo\Cast\stringify;

$array = arrayify($data);  // Converte para array com segurança
$string = stringify($value);  // Converte para string com segurança

Extração de Dados

<?php

use function Constructo\Util\extractString;
use function Constructo\Util\extractInt;
use function Constructo\Util\extractBool;
use function Constructo\Util\extractArray;

$name = extractString($data, 'name', 'padrão');
$age = extractInt($data, 'age', 0);
$active = extractBool($data, 'is_active', false);
$tags = extractArray($data, 'tags', []);

🧪 Extensões de Teste

Constructo fornece utilitários de teste para facilitar os testes:

<?php

use Constructo\Testing\BuilderExtension;
use Constructo\Testing\MakeExtension;
use PHPUnit\Framework\TestCase;

class MyTest extends TestCase
{
    use BuilderExtension, MakeExtension;
    
    public function testSerialization(): void
    {
        $user = $this->builder()->build(User::class, Set::createFrom($data));
        $this->assertInstanceOf(User::class, $user);
    }
}

📚 Conceitos Centrais

Classe Base Entity

Estenda a classe Entity para obter suporte automático de serialização:

<?php

use Constructo\Support\Entity;

class MyEntity extends Entity
{
    // Automaticamente implementa Exportable e JsonSerializable
    // Fornece método export() que retorna objeto com todas as propriedades públicas
}

Classe Set

A classe Set é usada para gerenciar coleções de dados com segurança de tipos:

<?php

use Constructo\Support\Set;

$set = Set::createFrom(['key' => 'valor']);
$set = new Set(['key' => 'valor']);
$value = $set->get('key', 'padrão');
$array = $set->toArray();

Classe Value

Para manipular valores individuais com validação e transformação:

<?php

use Constructo\Support\Value;

$value = new Value('alguns dados');
// Fornece vários métodos para manipulação e validação de valores

🔍 Funcionalidades Avançadas

Geração de Schema

Constructo pode gerar schemas para seus objetos:

<?php

use Constructo\Factory\SchemaFactory;
use Constructo\Factory\DefaultSpecsFactory;

$schemaFactory = new SchemaFactory(new DefaultSpecsFactory());
$schema = $schemaFactory->make();

Reflexão e Metadados

Capacidades avançadas de reflexão para introspecção de objetos:

<?php

use Constructo\Support\Reflective\Engine;
use Constructo\Factory\ReflectorFactory;

$reflectorFactory = new ReflectorFactory();
$reflector = $reflectorFactory->make();

Cache

Suporte integrado de cache para melhor performance:

<?php

use Constructo\Support\Cache;

$cache = new Cache();
// Fornece mecanismos de cache para dados de reflexão e schemas

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request. Para mudanças importantes, abra primeiro uma issue para discutir o que você gostaria de alterar.

Configuração de Desenvolvimento

Clone o repositório
Instale as dependências: composer install
Execute os testes: composer test
Execute o linting: composer lint:phpcs
Execute análise estática: composer lint:phpstan

Ferramentas de Qualidade de Código

O projeto usa várias ferramentas de qualidade de código:

PHPUnit para testes
PHPStan para análise estática
PHP_CodeSniffer para estilo de código
PHPMD para detecção de bagunça
Psalm para análise estática adicional
Rector para modernização de código

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🏢 Sobre a Devitools

Constructo é desenvolvido e mantido pela Devitools. Nós nos especializamos em criar ferramentas de desenvolvimento poderosas e bibliotecas para aplicações web modernas.

Para mais informações e exemplos de uso avançado, visite nossa documentação em devi.tools/constructo.

Name		Name	Last commit message	Last commit date
Latest commit History 71 Commits
.github/workflows		.github/workflows
.junie		.junie
examples		examples
src		src
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
compose.yml		compose.yml
composer.json		composer.json
makefile		makefile
phpcs.xml		phpcs.xml
phpmd.xml		phpmd.xml
phpstan.neon		phpstan.neon
phpunit.xml		phpunit.xml
psalm.xml		psalm.xml
rector.php		rector.php

devitools/constructo

Folders and files

Latest commit

History

Repository files navigation