Wildfire

Wildfire is a wrapper for Query Builder Class from the Codeigniter framework. It is also inspired by the Eloquent ORM from Laravel.

Installation

Install Wildfire via Composer:

$ composer require rougin/wildfire

Basic Usage

Preparation

-- Import this script to a SQLite database

CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL,
    name TEXT NOT NULL,
    age INTEGER NOT NULL,
    gender TEXT NOT NULL,
    accepted INTEGER DEFAULT 0
);

INSERT INTO users (name, age, gender) VALUES ('Rougin', 20, 'male');
INSERT INTO users (name, age, gender) VALUES ('Royce', 18, 'male');
INSERT INTO users (name, age, gender) VALUES ('Angel', 19, 'female');

// application/config/config.php

/*
|--------------------------------------------------------------------------
| Composer auto-loading
|--------------------------------------------------------------------------
|
| Enabling this setting will tell CodeIgniter to look for a Composer
| package auto-loader script in application/vendor/autoload.php.
|
|   $config['composer_autoload'] = TRUE;
|
| Or if you have your vendor/ directory located somewhere else, you
| can opt to set a specific path as well:
|
|   $config['composer_autoload'] = '/path/to/vendor/autoload.php';
|
| For more information about Composer, please visit http://getcomposer.org/
|
| Note: This will NOT disable or override the CodeIgniter-specific
|   autoloading (application/config/autoload.php)
*/
$config['composer_autoload'] = TRUE;

// application/models/User.php

class User extends \Rougin\Wildfire\Model
{
}

// application/controllers/Welcome.php

// Loads the database connection 
$this->load->database();

// Enables the inflector helper. It is being used to determine the class or the
// model name to use based from the given table name from the Wildfire.
$this->load->helper('inflector');

// Loads the required model/s
$this->load->model('user');

Using the Wildfire instance with CI_DB_query_builder

// application/controllers/Welcome.php

use Rougin\Wildfire\Wildfire;

// Pass the \CI_DB_query_builder instance
$wildfire = new Wildfire($this->db);

// Can also be called to \CI_DB_query_builder
$wildfire->like('name', 'Royce', 'both');

// Returns an array of User objects
$users = $wildfire->get('users')->result();

Using the Wildfire instance with CI_DB_result

// application/controllers/Welcome.php

use Rougin\Wildfire\Wildfire;

$query = 'SELECT p.* FROM post p';

// Create raw SQL queries here...
$result = $this->db->query($query);

// ...or even the result of $this->db->get()
$result = $this->db->get('users');

// Pass the result as the argument
$wildfire = new Wildfire($result);

// Returns an array of User objects
$users = $wildfire->result('User');

Properties for the Model instance

Casting attributes to native types

// application/models/User.php

class User extends \Rougin\Wildfire\Model
{
    /**
     * The attributes that should be cast to native types.
     *
     * @var array
     */
    protected $casts = array('accepted' => 'boolean');
}

Without native casts

{
    "id": 1,
    "name": "Rougin",
    "age": "20",
    "gender": "male",
    "accepted": "0",
}

With native casts

{
    "id": 1,
    "name": "Rougin",
    "age": "20",
    "gender": "male",
    "accepted": false,
}

Notice that the value of accepted was changed from string integer ('0') into native boolean (false). If not specified (e.g. age field), all values will be returned as string except the id field (which will be automatically casted as native integer, also if the said column exists) by default.

Hiding attributes for serialization

// application/models/User.php

class User extends \Rougin\Wildfire\Model
{
    /**
     * The attributes that should be hidden for serialization.
     *
     * @var array
     */
    protected $hidden = array('gender');
}

Without hidden attributes

{
    "id": 1,
    "name": "Rougin",
    "age": "20",
    "gender": "male",
    "accepted": "0",
}

With hidden attributes

{
    "id": 1,
    "name": "Rougin",
    "age": "20",
    "accepted": "0",
}

The gender field was not included in the result.

Visible attributes for serialization

// application/models/User.php

