kjdev/php-ext-unqlite

UnQLite Extension for PHP

UnQLite Extension for PHP

This extension allows UnQLite.

Documentation for UnQLite can be found at » http://unqlite.org/.

Dependencies

An Embeddable NoSQL Database Engine.

• UnQLite

json processing is not using the jansson library.

• jansson

Build

% phpize
% ./configure
% make
% make test
% make install

Configration

unqlite.ini:

extension=unqlite.so

Class

Namespace: UnQLite

UnQLite\DB

• UnQLite\DB::__construct — Create database
• UnQLite\DB::close — Close database
• UnQLite\DB::config — Configure a database
• UnQLite\DB::kvs — Create a new key/value store
• UnQLite\DB::doc — Create a new document store

UnQLite\Kvs

• UnQLite\Kvs::__construct — Create a new Key/Value store
• UnQLite\Kvs::store — Saves entry
• UnQLite\Kvs::fetch — Fetch data specified by key
• UnQLite\Kvs::append — Append entry data specified by key
• UnQLite\Kvs::remove — Delete entry specified by key
• UnQLite\Kvs::begin — Manually begin a write-transaction
• UnQLite\Kvs::commit — Commit all changes to the database
• UnQLite\Kvs::rollback — Rollback a write-transaction
• UnQLite\Kvs::cursor — Create a new Key/Value stotre cursor

UnQLite\Kvs\Cursor

• UnQLite\Kvs\Cursor::__construct — Create a new Key/Value stotre cursor
• UnQLite\Kvs\Cursor::first — Advances the cursor to the first
• UnQLite\Kvs\Cursor::last — Advances the cursor to the last
• UnQLite\Kvs\Cursor::next — Advances the cursor to the next
• UnQLite\Kvs\Cursor::prev — Advances the cursor to the prev
• UnQLite\Kvs\Cursor::seek — Seek cursor to key
• UnQLite\Kvs\Cursor::exists — Check whether cursor exists
• UnQLite\Kvs\Cursor::remove — Delete the current cursor
• UnQLite\Kvs\Cursor::key — Returns the current key
• UnQLite\Kvs\Cursor::data — Returns the current value

UnQLite\Doc

• UnQLite\Doc::__construct — Create a new document store
• UnQLite\Doc::eval — Evaluate a string as Jx9 code
• UnQLite\Doc::drop — remove a collection
• UnQLite\Doc::count — total number of inserted records
• UnQLite\Doc::store — Store one or more JSON values
• UnQLite\Doc::fetch — Fetch the current record
• UnQLite\Doc::fetch_all — Retrieve all records
• UnQLite\Doc::fetch_id — Fetch a record via its unique ID
• UnQLite\Doc::remove — remove a stored record
• UnQLite\Doc::begin — Manually begin a write-transaction
• UnQLite\Doc::commit — Commit all changes to the database
• UnQLite\Doc::rollback — Rollback a write-transaction

Class Methods

• UnQLite\DB::__construct — Create database

  Description:

  public UnQLite\DB::__construct ( string $filename [ , long $mode = UnQLite\OPEN_CREATE ] )

  Open UnQLite database.

  Pameters:

  • fielname

    database filaname.

  • flags

    options.

    • UnQLite\OPEN_READONLY
    • UnQLite\OPEN_READWRITE
    • UnQLite\OPEN_CREATE
    • UnQLite\OPEN_NOMUTEX
    • UnQLite\OPEN_IN_MEMORY
    • UnQLite\OPEN_MMAP

  Return Values:

  Returns a new UnQLite\DB object.

---

• UnQLite\DB::close — Close database

  Description:

  public UnQLite\DB::close ( void )

  Close database.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\DB::config — Configure a database

  Description:

  public bool UnQLite\DB::config ( long $option )

  Configure a database.

  Pameters:

  • option

    options.

    • UnQLite\CONFIG_DISABLE_AUTO_COMMIT

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\DB::kvs — Create a new key/value store

  Description:

  public object UnQLite\DB::kvs ( void )

  Create a new key/value store.

  Return Values:

  Returns a new UnQLite\Kvs object

---

• UnQLite\DB::doc — Create a new document store

  Description:

  public object UnQLite\DB::doc ( string $collection )

  Create a new document store.

  Pameters:

  • collection

    collection name.

Return Values:

Returns a new UnQLite\Doc object

---

• UnQLite\Kvs::__construct — Create a new Key/Value store

  Description:

  public UnQLite\Kvs::__construct ( object $db )

  Create a new Key/Value store.

  Pameters:

  • db

    UnQLite\DB class Object.

  Return Values:

  Returns a new UnQLite\Kvs object

---

