<div align='center'> <picture> <source media='(prefers-color-scheme: dark)' srcset='https://cdn.brj.app/images/brj-logo/logo-regular.png'> <img src='https://cdn.brj.app/images/brj-logo/logo-dark.png' alt='BRJ logo'> </picture> <br> <a href="https://brj.app">BRJ organisation</a> </div> <hr>

Baraja Doctrine Database

A simple and easy to use, maximum performance database layer with connection to Doctrine ORM, which allows you to use all the advantages of OOP and also has full support for Nette 3.

This package automatically installs Doctrine to your project (also sets everything up in the configuration) and runs stably.

Key Features

Full Doctrine ORM integration with Nette Framework 3.x
Automatic configuration and setup via DI extensions
Advanced Tracy debug panel with SQL query profiling
Built-in UUID and UUID Binary identifier traits
Custom DQL functions (RAND, ROUND, GEODISTANCE, MATCH AGAINST)
Multiple caching strategies (APCu, SQLite3, Filesystem)
Slow query logging and analysis
Entity inheritance support with discriminator mapping utilities
Blue Screen exception panels for detailed error debugging

Architecture Overview

+------------------+     +-------------------+     +------------------+
|   Nette DI       |---->| DatabaseExtension |---->| EntityManager    |
|   Container      |     | OrmExtension      |     | (Doctrine)       |
+------------------+     | OrmAnnotations    |     +------------------+
                         +-------------------+              |
                                  |                         v
                         +-------------------+     +------------------+
                         | ConnectionFactory |<----| DBAL Connection  |
                         +-------------------+     +------------------+
                                  |                         |
                         +-------------------+              v
                         | Cache Provider    |     +------------------+
                         | (APCu/SQLite/FS)  |     | Tracy QueryPanel |
                         +-------------------+     +------------------+

Main Components

DI Extensions

| Extension | Purpose | |-----------|---------| | DatabaseExtension | Main extension for database connection configuration | | OrmExtension | Doctrine ORM configuration (proxy classes, naming strategies) | | OrmAnnotationsExtension | Entity mapping and annotation reader setup | | OrmConsoleExtension | CLI commands integration | | DbalConsoleExtension | DBAL CLI commands |

Core Services

| Service | Description | |---------|-------------| | EntityManager | Extended Doctrine EntityManager with fluent interface and error handling | | DoctrineHelper | Utilities for entity inheritance, discriminator mapping, and type remapping | | Repository | Enhanced base repository with findPairs() and findByConditions() methods | | ConnectionFactory | Creates and configures DBAL connections with custom types |

Identifier Traits

| Trait | Type | Description | |-------|------|-------------| | Identifier | int | Auto-increment integer ID | | IdentifierUnsigned | int (unsigned) | Auto-increment unsigned integer ID | | UuidIdentifier | string | UUID v4 stored as string (36 chars) | | UuidBinaryIdentifier | binary | UUID v4 stored as binary (16 bytes) for better performance |

Custom DQL Functions

| Function | Description | |----------|-------------| | RAND() | Random number generation | | ROUND(value, precision) | Number rounding | | GEODISTANCE(lat1, lng1, lat2, lng2) | Geographic distance calculation in km | | MATCH(column) AGAINST(value) | MySQL fulltext search |

Caching Providers

| Provider | Best For | |----------|----------| | ApcuCache | Production with APCu extension | | SQLite3Cache | Production without APCu | | FilesystemCache | Development/fallback | | ArrayCache | Testing |

📦 Installation

It's best to use Composer for installation, and you can also find the package on Packagist and GitHub.

To install, simply use the command:

$ composer require baraja-core/doctrine

You can use the package manually by creating an instance of the internal classes, or register a DIC extension to link the services directly to the Nette Framework.

Requirements

PHP 8.0 or higher
PDO extension
Nette Framework 3.x
Optional: APCu extension (recommended for production caching)
Optional: SQLite3 extension (fallback caching)

Configuration

A model configuration can be found in the common.neon file inside the root of the package.

Basic Database Connection

In the project's common.neon you have to define the database credentials using the baraja.database extension:

baraja.database:
    connection:
        host: 127.0.0.1
        dbname: sandbox
        user: root
        password: root

Connection Options

The following connection options are available:

