{"id":29878671,"url":"https://github.com/devitools/constructo","last_synced_at":"2026-02-03T20:15:47.645Z","repository":{"id":305049506,"uuid":"1021736892","full_name":"devitools/constructo","owner":"devitools","description":null,"archived":false,"fork":false,"pushed_at":"2025-10-20T20:33:14.000Z","size":266,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-30T04:54:05.918Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devitools.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-17T21:41:50.000Z","updated_at":"2025-10-20T20:27:44.000Z","dependencies_parsed_at":"2025-09-09T05:33:18.177Z","dependency_job_id":"d41923c5-f66b-417a-972a-cb91d5bcf241","html_url":"https://github.com/devitools/constructo","commit_stats":null,"previous_names":["devitools/morph","devitools/constructo"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/devitools/constructo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devitools%2Fconstructo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devitools%2Fconstructo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devitools%2Fconstructo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devitools%2Fconstructo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devitools","download_url":"https://codeload.github.com/devitools/constructo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devitools%2Fconstructo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29055809,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-03T20:13:53.544Z","status":"ssl_error","status_checked_at":"2026-02-03T20:13:40.507Z","response_time":96,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-31T07:34:53.765Z","updated_at":"2026-02-03T20:15:47.638Z","avatar_url":"https://github.com/devitools.png","language":"PHP","readme":"# Constructo\n\n**O serializador e deserializador definitivo para PHP**\n\n[![Versão PHP](https://img.shields.io/badge/php-%5E8.3-blue.svg)](https://php.net/)\n[![Licença](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Composer](https://img.shields.io/badge/composer-devitools%2Fconstructo-orange.svg)](https://packagist.org/packages/devitools/constructo)\n\nConstructo é 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.\n\n## 🚀 Funcionalidades\n\n- **Conversão Bidirecional**: Serialize objetos para arrays/JSON e deserialize de volta para objetos tipados\n- **Segurança de Tipos**: Suporte completo ao sistema de tipos do PHP 8.3+ incluindo union types, backed enums e propriedades readonly\n- **Mapeamento Inteligente**: Mapeamento automático de propriedades com conversão de snake_case para camelCase\n- **Formatadores Personalizados**: Sistema de formatação extensível para transformações de dados customizadas\n- **Objetos Aninhados**: Manipule hierarquias de objetos complexas e coleções perfeitamente\n- **Tratamento de Erros**: Relatório de erros abrangente com contexto detalhado\n- **Validação**: Validação integrada com suporte a atributos personalizados\n- **Manipulação de Data/Hora**: Análise e formatação inteligente de DateTime\n- **Coleções**: Suporte de primeira classe para coleções tipadas\n- **Injeção de Dependência**: Resolução automática de dependência para construção de objetos\n\n## 📦 Instalação\n\nInstale o Constructo via Composer:\n\n```bash\ncomposer require devitools/constructo\n```\n\n### Requisitos\n\n- PHP 8.3 ou superior\n- ext-json\n\n## 🔧 Início Rápido\n\n### Serialização simples e rápida\n\n```php\n\u003c?php\n# ...\nuse Constructo\\Core\\Serialize\\Builder;\nuse Constructo\\Support\\Set;\nuse Constructo\\Type\\Timestamp;\n\n// Defina sua entidade informando os valores das propriedades no construtor\nreadonly class User\n{\n    public function __construct(\n        public int $id,\n        public string $name,\n        public Timestamp $birthDate,\n        public bool $isActive = true,\n        public array $tags = [],\n    ) {}\n}\n\n// Monte um set com os dados (de JSON, banco de dados, etc.)\n$set = Set::createFrom([\n    'id' =\u003e 1,\n    'name' =\u003e 'João Silva',\n    'birth_date' =\u003e '1981-08-13',\n    'is_active' =\u003e true,\n    'tags' =\u003e ['nice', 'welcome'],\n]);\n\n// Crie um novo builder e use-o para construir o objeto\n$user = (new Builder())-\u003ebuild(User::class, $set);\n\necho \"Usuário: \\n\";\necho sprintf(\"  ID: %s\\n\", $user-\u003eid);\necho sprintf(\"  Nome: %s\\n\", $user-\u003ename);\necho sprintf(\"  Ativo: %s\\n\", $user-\u003eisActive);\necho sprintf(\"  Tags: %s\\n\", implode(', ', $user-\u003etags));\necho sprintf(\"  Data de Nascimento: %s\\n\", $user-\u003ebirthDate-\u003eformat('Y-m-d'));\n```\n\n### Desserialização prática e direta\n\n```php\n\u003c?php\n\nuse Constructo\\Core\\Deserialize\\Demolisher;\n\n// Crie uma instância\n$user = new User(1, 'João Silva', 'joao@exemplo.com', true, ['admin', 'usuario']);\n\n// Serialize para objeto/array\n$demolisher = new Demolisher();\n$data = $demolisher-\u003edemolish($user);\n\necho json_encode($data);\n// Saída: {\"id\":1,\"name\":\"João Silva\",\"email\":\"joao@exemplo.com\",\"isActive\":true,\"tags\":[\"admin\",\"usuario\"]}\n```\n\n## 📋 Uso Avançado do Builder\n\n### Formatadores Personalizados no Builder\n\nConstructo suporta formatadores personalizados para transformação de dados durante a deserialização:\n\n```php\n\u003c?php\n\nuse Constructo\\Core\\Serialize\\Builder;\n\n// Formatador personalizado para arrays\nclass ArrayFormatter\n{\n    public function __invoke($value)\n    {\n        return is_string($value) ? json_decode($value, true) : $value;\n    }\n}\n\n// Use com Builder\n$builder = new Builder(formatters: [\n    'array' =\u003e new ArrayFormatter(),\n]);\n\n$data = [\n    'id' =\u003e 1,\n    'name' =\u003e 'Maria Santos',\n    'tags' =\u003e '[\"desenvolvedor\", \"php\"]' // String JSON será convertida para array\n];\n\n$user = $builder-\u003ebuild(User::class, Set::createFrom($data));\necho implode(', ', $user-\u003etags); // \"desenvolvedor, php\"\n```\n\n### Objetos Aninhados Complexos com Builder\n\n```php\n\u003c?php\n\nclass Address extends Entity\n{\n    public function __construct(\n        public readonly string $street,\n        public readonly string $city,\n        public readonly string $country\n    ) {}\n}\n\nclass User extends Entity\n{\n    public function __construct(\n        public readonly int $id,\n        public readonly string $name,\n        public readonly Address $address,\n        public readonly ?DateTime $createdAt = null\n    ) {}\n}\n\n// Dados aninhados\n$data = [\n    'id' =\u003e 1,\n    'name' =\u003e 'João Silva',\n    'address' =\u003e [\n        'street' =\u003e 'Rua Principal, 123',\n        'city' =\u003e 'São Paulo',\n        'country' =\u003e 'Brasil'\n    ],\n    'created_at' =\u003e '2023-01-15T10:30:00+00:00'\n];\n\n$builder = new Builder();\n$user = $builder-\u003ebuild(User::class, Set::createFrom($data));\n\necho $user-\u003eaddress-\u003ecity; // \"São Paulo\"\necho $user-\u003ecreatedAt-\u003eformat('d/m/Y'); // \"15/01/2023\"\n```\n\n### Suporte a Backed Enums com Builder\n\n```php\n\u003c?php\n\nenum Status: string\n{\n    case ACTIVE = 'ativo';\n    case INACTIVE = 'inativo';\n    case PENDING = 'pendente';\n}\n\nclass Order extends Entity\n{\n    public function __construct(\n        public readonly int $id,\n        public readonly Status $status,\n        public readonly float $amount\n    ) {}\n}\n\n$data = [\n    'id' =\u003e 1,\n    'status' =\u003e 'ativo',  // String será convertida para enum\n    'amount' =\u003e 99.99\n];\n\n$builder = new Builder();\n$order = $builder-\u003ebuild(Order::class, Set::createFrom($data));\n\necho $order-\u003estatus-\u003evalue; // \"ativo\"\n```\n\n### Tratamento de Erros com Datum\n\nQuando a deserialização falha, o Constructo fornece informações detalhadas de erro:\n\n```php\n\u003c?php\n\nuse Constructo\\Support\\Datum;\nuse Constructo\\Exception\\AdapterException;\n\ntry {\n    $result = $builder-\u003ebuild(User::class, Set::createFrom($invalidData));\n} catch (AdapterException $e) {\n    // Crie um objeto Datum com detalhes do erro\n    $datum = new Datum($e, $invalidData);\n    \n    $errorData = $datum-\u003eexport();\n    // Contém dados originais mais '@error' com detalhes da exceção\n}\n```\n\n## 📋 Uso Avançado do Demolisher\n\n### Formatadores Personalizados no Demolisher\n\n```php\n\u003c?php\n\nuse Constructo\\Core\\Deserialize\\Demolisher;\n\n// Formatador de string personalizado\n$stringFormatter = fn($value) =\u003e sprintf('[%s]', $value);\n\n// Use com Demolisher\n$demolisher = new Demolisher(formatters: [\n    'string' =\u003e $stringFormatter,\n]);\n\n$user = new User(1, 'Ana Costa', 'ana@exemplo.com');\n$data = $demolisher-\u003edemolish($user);\n\necho $data-\u003ename; // \"[Ana Costa]\"\n```\n\n### Trabalhando com Coleções\n\n```php\n\u003c?php\n\nuse Constructo\\Contract\\Collectable;\nuse Constructo\\Type\\Collection;\n\nclass UserCollection extends Collection implements Collectable\n{\n    protected function getItemClass(): string\n    {\n        return User::class;\n    }\n}\n\n// Serialize coleção\n$collection = new UserCollection();\n$collection-\u003epush($user1);\n$collection-\u003epush($user2);\n\n$demolisher = new Demolisher();\n$arrayData = $demolisher-\u003edemolishCollection($collection);\n```\n\n## 🛠️ Funções Utilitárias\n\nConstructo inclui várias funções utilitárias para operações comuns:\n\n### Helpers JSON\n\n```php\n\u003c?php\n\nuse function Constructo\\Json\\decode;\nuse function Constructo\\Json\\encode;\n\n$array = decode('{\"name\":\"João\",\"age\":30}');\n$json = encode(['name' =\u003e 'João', 'age' =\u003e 30]);\n```\n\n### Conversão de Tipos\n\n```php\n\u003c?php\n\nuse function Constructo\\Cast\\arrayify;\nuse function Constructo\\Cast\\stringify;\n\n$array = arrayify($data);  // Converte para array com segurança\n$string = stringify($value);  // Converte para string com segurança\n```\n\n### Extração de Dados\n\n```php\n\u003c?php\n\nuse function Constructo\\Util\\extractString;\nuse function Constructo\\Util\\extractInt;\nuse function Constructo\\Util\\extractBool;\nuse function Constructo\\Util\\extractArray;\n\n$name = extractString($data, 'name', 'padrão');\n$age = extractInt($data, 'age', 0);\n$active = extractBool($data, 'is_active', false);\n$tags = extractArray($data, 'tags', []);\n```\n\n## 🧪 Extensões de Teste\n\nConstructo fornece utilitários de teste para facilitar os testes:\n\n```php\n\u003c?php\n\nuse Constructo\\Testing\\BuilderExtension;\nuse Constructo\\Testing\\MakeExtension;\nuse PHPUnit\\Framework\\TestCase;\n\nclass MyTest extends TestCase\n{\n    use BuilderExtension, MakeExtension;\n    \n    public function testSerialization(): void\n    {\n        $user = $this-\u003ebuilder()-\u003ebuild(User::class, Set::createFrom($data));\n        $this-\u003eassertInstanceOf(User::class, $user);\n    }\n}\n```\n\n## 📚 Conceitos Centrais\n\n### Classe Base Entity\n\nEstenda a classe `Entity` para obter suporte automático de serialização:\n\n```php\n\u003c?php\n\nuse Constructo\\Support\\Entity;\n\nclass MyEntity extends Entity\n{\n    // Automaticamente implementa Exportable e JsonSerializable\n    // Fornece método export() que retorna objeto com todas as propriedades públicas\n}\n```\n\n### Classe Set\n\nA classe `Set` é usada para gerenciar coleções de dados com segurança de tipos:\n\n```php\n\u003c?php\n\nuse Constructo\\Support\\Set;\n\n$set = Set::createFrom(['key' =\u003e 'valor']);\n$set = new Set(['key' =\u003e 'valor']);\n$value = $set-\u003eget('key', 'padrão');\n$array = $set-\u003etoArray();\n```\n\n### Classe Value\n\nPara manipular valores individuais com validação e transformação:\n\n```php\n\u003c?php\n\nuse Constructo\\Support\\Value;\n\n$value = new Value('alguns dados');\n// Fornece vários métodos para manipulação e validação de valores\n```\n\n## 🔍 Funcionalidades Avançadas\n\n### Geração de Schema\n\nConstructo pode gerar schemas para seus objetos:\n\n```php\n\u003c?php\n\nuse Constructo\\Factory\\SchemaFactory;\nuse Constructo\\Factory\\DefaultSpecsFactory;\n\n$schemaFactory = new SchemaFactory(new DefaultSpecsFactory());\n$schema = $schemaFactory-\u003emake();\n```\n\n### Reflexão e Metadados\n\nCapacidades avançadas de reflexão para introspecção de objetos:\n\n```php\n\u003c?php\n\nuse Constructo\\Support\\Reflective\\Engine;\nuse Constructo\\Factory\\ReflectorFactory;\n\n$reflectorFactory = new ReflectorFactory();\n$reflector = $reflectorFactory-\u003emake();\n```\n\n### Cache\n\nSuporte integrado de cache para melhor performance:\n\n```php\n\u003c?php\n\nuse Constructo\\Support\\Cache;\n\n$cache = new Cache();\n// Fornece mecanismos de cache para dados de reflexão e schemas\n```\n\n## 🤝 Contribuindo\n\nContribuiçõ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.\n\n### Configuração de Desenvolvimento\n\n1. Clone o repositório\n2. Instale as dependências: `composer install`\n3. Execute os testes: `composer test`\n4. Execute o linting: `composer lint:phpcs`\n5. Execute análise estática: `composer lint:phpstan`\n\n### Ferramentas de Qualidade de Código\n\nO projeto usa várias ferramentas de qualidade de código:\n\n- **PHPUnit** para testes\n- **PHPStan** para análise estática\n- **PHP_CodeSniffer** para estilo de código\n- **PHPMD** para detecção de bagunça\n- **Psalm** para análise estática adicional\n- **Rector** para modernização de código\n\n## 📄 Licença\n\nEste projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.\n\n## 🏢 Sobre a Devitools\n\nConstructo é desenvolvido e mantido pela [Devitools](https://devi.tools/). Nós nos especializamos em criar ferramentas de desenvolvimento poderosas e bibliotecas para aplicações web modernas.\n\n---\n\nPara mais informações e exemplos de uso avançado, visite nossa documentação em [devi.tools/constructo](https://devi.tools/constructo).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevitools%2Fconstructo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevitools%2Fconstructo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevitools%2Fconstructo/lists"}