Doctrine ORM para PHP: guia completo com exemplos

O que é Doctrine ORM e para que serve?

\n\n

Doctrine ORM (Object-Relational Mapping) é uma biblioteca poderosa para PHP que permite aos desenvolvedores trabalhar com bancos de dados usando uma abordagem orientada a objetos, em vez de escrever consultas SQL brutas. Doctrine ORM é o padrão de facto para Symfony, mas também pode ser usado em qualquer outro projeto PHP (Laravel, Yii, PHP puro).

\n\n

O principal problema que o Doctrine resolve: a incompatibilidade entre o modelo relacional de dados (tabelas, linhas, colunas) e o modelo de objetos (classes, objetos, propriedades). O Doctrine converte automaticamente objetos PHP em registros de banco de dados e vice-versa.

\n\n

Principais recursos:

\n

\n
• Criação automática do esquema do banco de dados — com base em anotações/atributos nas classes
\n
• Repository Pattern — métodos convenientes para buscar e filtrar dados
\n
• DQL (Doctrine Query Language) — linguagem de consulta orientada a objetos
\n
• Lazy Loading — carregamento de dados relacionados apenas quando necessário
\n
• Migrações — gerenciamento de alterações no esquema do banco de dados
\n
• Transações — suporte completo a ACID
\n
• Cache — de metadados, consultas, resultados
\n

\n\n

Doctrine ORM é adequado para projetos de qualquer escala: desde pequenos sites até sistemas corporativos com centenas de tabelas.

\n\n

Instalação do Doctrine ORM

\n\n

A instalação é feita via Composer (gerenciador de pacotes PHP). Abra o terminal na raiz do seu projeto e execute:

\n\n

composer require doctrine/orm

\n\n

Para trabalhar com Symfony, recomenda-se instalar o pacote DoctrineBundle:

\n\n

composer require symfony/orm-pack\ncomposer require --dev symfony/maker-bundle  # para geração de código

\n\n

Se você estiver usando PHP puro sem framework, também será necessário instalar o driver para seu banco de dados:

\n\n

composer require doctrine/dbal\ncomposer require doctrine/annotations  # para trabalhar com anotações (PHP 7.4 e inferior)

\n\n

Para trabalhar com atributos PHP 8+ (forma recomendada): anotações não são necessárias, o Doctrine suporta atributos nativos.

\n\n

Início rápido: exemplo de código

\n\n

Vamos considerar um exemplo simples — criar uma entidade "Product" e salvá-la no banco de dados.

\n\n

1. Criando a classe de entidade (Entity)

\n\n

<?php\n// src/Entity/Product.php\nnamespace App\\Entity;\n\nuse Doctrine\\ORM\\Mapping as ORM;\n\n#[ORM\\Entity]\n#[ORM\\Table(name: 'products')]\nclass Product\n{\n    #[ORM\\Id]\n    #[ORM\\GeneratedValue]\n    #[ORM\\Column(type: 'integer')]\n    private int $id;\n\n    #[ORM\\Column(type: 'string', length: 255)]\n    private string $name;\n\n    #[ORM\\Column(type: 'float')]\n    private float $price;\n\n    // Getters e Setters\n    public function getId(): int\n    {\n        return $this->id;\n    }\n\n    public function getName(): string\n    {\n        return $this->name;\n    }\n\n    public function setName(string $name): self\n    {\n        $this->name = $name;\n        return $this;\n    }\n\n    public function getPrice(): float\n    {\n        return $this->price;\n    }\n\n    public function setPrice(float $price): self\n    {\n        $this->price = $price;\n        return $this;\n    }\n}

\n\n

2. Criando e salvando o objeto

\n\n

<?php\n// Em um controller Symfony ou em qualquer outro lugar\nuse App\\Entity\\Product;\nuse Doctrine\\ORM\\EntityManagerInterface;\n\nclass ProductController\n{\n    public function createProduct(EntityManagerInterface $entityManager)\n    {\n        $product = new Product();\n        $product->setName('Notebook');\n        $product->setPrice(49999.99);\n\n        // Diz ao Doctrine que o objeto precisa ser salvo\n        $entityManager->persist($product);\n        \n        // Executa o INSERT