library novus

devfake/novus

JSON-File Database For PHP

, _(*1)

Novus is a JSON-file database for PHP. Use this package for quick prototyping and to testing your application without to configure a mysql (or other) database., _(*2)

The syntax is a little like more typical sql, and not like ORM., _(*3)

Warning: This package is incomplete and it miss some important features., _(*4)

• Get Started
• Quick Overview
• First Steps
• Options
• Argument Values
• Create Table
• Add Fields
• Rename Fields
• Remove Fields
• Insert
• Select
• Order
• Limit
• Where Conditions
• Update
• Delete And Remove
• Last Primary Key
• Next Primary Key
• Rename Primary Key
• Last And First
• Find And FindOrFail

Get Started

Requirements

• PHP 5.4+
• Composer

Install

The easiest way to install Novus is via Composer. Add this to your composer.json file and run $ composer update:, _(*5)

{
  "require": {
    "devfake/novus": "dev-master"
  }
}

Feature release will have a bootstrap file if you don't want to use composer., _(*6)

Quick Overview

Let's see a quick overview of the syntax:, _(*7)

$novus = new \Devfake\Novus\Database();

// Create a new 'users' table.
$novus->table('users')->create('username, password, email');

// Add more fields.
$novus->table('users')->addFields('activated');

// Insert data.
$novus->table('users')->insert('username = Arya, email = a.stark@winterfell.com, password = n33dl3, activated = 1');

// Select all data.
$data = $novus->table('users')->select();

// Select only username and email.
$data = $novus->table('users')->select('username, email');

// Select all data from 'users' where id = 1.
$data = $novus->table('users')->where('id = 1')->select();

// Update username.
$novus->table('users')->update('username = Jon');

// Delete all data from 'users'.
$novus->table('users')->delete(true);

// Delete all data from 'users' with soft delete.
$novus->table('users')->delete();

// Remove complete 'users' file.
$novus->table('users')->remove();

// Limit and order data.
$novus->table('users')->where('id > 4')->limit(5)->orderBy('id desc')->select()

First Steps

Once you have created the object, you can normally work with them., _(*8)

However, there is a little rule: You must always specify which table you're working on at the beginning with table():, _(*9)

$novus = new \Devfake\Novus\Database();
$novus->table('myTable')->myMethods();

But you can also specify directly a table for the object:, _(*10)

$myTable = new \Devfake\Novus\Database('myTable');
$myTable->myMethods();

$users = new \Devfake\Novus\Database('users');
$users->orderBy('username, email')->select('username, email, date');

This way is recommended if you are working only with a few tables, or want to make your code a bit more readable. And of course, you have less to write., _(*11)

Options

You can pass a few options when you instantiate your class., _(*12)

// Pass a single string to specify directly a table.
$novus = new \Devfake\Novus\Database('myTable');

// Or pass a array with conditions.
$novus = new \Devfake\Novus\Database([
  'table' => 'myTable',
  'path' => 'myPathForDatabaseFiles',
  'primaryKey' => 'Number'
]);

The path for your database files is relative to your root folder (or where your composers vendor folder is)., _(*13)

The default folder is database. There are a saves folder to save your soft deletes., _(*14)

The primaryKey is only needed for the create() method., _(*15)

Argument Values

// First, pass a string as argument and separate the keywords with a comma.
$novus->table('users')->create('username, email, password');

// Or, pass a array as argument.
$novus->table('tableName')->create(['username', 'email', 'password']);

What is the difference? The first method is clear and fast to type., _(*16)

Use the second method if you have commas in your keys. But please, i hope you have no commas (or other special chars) in your field names. The second method you will (or need) to use for insert or update data., _(*17)

Create Table

Let‘s create a users table and work with them over the complete documentation. For the documentation we will work with table() to make it a little more detailed., _(*18)

// Create a new file without fields.
$novus->table('users')->create();

// Create a new file with fields.
$novus->table('users')->create('field1, field2');
// Or with the array spelling.
$novus->table('users')->create(['field1', 'field2']);

And that‘s it! You need the create() method only run once., _(*19)

There is a new database/users.json file. Let‘s open it:, _(*20)

{"table":"users","id":1,"fields":[["id"]],"data":[]}

// Format it a bit for the documentation
{
  "table": "users",
  "id": 1,

  "fields": [
    ["id"]
  ],

  "data": []
}

So, what we have in our table? First, we have "table", this is our table name, in this case "users". Then comes our primary key, "id". They will automatically increased., _(*21)

Then we have our "fields". The primary key will added by default., _(*22)

And last, we have our "data". Since we have no data entered, this field is empty. As you can see, "fields" and "data" are arrays which contains other arrays., _(*23)

Add Fields

$novus->table('users')->addFields('username, email');
$novus->table('users')->addFields(['username', 'email']);

Rename Fields

$novus->table('users')->renameFields('username = users, email = mail');
$novus->table('users')->renameFields(['username' => 'users', 'email' => 'mail']);

