guifcoelho / immu-table
Package for using immutable ndjson models instead of regular SQL or NoSQL databases with sintax similar to Laravel Eloquent.
Requires
- php: ~7.3
- illuminate/config: ^5.8
- symfony/finder: ^4.3
Requires (Dev)
- fzaninotto/faker: ^1.8
- illuminate/database: ^5.8
- illuminate/filesystem: ^5.8
- jaschilz/php-coverage-badger: ^2.0
- phpunit/phpunit: ^8
- symfony/var-dumper: ^4.3
- vlucas/phpdotenv: ^3.4
Suggests
- illuminate/database: Required to use pivot tables
- vlucas/phpdotenv: Required to use the env helper (^3.3).
README
ImmuTable
Package for using immutable ndjson models instead of regular SQL or NoSQL databases with sintax similar to Laravel Eloquent.
DO NOT use this package if your data are likely to change.
Installation
composer require guifcoelho/immu-table
How to use it
Configuration
The config class will look for a config_path()
function. This function must return the configuration files repository where the immutable.php
configuration file is located.
Copy immutable.php
configuration file from src/Config
and paste it into your own configuration folder.
By default, the tables will be stored in storage/app/immutable/tables
.
The Engine class will load the tables in chunks of data. You can increase or decrese the chunk_size
in the configuration file.
Declaring your model
Create models the same way as in Laravel Eloquent:
use guifcoelho\ImmuTable\Model; class Sample extends Model { protected $table = "table_example"; }
It will load your data from the table table_example.ndjson
and set all fields accordingly. If you want to restrict the fields to be loaded, just include the protected array $fields
:
use guifcoelho\ImmuTable\Model; class Sample extends Model { protected $fields = ['id', 'name', 'email']; }
If you do not want some fields to be returned in the toArray()
or toJson()
functions, just include their names in the $hidden
array:
use guifcoelho\ImmuTable\Model; class Sample extends Model { protected $hidden = ['this', 'that']; }
If you want your primary key to be anything but 'id', just declare it as below (remember that your primary key must be unique and integer):
use guifcoelho\ImmuTable\Model; class Sample extends Model { protected $primary_key = 'not_id'; }
Querying your models
You can query your model for data the same way as in Laravel Eloquent:
$query = SampleModel::where('id', 10)->first();
or,
$query = SampleModel::where('price', '>', 50)->first();
or chaining 'where' clauses,
$query = SampleModel::where('price', '>', 50)->where('id', '<=', 10)->get();
or chaining 'orWhere' clauses
$query = SampleModel::where('price', '>', 50) ->where('id', '<=', 10) ->orWhere('price', '<', 10) ->get();
Declaring relations
You can declare relations between models the same way as Laravel Eloquent. Please, look into the Model
class to see which relations are implemented.
use guifcoelho\ImmuTable\Model; use Sample2; use Sample3; use Sample4; use Sample5; class Sample1 extends Model { protected $table = "table_example"; public function owner(){ return $this->ImmuTable_belongsTo(Sample2::class [, $field, $field_in_parent_class]); } public function parents(){ return $this->ImmuTable_belongsToMany(Sample3::class [, $pivot_table, $field_in_pivot, $parent_field_in_pivot, $field, $field_in_parent]) } public function child(){ return $this->ImmuTable_hasOne(Sample4::class [, $field_in_child_model, $field]); } public function children(){ return $this->ImmuTable_hasMany(Sample5::class [, $field_in_child_models, $field]); } }
In the example above, the fields inside brackets are optional. See below a better explanation:
ImmuTable_belongsTo
: You must provide the parent class name. If necessary, provide the foreign key name inside the child model, and the related field name inside the parent model.ImmuTable_belongsToMany
: You must provide the parent class name. If necessary, provide the pivot table name, the current model's foreign key name in the pivot table, the parent model's foreign key name in the pivot table, the related current model's field name, and the related parent model's field name.ImmuTable_hasOne
: You must provide the child class name. If necessary, provide the foreign key name inside the child model and the related field name inside the parent model.ImmuTable_hasMany
: You must provide the children class name. If necessary, provide the foreign key name inside the children models and the related field name inside the parent model.
Contributing and testing
- Only tests:
./vendor/bin/phpunit
- Tests and coverage report:
composer tests-report-[linux|win]