https://github.com/devitools/constructo
https://github.com/devitools/constructo
Last synced: 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/devitools/constructo
- Owner: devitools
- Created: 2025-07-17T21:41:50.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-10-20T20:33:14.000Z (6 months ago)
- Last Synced: 2025-10-30T04:54:05.918Z (5 months ago)
- Language: PHP
- Size: 260 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Constructo
**O serializador e deserializador definitivo para PHP**
[](https://php.net/)
[](LICENSE)
[](https://packagist.org/packages/devitools/constructo)
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:
```bash
composer require devitools/constructo
```
### Requisitos
- PHP 8.3 ou superior
- ext-json
## 🔧 Início Rápido
### Serialização simples e rápida
```php
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
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
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
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
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
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
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
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
'João', 'age' => 30]);
```
### Conversão de Tipos
```php
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
'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
make();
```
### Reflexão e Metadados
Capacidades avançadas de reflexão para introspecção de objetos:
```php
make();
```
### Cache
Suporte integrado de cache para melhor performance:
```php