Mastering Doctrine ORM: A Beginner’s Guide to PHP’s Powerful Database Mapper

Overview

Doctrine ORM is a popular PHP object‑relational mapping (ORM) library that links database tables to PHP classes, allowing developers to work with data using object‑oriented code instead of raw SQL. It offers a clean API for querying, persisting, and managing transactions.

Key Features

1. Easy‑to‑use API

Doctrine provides an intuitive API so developers can perform most database operations without writing SQL.

2. Object‑oriented data model

Entities are defined as PHP classes, with relationships described via annotations or YAML, enabling a natural, language‑centric way of modeling data.

3. Powerful query builder

It includes a QueryBuilder and Doctrine Query Language (DQL), which let you construct complex queries programmatically; DQL resembles SQL but is more object‑oriented.

4. Support for multiple database systems

Doctrine works with MySQL, PostgreSQL, SQLite and other databases, so the same code runs regardless of the underlying DBMS.

5. Automatic schema synchronization

When entity classes change, Doctrine can detect the modifications and update the database schema automatically, saving manual migration effort.

Installation

Install the library via Composer:

composer require doctrine/orm

Sample Application

<?php
declare(strict_types=1);

require_once 'vendor/autoload.php';

use Doctrine\ORM\EntityManager;
use Doctrine\ORM\Tools\Setup;

$paths = array(__DIR__ . '/src');
$isDevMode = true;
$config = Setup::createAnnotationMetadataConfiguration($paths, $isDevMode);

$entityManager = EntityManager::create([
    'driver'   => 'pdo_mysql',
    'host'     => 'localhost',
    'dbname'   => 'my_database',
    'user'     => 'tinywan',
    'password' => '123456',
], $config);

/**
 * @ORM\Entity
 * @ORM\Table(name="users")
 */
class UserModel {
    /**
     * @ORM\Id
     * @ORM\GeneratedValue(strategy="AUTO")
     * @ORM\Column(type="integer")
     */
    private int $id;

    /**
     * @ORM\Column(name="username", type="string", length=100)
     */
    private string $username;

    public function setUsername(string $username): void { $this->username = $username; }
    public function getId(): int { return $this->id; }
    public function getUsername(): string { return $this->username; }
}

// Operate on the database
$user = new UserModel();
$user->setUsername('Tinywan');

$entityManager->persist($user);
$entityManager->flush();

$users = $entityManager->getRepository(UserModel::class)->findAll();
foreach ($users as $user) {
    echo "[x] id: {$user->getId()}, username: {$user->getUsername()}" . PHP_EOL;
}