README

💍 Simple Active Record

This is a simple Active Record Pattern compatible with PHP 7+ that provides a simple and secure interaction with your database using 💎 "Simple MySQLi" at its core. This is perfect for small scale applications such as cron jobs, facebook canvas campaigns or micro frameworks or sites.

Get "Simple Active Record"

You can download it from here, or require it using composer.

  {
      "require": {
        "voku/simple-active-record": "1.*"
      }
  }

Install via "composer require"

  composer require voku/simple-active-record

Starting the driver
Multiton && Singleton
Doctrine/DBAL as parent driver
Using the "ActiveRecord"-Class (OOP database-access)
Logging and Errors
Changelog

Starting the driver

  use voku\db\DB;

  require_once 'composer/autoload.php';

  $db = DB::getInstance('yourDbHost', 'yourDbUser', 'yourDbPassword', 'yourDbName');
  
  // example
  // $db = DB::getInstance('localhost', 'root', '', 'test');

Multiton && Singleton

You can use DB::getInstance() without any parameters and you will get your (as "singleton") first initialized connection. Or you can change the parameter and you will create an new "multiton"-instance which works like an singleton, but you need to use the same parameters again, otherwise (without the same parameter) you will get an new instance.

Doctrine/DBAL as parent driver

  use voku\db\DB;

  require_once 'composer/autoload.php';
  
  $connectionParams = [
      'dbname'   => 'yourDbName',
      'user'     => 'yourDbUser',
      'password' => 'yourDbPassword',
      'host'     => 'yourDbHost',
      'driver'   => 'mysqli', // 'pdo_mysql' || 'mysqli'
      'charset'  => 'utf8mb4',
  ];
  $config = new \Doctrine\DBAL\Configuration();
  $doctrineConnection = \Doctrine\DBAL\DriverManager::getConnection(
      $connectionParams,
      $config
  );
  $doctrineConnection->connect();

  $db = DB::getInstanceDoctrineHelper($doctrineConnection);

Using the "ActiveRecord"-Class (OOP database-access)

A simple implement of active record pattern via Arrayy.

setDb(DB $db)

set the DB connection.

  $db = DB::getInstance('YOUR_MYSQL_SERVER', 'YOUR_MYSQL_USER', 'YOUR_MYSQL_PW', 'YOUR_DATABASE');
  ActiveRecord::setDb($db);

insert() : bool|int

This function can build insert SQL queries and can insert the current record into database. If insert was successful, it will return the new id, otherwise it will return false or true (if there are no dirty data).

  $user = new User();
  $user->name = 'demo';
  $user->password = password_hash('demo', PASSWORD_BCRYPT, ["cost" => 15]);
  $user_id = $user->insert();
  
  var_dump($user_id); // the new id 
  var_dump($user->id); // also the new id 
  var_dump($user->getPrimaryKey()); // also the new id

fetch(integer $id = null) : bool|\ActiveRecord

This function can fetch one record and assign in to current object. If you call this function with the $id parameter, it will fetch records by using the current primary-key-name.

  $user = new User();

  $user->notnull('id')->orderBy('id desc')->fetch();
  
  // OR //
  
  $user->fetch(1);
  
  // OR //
  
  $user->fetchById(1); // thows "FetchingException" if the ID did not exists
  
  // OR //
  
  $user->fetchByIdIfExists(1); // return NULL if the ID did not exists
  
    
  // OR //
  
  $user->fetchByHashId('fsfsdwldasdar'); // thows "FetchingException" if the ID did not exists
  
  // OR //
  
  $user->fetchByHashIdIfExists('fsfsdwldasdar'); // return NULL if the ID did not exists
  
  var_dump($user->id); // (int) 1
  var_dump($user->getPrimaryKey()); // (int) 1

fetchAll() : $this[]

This function can fetch all records in the database and will return an array of ActiveRecord objects.

  $user = new User();

  $users = $user->fetchAll();
  
  // OR //
  
  $users = $user->fetchByIds([1]);
  
  // OR //
  
  $users = $user->fetchByIdsPrimaryKeyAsArrayIndex([1]);
    
  var_dump($users[0]->id) // (int) 1
  var_dump($users[0]->getPrimaryKey()); // (int) 1

update() : bool|int

This function can build update SQL queries and can update the current record in database, just write the dirty data into database. If update was successful, it will return the affected rows as int, otherwise it will return false or true (if there are no dirty data).

  $user = new User();
  $user->notnull('id')->orderBy('id desc')->fetch();
  $user->email = 'test@example.com';
  $user->update();

delete() : bool

This function can delete the current record in the database.

Active Record | SQL part functions

select()

This function can set the select columns.

  $user = new User();
  $user->select('id', 'name')->fetch();

from()

This function can set the table to fetch record from.

  $user = new User();
  $user->select('id', 'name')->from('user')->fetch();

join()

This function can set the table to fetch record from.

  $user = new User();
  $user->join('contact', 'contact.user_id = user.id')->fetch();

where()

This function can set where conditions.

  $user = new User();
  $user->where('id=1 AND name="demo"')->fetch();

groupBy()

This function can set the "group by" conditions.

  $user = new User();
  $user->select('count(1) as count')->groupBy('name')->fetchAll();

orderBy()

This function can set the "order by" conditions.

  $user = new User();
  $user->orderBy('name DESC')->fetch();

limit()

