Merge pull request #6 from cybercog/feature/is-approved-flag

Add Approved flag

Author: Pe Ell

CHANGELOG.md

@@ -2,22 +2,26 @@
 
 All notable changes to `laravel-eloquent-flag` will be documented in this file.
 
+## 1.5.0 - 2016-12-31
+
+- `is_approved` boolean flag added.
+
 ## 1.4.0 - 2016-12-26
 
-- `is_verified` flag added.
+- `is_verified` boolean flag added.
 
 ## 1.3.0 - 2016-12-14
 
-- `is_accepted` flag added.
+- `is_accepted` boolean flag added.
 
 ## 1.2.0 - 2016-12-10
 
-- `is_kept` flag added.
+- `is_kept` boolean flag added.
 
 ## 1.1.0 - 2016-09-25
 
-- `is_published` flag added.
+- `is_published` boolean flag added.
 
 ## 1.0.0 - 2016-09-25
 
-- Initial release with only `is_active` flag.
+- `is_active` boolean flag added.

README.md

@@ -22,6 +22,7 @@ Eloquent flagged attributes behavior. Add commonly used flags to models very qui
 | ---------- | ---------------- | --------- |
 | `HasAcceptedFlag` | `is_accepted` | Boolean |
 | `HasActiveFlag` | `is_active` | Boolean |
+| `HasApprovedFlag` | `is_approved` | Boolean |
 | `HasKeptFlag` | `is_kept` | Boolean |
 | `HasPublishedFlag` | `is_published` | Boolean |
 | `HasVerifiedFlag` | `is_verified` | Boolean |
@@ -154,6 +155,57 @@ Post::where('id', 4)->accept();
 Post::where('id', 4)->unaccept();
 ```
 
+### Setup an approvable model
+
+```php
+<?php
+
+namespace App\Models;
+
+use Cog\Flag\Traits\HasApprovedFlag;
+use Illuminate\Database\Eloquent\Model;
+
+class Post extends Model
+{
+    use HasApprovedFlag;
+}
+```
+
+*Model must have boolean `is_approved` column in database table.*
+
+### Available functions
+
+#### Get only approved models
+
+```shell
+Post::all();
+Post::withoutUnapproved();
+```
+
+#### Get only unapproved models
+
+```shell
+Post::onlyUnapproved();
+```
+
+#### Get approved + unapproved models
+
+```shell
+Post::withUnapproved();
+```
+
+#### Approve model
+
+```shell
+Post::where('id', 4)->approve();
+```
+
+#### Unapprove model
+
+```shell
+Post::where('id', 4)->unapprove();
+```
+
 ### Setup a publishable model
 
 ```php
@@ -365,6 +417,8 @@ If you discover any security related issues, please email [email protected] in
 
 *Not found.*
 
+*Feel free to add more alternatives as Pull Request.*
+
 ## License
 
 - `Laravel Eloquent Flag` package is open-sourced software licensed under the [MIT license](LICENSE).

composer.json

@@ -1,6 +1,32 @@
 {
     "name": "cybercog/laravel-eloquent-flag",
     "description": "Laravel Eloquent flagged attributes behavior",
+    "type": "library",
+    "license": "MIT",
+    "keywords": [
+        "cybercog",
+        "cog",
+        "laravel",
+        "trait",
+        "scopes",
+        "flag",
+        "boolean",
+        "timestamp",
+        "accepted",
+        "unaccepted",
+        "active",
+        "activated",
+        "deactivated",
+        "kept",
+        "unkept",
+        "published",
+        "unpublished",
+        "verified",
+        "unverified",
+        "persisted",
+        "approved",
+        "unapproved"
+    ],
     "authors": [
         {
             "name": "Anton Komarev",
@@ -9,11 +35,17 @@
             "role": "Developer"
         }
     ],
-    "license": "MIT",
-    "type": "library",
+    "homepage": "https://github.com/cybercog/laravel-eloquent-flag",
+    "support": {
+        "email": "[email protected]",
+        "issues": "https://github.com/cybercog/laravel-eloquent-flag/issues",
+        "wiki": "https://github.com/cybercog/laravel-eloquent-flag/wiki",
+        "source": "https://github.com/cybercog/laravel-eloquent-flag",
+        "docs": "https://github.com/cybercog/laravel-eloquent-flag/wiki"
+    },
     "require": {
         "php": "^5.6|^7.0",
-        "illuminate/database": "~5.2.0|~5.3.0"
+        "illuminate/database": "~5.2.0|~5.3.0|~5.4.0"
     },
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^1.11",
@@ -30,5 +62,8 @@
         "psr-4": {
             "Cog\\Flag\\Tests\\": "tests/"
         }
+    },
+    "config": {
+        "sort-packages": true
     }
 }

src/Scopes/ApprovedFlagScope.php

