iamludal / mysql-querybuilder

🔧 A simple PHP query builder for MySQL queries.

🔧 MySQL QueryBuilder

composer require ludal/mysql-querybuilder

ℹ️ Presentation

This is a PHP query builder for simple MySQL queries. It allows you to write them without using strings nor heredoc, which often breaks the code's cleanliness.

This package is designed to support MySQL DBMS. However, it may work with other DBMS (PostgreSQL, SQLite...), but I cannot guarantee that, so use it at your own risk.

💡 Made with ❤️ in 🇫🇷

📘 Usage

Getting Started

First, initialize a new instance of QueryBuilder.

$builder = new QueryBuilder();

💡 You can also pass a PDO instance as a parameter to execute and fetch queries directly.

$pdo = new PDO($dsn, $login, $password);
$builder = new QueryBuilder($pdo);

From this instance, you can now build your query:

$select = $builder
  ->select()
  ->from('users')
  ->where('name = :name');

$update = $builder
  ->update('users')
  ->set(['name' => 'John'])
  ->where('id = 6');

Then, you can either:

• Convert your query into a SQL string : toSQL()
• Bind parameters: setParam('name', 'John'), setParams(['name' => 'John'])...
• Execute the query : execute(), execute(['John'])...
• Fetch the results of your query : fetch(), fetchAll(), fetch(PDO::FETCH_COLUMN)...
• Get the rowCount : rowCount()
• Get the PDO statement corresponding to your query : getStatement()
• And more: see docs for a full reference

$select->toSQL(); // returns 'SELECT * FROM users'

$select->fetchAll(); // returns the rows fetched from the db

$select->getStatement(); // get the PDO statement, useful for handling errors

$update->execute(); // executes the UPDATE query

Supported Statements

• SELECT
• UPDATE
• DELETE FROM
• INSERT INTO

Supported Clauses

• WHERE
• GROUP BY
• ORDER BY
• LIMIT
• OFFSET

Code Samples

$pdo = new PDO(...);
$qb = new QueryBuilder($pdo);

QueryBuilder::setDefaultFetchMode(PDO::FETCH_ASSOC);

// SELECT
$res = $qb
  ->select()
  ->from('users')
  ->where('id < 4', 'name = :name')
  ->orWhere('age < 12')
  ->orderBy('id', 'desc')
  ->limit(2)
  ->offset(1)
  ->fetchAll();

// INSERT
$insert = $qb
  ->insertInto('articles')
  ->values(['title' => 'Lorem ipsum', 'content' => 'Some content'])
  ->getStatement(); 

$insert->execute();
$insert->errorCode(); // or any other PDOStatement method

// UPDATE
$updated = $qb
  ->update('connections')
  ->set(['exp' => true, 'date' => date('Y-m-d')])
  ->where(['token' => $token])
  ->orderBy('date')
  ->limit(1)
  ->execute();

// DELETE
$rowCount = $qb
  ->deleteFrom('users')
  ->where('id > 5')
  ->orWhere('name = :name')
  ->orderBy('id', 'desc')
  ->limit(10)
  ->setParam(':name', 'John')
  ->rowCount(); // will execute, and return the rowCount

📖 Docs

Wiki under construction. 🚧

🙏 Acknowledgements

• Vincent Aranega for tips and tricks about the code organization

mysql-querybuilder's Issues

Add Wiki documentation

Add complete documentation to the Wiki

setParams using compact()

setParams(compat('name', 'address'))

1. Check if the param starts with :. If not, then add :.

Add `DELETE ... ORDER BY ... LIMIT`

See #15 and https://dev.mysql.com/doc/refman/8.0/en/delete.html
Use OrderBy and Limit traits

Add contributing template

Add a CONTRIBUTING.md file to indicate how to contribute to the project

Add a security paragraph in README

Add a security paragraph to inform that when using the array notation, it is protected against SQL injections

['name' => 'Ludal'] // Becomes: 'name = :_name'

Add backticks to table and column names

Ex:

SELECT `id` FROM `users`

No bug detected for now, but just to be sure to prevent conflicting with predefined functions or whatever.

Add `HAVING` to `GroupBy` trait

Add `INSERT INTO ... SELECT`

See https://dev.mysql.com/doc/refman/8.0/en/insert.html
Use the existing Select statement

Add `UPDATE ... ORDER BY ... LIMIT`

See https://dev.mysql.com/doc/refman/8.0/en/update.html
Use OrderBy and Limit traits (create them if they don't exist yet)

OrderBy: add ASC and DESC constants

Example:

->orderBy('id', OrderBy::ASC)

Where conditions as associative array

$builder
  ->select()
  ->from('table')
  ->where(['id' => 5])

`orderBy` as associative array

Replace the orderBy method signature to receive an associative array as an argument.

Example:

$this->builder
 ->select('*')
 ->from('users')
 ->orderBy(['name' => 'asc', 'id' => 'desc', 'age'])
 ->toSQL();

This would produce the following SQL:

SELECT * FROM users ORDER BY name ASC, id DESC, age ASC;

Support for other DBMS

• PostgreSQL
• MySQL
• SQLite
• Oracle

Param overriding value of another param with same name

Describe the bug
Parameter overriing the value of the previously set param (that has the same name)

To Reproduce

$id = 'old_id';
$values = ['id' => 'new_id'];

$builder
  ->update('users')
  ->set($values)
  ->where('id = :id')
  ->setParam(':id', $id); // will replace 'new_id' by 'old_id'

Expected behavior
One should be able to set any value with setParam without overriding the value of another param (that has the same name) from set().

Possible fix
Just add padding chars in set() method (eg: :_id instead of :id)

Add `JOIN` clause

Ideas of usage:

->select('*')
->from('users u')
->join('profile p', ['u.id = p.userId']) 

join($table, $conditions)

getStatement() after query to get PDO statement

In order to be able to manage errorCode, errorInfo, etc...

Tests inheritance

ClauseTest: don't have to run on itself, only through subclasses.

Add `GROUP BY` clause

For the Select Clause

groupBy('id')

https://www.w3schools.com/sql/sql_groupby.asp

Autocomplete after "where"

Describe the bug
Autocomplete is broken after using where clause. This is because of the new WhereClause class.

Add RETURNING clause

$query->update(...)->returning('id', $var)->fetch()

https://dzone.com/articles/use-returning-clause-to-avoid-unnecessary-sql-stat