$post = \App\Models\Post::first();

// Set meta fluently for any key – `likes` is no column of `Post`.
$post->likes = 24;

// Or use the `setMeta` method.
$post->setMeta('likes', 24);

// You may also schedule changes, for example change the meta in 2 years:
$post->setMetaAt('likes', 6000, '+2 years');

use Illuminate\Database\Eloquent\Model;
use Kolossal\Multiplex\HasMeta;

class Post extends Model
{
    use HasMeta;
}

$model->setMeta('foo', 'bar');
// or
$model->foo = 'bar';

$model->setMeta([
    'hide' => true,
    'color' => '#000',
    'likes' => 24,
]);

$model->foo = 'bar';

$model->isMetaDirty(); // true

$model->save();

$model->isMetaDirty(); // false

$model->saveWithoutMeta();

$model->isMetaDirty(); // true

$model->saveMeta();

$model->resetMeta();

// Save the given meta value right now.
$model->saveMeta('foo', 123.45);

// Save only specific keys of the changed meta.
$model->setMeta(['color' => '#fff', 'hide' => false]);
$model->saveMeta('color');
$model->isMetaDirty('hide'); // true

// Save multiple meta values at once.
$model->saveMeta([
    'color' => '#fff',
    'hide' => true,
]);

$user = Auth::user();

$user->saveMeta('favorite_band', 'The Mars Volta');
$user->saveMetaAt('favorite_band', 'Portishead', '+1 week');

// Changing taste in music: This will return `The Mars Volta` now but `Portishead` in a week.
$user->favorite_band;

$user->saveMetaAt('favorite_band', 'Arctic Monkeys', '-5 years');
$user->saveMetaAt('favorite_band', 'Tool', '-1 year');

// This will return `Tool` – which is true since this is indeed a good band.
$user->favorite_band;

$user->setMeta('favorite_color', 'blue');
$user->setMeta('favorite_band', 'Jane’s Addiction');
$user->saveMetaAt('+1 week');

// or

$user->saveMetaAt([
    'favorite_color' => 'blue',
    'favorite_band' => 'Jane’s Addiction',
], '+1 week');

$post = Post::find(1);

$post->color; // string(4) "#000"
$post->likes; // int(24)
$post->hide; // bool(true)

// In the year 2030 `$post->color` will be `#fff`.

$post->likes; // (int) 24
$post->color; // (string) '#000'

$post->getMeta('likes', 0); // Use `0` as a fallback.

$post->saveMeta([
    'author' => 'Anthony Kiedis',
    'color' => 'black',
]);

$post->saveMetaAt('author', 'Jimi Hendrix', '1970-01-01');
$post->saveMetaAt('author', 'Omar Rodriguez', '+1 year');

$post->meta->pluck('value', 'key');

/**
 * Illuminate\Support\Collection {
 *   all: [
 *     "author" => "Anthony Kiedis",
 *     "color" => "black",
 *   ],
 * }
 */

// Allow any meta key and explicitly allow `foo` and `bar`.
$post->metaKeys(['*', 'foo', 'bar']);

$post->saveMeta('foo', 'a value');
$post->saveMeta('another', true);

$post->pluckMeta();
/**
 * Illuminate\Support\Collection {
 *   all: [
 *     "foo" => "a value",
 *     "bar" => null,
 *     "another" => true,
 *   ],
 * }
 */

// This array will also include `Jimi Hendrix´.
$post->publishedMeta->toArray();

$post->allMeta->toArray();

$meta = $post->allMeta->first();

$meta->is_current; // (bool)
$meta->is_planned; // (bool)

Meta::published()->get(); // Only current and historic meta.

Meta::planned()->get(); // Only meta not yet published.

Meta::publishedBefore('+1 week')->get(); // Only meta published by next week.

Meta::publishedAfter('+1 week')->get(); // Only meta still unpublished in a week.

Meta::onlyCurrent()->get(); // Only current meta without planned or historic data.

Meta::withoutHistory()->get(); // Query without stale records.

Meta::withoutCurrent()->get(); // Query without current records.

// Get records that have been current a month ago.
Meta::onlyCurrent('-1 month')->get();

// Get records that will not be history by tommorow.
Meta::withoutHistory(Carbon::now()->addDay())->get();