• UnQLite\Kvs::store — Saves entry

  Description:

  public bool UnQLite\Kvs::store ( string $key , string $value )

  Saves entry.

  Pameters:

  • key

    The key of the entry to be inserted.

  • value

    The value to be inserted.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Kvs::append — Append entry data specified by key

  Description:

  public bool UnQLite\Kvs::append ( string $key , string $value )

  Append entry data specified by key.

  Pameters:

  • key

    The key of the entry to be appended.

  • value

    The value to be appended.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Kvs::fetch — Fetch data specified by key

  Description:

  public string UnQLite\Kvs::fetch ( string $key )

  Fetch data specified by key.

  Pameters:

  • key

    The key of the entry to be inserted.

  Return Values:

  Returns the associated string if the key/data on key found, NULL on key not found, FALSE on failure.

---

• UnQLite\Kvs::remove — Delete entry specified by key

  Description:

  public bool UnQLite\Kvs::remove ( string $key )

  Delete entry specified by key.

  alias: UnQLite\Kvs::delete

  Pameters:

  • key

    The key of the entry to be appended.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Kvs::begin — Manually begin a write-transaction

  Description:

  public bool UnQLite\Kvs::begin ( void )

  Manually begin a write-transaction.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Kvs::commit — Commit all changes to the database

  Description:

  public bool UnQLite\Kvs::commit ( void )

  Commit all changes to the database.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Kvs::rollback — Rollback a write-transaction

  Description:

  public bool UnQLite\Kvs::rollback ( void )

  Rollback a write-transaction.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Kvs::cursor — Create a new Key/Value stotre cursor

  Description:

  public object UnQLite\Kvs::cursor ( [ long $option = NULL ] )

  Create a new Key/Value stotre cursor.

  Pameters:

  • option

    options.

    • UnQLite\CURSOR_FIRST
    • UnQLite\CURSOR_LAST

  Return Values:

  Returns a new UnQLite\Kvs\Cursor object.

---

• UnQLite\Kvs\Cursor::__construct — Create a new Key/Value stotre cursor.

  Description:

  public UnQLite\Kvs\Cursor::__construct ( object $kvs , [ long $option ] )

  Create a new Key/Value stotre cursor.

  Pameters:

  • kvs

    UnQLite\Kvs object.

  • option

    options.

    • UnQLite\CURSOR_FIRST
    • UnQLite\CURSOR_LAST

  Return Values:

  Returns a new UnQLite\Kvs\Cursor object.

---

• UnQLite\Kvs\Cursor::first — Advances the cursor to the first

  Description:

  public bool UnQLite\Kvs\Cursor::first ( void )

  Advances the cursor to the first.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Kvs\Cursor::last — Advances the cursor to the last

  Description:

  public bool UnQLite\Kvs\Cursor::last ( void )

  Advances the cursor to the last.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Kvs\Cursor::next — Advances the cursor to the next

  Description:

  public bool UnQLite\Kvs\Cursor::next ( void )

  This function has no parameters.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Kvs\Cursor::prev — Advances the cursor to the prev

  Description:

  public bool UnQLite\Kvs\Cursor::prev ( void )

  Advances the cursor to the prev.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Kvs\Cursor::seek — Seek cursor to key

  Description:

  public bool UnQLite\Kvs\Cursor::seek ( string $key , [ long $option = UnQLite\CURSOR_MATCH_EXACT ] )

  Seek cursor to key.

  Pameters:

  • key

    The key of the entry to be seek.

  • option

    options.

    • UnQLite\CURSOR_MATCH_EXACT
    • UnQLite\CURSOR_MATCH_LE
    • UnQLite\CURSOR_MATCH_GE

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Kvs\Cursor::exists — Check whether cursor exists

  Description:

  public bool UnQLite\Kvs\Cursor::exists ( void )

  Check whether cursor exists.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Kvs\Cursor::remove — Delete the current cursor

  Description:

  public bool UnQLite\Kvs\Cursor::remove ( void )

  Delete the current cursor.

  alias: UnQLite\Kvs\Cursor::delete

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Kvs\Cursor::key — Returns the current key

  Description:

  public string UnQLite\Kvs\Cursor::key ( void )

  Returns the current key.

  Return Values:

  The current cursor's key as a string.

---

• UnQLite\Kvs\Cursor::data — Returns the current value

  Description:

  public string UnQLite\Kvs\Cursor::data ( void )

  Returns the current value.

  Return Values:

  The current cursor's key as a string.

---

• UnQLite\Doc::__construct — Create a new document store

  Description:

  public UnQLite\Doc::__construct ( object $db , string $collection )

  Create a new document store.

  Pameters:

  • db

    UnQLite\DB class object.

  • collection

    collection name.

  Return Values:

  Returns a new UnQLite\Doc object.

---