This function can set the "limit" conditions.

  $user = new User();
  $user->orderBy('name DESC')->limit(0, 1)->fetch();

Active Record | WHERE conditions

equal()/eq()

  $user = new User();
  $user->eq('id', 1)->fetch();

notEqual()/ne()

  $user = new User();
  $user->ne('id', 1)->fetch();

greaterThan()/gt()

  $user = new User();
  $user->gt('id', 1)->fetch();

lessThan()/lt()

  $user = new User();
  $user->lt('id', 1)->fetch();

greaterThanOrEqual()/ge()/gte()

  $user = new User();
  $user->ge('id', 1)->fetch();

lessThanOrEqual()/le()/lte()

  $user = new User();
  $user->le('id', 1)->fetch();

like()

  $user = new User();
  $user->like('name', 'de')->fetch();

in()

  $user = new User();
  $user->in('id', [1, 2])->fetch();

notIn()

  $user = new User();
  $user->notin('id', [1, 3])->fetch();

isNull()

  $user = new User();
  $user->isnull('id')->fetch();

isNotNull()/notNull()

  $user = new User();
  $user->isNotNull('id')->fetch();

Active Record | Demo

Include && Init

use voku\db\DB;
use voku\db\ActiveRecord;

require_once 'composer/autoload.php';

$db = DB::getInstance('YOUR_MYSQL_SERVER', 'YOUR_MYSQL_USER', 'YOUR_MYSQL_PW', 'YOUR_DATABASE');
ActiveRecord::setDb($db);

Define Class

namespace demo;

use voku\db\ActiveRecord;

/**
 * @property int       $id
 * @property string    $name
 * @property string    $password
 * @property Contact[] $contacts
 * @property Contact   $contacts_with_backref
 * @property Contact   $contact
 */
class User extends ActiveRecord {
  public $table = 'user';

  public $primaryKey = 'id';
  
  protected function init()
  {
      $this->addRelation(
          'contacts',
          self::HAS_MANY,
          FoobarContact::class,
          'user_id'
      );

      $this->addRelation(
          'contacts_with_backref',
          self::HAS_MANY,
          FoobarContact::class,
          'user_id',
          null,
          'user'
      );

      $this->addRelation(
        'contact',
          self::HAS_ONE,
          FoobarContact::class,
          'user_id',
          [
              self::SQL_WHERE => '1 = 1',
              self::SQL_ORDER => 'id desc',
          ]
      );
  }
}

/**
 * @property int    $id
 * @property int    $user_id
 * @property string $email
 * @property string $address
 * @property User   $user_with_backref
 * @property User   $user
 */
class Contact extends ActiveRecord {
  public $table = 'contact';

  public $primaryKey = 'id';
  
  protected function init()
  {
      $this->addRelation(
          'user_with_backref',
          self::BELONGS_TO,
          FoobarUser::class,
          'user_id',
          null,
          'contact'
      );

      $this->addRelation(
          'user',
          self::BELONGS_TO,
          FoobarUser::class,
          'user_id'
      );
  }
}

Init data (for testing - use migrations for this step, please)

CREATE TABLE IF NOT EXISTS user (
  id INTEGER PRIMARY KEY, 
  name TEXT, 
  password TEXT 
);

CREATE TABLE IF NOT EXISTS contact (
  id INTEGER PRIMARY KEY, 
  user_id INTEGER, 
  email TEXT,
  address TEXT
);

Insert one User into database.

use demo\User;

$user = new User();
$user->name = 'demo';
$user->password = password_hash('demo', PASSWORD_BCRYPT, ["cost" => 15]);
$user_id = $user->insert();

var_dump($user_id); // the new id 
var_dump($user->id); // also the new id 
var_dump($user->getPrimaryKey()); // also the new id

Insert one Contact belongs the current user.

use demo\Contact;

$contact = new Contact();
$contact->address = 'test';
$contact->email = 'test1234456@domain.com';
$contact->user_id = $user->id;

var_dump($contact->insert()); // the new id 
var_dump($contact->id); // also the new id 
var_dump($contact->getPrimaryKey()); // also the new id

Example to using relations

use demo\User;
use demo\Contact;

$user = new User();

// fetch one user
var_dump($user->notnull('id')->orderBy('id desc')->fetch());

echo "\nContact of User # {$user->id}\n";
// get contacts by using relation:
//   'contacts' => [self::HAS_MANY, 'demo\Contact', 'user_id'],
var_dump($user->contacts);

$contact = new Contact();

// fetch one contact
var_dump($contact->fetch());

// get user by using relation:
//    'user' => [self::BELONGS_TO, 'demo\User', 'user_id'],
var_dump($contact->user);

Changelog

See CHANGELOG.md.

Support

For support and donations please visit Github | Issues | PayPal | Patreon.

For status updates and release announcements please visit Releases | Twitter | Patreon.

For professional support please contact me.

Thanks

Thanks to GitHub (Microsoft) for hosting the code and a good infrastructure including Issues-Managment, etc.
Thanks to IntelliJ as they make the best IDEs for PHP and they gave me an open source license for PhpStorm!
Thanks to Travis CI for being the most awesome, easiest continous integration tool out there!
Thanks to StyleCI for the simple but powerfull code style check.
Thanks to PHPStan && Psalm for relly great Static analysis tools and for discover bugs in the code!

voku / simple-active-record

Maintainers

Details