PHP Classes

File: README.md

Recommend this page to a friend!
  Classes of Lars Moelleken  >  Simple Active Record  >  README.md  >  Download  
File: README.md
Role: Documentation
Content type: text/markdown
Description: Documentation
Class: Simple Active Record
Store and fetch data with Active Records pattern
Author: By
Last change:
Date: 1 year ago
Size: 12,054 bytes
 

Contents

Class file image Download

Build Status Coverage Status Codacy Badge Latest Stable Version Total Downloads License

:ring: 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 :gem: "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

  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() : boolean|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) : boolean|\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')->order('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
  
  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() : boolean|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() : boolean

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();

group()

This function can set the "group by" conditions.

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

order()

This function can set the "order by" conditions.

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

limit()

This function can set the "limit" conditions.

  $user = new User();
  $user->order('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   $contact
 */
class User extends ActiveRecord {
  public $table = 'user';
  public $primaryKey = 'id';
  
  public $relations = [
    // format is [$relation_type, $child_namespaced_classname, $foreign_key_of_child]
    'contacts' => [
      self::HAS_MANY, 
      'demo\Contact', 
      'user_id'
    ],
    'contacts_with_backref' => [
        self::HAS_MANY,
        'demo\Contact',
        'user_id',
        null,
        'user',
    ],
    // format may be [$relation_type, $child_namespaced_classname, $foreign_key_of_child, $array_of_sql_part_functions]
    'contact' => [
      self::HAS_ONE, 
      'demo\Contact', 
      'user_id', 
      [
        'where' => '1', 
        'order' => 'id desc',
      ],
    ],
  ];
}

/
 * @property int    $id
 * @property int    $user_id
 * @property string $email
 * @property string $address
 * @property User   $user
 */
class Contact extends ActiveRecord {
  public $table = 'contact';
  public $primaryKey = 'id';
  
  public $relations = [
    // format is [$relation_type, $parent_namespaced_classname, $foreign_key_in_current_table]
    'user' => [
      self::BELONGS_TO, 
      'demo\User', 
      '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.


For more information send a message to info at phpclasses dot org.