FireSql – Getting Started

FireSql was created because we wanted it to be easy for devs to work with data without having to worry about SQL syntax. We also wanted the barrier to entry to be as simple as possible which is why we have removed the schema requirements and made this into a NoSql solution.

Install FireSql

composer require ua1-labs/firesql

Connect To a Database

Connecting to a database is simple as we used the traditional methodology for connecting to databases via PHP’s built in PDO. Please note, currently, we are only supporting MySQL and SQLite. If you have a database you’d like supported please submit an issue.

$pdo = new \PDO('sqlite:' . __DIR__ . '/demo.db');
$db = new \UA1Labs\Fire\Sql($pdo);

Obtain a Collection

At some point, you are going to want to interact with data in the database itself. Whether that is inserting, updating, deleting, or reading that data. In the concept of NoSQL or Non-Relationtional databases, we bundle objects together in what we call “collections.” A collection is a place to store similar objects. Not that the object schema matters, when you store objects with a similar nature of schema, it will be a lot easier to query them.

When obtaining a collection, you do not need to register it. Simply by asking for it by name, FireSql will return an object that will have access to the collection you are asking for.

$collection = $db->collection('CollectionName');

Inserting Your First Object

When dealing with objects in FireSql, you can insert any object in a collection. You don’t have to worry about the schema of the object. When inserting an object into the collection, FireSql will attempt to serialize the object as a JSON string and store that as the record. Each record is stored with other information as well. Objects will be also an indexed. Which will allow us to later retrieve the object easily.

$vehicle = new Vehicle();

$insertedObject = $carCollection->insert($vehicle);

Please take note that $insertedObject is no longer an instance of Vehicle. Instead it is an instance of stdClass as FireSql does not maintain the instance object. Rather, just the public data within the object.

Also, when an object is stored in the database, as a part of storing the object, there are 4 fields added to every object that will provide you with information about that object and how it is stored in the database.

$insertedObject->__id; // the unique ID the object was stored as
$insertedObject->__revision // the revision number of the object
$insertedObject->__updated // the datetime the object was updated
$insertedObject->__origin // the datetime the object was first stored in the database

Updating an Object

Updating an object is in essence the same process as inserting one. In fact, behind the scenes it uses the very same logic for both updating and inserting. The only difference, is that when you update, you provide an ID for which object you will be updating.

$updatedObject = $carCollection->update($id, $vehicle);

Deleting an Object

Deleting objects is also very easy. They are deleted by ID.


Finding Objects

The most complex part of FireSql is actually getting objects back out of the database once you have inserted them (and that’s not that hard either). For the most part, most of your searches will be easy to implement. So with that in mind, we will first talk about the easy way to get records out of the database.

Query Collections by Object ID

The easiest method for retrieving object from FireSql is to simply find() an object by ID.

$obj = $collection->find($id);

Query Collections by JSON Query

FireSql also supports querying a collection by using the find() method and passing in a JSON string.

Finding objects who’s firstName is Abigail:

$query = '{"firstName": "Abigail"}';
$response = $collection->find($query);

Finding objects who’s firstName is Abigail and middleInitial is E:

$query = '{"firstName": "Abigail", "middleInitial": "E"}';
$response = $collection->find($query);

Finding objects who’s firstName is Abigail or who’s firstName is Nicholas:

$query = '[{"firstName": "Abigail"}, {"firstName": "Nicholas"}]';
$response = $collection->find($query);

Querying Collection with Comparisons

You may find that in some of your queries, you may want to obtain an object between two numbers or return all responses above a certain number. FireSql queries support using comparisons.

Finding all people in your collection who is older than 50

$query = '{"age": ">50"}';
$response = $peopleCollection->find($query);

Supported Comparisons

Equal To{“name”:”josh”} or {“name”:”=josh”}
Not Equal To{“name”:”<>josh”}
Greater Than{“num”:”>5″}
Greater Than or Equal To{“num”:”>=5″}
Less Than{“num”:”<5″}
Less Than or Equal To{“num”:”<=5″}

Filtering The JSON Query Response

FireSql come built with the ability to filter query responses by including the query parameter within the query object.

Use length to adjust the number of objects of the response array (default: 10):

$query = '{"firstName": "Abigail", "length": 100}';
$response = $collection->find($query);

Use offset to adjust which object you starts the response (default: 0):

$query = '{"firstName": "Abigail", "offset": 10}';
$response = $collection->find($query);

Use order to determine which field you want to order your request by (default: __updated):

$query = '{"firstName": "Abigail", "order": "dateCreated"}';
$response = $collection->find($query);

Use reverse to determine if you’d like to receive the response in reverse order (default: true):

$query = '{"firstName": "Abigail", "reverse": false}';
$response = $collection->find($query);

Leave a comment

Leave a Reply