README

A modernized fork of the original FluentPDO project, updated for PHP 8.1+ with modern type declarations and enhanced features.

FluentPDO is a PHP SQL query builder using PDO. It's a quick and light library featuring a smart join builder, which automatically creates table joins for you.

About This Fork

This is a modernized fork of the original envms/fluentpdo project. Since the original project has been inactive for 3+ years (last commit in 2021), this fork provides:

PHP 8.1+ compatibility with modern type declarations
Strict typing throughout the codebase
Union types and mixed types where appropriate
Typed properties for better IDE support
Array parameter handling with automatic JSON serialization
Enhanced error handling and debugging capabilities
Updated dependencies and development tools

Features

Easy interface for creating robust queries
Supports any database compatible with PDO
Ability to build complex SELECT, INSERT, UPDATE & DELETE queries with little code
Type hinting for magic methods with code completion in smart IDEs

PHP Version Requirements

This fork requires PHP 8.1 or higher.

What's New in This PHP 8.1+ Edition

Modern Type System: Full use of PHP 8.1+ type declarations including union types
Strict Types: All files use declare(strict_types=1) for better type safety
Array Handling: Automatic JSON serialization of array parameters to prevent SQL errors
Enhanced Performance: Better memory usage and performance through strict typing
Developer Experience: Improved IDE support with proper type hints and autocomplete
Future Ready: Prepared for upcoming PHP versions

Migrating from Original FluentPDO

If you're upgrading from the original FluentPDO (v2.x), this version maintains API compatibility while requiring PHP 8.1+. The main changes are internal improvements and type safety enhancements.

Reference

Sitepoint - Getting Started with FluentPDO

Installation

Composer

The preferred way to install this PHP 8.1+ edition of FluentPDO is via composer.

composer require vitexsoftware/fluentpdo

Or add the following line in your composer.json file:

{
    "require": {
        "vitexsoftware/fluentpdo": "^3.0"
    }
}

Then run composer update and you're done!

Requirements

PHP 8.1+ (required)
PDO extension (required)
Any PDO-compatible database (MySQL, PostgreSQL, SQLite, etc.)

Getting Started

Create a new PDO instance, and pass the instance to FluentPDO:

<?php
declare(strict_types=1);

use Envms\FluentPDO\Query;

$pdo = new PDO('mysql:dbname=fluentdb', 'user', 'password');
$fluent = new Query($pdo);

Then, creating queries is quick and easy:

$query = $fluent->from('comment')
             ->where('article.published_at > ?', $date)
             ->orderBy('published_at DESC')
             ->limit(5);

which would build the query below:

SELECT comment.*
FROM comment
LEFT JOIN article ON article.id = comment.article_id
WHERE article.published_at > ?
ORDER BY article.published_at DESC
LIMIT 5

To get data from the select, all we do is loop through the returned array:

foreach ($query as $row) {
    echo "$row['title']\n";
}

Using the Smart Join Builder

Let's start with a traditional join, below:

$query = $fluent->from('article')
             ->leftJoin('user ON user.id = article.user_id')
             ->select('user.name');

That's pretty verbose, and not very smart. If your tables use proper primary and foreign key names, you can shorten the above to:

$query = $fluent->from('article')
             ->leftJoin('user')
             ->select('user.name');

That's better, but not ideal. However, it would be even easier to not write any joins:

$query = $fluent->from('article')
             ->select('user.name');

Awesome, right? FluentPDO is able to build the join for you, by you prepending the foreign table name to the requested column.

All three snippets above will create the exact same query:

SELECT article.*, user.name 
FROM article 
LEFT JOIN user ON user.id = article.user_id

Close your connection

Finally, it's always a good idea to free resources as soon as they are done with their duties:

$fluent->close();

CRUD Query Examples

SELECT

$query = $fluent->from('article')->where('id', 1)->fetch();
$query = $fluent->from('user', 1)->fetch(); // shorter version if selecting one row by primary key

INSERT

$values = array('title' => 'article 1', 'content' => 'content 1');

$query = $fluent->insertInto('article')->values($values)->execute();
$query = $fluent->insertInto('article', $values)->execute(); // shorter version

UPDATE

use Envms\FluentPDO\Literal;

$set = ['published_at' => new Literal('NOW()')];

$query = $fluent->update('article')->set($set)->where('id', 1)->execute();
$query = $fluent->update('article', $set, 1)->execute(); // shorter version if updating one row by primary key

DELETE

$query = $fluent->deleteFrom('article')->where('id', 1)->execute();
$query = $fluent->deleteFrom('article', 1)->execute(); // shorter version if deleting one row by primary key

Note: INSERT, UPDATE and DELETE queries will only run after you call ->execute()

Modern PHP 8.1+ Features

Array Parameter Handling

This edition automatically handles array parameters by converting them to JSON strings:

// Arrays are automatically converted to JSON
$data = [
    'name' => 'John Doe',
    'tags' => ['php', 'mysql', 'programming'],  // Automatically converts to JSON
    'metadata' => ['created' => '2025-01-01', 'active' => true]
];

$fluent->insertInto('users', $data)->execute();

Strict Type Declarations

All classes use strict typing for better performance and error detection:

<?php
declare(strict_types=1);

// Your code here...

Enhanced IDE Support

With full type declarations, you get better autocomplete and error detection in modern IDEs.

Credits

Original FluentPDO: envms/fluentpdo by envms
PHP 8.1+ Modernization: VitexSoftware

License

Free for commercial and non-commercial use under the Apache 2.0 or GPL 2.0 licenses.

vitexsoftware / fluentpdo

Maintainers

Details