Merge branch 'refs/heads/pr/2'

.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,130 @@
-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, 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'
+```
+
+### 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
@@ -13,3 +139,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,6 +9,20 @@
         }
     ],
     "require": {
+<<<<<<< HEAD
+        "illuminate/support": "^5.2",
+        "illuminate/database": "^5.2",
+        "ramsey/uuid": "^3.4",
+        "glmdev/foundation": "^0.0.10"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "~4.0"
+    },
+    "autoload": {
+        "psr-4": {
+            "Glmdev\\Meta\\": "src/",
+            "Glmdev\\Meta\\Tests\\": "tests/"
+=======
         "ramsey/uuid": "^3.2",
         "glmdev/foundation": "*"
     },
@@ -16,6 +30,7 @@
         "psr-4": {
             "AppRoot\\": "../../../app/",
             "Glmdev\\Meta\\": "src/"
+>>>>>>> refs/remotes/origin/master
         }
     }
 }

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,25 @@
+<?php
+
+use Illuminate\Database\Capsule\Manager as Capsule;
+use Illuminate\Database\Schema\Blueprint;
+use Glmdev\Meta\Meta;
+
+require __DIR__ . '/vendor/autoload.php'; 
+
+date_default_timezone_set('UTC');
+
+/*
+ * Prepare the db connection (spoofing that shit)
+ */
+$capsule = new Capsule;
+$capsule->addConnection([
+  'driver'   => 'sqlite',
+  'database' => ':memory:',
+]);
+$capsule->setAsGlobal();
+$capsule->bootEloquent();
+$capsule->schema()->dropIfExists('metas');
+$capsule->schema()->create('metas', function (Blueprint $table) {
+    $table->timestamps();
+    Meta::formTable($table);
+});

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,89 @@
+<?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|array $keyOrArray
+     * @param string|int|float|array|bool|null $value
+     *
+     * @return void
+     */
+    public function write( $keyOrArray, $value = null );
+
+    /**
+     * 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 );
+    
+    /**
+     * Get the model that has this UUID.
+     * 
+     * @param string $uuid
+     * 
+     * @return \Illuminate\Database\Eloquent\Builder
+     */
+    public static function withUuid( $uuid );
+}

src/Meta.php

@@ -1,77 +1,166 @@
 <?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'])) ? ((gettype($args['meta']) === 'array') ? serialize($args['meta']) : $args['meta']) : serialize([]);
+        $args['uuid'] = (isset($args['uuid'])) ? $args['uuid'] : Uuid::uuid4();
+
+        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;
     }
+
+    /**
+     * Adds the key-value pair into the serialized data set.
+     *
+     * @param string|int|array $keyOrArray
+     * @param string|int|float|array|bool|null $value
+     *
+     * @return void
+     */
+    public function write( $keyOrArray, $value = null ){
+        $meta = unserialize( $this->meta );
+
+        if( is_array( $keyOrArray ) ){
+            foreach( $keyOrArray as $key => $val ){
+                $meta[ $key ] = $val;
+            }
+        } else {
+            $meta[ $keyOrArray ] = $value;
         }
 
-    function write( $key, $value ){
-        $meta = unserialize( $this->meta );
-        $meta[ $key ] = $value;
         $meta = serialize( $meta );
         $this->meta = $meta;
         $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();
     }
     
+    /**
+     * Get the model that has this UUID.
+     * 
+     * @param string $uuid
+     * 
+     * @return \Illuminate\Database\Eloquent\Builder
+     */
+    public static function withUuid( $uuid ){
+        return parent::where('uuid', $uuid);
+    }
+
+    /**
+     * 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(){}
+<<<<<<< HEAD
+=======
 
     public static function create( array $args ){
         $args['meta'] = serialize([]);
@@ -80,4 +169,5 @@ class Meta extends Model implements FoundationModel
         return parent::create($args);
     }
 
+>>>>>>> refs/remotes/origin/master
 }

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,54 @@
+<?php
+
+namespace Glmdev\Meta\Tests;
+
+use Glmdev\Meta\Meta;
+use Ramsey\Uuid\Uuid;
+
+class MetaTest extends \PHPUnit_Framework_TestCase
+{
+    public function testReadWrite ()
+    {
+        $model = Meta::create();
+
+        $model->write('name', 'John');
+        $model->write('age', 15);
+        $model->write('true', false);
+
+        $model->write([
+            'food' => 'taco',
+            'old' => 'spice',
+            'new' => 1935
+        ]);
+
+        $this->assertEquals('John', $model->read('name'));
+        $this->assertEquals(15, $model->read('age'));
+        $this->assertEquals(false, $model->read('true'));
+
+        $this->assertEquals('taco', $model->read('food'));
+        $this->assertEquals('spice', $model->read('old'));
+        $this->assertEquals(1935, $model->read('new'));
+    }
+    
+    public function testUuid ()
+    {
+        $model = Meta::create();
+        $uuid = Uuid::uuid4();
+
+        $this->assertTrue($model->hasUuid());
+        
+        $model->setRawUuid($uuid);
+        $this->assertEquals($uuid, $model->getUuid());
+    }
+    
+    public function testUuidQuery ()
+    {
+        $model = Meta::create([
+           'meta' => ['name' => 'Tony']
+        ]);
+
+        $queried = Meta::withUuid($model->getUuid())->first();
+
+        $this->assertEquals($model->read('name'), $queried->read('name'));
+    }
+}