// Find posts having at least one meta records for `color` key.
Post::whereHasMeta('color')->get();

// Or pass an array to find records having meta for at least one of the given keys.
Post::whereHasMeta(['color', 'background_color'])->get();

// Find posts not having any meta records for `color` key.
Post::whereDoesntHaveMeta('color')->get();

// Or find records not having meta for any of the given keys.
Post::whereDoesntHaveMeta(['color', 'background_color'])->get();

// Find posts where the current attached color is `black`.
Post::whereMeta('color', 'black')->get();

// Find posts where the current attached color is not `black`.
Post::whereMeta('color', '!=', 'black')->get();

// Find posts that are `visible`.
Post::whereMeta('visible', true)->get();

// There are alternatives for building `or` clauses for all scopes.
Post::whereMeta('visible', true)->orWhere('hidden', false)->get();

// Matches only meta records with type `boolean`.
Post::whereMeta('hidden', false)->get();

// Matches only meta records with type `datetime`.
Post::whereMeta('release_at', '<=', Carbon::now())->get();

// Find posts where `color` is `black` (string) or `false` (boolean).
Post::whereMetaIn('color', ['black', false])->get();

Post::whereRawMeta('hidden', '')->get();

Post::whereRawMeta('likes', '>', '100')->get();

Post::whereMetaOfType('integer', 'count', '0')->get();

Post::whereMetaOfType('null', 'foo', '')->get();

Post::whereMetaEmpty('favorite_band')->get();

// Get all posts having meta names `likes` and `comments` where *both* of them are not empty.
Post::whereMetaNotEmpty(['likes', 'comments'])->get();

use Kolossal\Multiplex\Events\MetaHasBeenAdded;

class SomeListener
{
    public function handle(MetaHasBeenAdded $event)
    {
        $event->meta; // The Meta model that was added.
        $event->model; // The parent model, same as $event->meta->metable.
        $event->type; // The class name of the parent model.
    }
}

use Kolossal\Multiplex\Events\MetaHasBeenRemoved;

class SomeListener
{
    public function handle(MetaHasBeenRemoved $event)
    {
        $event->meta; // The Meta model that was removed.
        $event->model; // The parent model, same as $event->meta->metable.
        $event->type; // The class name of the parent model.
    }
}

$user = Auth::user()->withMetaAt('-1 week');
$user->favorite_band; // Tool
$user->withMetaAt(Carbon::now())->favorite_band; // The Mars Volta

Post::first()->withMetaAt('2022-10-01 15:00:00')->meta->pluck('value', 'key');

Post::travelTo('-14 days')->whereMetaIn('foo', [false, 0])->get();

Post::travelTo('+2 years')->where('category', 'tech')->get();

Post::travelTo('-1 year')->where('category', 'tech')->get();
Post::where('category', 'tech')->get(); // Will still look for meta published last year.

Post::travelBack();
Post::where('category', 'tech')->get(); // Find current meta.

class Post extends Model
{
    use HasMeta;

    protected array $metaKeys = [
        'color',
        'hide',
    ];
}

protected array $metaKeys = ['*'];

$model->metaKeys(['color', 'hide']);

use Kolossal\Multiplex\MetaAttribute;

class Post extends Model
{
    use HasMeta;

    protected $metaKeys = [];

    protected $casts = [
        'body' => MetaAttribute::class,
    ];
}

protected array $metaKeys = [
    'foo',
    'count' => 'integer',
    'color' => 'string',
    'hide' => 'boolean',
];

class Post extends Model
{
    use HasMeta;

    protected $metaKeys = [
        '*',
        'body',
    ];
}

\DB::table('posts')->create(['title' => 'A title', 'body' => 'A body.']);

$post = Post::first();

$post->body; // A body.

$post->body = 'This. Is. Meta.';
$post->save();

$post->body; // This. Is. Meta.
$post->deleteMeta('body');

$post->body; // A body.

// Delete all meta records for the `color` key.
$post->deleteMeta('color');

// Or delete all meta records associated with the model.
$post->purgeMeta();

// Worst case: 26 queries if `color` is a meta value.
$colors = Post::take(25)->get()->map(
    fn ($post) => $post->color;
);

// Same result with only 2 queries.
$colors = Post::with('meta')->take(25)->get()->map(
    fn ($post) => $post->color;
);