Add BannedAtScope (#5)

Add BannedAtScope

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to `laravel-ban` will be documented in this file.
 
+## [2.1.0] - 2017-03-21
+
+### Added
+
+- `withBanned`, `withoutBanned`, `onlyBanned` scopes added to all bannable models
+
+### Changed
+
+- `HasBans` is a collection of traits `HasBannedAtHelpers`, `HasBannedAtScope`, `HasBansRelation` now.
+
 ## [2.0.1] - 2017-03-19
 
 ### Changed
@@ -19,5 +29,6 @@ All notable changes to `laravel-ban` will be documented in this file.
 
 - Initial release
 
+[2.1.0]: https://github.com/cybercog/laravel-ban/compare/2.0.1...2.1.0
 [2.0.1]: https://github.com/cybercog/laravel-ban/compare/2.0.0...2.0.1
 [2.0.0]: https://github.com/cybercog/laravel-ban/compare/1.0.0...2.0.0

README.md

@@ -21,6 +21,7 @@ Use case is not limited to User model, any Eloquent model could be banned: Organ
     - [Prepare bannable model](#prepare-bannable-model)
     - [Prepare bannable model database table](#prepare-bannable-model-database-table)
     - [Available methods](#available-methods)
+    - [Scopes](#scopes)
     - [Events](#events)
     - [Middleware](#middleware)
     - [Scheduling](#scheduling)
@@ -186,6 +187,51 @@ $user->isNotBanned();
 app(\Cog\Ban\Services\BanService::class)->deleteExpiredBans();
 ```
 
+### Scopes
+
+#### Get all models which are not banned
+
+```php
+$users = User::withoutBanned()->get();
+```
+
+#### Get banned and not banned models
+
+```php
+$users = User::withBanned()->get();
+```
+
+#### Get only banned models
+
+```php
+$users = User::onlyBanned()->get();
+```
+
+#### Scope auto-apply
+
+To apply query scopes all the time you can define `shouldApplyBannedAtScope` method in bannable model. If method returns `true` all banned models will be hidden by default.
+
+```php
+use Cog\Ban\Contracts\HasBans as HasBansContract;
+use Cog\Ban\Traits\HasBans;
+use Illuminate\Foundation\Auth\User as Authenticatable;
+
+class User extends Authenticatable implements HasBansContract
+{
+    use HasBans;
+
+    /**
+     * Determine if BannedAtScope should be applied by default.
+     *
+     * @return bool
+     */
+    public function shouldApplyBannedAtScope()
+    {
+        return true;
+    }
+}
+```
+
 ### Events
 
 If entity is banned `\Cog\Ban\Events\ModelWasBanned` event is fired.

src/Scopes/BannedAtScope.php

@@ -0,0 +1,99 @@
+<?php
+
+/*
+ * This file is part of Laravel Ban.
+ *
+ * (c) Anton Komarev <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Cog\Ban\Scopes;
+
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Scope;
+
+/**
+ * Class BannedAtScope.
+ *
+ * @package Cog\Ban\Scopes
+ */
+class BannedAtScope implements Scope
+{
+    /**
+     * All of the extensions to be added to the builder.
+     *
+     * @var array
+     */
+    protected $extensions = ['WithBanned', 'WithoutBanned', 'OnlyBanned'];
+
+    /**
+     * 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)
+    {
+        if (method_exists($model, 'shouldApplyBannedAtScope') && $model->shouldApplyBannedAtScope()) {
+            return $builder->whereNull('banned_at');
+        }
+
+        return $builder;
+    }
+
+    /**
+     * 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 `withBanned` extension to the builder.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $builder
+     * @return void
+     */
+    protected function addWithBanned(Builder $builder)
+    {
+        $builder->macro('withBanned', function (Builder $builder) {
+            return $builder->withoutGlobalScope($this);
+        });
+    }
+
+    /**
+     * Add the `withoutBanned` extension to the builder.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $builder
+     * @return void
+     */
+    protected function addWithoutBanned(Builder $builder)
+    {
+        $builder->macro('withoutBanned', function (Builder $builder) {
+            return $builder->withoutGlobalScope($this)->whereNull('banned_at');
+        });
+    }
+
+    /**
+     * Add the `onlyBanned` extension to the builder.
+     *
+     * @param \Illuminate\Database\Eloquent\Builder $builder
+     * @return void
+     */
+    protected function addOnlyBanned(Builder $builder)
+    {
+        $builder->macro('onlyBanned', function (Builder $builder) {
+            return $builder->withoutGlobalScope($this)->whereNotNull('banned_at');
+        });
+    }
+}

src/Traits/HasBannedAt.php → src/Traits/HasBannedAtHelpers.php

@@ -12,13 +12,14 @@
 namespace Cog\Ban\Traits;
 
 use Carbon\Carbon;
+use Cog\Ban\Contracts\BanService as BanServiceContract;
 
 /**
- * Class HasBannedAt.
+ * Class HasBannedAtHelpers.
  *
  * @package Cog\Ban\Traits
  */
-trait HasBannedAt
+trait HasBannedAtHelpers
 {
     /**
      * Set banned flag.
@@ -63,4 +64,27 @@ public function isNotBanned()
     {
         return !$this->isBanned();
     }
+
+    /**
+     * Ban model.
+     *
+     * @param null|array $attributes
+     * @return \Cog\Ban\Contracts\Ban
+     */
+    public function ban(array $attributes = [])
+    {
+        $ban = app(BanServiceContract::class)->ban($this, $attributes);
+
+        return $ban;
+    }
+
+    /**
+     * Remove ban from model.
+     *
+     * @return void
+     */
+    public function unban()
+    {
+        app(BanServiceContract::class)->unban($this);
+    }
 }

src/Traits/HasBannedAtScope.php

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

src/Traits/HasBans.php

@@ -11,48 +11,14 @@
 
 namespace Cog\Ban\Traits;
 
-use Cog\Ban\Contracts\Ban as BanContract;
-use Cog\Ban\Contracts\BanService as BanServiceContract;
-
 /**
  * Class HasBans.
  *
  * @package Cog\Ban\Traits
  */
 trait HasBans
 {
-    use HasBannedAt;
-
-    /**
-     * Entity Bans.
-     *
-     * @return \Illuminate\Database\Eloquent\Relations\MorphMany
-     */
-    public function bans()
-    {
-        return $this->morphMany(app(BanContract::class), 'owned_by');
-    }
-
-    /**
-     * Ban model.
-     *
-     * @param null|array $attributes
-     * @return \Cog\Ban\Contracts\Ban
-     */
-    public function ban(array $attributes = [])
-    {
-        $ban = app(BanServiceContract::class)->ban($this, $attributes);
-
-        return $ban;
-    }
-
-    /**
-     * Remove ban from model.
-     *
-     * @return void
-     */
-    public function unban()
-    {
-        app(BanServiceContract::class)->unban($this);
-    }
+    use HasBannedAtHelpers,
+        HasBannedAtScope,
+        HasBansRelation;
 }

src/Traits/HasBansRelation.php

@@ -0,0 +1,32 @@
+<?php
+
+/*
+ * This file is part of Laravel Ban.
+ *
+ * (c) Anton Komarev <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Cog\Ban\Traits;
+
+use Cog\Ban\Contracts\Ban as BanContract;
+
+/**
+ * Class HasBansRelation.
+ *
+ * @package Cog\Ban\Traits
+ */
+trait HasBansRelation
+{
+    /**
+     * Entity Bans.
+     *
+     * @return \Illuminate\Database\Eloquent\Relations\MorphMany
+     */
+    public function bans()
+    {
+        return $this->morphMany(app(BanContract::class), 'owned_by');
+    }
+}

tests/stubs/Models/UserWithBannedAtScopeApplied.php

@@ -0,0 +1,30 @@
+<?php
+
+/*
+ * This file is part of Laravel Ban.
+ *
+ * (c) Anton Komarev <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Cog\Ban\Tests\Stubs\Models;
+
+/**
+ * Class UserWithBannedAtScopeApplied.
+ *
+ * @package Cog\Ban\Tests\Stubs\Models
+ */
+class UserWithBannedAtScopeApplied extends User
+{
+    /**
+     * Determine which BannedAtScope should be applied by default.
+     *
+     * @return bool
+     */
+    public function shouldApplyBannedAtScope()
+    {
+        return true;
+    }
+}