From ea3ec0baccda37fbd8778bcb357d01dd9cc96e91 Mon Sep 17 00:00:00 2001 From: Jake Mitchell Date: Sat, 25 Jun 2016 21:12:01 +0000 Subject: [PATCH] added docblocks, contract, and service provider --- .gitignore | 3 +- .scrutinizer.yml | 4 + .travis.yml | 8 ++ README.md | 134 +++++++++++++++++++++++++++++- composer.json | 12 ++- composer.lock | 145 --------------------------------- contributors.txt | 3 +- phpunit.php | 5 ++ phpunit.xml | 16 ++++ src/Contracts/MetaContract.php | 80 ++++++++++++++++++ src/Meta.php | 121 +++++++++++++++++++++------ src/MetaServiceProvider.php | 40 +++++++++ tests/MetaTest.php | 15 ++++ 13 files changed, 407 insertions(+), 179 deletions(-) create mode 100644 .scrutinizer.yml create mode 100644 .travis.yml delete mode 100644 composer.lock create mode 100644 phpunit.php create mode 100644 phpunit.xml create mode 100644 src/Contracts/MetaContract.php create mode 100644 src/MetaServiceProvider.php create mode 100644 tests/MetaTest.php diff --git a/.gitignore b/.gitignore index a725465..4f4acd3 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ -vendor/ \ No newline at end of file +vendor/ +composer.lock \ No newline at end of file diff --git a/.scrutinizer.yml b/.scrutinizer.yml new file mode 100644 index 0000000..474553d --- /dev/null +++ b/.scrutinizer.yml @@ -0,0 +1,4 @@ +checks: + php: + code_rating: true + duplication: true \ No newline at end of file diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..e246774 --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/README.md b/README.md index 19a54ad..6deda6f 100644 --- a/README.md +++ b/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 + *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 +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 @@ -12,4 +126,20 @@ Laravel Meta-Articles Package 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 . \ No newline at end of file + along with this program. If not, see . + +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 \ No newline at end of file diff --git a/composer.json b/composer.json index 1122ddb..7e45d01 100644 --- a/composer.json +++ b/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/" } } } diff --git a/composer.lock b/composer.lock deleted file mode 100644 index cbb26a3..0000000 --- a/composer.lock +++ /dev/null @@ -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": [] -} diff --git a/contributors.txt b/contributors.txt index 9dc2d57..22c5c68 100644 --- a/contributors.txt +++ b/contributors.txt @@ -1 +1,2 @@ -Garrett Mills \ No newline at end of file +Garrett Mills +Jake Mitchell \ No newline at end of file diff --git a/phpunit.php b/phpunit.php new file mode 100644 index 0000000..50765d6 --- /dev/null +++ b/phpunit.php @@ -0,0 +1,5 @@ + + + + + ./tests + + + diff --git a/src/Contracts/MetaContract.php b/src/Contracts/MetaContract.php new file mode 100644 index 0000000..47bc3df --- /dev/null +++ b/src/Contracts/MetaContract.php @@ -0,0 +1,80 @@ +meta ); + if ( array_key_exists( $key, $meta ) ){ return $meta[ $key ]; } - else { - return null; - } + + 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( !isset($this->uuid) || is_null($this->uuid) || $this->uuid === "" ){ + if( 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(){} - } \ No newline at end of file diff --git a/src/MetaServiceProvider.php b/src/MetaServiceProvider.php new file mode 100644 index 0000000..38c0d00 --- /dev/null +++ b/src/MetaServiceProvider.php @@ -0,0 +1,40 @@ +app->bind(Contracts\Meta::class, 'Meta'); + } + + /** + * Get the services provided by the provider. + * + * @return array + */ + public function provides() + { + return [ + Contracts\Meta::class, + 'Meta', + ]; + } +} diff --git a/tests/MetaTest.php b/tests/MetaTest.php new file mode 100644 index 0000000..7b88928 --- /dev/null +++ b/tests/MetaTest.php @@ -0,0 +1,15 @@ +assertTrue(true); + } +}