1. class
  2. App
  3. \
  4. G6K
  5. \
  6. Manager
  7. \
  8. Json
  9. \
  10. JsonSQL
  11. \
  12. Engine

Engine

class Engine

This class allows you to store and retrieve data from files in JSON format using SQL standard.

  • The data are described by a json schema in compliance with the spécifications of http://json-schema.org

  • This schema can be generated on this site: http://jsonschema.net

  • The API is very similar to PDO

  • The JSON schema is saved in a file whose name is in the form .schema.json

  • The data is saved in a file whose name is in the form .json

Properties

private JsonSQL|null $jsonsql A pointer on the JsonSQL owner.
private string|null $name Name of the JSON database managed by that engine
private object|null $json The committed content of the JSON database managed by that engine
static private bool $compact Indicates whether to save the json file in a compact form or not
private bool $transaction true if a transaction is currently active, and false if not.
private object|null $backup Content being updated during a transaction
private bool $modified true if data has been modified, and false if not.
private bool $schemaModified true if the database schema has been modified, and false if not.
private string|false $lastInsertId Stores the ID of the last inserted row.
private object $db A pointer on the content of the JSON database managed by that engine.

Methods

void
__construct(JsonSQL $jsonsql)

Constructor of class Engine

__destruct()

Class destructor

object
getDb()

Returns the pointer on the content of the JSON database

open(string $name, bool $create = false)

Open a json database

create(string $name, bool $compact = false)

Creates a json database then open it

object
schema()

Returns a pointer to the json schema object

ArrayIterator
table(string $name)

returns a ArrayIterator on the rows of the table $name

string
quote(string $string, int $type = \PDO::PARAM_STR)

Quotes a string for use in a query.

string|false
lastInsertId()

Returns the ID of the last inserted row.

bool
beginTransaction()

Initiates a transaction.

void
endTransaction()

Ends a transaction.

bool
commit()

Commits a transaction.

bool
notifyModification()

Commits any modification

bool
notifySchemaModification()

Commits any modification of the schema

bool
rollBack()

Rolls back the current transaction, as initiated by beginTransaction().

bool
inTransaction()

Checks if inside a transaction.

object
loadJsonFromCache(string $path)

Loads a json database into memory.

object
loadRequestFromCache(string $sql)

Loads a parsed request from memory cache.

void
checkDuplicateKeys(string $table, array $keys, int $exclude = -1)

Checks if the table already contains a record with the provided keys

void
insert(string $table, array $row)

Appends a row to a table

void
delete(string $table, int $index)

Deletes a table row

void
replace(string $table, int $index, stdClass $row)

Replaces a table row by another

void
createTable(string $table, stdClass $columns, array $required, array $foreignkeys, bool $ifnotexists = false)

Creates a table in the database

void
truncate(string $table)

Deletes all rows from a table

void
dropTable(string $table, bool $ifexists = false)

Drops a table

void
renameTable(string $table, string $newname)

Renames a table

void
addColumn(string $table, string $column, stdClass $columnDef, array $required = array())

Adds a column in a table of the database

void
renameColumn(string $table, string $column, string $newname)

Renames a column

void
dropColumn(string $table, string $column, bool $ifexists = false)

Drops a column

void
setColumnType(string $table, string $column, string $type, string $format = '', string $datatype = '')

Changes the type of a column

void
setNotNull(string $table, string $column, bool $allownull = false)

Changes whether a column is marked to allow null values or to reject null values

void
setDefault(string $table, string $column, string|bool $default = false)

Set or remove the default value for a column.

void
setPrimaryKey(string $table, string $column, bool $remove = false)

Set or remove primary key for a column.

void
setAutoincrement(string $table, string $column, bool $remove = false)

Set or remove autoincrement for a column.

void
setTableTitle(string $table, string|bool $title = false)

Set or remove the title of a table.

void
setTableDescription(string $table, string|bool $description = false)

Set or remove the description of a table.

void
setColumnTitle(string $table, string $column, string|bool $title = false)

Set or remove the title of a column.

void
setColumnDescription(string $table, string $column, string|bool $description = false)

Set or remove the description of a column.

void
save()

Saves the current database and/or its schema on the file system

string|float|bool|int|null
normalizeValue(string $type, string $value)