| Option | Type | Description | |--------|------|-------------| | url | string | DSN connection URL | | pdo | string | Existing PDO instance | | memory | string | In-memory database | | driver | string | DBAL driver (default: pdo_mysql) | | driverClass | string | Custom driver class | | driverOptions | array | Driver-specific options | | unix_socket | string | Unix socket path | | host | string | Database host | | port | int | Database port | | dbname | string | Database name | | servicename | string | Oracle service name | | user | string | Username | | password | string | Password | | charset | string | Character set (default: UTF8) | | portability | int | Portability mode | | fetchCase | int | Fetch case mode | | persistent | bool | Persistent connection | | types | array | Custom DBAL types | | typesMapping | array | Type mappings | | wrapperClass | string | Custom connection wrapper | | serverVersion | string | Server version hint |

Environment Variable Support

The package supports the DB_URI environment variable for connection configuration:

DB_URI=mysql://user:password@host:3306/dbname

Additionally, you can use DB_NAME to override the database name from the URI.

⚙️ Drivers

In default settings Doctrine uses the MySql driver.

PostgreSQL

You can switch to PostgreSQL by specifying the driver class:

baraja.database:
    connection:
        driverClass: Doctrine\DBAL\Driver\PDO\PgSQL\Driver

Other Supported Drivers

pdo_mysql - MySQL (default)
pdo_pgsql - PostgreSQL
pdo_sqlite - SQLite
pdo_sqlsrv - Microsoft SQL Server
pdo_oci - Oracle

Entity Mapping

In order for Doctrine to know which classes are entities and which application logic, it is necessary to set up a mapping.

Configuration

For mapping, it is necessary to set the introductory part of the namespace entities and the directory where they occur:

orm.annotations:
    paths:
        App\Baraja\Entity: %rootDir%/app/model/Entity

Excluding Paths

You can exclude specific directories from scanning:

orm.annotations:
    excludePaths:
        - %rootDir%/app/model/Entity/Deprecated

Ignoring Annotations

Custom annotations can be ignored:

orm.annotations:
    ignore:
        - myCustomAnnotation

Cache Configuration

Configure the annotation cache driver:

orm.annotations:
    defaultCache: filesystem  # Options: apcu, array, filesystem
    debug: false              # Enable for development

Important warning:

The value of the %rootDir%, %appDir%, %wwwDir%, %vendorDir% and %tempDir% parameters may be corrupted when running schema generation in CLI mode. To resolve this mistake, please install Package Manager and call the command as a composer dump.

Entity Identifiers

The package provides several traits for entity identification. Insert one trait to define the ID in your entities:

Auto-increment Integer

<?php

declare(strict_types=1);

namespace App\Entity;

use Baraja\Doctrine\Identifier\Identifier;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
class Article
{
    use Identifier;

    #[ORM\Column(type: 'string')]
    private string $title;
}

UUID (String)

<?php

declare(strict_types=1);

namespace App\Entity;

use Baraja\Doctrine\UUID\UuidIdentifier;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
class User
{
    use UuidIdentifier;

    #[ORM\Column(type: 'string')]
    private string $email;
}

UUID Binary (High Performance)

For better performance, use binary UUID storage:

<?php

declare(strict_types=1);

namespace App\Entity;

use Baraja\Doctrine\UUID\UuidBinaryIdentifier;
use Doctrine\ORM\Mapping as ORM;

#[ORM\Entity]
class Product
{
    use UuidBinaryIdentifier;

    #[ORM\Column(type: 'string')]
    private string $name;
}

UUID will be generated automatically in PHP using the Ramsey UUID library.

TIP: Read more about UUID binary performance (Czech language)

Generate Database Structure from Entities

This package implements a bridge to automatically execute Doctrine commands.

Update Schema

php www/index.php o:s:u -f --dump-sql

The command o:s:u means orm:schema-tool:update.

Options:

-f or --force - Execute changes in SQL
--dump-sql - Renders the list of SQL commands that will be executed

Validate Schema

php www/index.php o:v

Available Commands

| Command | Description | |---------|-------------| | orm:schema-tool:create | Create database schema | |

Doctrine

Install / Use

README

Baraja Doctrine Database

Key Features

Architecture Overview

Main Components

DI Extensions

Core Services

Identifier Traits

Custom DQL Functions

Caching Providers

📦 Installation

Requirements

Configuration

Basic Database Connection

Connection Options

Environment Variable Support

⚙️ Drivers

PostgreSQL

Other Supported Drivers

Entity Mapping

Configuration

Excluding Paths

Ignoring Annotations

Cache Configuration

Entity Identifiers

Auto-increment Integer

UUID (String)

UUID Binary (High Performance)

Generate Database Structure from Entities

Update Schema

Validate Schema

Available Commands