Merge pull request #1 from cybercog/feature/is-kept-flag

Add Kept flag

Author: Pe Ell

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to `laravel-eloquent-flag` will be documented in this file.
 
+## 1.2.0 - 2016-12-10
+
+- `is_kept` flag added.
+
 ## 1.1.0 - 2016-09-25
 
 - `is_published` flag added.

README.md

@@ -5,12 +5,13 @@
 [![Releases](https://img.shields.io/github/release/cybercog/laravel-eloquent-flag.svg?style=flat-square)](https://github.com/cybercog/laravel-eloquent-flag/releases)
 [![License](https://img.shields.io/github/license/cybercog/laravel-eloquent-flag.svg?style=flat-square)](https://github.com/cybercog/laravel-eloquent-flag/blob/master/LICENSE)
 
-Eloquent flagged attributes behavior.
+Eloquent flagged attributes behavior. Add commonly used flags to models very quick and easy.
 
 ## Available flags list
 
 - `is_active`
 - `is_published`
+- `is_kept`
 
 ## Installation
 
@@ -132,6 +133,87 @@ Post::where('id', 4)->publish();
 Post::where('id', 4)->unpublish();
 ```
 
+### Setup a keepable model
+
+Keep functionality required when you are trying to attach related models before parent one isn't saved.
+
+**Issue:**
+
+1. User press `Create Post` button.
+2. Create post form has image uploader.
+3. On image uploading user can't attach image to post before it wouldn't been stored in database.
+
+**Solution:**
+
+1. Add `HasKeptFlag` trait to model (and add boolean `is_kept` column to database).
+2. Create empty model on form loading (it will has `is_kept = 0` by default).
+3. Feel free to add any relations to the model.
+
+*Model will be marked as required to be kept as soon as client will save\update model for the first time.*
+
+*Remove the unkept models on a predetermined schedule (once a week for example).*
+
+```php
+<?php
+
+namespace App\Models;
+
+use Cog\Flag\Traits\HasKeptFlag;
+use Illuminate\Database\Eloquent\Model;
+
+class Post extends Model
+{
+    use HasKeptFlag;
+}
+```
+
+Your model is now can be marked to be kept!
+
+*Model must have boolean `is_kept` column in database table.*
+
+By default all records that have a `is_kept` equals to 0 will be excluded from your query results. To include unkept records, all you need to do is call the `withUnkept()` method on your query.
+
+### Available functions
+
+#### Get only kept models
+
+```shell
+Post::all();
+Post::withoutUnkept();
+```
+
+#### Get only unkept models
+
+```shell
+Post::onlyUnkept();
+```
+
+#### Get kept + unkept models
+
+```shell
+Post::withUnkept();
+```
+
+#### Keep model
+
+```shell
+Post::where('id', 4)->keep();
+```
+
+#### Unkeep model
+
+```shell
+Post::where('id', 4)->unkeep();
+```
+
+#### Get unkept models which older than hours
+
+```shell
+Post::onlyUnkeptOlderThanHours(4);
+```
+
+Output will have all unkept models created earlier than 4 hours ago.
+
 ## Testing
 
 Run the tests with:

src/Scopes/ActiveFlagScope.php

@@ -11,8 +11,8 @@
 
 namespace Cog\Flag\Scopes;
 
-use Illuminate\Database\Eloquent\Scope;
 use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Scope;
 use Illuminate\Database\Eloquent\Builder;
 
 /**
@@ -55,7 +55,7 @@ public function extend(Builder $builder)
     }
 
     /**
-     * Add the activate extension to the builder.
+     * Add the `activate` extension to the builder.
      *
      * @param \Illuminate\Database\Eloquent\Builder $builder
      * @return void
@@ -70,7 +70,7 @@ protected function addActivate(Builder $builder)
     }
 
     /**
-     * Add the deactivate extension to the builder.
+     * Add the `deactivate` extension to the builder.
      *
      * @param \Illuminate\Database\Eloquent\Builder $builder
      * @return void
@@ -83,7 +83,7 @@ protected function addDeactivate(Builder $builder)
     }
 
     /**
-     * Add the with-inactive extension to the builder.
+     * Add the `withInactive` extension to the builder.
      *
      * @param \Illuminate\Database\Eloquent\Builder $builder
      * @return void
@@ -96,7 +96,7 @@ protected function addWithInactive(Builder $builder)
     }
 
     /**
-     * Add the without-inactive extension to the builder.
+     * Add the `withoutInactive` extension to the builder.
      *
      * @param \Illuminate\Database\Eloquent\Builder $builder
      * @return void
@@ -109,7 +109,7 @@ protected function addWithoutInactive(Builder $builder)
     }
 
     /**
-     * Add the only-inactive extension to the builder.
+     * Add the `onlyInactive` extension to the builder.
      *
      * @param \Illuminate\Database\Eloquent\Builder $builder
      * @return void

src/Scopes/KeptFlagScope.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 KeptFlagScope.
+ *
+ * @package Cog\Flag\Scopes
+ */
+class KeptFlagScope implements Scope
+{
+    /**
+     * All of the extensions to be added to the builder.
+     *
+     * @var array
+     */
+    protected $extensions = ['Keep', 'Unkeep', 'WithUnkept', 'WithoutUnkept', 'OnlyUnkept'];
+
+    /**
+     * 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_kept', 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 `keep` extension to the builder.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $builder
+     * @return void
+     */
+    protected function addKeep(Builder $builder)
+    {
+        $builder->macro('keep', function (Builder $builder) {
+            $builder->withUnkept();
+
+            return $builder->update(['is_kept' => 1]);
+        });
+    }
+
+    /**
+     * Add the `unkeep` extension to the builder.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $builder
+     * @return void
+     */
+    protected function addUnkeep(Builder $builder)
+    {
+        $builder->macro('unkeep', function (Builder $builder) {
+            return $builder->update(['is_kept' => 0]);
+        });
+    }
+
+    /**
+     * Add the `withUnkept` extension to the builder.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $builder
+     * @return void
+     */
+    protected function addWithUnkept(Builder $builder)
+    {
+        $builder->macro('withUnkept', function (Builder $builder) {
+            return $builder->withoutGlobalScope($this);
+        });
+    }
+
+    /**
+     * Add the `withoutUnkept` extension to the builder.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $builder
+     * @return void
+     */
+    protected function addWithoutUnkept(Builder $builder)
+    {
+        $builder->macro('withoutUnkept', function (Builder $builder) {
+            return $builder->withoutGlobalScope($this)->where('is_kept', 1);
+        });
+    }
+
+    /**
+     * Add the `onlyUnkept` extension to the builder.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $builder
+     * @return void
+     */
+    protected function addOnlyUnkept(Builder $builder)
+    {
+        $builder->macro('onlyUnkept', function (Builder $builder) {
+            return $builder->withoutGlobalScope($this)->where('is_kept', 0);
+        });
+    }
+}

src/Scopes/PublishedFlagScope.php

@@ -11,8 +11,8 @@
 
 namespace Cog\Flag\Scopes;
 
-use Illuminate\Database\Eloquent\Scope;
 use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Scope;
 use Illuminate\Database\Eloquent\Builder;
 
 /**
@@ -55,7 +55,7 @@ public function extend(Builder $builder)
     }
 
     /**
-     * Add the publish extension to the builder.
+     * Add the `publish` extension to the builder.
      *
      * @param \Illuminate\Database\Eloquent\Builder $builder
      * @return void
@@ -70,7 +70,7 @@ protected function addPublish(Builder $builder)
     }
 
     /**
-     * Add the unpublish extension to the builder.
+     * Add the `unpublish` extension to the builder.
      *
      * @param \Illuminate\Database\Eloquent\Builder $builder
      * @return void
@@ -83,7 +83,7 @@ protected function addUnpublish(Builder $builder)
     }
 
     /**
-     * Add the with-unpublished extension to the builder.
+     * Add the `withUnpublished` extension to the builder.
      *
      * @param \Illuminate\Database\Eloquent\Builder $builder
      * @return void
@@ -96,7 +96,7 @@ protected function addWithUnpublished(Builder $builder)
     }
 
     /**
-     * Add the without-unpublished extension to the builder.
+     * Add the `withoutUnpublished` extension to the builder.
      *
      * @param \Illuminate\Database\Eloquent\Builder $builder
      * @return void
@@ -109,7 +109,7 @@ protected function addWithoutUnpublished(Builder $builder)
     }
 
     /**
-     * Add the only-unpublished extension to the builder.
+     * Add the `onlyUnpublished` extension to the builder.
      *
      * @param \Illuminate\Database\Eloquent\Builder $builder
      * @return void