Converts a string value according to its json data type

object
properties(string $arg)

Tokenizes a list of comma separated internal properties and returns an object with these properties.

Details

at line 140
void __construct(JsonSQL $jsonsql)

Constructor of class Engine

Parameters

JsonSQL $jsonsql The JsonSQL instance

Return Value

void

at line 150
__destruct()

Class destructor

commit all changes if a transaction is currently active

at line 161
object getDb()

Returns the pointer on the content of the JSON database

Return Value

object The pointer on the content of the JSON database

at line 172
open(string $name, bool $create = false)

Open a json database

Parameters

string $name the name of json database (without the file extension)
bool $create if true, creates the database if it doesn't exists

at line 207
create(string $name, bool $compact = false)

Creates a json database then open it

Parameters

string $name The name of json database (without the file extension)
bool $compact if true, the content of the database will be compact

Exceptions

JsonSQLException

at line 232
object schema()

Returns a pointer to the json schema object

Return Value

object The json schema object

at line 243
ArrayIterator table(string $name)

returns a ArrayIterator on the rows of the table $name

Parameters

string $name The table name

Return Value

ArrayIterator The ArrayIterator

at line 255
string quote(string $string, int $type = \PDO::PARAM_STR)

Quotes a string for use in a query.

Parameters

string $string The string to be quoted.
int $type provides a PDO data type hint (default : PDO::PARAM_STR).

Return Value

string a quoted string that is safe to pass into an SQL statement

at line 275
string|false lastInsertId()

Returns the ID of the last inserted row.

Return Value

string|false a string representing the row ID of the last row that was inserted into the database

at line 285
bool beginTransaction()

Initiates a transaction.

Return Value

bool always true

at line 300
protected void endTransaction()

Ends a transaction.

Return Value

void

at line 314
bool commit()

Commits a transaction.

Return Value

bool always true

at line 329
bool notifyModification()

Commits any modification

Return Value

bool always true

at line 340
bool notifySchemaModification()

Commits any modification of the schema

Return Value

bool always true

at line 351
bool rollBack()

Rolls back the current transaction, as initiated by beginTransaction().

Return Value

bool always true

at line 366
bool inTransaction()

Checks if inside a transaction.

Return Value

bool true if a transaction is currently active, and false if not.

at line 380
private object loadJsonFromCache(string $path)

Loads a json database into memory.

If APCu is enabled and the database is stored in memory then return it. otherwise, the database is loaded from the filesystem and decoded.

Parameters

string $path The name of json database (without the file extension)

Return Value

object The json database (schema and data)

Exceptions

JsonSQLException

at line 420
object loadRequestFromCache(string $sql)

Loads a parsed request from memory cache.

If APCu is enabled and the request is stored in memory then return it. otherwise, the request is parsed. only select statement are stored into memory cache.

Parameters

string $sql The sql statement

Return Value

object The parsed request (select statement only)

at line 444
protected void checkDuplicateKeys(string $table, array $keys, int $exclude = -1)

Checks if the table already contains a record with the provided keys

Parameters

string $table The table name
array $keys The array of keys
int $exclude optionally, don't verify for the row with this index

Return Value

void

Exceptions

JsonSQLException

at line 472
void insert(string $table, array $row)

Appends a row to a table

Parameters

string $table The table name
array $row The row to append

Return Value

void

Exceptions

JsonSQLException

at line 543
void delete(string $table, int $index)

Deletes a table row

Parameters

string $table The table name
int $index The position of the row in the table

Return Value

void

at line 559
void replace(string $table, int $index, stdClass $row)

Replaces a table row by another

Parameters

string $table The table name
int $index The position of the row in the table
stdClass $row The new row

Return Value

void

Exceptions

JsonSQLException

at line 612
void createTable(string $table, stdClass $columns, array $required, array $foreignkeys, bool $ifnotexists = false)

Creates a table in the database

Parameters

string $table The table name
stdClass $columns The columns definition
array $required The list of required columns
array $foreignkeys The list of foreign keys definition
bool $ifnotexists if true, don't throw an error if the table already exists

Return Value

void

Exceptions

JsonSQLException

at line 624
void truncate(string $table)

Deletes all rows from a table

Parameters

string $table The table name

Return Value

void

Exceptions

