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.
- 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
Instale o Constructo via Composer:
composer require devitools/constructo- PHP 8.3 ou superior
- ext-json
<?php# ...useConstructo\Core\Serialize\Builder;
useConstructo\Support\Set;
useConstructo\Type\Timestamp;
// Defina sua entidade informando os valores das propriedades no construtorreadonlyclass User
{
publicfunction__construct(
publicint$id,
publicstring$name,
publicTimestamp$birthDate,
publicbool$isActive = true,
publicarray$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 = (newBuilder())->build(User::class, $set);
echo"Usuário: \n";
echosprintf(" ID: %s\n", $user->id);
echosprintf(" Nome: %s\n", $user->name);
echosprintf(" Ativo: %s\n", $user->isActive);
echosprintf(" Tags: %s\n", implode(', ', $user->tags));
echosprintf(" Data de Nascimento: %s\n", $user->birthDate->format('Y-m-d'));<?phpuseConstructo\Core\Deserialize\Demolisher;
// Crie uma instância$user = newUser(1, 'João Silva', 'joao@exemplo.com', true, ['admin', 'usuario']);
// Serialize para objeto/array$demolisher = newDemolisher();
$data = $demolisher->demolish($user);
echojson_encode($data);
// Saída: {"id":1,"name":"João Silva","email":"joao@exemplo.com","isActive":true,"tags":["admin","usuario"]}Constructo suporta formatadores personalizados para transformação de dados durante a deserialização:
<?phpuseConstructo\Core\Serialize\Builder;
// Formatador personalizado para arraysclass ArrayFormatter
{
publicfunction__invoke($value)
{
returnis_string($value) ? json_decode($value, true) : $value;
}
}
// Use com Builder$builder = newBuilder(formatters: [
'array' => newArrayFormatter(),
]);
$data = [
'id' => 1,
'name' => 'Maria Santos',
'tags' => '["desenvolvedor", "php"]'// String JSON será convertida para array
];
$user = $builder->build(User::class, Set::createFrom($data));
echoimplode(', ', $user->tags); // "desenvolvedor, php"<?phpclass Address extends Entity
{
publicfunction__construct(
publicreadonlystring$street,
publicreadonlystring$city,
publicreadonlystring$country
) {}
}
class User extends Entity
{
publicfunction__construct(
publicreadonlyint$id,
publicreadonlystring$name,
publicreadonlyAddress$address,
publicreadonly ?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 = newBuilder();
$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"<?phpenum Status: string
{
caseACTIVE = 'ativo';
caseINACTIVE = 'inativo';
casePENDING = 'pendente';
}
class Order extends Entity
{
publicfunction__construct(
publicreadonlyint$id,
publicreadonlyStatus$status,
publicreadonlyfloat$amount
) {}
}
$data = [
'id' => 1,
'status' => 'ativo', // String será convertida para enum'amount' => 99.99
];
$builder = newBuilder();
$order = $builder->build(Order::class, Set::createFrom($data));
echo$order->status->value; // "ativo"Quando a deserialização falha, o Constructo fornece informações detalhadas de erro:
<?phpuseConstructo\Support\Datum;
useConstructo\Exception\AdapterException;
try {
$result = $builder->build(User::class, Set::createFrom($invalidData));
} catch (AdapterException$e) {
// Crie um objeto Datum com detalhes do erro$datum = newDatum($e, $invalidData);
$errorData = $datum->export();
// Contém dados originais mais '@error' com detalhes da exceção
}<?phpuseConstructo\Core\Deserialize\Demolisher;
// Formatador de string personalizado$stringFormatter = fn($value) => sprintf('[%s]', $value);
// Use com Demolisher$demolisher = newDemolisher(formatters: [
'string' => $stringFormatter,
]);
$user = newUser(1, 'Ana Costa', 'ana@exemplo.com');
$data = $demolisher->demolish($user);
echo$data->name; // "[Ana Costa]"<?phpuseConstructo\Contract\Collectable;
useConstructo\Type\Collection;
class UserCollection extends Collection implements Collectable
{
protectedfunctiongetItemClass(): string
{
return User::class;
}
}
// Serialize coleção$collection = newUserCollection();
$collection->push($user1);
$collection->push($user2);
$demolisher = newDemolisher();
$arrayData = $demolisher->demolishCollection($collection);Constructo inclui várias funções utilitárias para operações comuns:
<?phpusefunctionConstructo\Json\decode;
usefunctionConstructo\Json\encode;
$array = decode('{"name":"João","age":30}');
$json = encode(['name' => 'João', 'age' => 30]);<?phpusefunctionConstructo\Cast\arrayify;
usefunctionConstructo\Cast\stringify;
$array = arrayify($data); // Converte para array com segurança$string = stringify($value); // Converte para string com segurança<?phpusefunctionConstructo\Util\extractString;
usefunctionConstructo\Util\extractInt;
usefunctionConstructo\Util\extractBool;
usefunctionConstructo\Util\extractArray;
$name = extractString($data, 'name', 'padrão');
$age = extractInt($data, 'age', 0);
$active = extractBool($data, 'is_active', false);
$tags = extractArray($data, 'tags', []);Constructo fornece utilitários de teste para facilitar os testes:
<?phpuseConstructo\Testing\BuilderExtension;
useConstructo\Testing\MakeExtension;
usePHPUnit\Framework\TestCase;
class MyTest extends TestCase
{
use BuilderExtension, MakeExtension;
publicfunctiontestSerialization(): void
{
$user = $this->builder()->build(User::class, Set::createFrom($data));
$this->assertInstanceOf(User::class, $user);
}
}Estenda a classe Entity para obter suporte automático de serialização:
<?phpuseConstructo\Support\Entity;
class MyEntity extends Entity
{
// Automaticamente implementa Exportable e JsonSerializable// Fornece método export() que retorna objeto com todas as propriedades públicas
}A classe Set é usada para gerenciar coleções de dados com segurança de tipos:
<?phpuseConstructo\Support\Set;
$set = Set::createFrom(['key' => 'valor']);
$set = newSet(['key' => 'valor']);
$value = $set->get('key', 'padrão');
$array = $set->toArray();Para manipular valores individuais com validação e transformação:
<?phpuseConstructo\Support\Value;
$value = newValue('alguns dados');
// Fornece vários métodos para manipulação e validação de valoresConstructo pode gerar schemas para seus objetos:
<?phpuseConstructo\Factory\SchemaFactory;
useConstructo\Factory\DefaultSpecsFactory;
$schemaFactory = newSchemaFactory(newDefaultSpecsFactory());
$schema = $schemaFactory->make();Capacidades avançadas de reflexão para introspecção de objetos:
<?phpuseConstructo\Support\Reflective\Engine;
useConstructo\Factory\ReflectorFactory;
$reflectorFactory = newReflectorFactory();
$reflector = $reflectorFactory->make();Suporte integrado de cache para melhor performance:
<?phpuseConstructo\Support\Cache;
$cache = newCache();
// Fornece mecanismos de cache para dados de reflexão e schemasContribuiçõ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.
- 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
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
Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.
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.