README

Metadata

A package to simply add metadata to any Eloquent model with a simple cast. Metadata is stored in a single related table as JSON, keyed per model, so you can attach arbitrary attributes to a model without adding extra columns.

Installation

You can install the package via composer:

composer require marshmallow/metadata

You can publish and run the migrations with:

php artisan vendor:publish --tag="metadata-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="metadata-config"

This is the contents of the published config file:

return [
    /*
     * The fully qualified class name of the metadata model.
     */
    'metadata_model' => Marshmallow\Metadata\Models\Metadata::class,

    /*
     * The fully qualified class name of the metadata cast.
     */
    'metadata_cast' => Marshmallow\Metadata\Casts\MetadataCast::class,

    /*
     * Automatically eager load metadata to prevent N+1 queries.
     * Set to false if you prefer to manually eager load metadata.
     */
    'eager_load' => false,
];

Configuration

Key	Default	Description
`metadata_model`	`Marshmallow\Metadata\Models\Metadata::class`	The model used to store metadata. Swap it to use your own.
`metadata_cast`	`Marshmallow\Metadata\Casts\MetadataCast::class`	The cast that maps a model attribute to metadata storage.
`eager_load`	`false`	When `true`, the `metadata` relation is automatically eager loaded on models using the trait to prevent N+1 queries.

Usage

Add the HasMetadata trait to your model:

use Marshmallow\Metadata\Traits\HasMetadata;

class Example extends Model
{
    use HasMetadata;
}

Add a cast for every field you want to store as metadata:

use Marshmallow\Metadata\Casts\MetadataCast;

protected $casts = [
    'example_field' => MetadataCast::class,
];

After which you can get & set your field using normal model attribute access:

$example_model->example_field = 'This is an example';
$example_model->save();

$example_field = $example_model->example_field;
// 'This is an example'

Array and object values are automatically encoded to JSON on write and decoded on read:

$example_model->example_field = ['key' => 'value'];

$example_model->example_field;
// ['key' => 'value']

When you set metadata on a model that has not been persisted yet, the value is queued and written automatically once the model is created. Metadata is also automatically deleted when the model itself is deleted.

Working with the metadata relation directly

Each model that uses the trait exposes a metadata morph-one relation backed by the Metadata model, which offers a few helpers:

// Read or write a single key
$example_model->metadata->getMetadata('example_field');
$example_model->metadata->addMetadata('example_field', 'value');

// Remove a single key
$example_model->metadata->removeKey('example_field');

// Clear all metadata for the model
$example_model->metadata->clear();

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please report security vulnerabilities by email rather than via the public issue tracker.

Credits

License

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

marshmallow / metadata

Maintainers

Package info

Statistics

Security