eloquent-meta/README.md

# Laravel Meta-Articles

[![Latest Unstable Version][ico-unstable]][link-packagist]
[![License][ico-license]][link-license]
[![Total Downloads][ico-downloads]][link-packagist]
[![Latest Stable Version][ico-stable]][link-packagist]

The Framework for Meta enabled Laravel models.


## Install

Via Composer

``` bash
$ composer require glmdev/meta
```

### Update the Laravel Framework

Add the following provider to config/app.php

``` php
'providers' => [
    Glmdev\Meta\MetaServiceProvider::class
]
```


## Usage

When declaring a new model, extend the Meta model:

``` php
<?php

namespace App;

class Post extends Meta 
{
    // fillable, hidden, etc. arrays
}
```

> *Important*: do not extend the Model class, Meta does this for you

The Meta plugin adds a custom Artisan command to auto-generate migrations for meta-enabled models.
To generate a migration for a new meta-model, use the following command:

``` bash
$ php artisan meta:migration name_of_migration --create=table_name
```

> (The `meta:migration` command extends the `make:migration`, so it contains all of the original functionality.)


Add your custom fields, if any, then migrate as usual:

``` bash
$ php artisan migrate
```

Then, just create a model like usual:

``` php
public function createPost () {
    $post = Post::create([
        // post data
    ]);
}
```

But now, you have access to a universal identifier for every model in the entire project.

You can check if a model has a UUID, and get it if it does:
``` php
$post->hasUuid(); // returns true or false
$post->getUuid(); // returns the UUID
```

The other big feature of the Meta model is saving meta information.
This information is stored in the database in one column: 'meta'

To save meta information, use the 'write' method.
``` php
$post->write('author', 'Bob Saget');
```

And to retrieve meta information, use the 'read' method.
``` php
$post->read('author'); //returns 'Bob Saget'
```

### Adding Meta functionality to existing models

To add Meta capabilities to existing models, you need to add the database columns and tweak the model's class as follows:

##### Database update

Create a new database migration using the custom Meta command:

``` bash
$ php artisan meta:migration --table=existing_table_name
```

Make sure the inside of the `up()` function contains the `formTable` function:

``` php
public function up()
{
    Schema::table('existing_table_name', function (Blueprint $table) {
        Meta::formTable($table);
    });
}
```

Then, migrate:

``` bash
$ php artisan migrate
```

##### Model Class updates

To enable the database functionality, the class for the model needs to extend the Meta class. Modify the class header to the following format:

``` php

class ClassNameHere extends Meta {
    // your class stuff here
}
```

> *Important*: you no longer need to extend the Model class, Meta does this for you

After that, you can use the full meta functionality with your model. 

### Query Builder

Let's say you need to retrieve the post that has a certain UUID (maybe you gave it out in a url or something)

It's super easy to search for it:
``` php
Post::withUuid($uuid)->first();
```

It is completely integrated into the query builder, so you can still do stuff like:
``` php
Post::withUuid($uuid)->pluck('username');
Post::withUuid($uuid)->firstOrFail();
```

## Credits

- [Garrett Mills][link-author]
- [All Contributors][link-contributors]


## License and Copyright

    Copyright (C) 2016 Garrett Mills

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Affero General Public License as
    published by the Free Software Foundation, either version 3 of the
    License, or any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Affero General Public License for more details.

    You should have received a copy of the GNU Affero General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.

Please see [License File][link-license] for more details.

[ico-stable]: https://poser.pugx.org/glmdev/meta/v/stable
[ico-unstable]: https://poser.pugx.org/glmdev/meta/v/unstable
[ico-downloads]: https://poser.pugx.org/glmdev/meta/downloads
[ico-license]: https://poser.pugx.org/glmdev/meta/license
[ico-scrutinizer]: https://scrutinizer-ci.com/g/glmdev/meta/badges/quality-score.png?b=master
[ico-build]: https://travis-ci.org/glmdev/meta.svg

[link-travis]: https://travis-ci.org/glmdev/meta
[link-packagist]: https://packagist.org/packages/glmdev/meta
[link-scrutinizer]: https://scrutinizer-ci.com/g/glmdev/meta
[link-license]: ./LICENSE
[link-author]: https://github.com/glmdev
[link-contributors]: ../../contributors