Remove Fields

The removeFields() method also deletes the associated data., _(*24)

$novus->table('users')->removeFields('username, email');
$novus->table('users')->removeFields(['username', 'email']);

Insert

$novus->table('users')->insert('username = devfake, email = devfakeplus@googlemail.com');
$novus->table('users')->insert(['username' => 'devfake', 'email' => 'devfakeplus@googlemail.com']);

Select

// Select all data from 'users'.
$data = $novus->table('users')->select();
$data = $novus->table('users')->select('*');

// Select only username and email.
$data = $novus->table('users')->select('username, email');
$data = $novus->table('users')->select(['username', 'email']);

// Select all data from where id = 1.
$data = $novus->table('users')->where('id = 1')->select();

// Iterate over $data
foreach($data as $content) {
  echo $content['username'];
}

Order

Order your output with the orderBy() method., _(*25)

// Order by id ASC and username DESC.
$order = $novus->table('users')->orderBy('id asc, username desc')->select();
// Or with array spelling.
$order = $novus->table('users')->orderBy(['id' => 'asc', 'username' => 'desc'])->select();

// ASC is default passed.
$order = $novus->table('users')->orderBy('id, username desc')->select();
$order = $novus->table('users')->orderBy(['id', 'username' => 'desc')->select();

// ASC and DESC are case insensitive.
$order = $novus->table('users')->orderBy('id DESC, username ASC')->select();

Limit

1 => first_user, 2 => second_user, 3 => third_user, 4 => fourth_user, 5 => fifth_user, 6 => sixth_user, 7 => seventh_user 

These are pseudo data of the users table. With them we demonstrate the limit() method., _(*26)

// Select the first three data.
$limit = $novus->table('users')->limit(3)->select();
1 => first_user, 2 => second_user, 3 => third_user

// Select the next four data after the first two.
$limit = $novus->table('users')->limit(2, 4)->select();
3 => third_user, 4 => fourth_user, 5 => fifth_user, 6 => sixth_user

// Select the last three data in reverse.
$limit = $novus->table('users')->limit(3, true)->select();
5 => fifth_user, 6 => sixth_user, 7 => seventh_user

// Select the last four data in reverse before the last two.
$limit = $novus->table('users')->limit(2, 4, true)->select();
2 => second_user, 3 => third_user, 4 => fourth_user, 5 => fifth_user

The reverse mode return the data in ASC. Use case is for example a chat., _(*27)

If you don't want this, order them, for example by id., _(*28)

// Select the last four data without reverse.
$limit = $novus->table('users')->limit(4, true)->orderBy('id DESC')->select();
7 => seventh_user, 6 => sixth_user, 5 => fifth_user, 4 => fourth_user

It does not matter whether the orderBy() method is written before or after limit()., _(*29)

Where Conditions

Warning: This method is currently very limited. It only works with select() and only one query. But i will fix it soon., _(*30)

$data = $novus->table('users')->where('id = 1')->select();
$data = $novus->table('users')->where('username = Arya')->select();
$data = $novus->table('users')->where('id > 10')->select();

Use <=, >=, !=, =, > and <., _(*31)

Update

Warning: update() will currently update ALL data. I will fix it soon with where()., _(*32)

$novus->table('users')->update('username = newUsername, email = newEmail');
$novus->table('users')->update(['username' => 'newUsername', 'email' => 'newEmail']);

Delete And Remove

If you use delete() or remove(), novus will make a backup file in the saves folder. This folder is created in the beginning and is inside of your database folder., _(*33)

Pass true as argument to avoid the soft delete., _(*34)

Delete

With delete() you can remove a dataset., _(*35)

Warning: This method is currently very limited and removed all data from a table. I will fix it soon with where()., _(*36)

$novus->table('users')->delete();
$novus->table('users')->delete(true);

Remove

With remove() you can remove a complete table file., _(*37)

$novus->table('users')->remove();
$novus->table('users')->remove(true);

Last Primary Key

Return the primary key of last data. If data is empty, the method returns null., _(*38)

$key = $novus->table('users')->lastPrimaryKey();

Next Primary Key

Return the primary key of next insert data., _(*39)

$key = $novus->table('users')->nextPrimaryKey();

Rename Primary Key

Change your primary key of a table. This has no effect on the primary key that was defined by the options., _(*40)

$novus->table('users')->renamePrimaryKey('number');

Last And First

$first = $novus->table('users')->first();
echo $first['username'];

$last = $novus->table('users')->last();
echo $last['username'];

Find And FindOrFail

Find data by primary key. If no data found, find() will return an empty array and findOrFail() will return an exception., _(*41)

$find = $novus->table('users')->find(1);
echo $find['username'];

$find = $novus->table('users')->findOrFail(2);
echo $find['username'];

ToDo

• Finish where() conditions.
• Types for fields.
• Write tests.
• Own autoloader.
• Object access.