Introduction

A framework agnostic attributes package that allows you to attach attributes to objects, it utilizes the Entity-Attribute-Value Model to assign values to objects.

The package follows the FIG standard PSR-4 to ensure a high level of interoperability between shared PHP code and is fully unit-tested.

Getting started

The package requires PHP 5.4+.

Have a read through the Installation Guide.

Prepare your Class

use Cartalyst\Attributes\EntityInterface;
use Cartalyst\Attributes\EntityTrait;

class Page extends Eloquent implements EntityInterface {

    use EntityTrait;

    protected $guarded = [
        'id',
        'created_at',
        'updated_at',
    ];

}

Assign Values to Attributes

$page = Page::create([
    'name'       => 'Page #1',
    'slug'       => 'page-1',
    'meta_title' => 'Homepage', // An Attribute
]);

Installation

The best and easiest way to install the Attributes package is with Composer.

Preparation

Open your composer.json and add the following to the require array:

"cartalyst/attributes": "1.1.*"

Add the following lines after the require array on your composer.json file:

"repositories": [
    {
        "type": "composer",
        "url": "https://packages.cartalyst.com"
    }
]

Note: Make sure your composer.json file is in a valid JSON format after the required changes.

Install the dependencies

Run Composer to install or update the new requirement.

php composer install

or

php composer update

Now you are able to require the vendor/autoload.php file to autoload the package.

Run the migrations

Generate the required database tables.

php artisan migrate --package=cartalyst/attributes

Example

// Include the composer autoload file
require_once 'vendor/autoload.php';

use Cartalyst\Attributes\EntityInterface;
use Cartalyst\Attributes\EntityTrait;

// Your eloquent model must implement EntityInterface and the EntityTrait
class Page extends Eloquent implements EntityInterface {

    use EntityTrait;

    protected $guarded = [
        'id',
        'created_at',
        'updated_at',
    ];

}

Now you can use any attributes as if they are real properties existing on your model.

Usage

Prepare your Class

Your Eloquent implementation must implement Cartalyst\Attributes\EntityInterface and use the Cartalyst\Attributes\EntityTrait trait.

use Cartalyst\Attributes\EntityTrait;
use Cartalyst\Attributes\EntityInterface;

class Page extends Eloquent implements EntityInterface {

    use EntityTrait;

    protected $fillable = [
        'title',
        'slug',
    ];

}

Note: You can use either the $guarded or the $fillable properties when using attributes.

Create an Attribute

use Cartalyst\Attributes\Attribute

Attribute::create([
    'slug' => 'meta_title',
]);

Assign Values to Attributes

To set values for the new attribute you simply provide the attribute slug as a parameter to the create or update function

// Create a new record
$page = Page::create([
    'name' => 'Page #1',
    'slug' => 'page-1',
    'meta_title' => 'Homepage', // An Attribute
]);

// Update an existing record
$page = Page::find(1);

$data = [
    'options' => [ // An Attribute
        'option1',
        'option2',
    ],
];

$page->fill($data)->update();

Note: You can also set the attribute value to an array, it will be encoded as json.

Retrieve Values

Values are retrieved along with your object

$page = Page::find(1);

Retrieved Object

// Page Object

{
    "id":2,
    "name": "Page #1",
    "slug": "page-1",
    "meta_title":"The Default Homepage",
    "values":[
        {
            "id":1,
            "attribute_id":1,
            "entity_type":"Foo\Bar\User",
            "entity_id":2,
            "value":"The Default Homepage",
            "created_at":"2013-12-12 18:26:17",
            "updated_at":"2013-12-12 18:26:17",
            "attribute":{
                "id":1,
                "slug":"meta_title",
                "created_at":"2013-12-11 21:39:32",
                "updated_at":"2013-12-11 21:39:32"
            }
        }
    ]
}

Note: If you use arrays as values, you may want to define an accessor for your attribute to decode json encoded arrays for you

public function getMetaTitleAttribute($value)
{
    return is_array(json_decode($value, true)) ? json_decode($value, true) : $value;
}