JsonSQLException

at line 643
void dropTable(string $table, bool $ifexists = false)

Drops a table

Parameters

string $table The table name
bool $ifexists if true, don't throw an error if the table doesn't exists

Return Value

void

Exceptions

JsonSQLException

at line 656
void renameTable(string $table, string $newname)

Renames a table

Parameters

string $table The table name
string $newname The new name of the table

Return Value

void

Exceptions

JsonSQLException

at line 671
void addColumn(string $table, string $column, stdClass $columnDef, array $required = array())

Adds a column in a table of the database

Parameters

string $table The table name
string $column The name of the new column
stdClass $columnDef The column definition
array $required an array with the column name if required

Return Value

void

Exceptions

JsonSQLException

at line 685
void renameColumn(string $table, string $column, string $newname)

Renames a column

Parameters

string $table The table name
string $column The actual column name in the table
string $newname The new name of the column

Return Value

void

Exceptions

JsonSQLException

at line 699
void dropColumn(string $table, string $column, bool $ifexists = false)

Drops a column

Parameters

string $table The table name
string $column The actual column name to drop in the table
bool $ifexists if true, don't throw an error if the table or the column doesn't exists

Return Value

void

Exceptions

JsonSQLException

at line 715
void setColumnType(string $table, string $column, string $type, string $format = '', string $datatype = '')

Changes the type of a column

Parameters

string $table The table name
string $column The actual column name
string $type The type of the column
string $format The format of the column
string $datatype The datatype of the column

Return Value

void

Exceptions

JsonSQLException

at line 729
void setNotNull(string $table, string $column, bool $allownull = false)

Changes whether a column is marked to allow null values or to reject null values

Parameters

string $table The table name
string $column The actual column name
bool $allownull if true, the column allow null value

Return Value

void

Exceptions

JsonSQLException

at line 743
void setDefault(string $table, string $column, string|bool $default = false)

Set or remove the default value for a column.

Parameters

string $table The table name
string $column The actual column name
string|bool $default The default value. If false, remove the default

Return Value

void

Exceptions

JsonSQLException

at line 757
void setPrimaryKey(string $table, string $column, bool $remove = false)

Set or remove primary key for a column.

Parameters

string $table The table name
string $column The actual column name
bool $remove if true, remove the primary key

Return Value

void

Exceptions

JsonSQLException

at line 771
void setAutoincrement(string $table, string $column, bool $remove = false)

Set or remove autoincrement for a column.

Parameters

string $table The table name
string $column The actual column name
bool $remove if true, remove the primary key

Return Value

void

Exceptions

JsonSQLException

at line 784
void setTableTitle(string $table, string|bool $title = false)

Set or remove the title of a table.

Parameters

string $table The table name
string|bool $title The title content. If false, remove the title

Return Value

void

Exceptions

JsonSQLException

at line 797
void setTableDescription(string $table, string|bool $description = false)

Set or remove the description of a table.

Parameters

string $table The table name
string|bool $description The description content. If false, remove the description

Return Value

void

Exceptions

JsonSQLException

at line 811
void setColumnTitle(string $table, string $column, string|bool $title = false)

Set or remove the title of a column.

Parameters

string $table The table name
string $column The actual column name
string|bool $title The title content. If false, remove the title

Return Value

void

Exceptions

JsonSQLException

at line 825
void setColumnDescription(string $table, string $column, string|bool $description = false)

Set or remove the description of a column.

Parameters

string $table The table name
string $column The actual column name
string|bool $description The description content. If false, remove the description

Return Value

void

Exceptions

JsonSQLException

at line 836
void save()

Saves the current database and/or its schema on the file system

Return Value

void

Exceptions

JsonSQLException

at line 865
string|float|bool|int|null normalizeValue(string $type, string $value)

Converts a string value according to its json data type

Parameters

string $type The json data type (string, integer, number or boolean)
string $value The value to convert

Return Value

string|float|bool|int|null The converted value

at line 891
object properties(string $arg)

Tokenizes a list of comma separated internal properties and returns an object with these properties.

Internal properties are stored into the title property of the column definition in the database schema. Actually, only 'primarykey' and 'autoincrement' are used.

Parameters

string $arg The list of comma separated properties

Return Value

object The properties object.