Download the PHP package welshdev/doctrix without Composer

Doctrix

A powerful, flexible query builder library for Doctrine ORM that provides an enhanced array-based criteria system and modern fluent interfaces for building complex queries.

Features

Core Query Features

• ✅ Hybrid Approach - Use via inheritance OR as a service
• ✅ Clean API - Simple fetch() and fetchOne() methods
• ✅ Fluent Interface - Modern, chainable API for building queries
• ✅ Advanced Operators - Support for gte, lte, like, contains, between, etc.
• ✅ Automatic Joins - Detects and applies joins from dot notation
• ✅ Filter Functions - Reusable, named filters
• ✅ Global Scopes - Automatically applied filters (like soft deletes)

Data Operations

• ✅ Pagination - Built-in pagination with metadata and cursor support
• ✅ Bulk Operations - Efficient bulkUpdate() and bulkDelete() without fetching entities
• ✅ Aggregations - count(), sum(), avg(), max(), min()
• ✅ Query Caching - Built-in result caching support

Error Handling & Recovery

• ✅ Fetch or Fail - fetchOneOrFail() with configurable exceptions (throw 404s directly)
• ✅ Fetch or Create - fetchOneOrCreate() and updateOrCreate() patterns
• ✅ Sole Results - sole() ensures exactly one result

Memory-Efficient Processing

• ✅ Chunk Processing - Process large datasets with chunk() and each()
• ✅ Lazy Loading - Generator-based iteration with lazy()
• ✅ Batch Processing - Transaction-wrapped batches with batchProcess()
• ✅ Data Transformation - Transform entities with map()

Existence & Counting

• ✅ Existence Checks - exists(), doesntExist(), isEmpty()
• ✅ Count Checks - hasExactly(), hasAtLeast(), hasAtMost(), hasBetween()
• ✅ Optimized Counting - Check existence without fetching entities

Random Selection

• ✅ Random Entities - random() and randomWhere() with database-specific optimization
• ✅ Weighted Random - weightedRandom() for biased selection
• ✅ Random Distinct - randomDistinct() for unique values

Relationship Management

• ✅ Relationship Checks - has(), doesntHave(), hasCount()
• ✅ Complex Conditions - whereHas(), whereRelation() with nested criteria
• ✅ Eager Loading - withRelations() to prevent N+1 queries
• ✅ Relationship Counts - withCount() for efficient counting

Data Validation & Integrity

• ✅ Uniqueness Checks - isUnique(), ensureUnique(), isUniqueCombination()
• ✅ Duplicate Detection - fetchDuplicates() finds duplicate entries
• ✅ Duplicate Removal - removeDuplicates() with keep strategies
• ✅ Entity Validation - validate() with rule-based validation

Advanced Features

• ✅ Persistent Filters - Filters that survive across paginate() and other operations
• ✅ Request Queries - Build secure queries from HTTP requests with validation
• ✅ Macros - Register reusable custom query methods
• ✅ Query Debugging - See SQL, parameters, execution plan, and timing
• ✅ Works with ANY Repository - Enhance existing/legacy repositories

Installation

Install via Composer:

Quick Start

Option 1: Inheritance (Simple & Clean)

Option 2: Service Approach (Flexible & Testable)

Basic Usage

Array-Based Criteria

Fluent Interface

Pagination

Available Operators

Comparison

• =, eq - Equals
• !=, neq - Not equals
• <, lt - Less than
• <=, lte - Less than or equal
• >, gt - Greater than
• >=, gte - Greater than or equal

Text

• like - SQL LIKE
• not_like - SQL NOT LIKE
• contains - Contains substring
• starts_with - Starts with string
• ends_with - Ends with string

Null Checks

• is_null - Check for NULL
• is_not_null - Check for NOT NULL

Collections

• in - IN clause
• not_in - NOT IN clause
• between - BETWEEN clause
• not_between - NOT BETWEEN clause

Logical

• or - OR conditions
• and - AND conditions (default)
• not - NOT condition

Advanced Features

Named Filters (One-Time Application)

Named filters are pre-defined, reusable query modifications that are applied once per query:

Note: Named filters are cleared after each query execution. For filters that need to persist across operations like pagination (where count() and fetch() are called separately), use Persistent Filters instead (see below).

Global Scopes

Query Caching

Aggregations

Bulk Operations

Persistent Filters

Persistent filters allow you to apply filters that remain active across multiple query operations, especially useful with pagination where count() and fetch() are called separately.

Convention-Based Filter Application

The PersistentFiltersTrait uses a naming convention to automatically find and apply filter methods:

1. Call withFilter('filterName', $value) to register a filter
2. Define applyFilterNameFilter(QueryBuilder $qb, $value) to handle the filter
3. The trait automatically calls your method when building queries

Complex Filter Example

Macros (Custom Query Methods)

Query Debugging

Request-Based Queries

Quick Method Reference

Fetching Data

Checking Existence

Processing Large Datasets

Working with Relationships

Data Validation

Random Selection

Using Traits

Mix and match traits for additional functionality: