added docblocks, contract, and service provider

.gitignore

@@ -1 +1,2 @@
 vendor/
+composer.lock

.scrutinizer.yml

@@ -0,0 +1,4 @@
+checks:
+    php:
+        code_rating: true
+        duplication: true

.travis.yml

@@ -0,0 +1,8 @@
+language: php
+php:
+  - 5.5
+  - 5.6
+  - 7.0
+  - hhvm
+before_script: travis_retry composer install --no-interaction --prefer-source 
+script: phpunit

README.md

@@ -1,4 +1,118 @@
-Laravel Meta-Articles Package
+# Laravel Meta-Articles
+
+[![Build Status][ico-build]][link-travis]
+[![Quality Score][ico-scrutinizer]][link-scrutinizer]
+[![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;
+
+use Glmdev\Meta\Meta;
+
+class Post extends Meta 
+{
+    // fillable, hidden, etc. arrays
+}
+```
+
+> *Important*: do not extend the Model class, Meta does this for you
+
+Then, include the 'meta' and 'uuid' columns in your database table:
+
+In your migration,
+``` php
+<?php
+
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Database\Migrations\Migration;
+
+use Glmdev\Meta\Meta;
+
+class CreatePostsTable extends Migration
+{
+    public function up()
+    {
+        Schema::create('posts', function (Blueprint $table) {
+            // all your table values
+            Meta::formTable($table);
+        });
+    }
+}
+```
+
+Then, when you create a new model, a Post in this case, your function would look something like this:
+
+``` php
+public function createPost () {
+    $post = Post::create([
+        // post data
+    ]);
+    
+    $post->setUuid();
+}
+```
+
+You now 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 if it exists, else null
+```
+
+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'
+```
+
+
+## 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
@@ -13,3 +127,19 @@ Laravel Meta-Articles Package
 
     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

composer.json

@@ -9,13 +9,19 @@
         }
     ],
     "require": {
-        "ramsey/uuid": "^3.2",
+        "php": ">=5.6.4",
+        "illuminate/support": "^5.2",
+        "illuminate/database": "^5.2",
+        "ramsey/uuid": "^3.4",
         "glmdev/foundation": "^0.0.004"
     },
+    "require-dev": {
+        "phpunit/phpunit": "~4.0"
+    },
     "autoload": {
         "psr-4": {
-            "App\\": "../../../app/",
+            "Glmdev\\Meta\\": "src/",
-            "Glmdev\\Meta\\": "src/"
+            "Glmdev\\Meta\\Tests\\": "tests/"
         }
     }
 }

composer.lock

@@ -1,145 +0,0 @@
-{
-    "_readme": [
-        "This file locks the dependencies of your project to a known state",
-        "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file",
-        "This file is @generated automatically"
-    ],
-    "hash": "f28a14cc53da5df0fb6ab22362338395",
-    "content-hash": "b07b9654708a316c5adb2dec5078fe8a",
-    "packages": [
-        {
-            "name": "paragonie/random_compat",
-            "version": "v2.0.2",
-            "source": {
-                "type": "git",
-                "url": "https://github.com/paragonie/random_compat.git",
-                "reference": "088c04e2f261c33bed6ca5245491cfca69195ccf"
-            },
-            "dist": {
-                "type": "zip",
-                "url": "https://api.github.com/repos/paragonie/random_compat/zipball/088c04e2f261c33bed6ca5245491cfca69195ccf",
-                "reference": "088c04e2f261c33bed6ca5245491cfca69195ccf",
-                "shasum": ""
-            },
-            "require": {
-                "php": ">=5.2.0"
-            },
-            "require-dev": {
-                "phpunit/phpunit": "4.*|5.*"
-            },
-            "suggest": {
-                "ext-libsodium": "Provides a modern crypto API that can be used to generate random bytes."
-            },
-            "type": "library",
-            "autoload": {
-                "files": [
-                    "lib/random.php"
-                ]
-            },
-            "notification-url": "https://packagist.org/downloads/",
-            "license": [
-                "MIT"
-            ],
-            "authors": [
-                {
-                    "name": "Paragon Initiative Enterprises",
-                    "email": "security@paragonie.com",
-                    "homepage": "https://paragonie.com"
-                }
-            ],
-            "description": "PHP 5.x polyfill for random_bytes() and random_int() from PHP 7",
-            "keywords": [
-                "csprng",
-                "pseudorandom",
-                "random"
-            ],
-            "time": "2016-04-03 06:00:07"
-        },
-        {
-            "name": "ramsey/uuid",
-            "version": "3.3.0",
-            "source": {
-                "type": "git",
-                "url": "https://github.com/ramsey/uuid.git",
-                "reference": "f44f53e5ceb7474a83b6e11e6623ff9d6f6da598"
-            },
-            "dist": {
-                "type": "zip",
-                "url": "https://api.github.com/repos/ramsey/uuid/zipball/f44f53e5ceb7474a83b6e11e6623ff9d6f6da598",
-                "reference": "f44f53e5ceb7474a83b6e11e6623ff9d6f6da598",
-                "shasum": ""
-            },
-            "require": {
-                "paragonie/random_compat": "^1.0|^2.0",
-                "php": ">=5.4"
-            },
-            "replace": {
-                "rhumsaa/uuid": "self.version"
-            },
-            "require-dev": {
-                "apigen/apigen": "^4.1",
-                "ircmaxell/random-lib": "^1.1",
-                "jakub-onderka/php-parallel-lint": "^0.9.0",
-                "mockery/mockery": "^0.9.4",
-                "moontoast/math": "^1.1",
-                "phpunit/phpunit": "^4.7|^5.0",
-                "satooshi/php-coveralls": "^0.6.1",
-                "squizlabs/php_codesniffer": "^2.3"
-            },
-            "suggest": {
-                "ext-libsodium": "Provides the PECL libsodium extension for use with the SodiumRandomGenerator",
-                "ext-uuid": "Provides the PECL UUID extension for use with the PeclUuidTimeGenerator and PeclUuidRandomGenerator",
-                "ircmaxell/random-lib": "Provides RandomLib for use with the RandomLibAdapter",
-                "moontoast/math": "Provides support for converting UUID to 128-bit integer (in string form).",
-                "ramsey/uuid-console": "A console application for generating UUIDs with ramsey/uuid",
-                "ramsey/uuid-doctrine": "Allows the use of Ramsey\\Uuid\\Uuid as Doctrine field type."
-            },
-            "type": "library",
-            "extra": {
-                "branch-alias": {
-                    "dev-master": "3.x-dev"
-                }
-            },
-            "autoload": {
-                "psr-4": {
-                    "Ramsey\\Uuid\\": "src/"
-                }
-            },
-            "notification-url": "https://packagist.org/downloads/",
-            "license": [
-                "MIT"
-            ],
-            "authors": [
-                {
-                    "name": "Marijn Huizendveld",
-                    "email": "marijn.huizendveld@gmail.com"
-                },
-                {
-                    "name": "Thibaud Fabre",
-                    "email": "thibaud@aztech.io"
-                },
-                {
-                    "name": "Ben Ramsey",
-                    "email": "ben@benramsey.com",
-                    "homepage": "https://benramsey.com"
-                }
-            ],
-            "description": "Formerly rhumsaa/uuid. A PHP 5.4+ library for generating RFC 4122 version 1, 3, 4, and 5 universally unique identifiers (UUID).",
-            "homepage": "https://github.com/ramsey/uuid",
-            "keywords": [
-                "guid",
-                "identifier",
-                "uuid"
-            ],
-            "time": "2016-03-22 18:40:53"
-        }
-    ],
-    "packages-dev": [],
-    "aliases": [],
-    "minimum-stability": "beta",
-    "stability-flags": [],
-    "prefer-stable": false,
-    "prefer-lowest": false,
-    "platform": [],
-    "platform-dev": []
-}

contributors.txt

@@ -1 +1,2 @@
 Garrett Mills <garrett@glmills.gq>
+Jake Mitchell <jake@jmitchell.co>

phpunit.php

@@ -0,0 +1,5 @@
+<?php
+
+require __DIR__ . '/vendor/autoload.php'; 
+
+date_default_timezone_set('UTC');

phpunit.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<phpunit backupGlobals="false"
+         backupStaticAttributes="false"
+         bootstrap="phpunit.php"
+         colors="true"
+         convertErrorsToExceptions="true"
+         convertNoticesToExceptions="true"
+         convertWarningsToExceptions="true"
+         processIsolation="false"
+         stopOnFailure="false">
+    <testsuites>
+        <testsuite name="Meta Test Suite">
+            <directory suffix="Test.php">./tests</directory>
+        </testsuite>
+    </testsuites>
+</phpunit>

src/Contracts/MetaContract.php

@@ -0,0 +1,80 @@
+<?php
+
+namespace Glmdev\Meta\Contracts;
+
+interface MetaContract
+{
+    /**
+     * Ensure the model recieves valid UUID and meta columns when created.
+     *
+     * @param array $args
+     *
+     * @return callable
+     */
+    public static function create( array $args = [] );
+
+    /**
+     * Read the serialized value.
+     *
+     * @param string|int $key
+     *
+     * @return string|int|float|array|bool|null
+     */
+    public function read( $key );
+
+    /**
+     * Adds the key-value pair into the serialized data set.
+     *
+     * @param string|int $key
+     * @param string|int|float|array|bool|null $value
+     *
+     * @return void
+     */
+    public function write( $key, $value );
+
+    /**
+     * Get the serialized value of the meta info.
+     *
+     * @return string
+     */
+    public function readRaw();
+
+    /**
+     * Set (override) the entire meta with an unmodified string.
+     *
+     * @param string $serialized
+     *
+     * @return void
+     */
+    public function writeRaw( $serialized );
+
+    /**
+     * Get the universal identifier of the model.
+     *
+     * @return \Ramsey\Uuid\Uuid
+     */
+    public function getUuid();
+
+    /**
+     * Set the universal identifier of the model (can only be set once).
+     *
+     * @return void
+     */
+    public function setUuid();
+    
+    /**
+     * Ask if the model has a universal identifier.
+     *
+     * @return bool
+     */
+    public function hasUuid();
+
+    /**
+     * Set the universal identifier via existing UUID.
+     *
+     * @param \Ramsey\Uuid\Uuid $uuid
+     *
+     * @return void
+     */
+    public function setRawUuid( \Ramsey\Uuid\Uuid $uuid );
+}

src/Meta.php

@@ -1,34 +1,63 @@
 <?php
-/**
- * Created by PhpStorm.
- * User: garrett
- * Date: 4/17/16
- * Time: 11:59 AM
- */
 
 namespace Glmdev\Meta;
 
+use Glmdev\Foundation\FoundationModel;
+use Glmdev\Meta\Contracts\MetaContract;
+
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Database\Schema\Blueprint;
 use Ramsey\Uuid\Uuid;
-use Glmdev\Foundation\FoundationModel;
 
-class Meta extends Model implements FoundationModel
+class Meta extends Model implements FoundationModel, MetaContract
 {
-
+    /**
+     * Allow the changing of the meta and uuid database fields.
+     * 
+     * @var array
+     */
     protected $fillable = ['meta', 'uuid'];
 
-    function read( $key ){
+    /**
+     * Ensure the model recieves valid UUID and meta columns when created.
+     *
+     * @param array $args
+     *
+     * @return callable
+     */
+    public static function create( array $args = [] ){
+        $args['meta'] = (isset($args['meta'])) ? $args['meta'] : serialize([]);
+        $args['uuid'] = (isset($args['uuid'])) ? $args['uuid'] : '';
+
+        return parent::create($args);
+    }
+
+    /**
+     * Read the serialized value.
+     *
+     * @param string|int $key
+     *
+     * @return string|int|float|array|bool|null
+     */
+    public function read( $key ){
         $meta = unserialize( $this->meta );
+
         if ( array_key_exists( $key, $meta ) ){
             return $meta[ $key ];
         }
-        else {
+
         return null;
     }
-    }
 
-    function write( $key, $value ){
+    /**
+     * Adds the key-value pair into the serialized data set.
+     *
+     * @param string|int $key
+     * @param string|int|float|array|bool|null $value
+     *
+     * @return void
+     */
+    public function write( $key, $value ){
         $meta = unserialize( $this->meta );
         $meta[ $key ] = $value;
         $meta = serialize( $meta );
@@ -36,41 +65,79 @@ class Meta extends Model implements FoundationModel
         $this->save();
     }
 
-    function readRaw(){
+    /**
+     * Get the serialized value of the meta info.
+     *
+     * @return string
+     */
+    public function readRaw(){
         return $this->meta;
     }
 
-    function writeRaw( $serialized ){
+    /**
+     * Set (override) the entire meta with an unmodified string.
+     *
+     * @param string $serialized
+     *
+     * @return void
+     */
+    public function writeRaw( $serialized ){
         $this->meta = $serialized;
         $this->save();
     }
 
+    /**
+     * Get the universal identifier of the model.
+     *
+     * @return \Ramsey\Uuid\Uuid
+     */
     public function getUUID(){
         return $this->uuid;
     }
 
+    /**
+     * Set the universal identifier of the model (can only be set once).
+     *
+     * @return void
+     */
     public function setUuid(){
-        // check if UUID is set
+        if( is_null($this->uuid) || $this->uuid === "" ){
-        if( !isset($this->uuid) || is_null($this->uuid) || $this->uuid === "" ){
             $this->uuid = Uuid::uuid4();
-
-            return true;
-        }
-        else {
-            return false;
         }
     }
 
-    public function rawUuid( Uuid $uuid ){
+    /**
+     * Ask if the model has a universal identifier.
+     *
+     * @return bool
+     */
+    public function hasUuid(){
+        return ( isset($this->uuid) && $this->uuid !== "" );
+    }
+
+    /**
+     * Set the universal identifier via existing UUID.
+     *
+     * @param \Ramsey\Uuid\Uuid $uuid
+     *
+     * @return void
+     */
+    public function setRawUuid( Uuid $uuid ){
         $this->uuid = $uuid;
         $this->save();
     }
 
+    /**
+     * Add the UUID and Meta columns to the table.
+     * 
+     * @param \Illuminate\Database\Schema\Blueprint
+     *
+     * @return void
+     */
     public static function formTable( Blueprint $table ){
         $table->uuid('uuid');
         $table->text('meta');
     }
 
     public static function route(){}
-
 }

src/MetaServiceProvider.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Glmdev\Meta;
+
+use Glmdev\Meta\Contracts;
+use Glmdev\Meta\Meta;
+use Illuminate\Support\ServiceProvider;
+
+class MetaServiceProvider extends ServiceProvider
+{
+    /**
+     * Indicates if loading of the provider is deferred.
+     *
+     * @var bool
+     */
+    protected $defer = true;
+    
+    /**
+     * Register any package services.
+     *
+     * @return void
+     */
+    public function register()
+    {
+        $this->app->bind(Contracts\Meta::class, 'Meta');
+    }
+    
+    /**
+     * Get the services provided by the provider.
+     *
+     * @return array
+     */
+    public function provides()
+    {
+        return [
+            Contracts\Meta::class,
+            'Meta',
+        ];
+    }
+}

tests/MetaTest.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Glmdev\Meta\Tests;
+
+use Glmdev\Meta\Meta;
+
+class MetaTest extends \PHPUnit_Framework_TestCase
+{
+    // TODO: write tests
+    
+    public function testItReturnsTrue ()
+    {
+        $this->assertTrue(true);
+    }
+}