@@ -0,0 +1,123 @@
+<?php
+
+/*
+ * This file is part of Laravel Eloquent Flag.
+ *
+ * (c) CyberCog <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Cog\Flag\Scopes;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Scope;
+use Illuminate\Database\Eloquent\Builder;
+
+/**
+ * Class ApprovedFlagScope.
+ *
+ * @package Cog\Flag\Scopes
+ */
+class ApprovedFlagScope implements Scope
+{
+    /**
+     * All of the extensions to be added to the builder.
+     *
+     * @var array
+     */
+    protected $extensions = ['Approve', 'Unapprove', 'WithUnapproved', 'WithoutUnapproved', 'OnlyUnapproved'];
+
+    /**
+     * Apply the scope to a given Eloquent query builder.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $builder
+     * @param \Illuminate\Database\Eloquent\Model $model
+     * @return \Illuminate\Database\Eloquent\Builder
+     */
+    public function apply(Builder $builder, Model $model)
+    {
+        return $builder->where('is_approved', 1);
+    }
+
+    /**
+     * Extend the query builder with the needed functions.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $builder
+     * @return void
+     */
+    public function extend(Builder $builder)
+    {
+        foreach ($this->extensions as $extension) {
+            $this->{"add{$extension}"}($builder);
+        }
+    }
+
+    /**
+     * Add the `approve` extension to the builder.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $builder
+     * @return void
+     */
+    protected function addApprove(Builder $builder)
+    {
+        $builder->macro('approve', function (Builder $builder) {
+            $builder->withUnapproved();
+
+            return $builder->update(['is_approved' => 1]);
+        });
+    }
+
+    /**
+     * Add the `unapprove` extension to the builder.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $builder
+     * @return void
+     */
+    protected function addUnapprove(Builder $builder)
+    {
+        $builder->macro('unapprove', function (Builder $builder) {
+            return $builder->update(['is_approved' => 0]);
+        });
+    }
+
+    /**
+     * Add the `withUnapproved` extension to the builder.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $builder
+     * @return void
+     */
+    protected function addWithUnapproved(Builder $builder)
+    {
+        $builder->macro('withUnapproved', function (Builder $builder) {
+            return $builder->withoutGlobalScope($this);
+        });
+    }
+
+    /**
+     * Add the `withoutUnapproved` extension to the builder.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $builder
+     * @return void
+     */
+    protected function addWithoutUnapproved(Builder $builder)
+    {
+        $builder->macro('withoutUnapproved', function (Builder $builder) {
+            return $builder->withoutGlobalScope($this)->where('is_approved', 1);
+        });
+    }
+
+    /**
+     * Add the `onlyUnapproved` extension to the builder.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $builder
+     * @return void
+     */
+    protected function addOnlyUnapproved(Builder $builder)
+    {
+        $builder->macro('onlyUnapproved', function (Builder $builder) {
+            return $builder->withoutGlobalScope($this)->where('is_approved', 0);
+        });
+    }
+}

src/Traits/HasAcceptedFlag.php

@@ -21,7 +21,7 @@
 trait HasAcceptedFlag
 {
     /**
-     * Boot the has accepted flag trait for a model.
+     * Boot the HasAcceptedFlag trait for a model.
      *
      * @return void
      */

src/Traits/HasActiveFlag.php

@@ -21,7 +21,7 @@
 trait HasActiveFlag
 {
     /**
-     * Boot the has active flag trait for a model.
+     * Boot the HasKeptFlag trait for a model.
      *
      * @return void
      */

src/Traits/HasApprovedFlag.php

@@ -0,0 +1,32 @@
+<?php
+
+/*
+ * This file is part of Laravel Eloquent Flag.
+ *
+ * (c) CyberCog <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Cog\Flag\Traits;
+
+use Cog\Flag\Scopes\ApprovedFlagScope;
+
+/**
+ * Class HasApprovedFlag.
+ *
+ * @package Cog\Flag\Traits
+ */
+trait HasApprovedFlag
+{
+    /**
+     * Boot the HasApprovedFlag trait for a model.
+     *
+     * @return void
+     */
+    public static function bootHasApprovedFlag()
+    {
+        static::addGlobalScope(new ApprovedFlagScope);
+    }
+}

src/Traits/HasKeptFlag.php

@@ -23,7 +23,7 @@
 trait HasKeptFlag
 {
     /**
-     * Boot the has kept flag trait for a model.
+     * Boot the HasKeptFlag trait for a model.
      *
      * @return void
      */

src/Traits/HasPublishedFlag.php

@@ -21,7 +21,7 @@
 trait HasPublishedFlag
 {
     /**
-     * Boot the has published flag trait for a model.
+     * Boot the HasPublishedFlag trait for a model.
      *
      * @return void
      */

tests/database/factories/EntityWithApprovedFlagFactory.php

@@ -0,0 +1,17 @@
+<?php
+
+/*
+ * This file is part of Laravel Eloquent Flag.
+ *
+ * (c) CyberCog <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+$factory->define(\Cog\Flag\Tests\Stubs\Models\EntityWithApprovedFlag::class, function (\Faker\Generator $faker) {
+    return [
+        'name' => $faker->word,
+        'is_approved' => true,
+    ];
+});