miniflux-legacy/vendor/fguillot/picodb/README.md

563 lines
9.0 KiB
Markdown
Raw Normal View History

PicoDb
======
PicoDb is a minimalist database query builder for PHP.
2015-08-15 03:33:39 +02:00
[![Build Status](https://travis-ci.org/fguillot/picoDb.svg?branch=master)](https://travis-ci.org/fguillot/picoDb)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/fguillot/picoDb/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/fguillot/picoDb/?branch=master)
Features
--------
2015-01-28 02:13:16 +01:00
- Easy to use, easy to hack, fast and very lightweight
- Supported drivers: Sqlite, Mysql, Postgresql
- Requires only PDO
- Use prepared statements
2015-08-15 03:33:39 +02:00
- Handle schema migrations
- Fully unit tested on PHP 5.3, 5.4, 5.5, 5.6 and 7.0
2015-06-21 15:56:36 +02:00
- License: MIT
Requirements
------------
- PHP >= 5.3
2015-08-15 03:33:39 +02:00
- PDO extension
- Sqlite or Mysql or Postgresql
Author
------
Frédéric Guillot
Documentation
-------------
### Installation
```bash
2015-01-28 02:13:16 +01:00
composer require fguillot/picodb @stable
```
2015-08-15 03:33:39 +02:00
### Database connection
Sqlite:
```php
2015-01-28 02:13:16 +01:00
use PicoDb\Database;
// Sqlite driver
$db = new Database(['driver' => 'sqlite', 'filename' => ':memory:']);
2015-08-15 03:33:39 +02:00
```
2015-01-28 02:13:16 +01:00
2015-08-15 03:33:39 +02:00
The Sqlite driver enable foreign keys by default.
Mysql:
```php
// Optional attributes:
// "charset"
// "schema_table" (the default table name is "schema_version")
// "port"
$db = new Database([
2015-01-28 02:13:16 +01:00
'driver' => 'mysql',
'hostname' => 'localhost',
'username' => 'root',
'password' => '',
'database' => 'my_db_name',
2015-08-15 03:33:39 +02:00
]);
```
Postgres:
```php
// Optional attributes:
// "schema_table" (the default table name is "schema_version")
// "port"
$db = new Database([
'driver' => 'postgres',
'hostname' => 'localhost',
'username' => 'root',
'password' => '',
'database' => 'my_db_name',
]);
```
2015-08-15 03:33:39 +02:00
### Execute any SQL query
```php
2015-08-15 03:33:39 +02:00
$db->execute('CREATE TABLE mytable (column1 TEXT)');
```
2015-08-15 03:33:39 +02:00
- Returns a `PDOStatement` if successful
- Returns `false` if there is a duplicate key error
- Throws a `SQLException` for other errors
### Insertion
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')->save(['column1' => 'test']);
```
2015-01-28 02:13:16 +01:00
or
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')->insert(['column1' => 'test']);
```
### Fetch last inserted id
```php
$db->getLastId();
2015-01-28 02:13:16 +01:00
```
### Transactions
```php
$db->transaction(function ($db) {
2015-08-15 03:33:39 +02:00
$db->table('mytable')->save(['column1' => 'foo']);
$db->table('mytable')->save(['column1' => 'bar']);
2015-01-28 02:13:16 +01:00
});
```
2015-08-15 03:33:39 +02:00
- Returns `true` if the callback returns null
- Returns the callback return value otherwise
- Throws an SQLException if something is wrong
2015-01-28 02:13:16 +01:00
or
```php
2015-01-28 02:13:16 +01:00
$db->startTransaction();
// Do something...
$db->closeTransaction();
// Rollback
$db->cancelTransaction();
```
### Fetch all data
```php
2015-08-15 03:33:39 +02:00
$records = $db->table('mytable')->findAll();
2015-01-28 02:13:16 +01:00
foreach ($records as $record) {
var_dump($record['column1']);
}
```
2015-08-15 03:33:39 +02:00
### Updates
2015-01-28 02:13:16 +01:00
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')->eq('id', 1)->save(['column1' => 'hey']);
2015-01-28 02:13:16 +01:00
```
2015-08-15 03:33:39 +02:00
or
```php
$db->table('mytable')->eq('id', 1)->update(['column1' => 'hey']);
```
2015-08-15 03:33:39 +02:00
### Remove records
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')->lt('column1', 10)->remove();
```
### Sorting
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')->asc('column1')->findAll();
```
or
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')->desc('column1')->findAll();
2015-01-28 02:13:16 +01:00
```
2015-06-21 15:56:36 +02:00
or
2015-01-28 02:13:16 +01:00
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')->orderBy('column1', 'ASC')->findAll();
```
Multiple sorting:
```php
$db->table('mytable')->asc('column1')->desc('column2')->findAll();
```
### Limit and offset
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')->limit(10)->offset(5)->findAll();
```
### Fetch only some columns
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')->columns('column1', 'column2')->findAll();
2015-01-28 02:13:16 +01:00
```
### Fetch only one column
Many rows:
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')->findAllByColumn('column1');
2015-01-28 02:13:16 +01:00
```
One row:
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')->findOneColumn('column1');
```
2015-08-15 03:33:39 +02:00
### Custom select
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')->select(1)->eq('id', 42)->findOne();
```
### Distinct
```php
$db->table('mytable')->distinct('columnA')->findOne();
```
### Group by
```php
$db->table('mytable')->groupBy('columnA')->findAll();
```
### Count
```php
$db->table('mytable')->count();
```
### Sum
```php
$db->table('mytable')->sum('columnB');
```
### Sum column values during update
Add the value 42 to the existing value of the column "mycolumn":
```php
$db->table('mytable')->sumColumn('mycolumn', 42)->update();
```
### Exists
Returns true if a record exists otherwise false.
```php
$db->table('mytable')->eq('column1', 12)->exists();
```
### Left joins
```php
// SELECT * FROM mytable LEFT JOIN my_other_table AS t1 ON t1.id=mytable.foreign_key
$db->table('mytable')->left('my_other_table', 't1', 'id', 'mytable', 'foreign_key')->findAll();
```
or
```php
2015-08-15 03:33:39 +02:00
// SELECT * FROM mytable LEFT JOIN my_other_table ON my_other_table.id=mytable.foreign_key
$db->table('mytable')->join('my_other_table', 'id', 'foreign_key')->findAll();
```
### Equals condition
```php
$db->table('mytable')
2015-01-28 02:13:16 +01:00
->eq('column1', 'hey')
->findAll();
```
### IN condition
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')
2015-01-28 02:13:16 +01:00
->in('column1', ['hey', 'bla'])
->findAll();
```
### Like condition
Case-sensitive (only Mysql and Postgres):
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')
2015-01-28 02:13:16 +01:00
->like('column1', '%Foo%')
->findAll();
```
Not case-sensitive:
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')
2015-01-28 02:13:16 +01:00
->ilike('column1', '%foo%')
->findAll();
```
2015-08-15 03:33:39 +02:00
### Lower than condition
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')
2015-01-28 02:13:16 +01:00
->lt('column1', 2)
->findAll();
```
2015-08-15 03:33:39 +02:00
### Lower than or equal condition
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')
2015-01-28 02:13:16 +01:00
->lte('column1', 2)
->findAll();
```
2015-08-15 03:33:39 +02:00
### Greater than condition
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')
->gt('column1', 3)
2015-01-28 02:13:16 +01:00
->findAll();
```
2015-08-15 03:33:39 +02:00
### Greater than or equal condition
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')
->gte('column1', 3)
->findAll();
```
2015-08-15 03:33:39 +02:00
### IS NULL condition
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')
->isNull('column1')
2015-01-28 02:13:16 +01:00
->findAll();
```
2015-08-15 03:33:39 +02:00
### IS NOT NULL condition
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')
->notNull('column1')
->findAll();
```
### Multiple conditions
2015-08-15 03:33:39 +02:00
Add conditions are joined by a `AND`.
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')
->like('column2', '%mytable')
2015-01-28 02:13:16 +01:00
->gte('column1', 3)
->findAll();
```
How to make a OR condition:
```php
2015-08-15 03:33:39 +02:00
$db->table('mytable')
2015-01-28 02:13:16 +01:00
->beginOr()
2015-08-15 03:33:39 +02:00
->like('column2', '%mytable')
2015-01-28 02:13:16 +01:00
->gte('column1', 3)
->closeOr()
->eq('column5', 'titi')
->findAll();
```
### Debugging
Log generated queries:
```php
2015-08-15 03:33:39 +02:00
$db->logQueries = true;
2015-01-28 02:13:16 +01:00
```
Mesure each query time:
```php
$db->stopwatch = true;
```
Get the number of queries executed:
```php
2015-08-15 03:33:39 +02:00
echo $db->nbQueries;
2015-01-28 02:13:16 +01:00
```
Get log messages:
```php
print_r($db->getLogMessages());
```
### Hashtable (key/value store)
How to use a table as a key/value store:
```php
$db->execute(
2015-08-15 03:33:39 +02:00
'CREATE TABLE mytable (
2015-01-28 02:13:16 +01:00
column1 TEXT NOT NULL UNIQUE,
column2 TEXT default NULL
)'
);
2015-08-15 03:33:39 +02:00
$db->table('mytable')->insert(['column1' => 'option1', 'column2' => 'value1']);
2015-01-28 02:13:16 +01:00
```
Add/Replace some values:
```php
2015-08-15 03:33:39 +02:00
$db->hashtable('mytable')
2015-01-28 02:13:16 +01:00
->columnKey('column1')
->columnValue('column2')
->put(['option1' => 'new value', 'option2' => 'value2']));
```
Get all values:
```php
2015-08-15 03:33:39 +02:00
$result = $db->hashtable('mytable')->columnKey('column1')->columnValue('column2')->get();
2015-01-28 02:13:16 +01:00
print_r($result);
Array
(
[option2] => value2
[option1] => new value
)
```
or
```php
2015-08-15 03:33:39 +02:00
$result = $db->hashtable('mytable')->getAll('column1', 'column2');
2015-01-28 02:13:16 +01:00
```
Get a specific value:
```php
2015-08-15 03:33:39 +02:00
$db->hashtable('mytable')
2015-01-28 02:13:16 +01:00
->columnKey('column1')
->columnValue('column2')
->put(['option3' => 'value3']);
2015-08-15 03:33:39 +02:00
$result = $db->hashtable('mytable')
2015-01-28 02:13:16 +01:00
->columnKey('column1')
->columnValue('column2')
->get('option1', 'option3');
print_r($result);
Array
(
[option1] => new value
[option3] => value3
)
```
### Schema migrations
#### Define a migration
- Migrations are defined in simple functions inside a namespace named "Schema".
- An instance of PDO is passed to first argument of the function.
- Function names has the version number at the end.
Example:
```php
2015-01-28 02:13:16 +01:00
namespace Schema;
function version_1($pdo)
{
$pdo->exec('
CREATE TABLE users (
id INTEGER PRIMARY KEY,
name TEXT UNIQUE,
email TEXT UNIQUE,
password TEXT
)
');
}
function version_2($pdo)
{
$pdo->exec('
CREATE TABLE tags (
id INTEGER PRIMARY KEY,
name TEXT UNIQUE
)
');
}
```
#### Run schema update automatically
2015-08-15 03:33:39 +02:00
- The method `check()` execute all migrations until the version specified
- If an error occurs, the transaction is rollbacked
- Foreign keys checks are disabled if possible during the migration
Example:
```php
2015-01-28 02:13:16 +01:00
$last_schema_version = 5;
2015-01-28 02:13:16 +01:00
$db = new PicoDb\Database(array(
'driver' => 'sqlite',
'filename' => '/tmp/mydb.sqlite'
));
2015-01-28 02:13:16 +01:00
if ($db->schema()->check($last_schema_version)) {
2015-01-28 02:13:16 +01:00
// Do something...
}
else {
2015-01-28 02:13:16 +01:00
die('Unable to migrate database schema.');
}
```
### Use a singleton to handle database instances
Setup a new instance:
```php
2015-08-15 03:33:39 +02:00
PicoDb\Database::setInstance('myinstance', function() {
2015-01-28 02:13:16 +01:00
$db = new PicoDb\Database(array(
'driver' => 'sqlite',
'filename' => DB_FILENAME
));
2015-01-28 02:13:16 +01:00
if ($db->schema()->check(DB_VERSION)) {
return $db;
}
else {
die('Unable to migrate database schema.');
}
});
```
Get this instance anywhere in your code:
```php
2015-08-15 03:33:39 +02:00
PicoDb\Database::getInstance('myinstance')->table(...)
2015-01-28 02:13:16 +01:00
```