Download the PHP package scienta/doctrine-json-functions without Composer

DoctrineJsonFunctions

A set of extensions to Doctrine ORM that add support for JSON functions in DQL (Doctrine Query Language). Supports MySQL, MariaDB, PostgreSQL, SQLite, and SQL Server.

Overview

Doctrine ORM does not natively support database-specific JSON functions in DQL. This library bridges that gap by registering custom DQL function nodes for each supported platform. Each function validates at SQL generation time that the correct database platform is in use, so you get an early error if a function is used against the wrong database.

Supported Platforms and Functions

Table of Contents

• Requirements
• Installation
• Testing
• Registration
  • Doctrine ORM
  • Symfony with DoctrineBundle
• Usage
  • MySQL / MariaDB
  • PostgreSQL
  • SQLite
  • SQL Server
• DQL Function Reference
  • MySQL 5.7+ and MariaDB (shared)
  • MySQL 8.0.21+ only
  • MariaDB only
  • PostgreSQL 9.3+
  • SQLite json1 extension
  • SQL Server 2016+
• Architecture
• Extending the Library
  • Adding a new function
  • Adding a new platform
• Changelog
• See Also

Requirements

• PHP 8.1+
• doctrine/orm: ^2.19 or ^3
• doctrine/dbal: ^3.2 or ^4
• doctrine/lexer: ^2.0 or ^3.0

Installation

Install via Composer:

Testing

This repository uses PHPUnit. There are two test suites:

• Unit tests — mock the Doctrine infrastructure, no real database needed
• Integration tests — run DQL queries against real MySQL, MariaDB, PostgreSQL, and SQLite databases

Unit tests

Or with Docker Compose (PHP 8.4):

Code coverage

The Docker image includes the PCOV extension. Run the unit tests with Clover coverage output:

This writes coverage.xml to the project root. Coverage is also reported automatically on every PR and push to master via the Coverage workflow.

Integration test coverage

PCOV is available inside the container. Start the database services first, then run:

This writes coverage-integration.xml to the project root. Integration coverage is also reported automatically on every PR alongside unit coverage.

Integration tests

Start the database containers, then run the tests inside the PHP container:

Run a single platform:

Running locally without Docker: copy .env.dist to .env, fill in your connection URLs, then:

SQLite always runs in-memory and needs no configuration.

Registration

All functions must be registered as custom string functions in the Doctrine configuration before they can be used in DQL. Each function class exposes a FUNCTION_NAME constant that matches the DQL keyword you use in queries.

Note on boolean functions: Doctrine DQL does not have a native boolean function type (upstream issue). Register boolean-returning functions (e.g., JSONB_CONTAINS, JSON_CONTAINS) as string_functions and compare them explicitly with = true or = 1 in your DQL to avoid parser errors.

Doctrine ORM

Symfony with DoctrineBundle

Usage

Use the registered DQL function names directly in your DQL queries or query builders. JSON path expressions must use single-quoted strings in DQL (not double-quoted).

MySQL / MariaDB

PostgreSQL

PostgreSQL operators (->, ->>, @>, ?, etc.) are exposed as named DQL functions because Doctrine DQL does not support custom operators.

PostgreSQL operator chaining (e.g., col->'a'->'b') is not supported. Use JSON_GET_PATH (works on both json and jsonb) or JSON_EXTRACT_PATH (json columns only) instead.

SQLite

SQL Server

To apply type conversion, use CAST outside the function: CAST(JSON_VALUE(c.attributes, '$.score') AS DECIMAL(4,2))

DQL Function Reference

MySQL 5.7+ and MariaDB (shared)

All functions in the Scienta\DoctrineJsonFunctions\Query\AST\Functions\Mysql namespace unless noted. Functions marked as shared also work on MariaDB (they are registered under the MySQL namespace but validate against AbstractMySQLPlatform / MariaDBPlatform).

MySQL functions that also apply to MariaDB use MysqlAndMariadbJsonFunctionNode as their base, which validates against AbstractMySQLPlatform (DBAL 3.3+) or MySQLPlatform (older DBAL).

MySQL 8.0.21+ only

This function uses MysqlJsonFunctionNode and only works on MySQL (not MariaDB).

MariaDB only

Namespace: Scienta\DoctrineJsonFunctions\Query\AST\Functions\Mariadb

MySQL operators like JSON_EXTRACT are also available on MariaDB — register them from the Mysql namespace.

PostgreSQL 9.3+

Namespace: Scienta\DoctrineJsonFunctions\Query\AST\Functions\Postgresql

PostgreSQL JSON operators are wrapped as named functions. SQL output uses the native operators.

Boolean functions (JSONB_CONTAINS, JSONB_EXISTS, JSONB_EXISTS_ALL, JSONB_EXISTS_ANY, JSONB_IS_CONTAINED) must be compared with = true due to the Doctrine DQL boolean function limitation:

SQLite json1 extension

Namespace: Scienta\DoctrineJsonFunctions\Query\AST\Functions\Sqlite

SQLite must have the json1 extension enabled (it is compiled in by default since SQLite 3.38.0).

Scalar functions

Aggregate functions

SQL Server 2016+

Namespace: Scienta\DoctrineJsonFunctions\Query\AST\Functions\Mssql

SQL Server does not support inline type conversion inside JSON_VALUE. Use CAST(JSON_VALUE(...) AS type) in your DQL for type conversion.

Architecture

Class Hierarchy

The library uses a layered inheritance model to separate argument parsing (generic) from platform validation (platform-specific):

Each concrete function class only needs to declare:

• FUNCTION_NAME constant — the DQL keyword
• $requiredArgumentTypes — argument types that must be present
• $optionalArgumentTypes — argument types that may optionally be present
• $allowOptionalArgumentRepeat — whether optional args can repeat (variadic)

Argument Types

Naming Convention

Examples:

• Scienta\DoctrineJsonFunctions\Query\AST\Functions\Mysql\JsonExtract
• Scienta\DoctrineJsonFunctions\Query\AST\Functions\Postgresql\JsonbContains
• Scienta\DoctrineJsonFunctions\Query\AST\Functions\Mariadb\JsonCompact

DBAL Version Compatibility

DBALCompatibility is an internal helper that resolves class names that changed between DBAL 3 and DBAL 4:

Extending the Library

Adding a new function

1. Create a class in the appropriate platform namespace extending the platform's base node class.
2. Declare FUNCTION_NAME, $requiredArgumentTypes, $optionalArgumentTypes, and $allowOptionalArgumentRepeat.
3. Override parse() and/or getSqlForArgs() only if the function has non-standard argument syntax.

Example — a simple single-argument MySQL function:

Register it:

Use it in DQL:

Adding a new platform

1. Create a new namespace folder: src/Query/AST/Functions/{PlatformName}/
2. Create a base node class that extends AbstractJsonFunctionNode and implements validatePlatform() to check the correct DatabasePlatform instance.
3. Add platform detection to DBALCompatibility if needed (e.g., when the class name differs between DBAL versions).
4. Implement individual function classes extending your new base.

Example base node:

Changelog

Changes per release are documented in GitHub releases.

See Also

• dunglas/doctrine-json-odm — serialize/deserialize plain PHP objects as JSON columns using Doctrine ORM
• Doctrine DQL User Defined Functions
• MySQL JSON function reference
• PostgreSQL JSON function reference
• MariaDB JSON function reference
• SQLite json1 extension reference