class User extends \Rougin\Wildfire\Model
{
    /**
     * The attributes that should be visible for serialization.
     *
     * @var array
     */
    protected $visible = array('gender');
}

Without visible attributes

{
    "id": 1,
    "name": "Rougin",
    "age": "20",
    "gender": "male",
    "accepted": "0",
}

With visible attributes

{
    "gender": "male"
}

In contrast to the hidden attribute, only the gender field was displayed in the result because it was the only field specified the in visible property of the User model.

Migrating to the v0.5.0 release

The new release for v0.5.0 will be having a backward compatibility break (BC break). So some functionalities on the earlier versions might not be working after updating. This was done to increase the maintainability of the project while also adhering to the functionalities for both Codeigniter and Eloquent ORM. It was also introduced to remove code complexity and to simplify arguments on existing methods. To check the documentation for the last release (v0.4.0), kindly click here.

Change the CodeigniterModel class to Model class

Before

class User extends \Rougin\Wildfire\CodeigniterModel
{
}

After

class User extends \Rougin\Wildfire\Model
{
}

When Wildfire is used as a CI_Model, use WildfireTrait instead.

Before

class User extends \Rougin\Wildfire\Wildfire
{
}

After

class User extends \Rougin\Wildfire\Model
{
    use \Rougin\Wildfire\Traits\WildfireTrait;
}

Change the arguments for PaginateTrait::paginate

Before

// PaginateTrait::paginate($perPage, $config = array())
list($result, $links) = $this->user->paginate(5, $config);

After

$total = $this->db->count_all_results('users');

// PaginateTrait::paginate($perPage, $total, $config = array())
list($offset, $links) = $this->user->paginate(5, $total, $config);

The total count must be passed in the second parameter.

Remove Model::countAll

Before

$total = $this->user->countAll();

After

$total = $this->db->count_all_results('users');

This is being used only in PaginateTrait::paginate.

Change the method ValidateTrait::validation_errors to ValidateTrait::errors

Before

ValidateTrait::validation_errors()

After

ValidateTrait::errors()

Change the property ValidateTrait::validation_rules to ValidateTrait::rules

Before

// application/models/User.php

protected $validation_rules = array();

After

// application/models/User.php

protected $rules = array();

Change the arguments for Wildfire::__construct

Before

$query = $this->db->query('SELECT * FROM users');

// Wildfire::__construct($database = null, $query = null)
$wildfire = new Wildfire($this->db, $query);

After

// $this->db->query returns a CI_DB_result class
$query = $this->db->query('SELECT * FROM users');

// Wildfire::__construct($data)
$wildfire = new Wildfire($query);

If the data is a CI_DB_result, it should be passed on the first parameter.

Change the method Wildfire::asDropdown to Wildfire::dropdown

Before

// Wildfire::asDropdown($description = 'description')
$dropdown = $wildfire->asDropdown();

After

// Wildfire::dropdown($column)
$dropdown = $wildfire->dropdown('description');

Also take note that there is no default value in the argument.

Replace $delimiters with $id in Wildfire::find

Before

$delimiters = array('name' => 'Rougin');

// Wildfire::find($table, $delimiters = array())
$users = $wildfire->find('users', $delimiters);

After

$this->db->where('name', (string) 'Rougin');

$users = $wildfire->get('users')->result();

Use only Wildfire::find to return single row data.

// Wildfire::find($table, $id)
$user = $wildfire->find('users', 1);

Remove set_database and set_query methods

Before

use Rougin\Wildfire\Wildfire;

$wildfire = new Wildfire;

$wildfire->set_database($this->db);

$query = $this->db->query('SELECT * FROM users');

$wildfire->set_query($query);

After

use Rougin\Wildfire\Wildfire;

$wildfire = new Wildfire($this->db);

// or

$query = $this->db->query('SELECT * FROM users');

$wildfire = new Wildfire($query);

The Wildfire parameter must be defined with either CI_DB_query_builder ($this->db) or CB_DB_result instances.

Changelog

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

Credits

• All contributors

License

The MIT License (MIT). Please see LICENSE for more information.