Entities & Database

Define database structures using Doctrine ORM entities and manage schema changes with migrations.

Basic Entity

<?php
namespace Plugins\MyPlugin\Entity;

use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity(repositoryClass: MyEntityRepository::class)]
#[ORM\Table(name: 'plg_my_visit_log')]
#[ORM\Index(columns: ['created_at'], name: 'idx_created_at')]
class VisitLog
{
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column(type: 'integer')]
    private ?int $id = null;

    #[ORM\Column(type: 'string', length: 255)]
    private string $ipAddress;

    #[ORM\Column(type: 'string', length: 500)]
    private string $userAgent;

    #[ORM\Column(type: 'datetime_immutable')]
    private \DateTimeImmutable $createdAt;

    public function __construct()
    {
        $this->createdAt = new \DateTimeImmutable();
    }

    // Getters and setters
    public function getId(): ?int
    {
        return $this->id;
    }

    public function getIpAddress(): string
    {
        return $this->ipAddress;
    }

    public function setIpAddress(string $ipAddress): self
    {
        $this->ipAddress = $ipAddress;
        return $this;
    }

    // ... more getters/setters
}

Table Naming Convention

Always use the plg_ prefix with a short plugin identifier:

plg_{short_identifier}_{table_name}

Examples:

• plg_hello_visit_log (hello-world plugin)

• plg_paypal_transaction (paypal-payment plugin)

• plg_my_user_data (my-plugin)

Entity Best Practices

1. Use DateTimeImmutable for timestamps:

#[ORM\Column(type: 'datetime_immutable')]
private \DateTimeImmutable $createdAt;

1. Add indexes for frequently queried columns:

#[ORM\Index(columns: ['user_id'], name: 'idx_user_id')]
#[ORM\Index(columns: ['created_at'], name: 'idx_created_at')]

1. Use appropriate column lengths:

#[ORM\Column(type: 'string', length: 255)]  // Standard text
#[ORM\Column(type: 'text')]                  // Long text

1. Add validation constraints:

use Symfony\Component\Validator\Constraints as Assert;

#[ORM\Column(type: 'string', length: 255)]
#[Assert\NotBlank]
#[Assert\Email]
private string $email;

Custom Repository

<?php
namespace Plugins\MyPlugin\Repository;

use Doctrine\Bundle\DoctrineBundle\Repository\ServiceEntityRepository;
use Doctrine\Persistence\ManagerRegistry;
use Plugins\MyPlugin\Entity\VisitLog;

class VisitLogRepository extends ServiceEntityRepository
{
    public function __construct(ManagerRegistry $registry)
    {
        parent::__construct($registry, VisitLog::class);
    }

    public function findRecentVisits(int $limit = 10): array
    {
        return $this->createQueryBuilder('v')
            ->orderBy('v.createdAt', 'DESC')
            ->setMaxResults($limit)
            ->getQuery()
            ->getResult();
    }

    public function countVisitsByIp(string $ipAddress): int
    {
        return $this->createQueryBuilder('v')
            ->select('COUNT(v.id)')
            ->where('v.ipAddress = :ip')
            ->setParameter('ip', $ipAddress)
            ->getQuery()
            ->getSingleScalarResult();
    }
}

Using Entities in Controllers

use Doctrine\ORM\EntityManagerInterface;
use Plugins\MyPlugin\Entity\VisitLog;

class MyController extends AbstractController
{
    public function __construct(
        private readonly EntityManagerInterface $entityManager,
    ) {}

    #[Route('/log-visit', name: 'log_visit')]
    public function logVisit(Request $request): Response
    {
        $visit = new VisitLog();
        $visit->setIpAddress($request->getClientIp());
        $visit->setUserAgent($request->headers->get('User-Agent'));

        $this->entityManager->persist($visit);
        $this->entityManager->flush();

        return $this->json(['status' => 'logged']);
    }

    #[Route('/visits', name: 'visits')]
    public function listVisits(): Response
    {
        $visits = $this->entityManager
            ->getRepository(VisitLog::class)
            ->findRecentVisits(20);

        return $this->render('@PluginMyPlugin/visits.html.twig', [
            'visits' => $visits
        ]);
    }
}

Migrations

Migrations manage database schema changes and initial data setup.

Creating a Migration

docker exec pteroca_web_dev php bin/console make:migration

This generates a migration file in your plugin's Migrations/ directory.

Migration Structure

<?php
namespace Plugins\MyPlugin\Migrations;

use Doctrine\DBAL\Schema\Schema;
use Doctrine\Migrations\AbstractMigration;

final class Version20251214000001 extends AbstractMigration
{
    public function getDescription(): string
    {
        return 'Create visit_log table for MyPlugin';
    }

    public function up(Schema $schema): void
    {
        $this->addSql('
            CREATE TABLE plg_my_visit_log (
                id INT AUTO_INCREMENT PRIMARY KEY,
                ip_address VARCHAR(255) NOT NULL,
                user_agent VARCHAR(500) NOT NULL,
                created_at DATETIME NOT NULL COMMENT \'(DC2Type:datetime_immutable)\',
                INDEX idx_created_at (created_at)
            ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
        ');
    }

    public function down(Schema $schema): void
    {
        $this->addSql('DROP TABLE plg_my_visit_log');
    }
}

Settings Initialization Migration

Create a separate migration for plugin settings:

<?php
namespace Plugins\MyPlugin\Migrations;

use Doctrine\DBAL\Schema\Schema;
use Doctrine\Migrations\AbstractMigration;

final class Version20251214000002 extends AbstractMigration
{
    public function getDescription(): string
    {
        return 'Initialize MyPlugin settings';
    }

    public function up(Schema $schema): void
    {
        // Initialize plugin settings
        $this->addSql("
            INSERT INTO setting (name, value, context)
            VALUES
                ('api_key', '', 'plugin:my-plugin'),
                ('api_endpoint', 'https://api.example.com', 'plugin:my-plugin'),
                ('enabled_features', 'basic', 'plugin:my-plugin'),
                ('debug_mode', '0', 'plugin:my-plugin')
        ");
    }

    public function down(Schema $schema): void
    {
        // Remove plugin settings
        $this->addSql("
            DELETE FROM setting
            WHERE context = 'plugin:my-plugin'
        ");
    }
}

Migration Best Practices

1. Use MySQL/MariaDB syntax (PteroCA's database):

CREATE TABLE ... ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci

1. Always include down() method for rollback:

public function down(Schema $schema): void
{
    $this->addSql('DROP TABLE plg_my_table');
}

1. Use table prefix plg_:

CREATE TABLE plg_my_plugin_data ...

1. Settings context must be plugin:{plugin-name}:

INSERT INTO setting (name, value, context)
VALUES ('setting_name', 'value', 'plugin:my-plugin')

1. Add indexes for performance:

INDEX idx_user_id (user_id),
INDEX idx_created_at (created_at)

1. Handle datetime immutable with comment:

created_at DATETIME NOT NULL COMMENT '(DC2Type:datetime_immutable)'

Running Migrations

Migrations run automatically when plugin is enabled:

php bin/console pteroca:plugin:enable my-plugin

Manual migration execution:

docker exec pteroca_web_dev php bin/console doctrine:migrations:migrate --configuration=plugins/my-plugin/migrations.yaml

Related Guides

• Plugin Structure - Entity directory organization

• Bootstrap & Lifecycle - Don't create tables in Bootstrap

• CRUD Controllers - Manage entities in admin panel