Laravel Flex Properties
Introduction
With this package you can define custom attributes for Laravel's Eloquent models.
Installation
You can install the package via composer:
composer require tkivelip/laravel-flex-properties
How to use?
Set up the model
Simple setup
The easiest to use this package it to extended the shipped model. Anything you need is already setted up. Now you can customize your flex attributes by creating a property called 'flex_properties';
namespace Example;
use tkivelip\LaravelFlexProperties\Model;
class ExampleModel extends Model
{
protected $flex_properties = [
'title' => 'string',
'text' => 'text',
'data' => 'json',
];
}
The $flex_properties
keys are the names of your properties. As value you
have to set up a valid flex property type. You can add or change flex
property types in the main config file config/flex-properties.php
Publish Config and Migrations
If you like to custoize the configuration or the migrations, you can publish these files to your local installation. Same old story. Use any terminal, go to your project root dir and type:
php artisan vendor:publish
Extended Setup
Coming soon...
Using Flex Properties
Flex properties are working with all usual Eloquent functions like fill()
,
update()
, create()
, etc. They have their own type based database tables,
so there is no need to update your migrations, if you change your flex property
configuration.
Setting Values
After you have setted up your eloquent model configuration, you can set flex properties like any other model attributes. Here are some examples:
namespace Example;
// You can use make() to fill flex properties
$model = ExampleModel::make([
'title' => 'Example',
'description' => 'Look at this fill() example'
]);
// Or set a property directly
$model->title = 'Overrides example';
// Or use fill() on an existing object
$model->fill([
'title' => 'Example',
'description' => 'Look at this fill() example'
]);
// Don't forget to save you changes
ExampleModel->save();
Note: That you have to configure
$fillable
and/or$guarded
property to allow mass assignment. Take a look at Laravel's Mass Assignment Documentation for more details.
Getting Values
You can direct access the value as a property like any other Eloquent attributes.
namespace Example;
$model = ExampleModel::create([
'title' => 'Example',
'description' => 'Look at this fill() example'
]);
echo $model->title;
echo $model->description;
Appending Flex Properties
You can also use Eloquent's append function to auto append flex properties to your model:
namespace Example;
use tkivelip\LaravelFlexProperties\Model;
class ExampleModel extends Model
{
protected $flex_properties = [
'title' => 'string',
'text' => 'text',
];
protected $appends = [
'title',
'text',
];
}
Create and Update Models
Creating and updating models is very easy. Just use the usual Eloquent methods.
namespace Example;
$example = ExampleModel::create([
'title' => 'Example',
'description' => 'Look at this fill() example'
]);
$example->update([
'title' => 'New title',
'description' => 'A more senceless description'
]);
Localization
Flex properties have an implemented localization mechanism. So you can set, get
and query flex properties in any language you like. Just use the locale()
method
to change the locale at any time.
IMPORTANT NOTE: The
locale()
method changes only the flex property locale. This will not change your application enviorment.
// Set the english title
$model->locale('en')->title = 'Example';
/
/ Set the german title
$model->locale('de')->title = 'Beispiel';
// Or fill frensh translations
$model->locale('fr)->fill([
'title' => 'Exemple',
'description' => 'Parlez-vous français?'
]);
Note: If you do not set up a locale, the default locale is used. If you
manually changed the locale, it will be saved on the model for the current lifecycle, but not in the persistence layer.
Flex Helper
You can find some helpfull tools in the Flex
helper class.
For example we can use the typeExists()
method to determaniate,
if a flex property type is configured:
namespace Example;
use tkivelip\LaravelFlexProperties\Flex;
Flex::typeExists('string'); // returns true
Querying Flex Properties
You can use the Flex::where()
helper to extend the usual
query builder functions like where(), orWhere(), andWhere(), etc.
It takes the flex property name as first parameter. All other
parameters are equal to the eloquent builder methods.
namespace Example;
ExampleModel::where(
Flex::where('property_name', $value);
);
ExampleModel::where(
Flex::where('description', 'LIKE', 'Starts with%');
);
Changelog
Please see CHANGELOG for more information what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Credits
License
The MIT License (MIT). Please see License File for more information.