• UnQLite\Doc::eval — Evaluate a string as Jx9 code

  Description:

  public string UnQLite\Doc::eval ( string $code )

  Evaluate a string as Jx9 code.

  Pameters:

  • code

    Jx9 code.

  Return Values:

  Returns execution result on success or FALSE on failure.

---

• UnQLite\Doc::drop — remove a collection

  Description:

  public bool UnQLite\Doc::drop ( void )

  remove a collection.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Doc::count — total number of inserted records

  Description:

  public int UnQLite\Doc::drop ( void )

  total number of inserted records.

  Return Values:

  total nuber of records.

---

• UnQLite\Doc::store — Store one or more JSON values

  Description:

  public bool UnQLite\Doc::store ( array|object $data )

  Store one or more JSON values.

  Pameters:

  • data

    JSON values.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Doc::fetch — Fetch the current record

  Description:

  public mixed UnQLite\Doc::fetch ( [ int $offset = 0 ] )

  Fetch the current record.

  Pameters:

  • offset

    cursor offset.

  Return Values:

  record value.

---

• UnQLite\Doc::fetch_all — Retrieve all records

  Description:

  public array UnQLite\Doc::fetch_all ( void )

  Retrieve all records.

  alias: UnQLite\Doc::fetchAll

  Return Values:

  JSON array holding the filtered records.

---

• UnQLite\Doc::fetch_id — Fetch a record via its unique ID

  Description:

  public mixed UnQLite\Doc::fetch_id ( int $id )

  Fetch a record via its unique ID.

  alias: UnQLite\Doc::fetchId

  Pameters:

  • id

    id number.

  Return Values:

  record value.

---

• UnQLite\Doc::remove — remove a stored record

  Description:

  public bool UnQLite\Doc::remove ( int $id )

  remove a stored record.

  Pameters:

  • id

    id number.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Doc::begin — Manually begin a write-transaction

  Description:

  public bool UnQLite\Doc::begin ( void )

  Manually begin a write-transaction.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Doc::commit — Commit all changes to the database

  Description:

  public bool UnQLite\Doc::commit ( void )

  Commit all changes to the database.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

• UnQLite\Doc::rollback — Rollback a write-transaction

  Description:

  public bool UnQLite\Doc::rollback ( void )

  Rollback a write-transaction.

  Return Values:

  Returns TRUE on success or FALSE on failure.

---

Examples

Key/Value store

namespace UnQLite;

$db = new DB(dirname(__FILE__) . '/kvs.db');
$kvs = $db->kvs(); // or $kvs = new Kvs($db);
$kvs->store("foo", "bar");
$kvs->fetch("foo"); // => bar

$kvs->remove("foo"); // or $kvs->delete("foo")

$kvs->store("a", "A");
$kvs->store("b", "B");
$kvs->store("c", "C");

$cursor = $kvs->cursor();
$cursor->first();
do {
    $cursor->key();  // => a .. b  .. c
    $cursor->data(); // => A .. B  .. C
} while ($cursor->next());

Document store

namespace UnQLite;

$db = new DB(dirname(__FILE__) . '/doc.db');
$doc = $db->doc('test'); // or $doc = new Doc($db, 'test');
$doc->store(array("a" => "A"));
$doc->store(array("b" => "B"));
$doc->store(array("c" => "C"));
$doc->fetch();
// => array (
//      [a] => A
//      [__id] => 0
//    )

$doc->fetch_all(); // or $doc ->fetchAll()
// =>
// => array (
//      [0] => array (
//              [a] => A
//              [__id] => 0
//             )
//      [1] => array (
//              [__id] => 1
//              [b] => B
//             )
//      [2] => array (
//              [c] => C
//              [__id] => 2
//             )
//    )

$doc->fetch_id(1); // or $doc ->fetchId(1)
// => bar
// => array (
//      [__id] => 1
//      [b] => B
//    )

$doc->remove(1); // or $doc->delete(1)

$doc->fetch_all(); // or $doc ->fetchAll()
// => array (
//      [0] => array (
//              [a] => A
//              [__id] => 0
//             )
//      [1] => array (
//              [c] => C
//              [__id] => 2
//             )
//    )

Transaction

namespace UnQLite;

$db = new DB(dirname(__FILE__) . '/kvs.db');
$kvs = $db->kvs(); // begin is performed implicitly
$kvs->store("foo", "bar");

$kvs->fetch("foo");  // => bar
$kvs->fetch("test"); // => NULL

$kvs->commit(); // transaction commit (write here)

$kvs->begin(); // transaction start

$kvs->store("test", "message");
$kvs->remove("foo");

$kvs->fetch("foo");  // => NULL
$kvs->fetch("test"); // => message

$kvs->rollback(); // transaction rollback

$kvs->fetch("foo");  // => bar
$kvs->fetch("test"); // => NULL

Related

• api document