Adds v2.1 functionality

Author: peterfox

README.md

@@ -234,6 +234,7 @@ Features::noScheduling();
 Features::noValidations();
 Features::noCommands();
 Features::noMiddlewares();
+Features::noQueryBuilderMixin();
 ```
 
 ## Usage
@@ -301,6 +302,22 @@ $schedule->command('emails:send Peter --force')
     ->skipWithoutFeature('my-other-feature')    
 ```
 
+### Query Builder
+
+A useful extension of this package is also in being able to decide if part of a query should occur if a feature is
+enabled or disabled.
+
+```php
+$results = DB::table('users')
+    ->whenFeatureIsAccessible('my-feature', function (Builder $query) {
+        return $query->where('type', 'new');
+    })
+    ->whenFeatureIsNotAccessible('my-feature', function (Builder $query) {
+        return $query->where('type', 'old');
+    })
+    ->get();
+```
+
 ### Artisan Commands
 
 You may run the following commands to toggle the on or off state of the feature.
@@ -311,6 +328,36 @@ php artisan feature:on <gateway> <feature>
 php artisan feature:off <gateway> <feature>
 ```
 
+### Cleaning up Features
+
+Often when working with feature flags you will want to remove flags frequently but aren't clear where
+such flags are referenced within the application you're developing. To help with this you can then
+add a list of features that you have expired. When these features are accessed, an exception will be thrown.
+
+This is useful when used in conjunction with a test suit.
+
+```php
+Features::callOnExpiredFeatures([
+    'my-feature',
+])
+```
+
+You may also customise this and provide your own callback if you wish to.
+
+```php
+Features::callOnExpiredFeatures([
+    'my-feature',
+], function (string $feature): void {
+    logger()->debug('Expired Feature!', ['feature' => $feature]);
+})
+```
+
+You can even implement your own `ExpiredFeaturesHandler` which decides how a feature is expired etc.
+
+```php
+Features::applyOnExpiredHandler(new CustomExpiredFeaturesHandler));
+```
+
 ### Implementing your Own Gateway Drivers
 
 You can create your own gateway drivers. To do so you will need to make your own class
@@ -361,7 +408,73 @@ Then you only need use it in your `features.php` config.
 
 You may also make your driver be `Toggleable` and `Cacheable`
 
-## Testing
+### Writing tests with Flags
+
+There is a simple Features Fake that can be used when writing tests. You can do so by simply listing the
+feature you wish to be faked.
+
+```php
+Features::fake(['my-feature' => true])
+```
+
+If you know a feature will be called multiple times that you wish to change the state of during the test you
+can supply and array of values which will be used.
+
+```php
+Features::fake(['my-feature' => [true, false, true]])
+```
+
+There are then also assertions that can be used to check if a feature was or was not accessed and how many 
+times it was accessed during the test.
+
+```php
+Features::assertAccessed('my-feature');
+Features::assertAccessedCount('my-feature', 2);
+Features::assertNotAccessed('my-feature');
+```
+
+If you are using the service container to resolve the `Features` class you must inject the service using the
+`Accessibles` contract.
+
+```php
+public function get(\YlsIdeas\FeatureFlags\Contracts\Features $features)
+{
+    $features->accessible('my-feature');
+}
+```
+
+### Debugging Flag access
+
+If you wish to see what features are being accessed during a request you can enable the debug mode.
+
+```php
+Features::configureDebugging();
+```
+
+Then using an event listener you can use the ActionDebugLog to inspect how the decision was made, such as
+which gateway responded or if it came from the cache.
+
+```php
+\Illuminate\Support\Facades\Event::listen(
+    \YlsIdeas\FeatureFlags\Events\FeatureAccessed::class, 
+    function (\YlsIdeas\FeatureFlags\Events\FeatureAccessed $event) {
+        $event->log->file; // the file that accessed the feature
+        $event->log->line; // the line of the file that accessed the feature
+        // the decisions made by each gateway in order of access
+        // e.g. [
+        //  ['pipe' => 'redis', 'reason' => ActionDebugLog::REASON_NO_RESULT, 'result' => false],
+        //  ['pipe' => 'database', 'reason' => ActionDebugLog::REASON_RESULT, 'result' => true],
+        // ]
+        $event->log->decisions;
+    }
+);
+```
+
+Logging this information can then help you if you're finding that a feature is not behaving as expected.
+
+## Package Testing
+
+If you wish to develop new features for this package you may run the tests using the following command.
 
 ``` bash
 composer test

src/ActionableFlag.php

@@ -2,12 +2,14 @@
 
 namespace YlsIdeas\FeatureFlags;
 
-use YlsIdeas\FeatureFlags\Contracts\ActionableFlag as ActionableFlagContract;
+use YlsIdeas\FeatureFlags\Contracts\DebuggableFlag as ActionableFlagContract;
+use YlsIdeas\FeatureFlags\Support\ActionDebugLog;
 
 class ActionableFlag implements ActionableFlagContract
 {
     public string $feature;
     public ?bool $result = null;
+    public ?Support\ActionDebugLog $debug = null;
 
     public function feature(): string
     {
@@ -28,4 +30,19 @@ public function hasResult(): bool
     {
         return ! is_null($this->result);
     }
+
+    public function isDebuggable(): bool
+    {
+        return (bool) $this->debug;
+    }
+
+    public function storeInspectionInformation(string $pipe, string $reason, ?bool $result = null)
+    {
+        $this->debug->addDecision($pipe, $reason, $result);
+    }
+
+    public function log(): ?ActionDebugLog
+    {
+        return $this->debug;
+    }
 }

src/Contracts/DebuggableFlag.php

@@ -0,0 +1,14 @@
+<?php
+
+namespace YlsIdeas\FeatureFlags\Contracts;
+
+use YlsIdeas\FeatureFlags\Support\ActionDebugLog;
+
+interface DebuggableFlag extends ActionableFlag
+{
+    public function isDebuggable(): bool;
+
+    public function storeInspectionInformation(string $pipe, string $reason, ?bool $result = null);
+
+    public function log(): ?ActionDebugLog;
+}

src/Contracts/ExpiredFeaturesHandler.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace YlsIdeas\FeatureFlags\Contracts;
+
+interface ExpiredFeaturesHandler
+{
+    public function isExpired(string $feature): void;
+}

src/Contracts/Features.php

@@ -0,0 +1,8 @@
+<?php
+
+namespace YlsIdeas\FeatureFlags\Contracts;
+
+interface Features
+{
+    public function accessible(string $feature): bool;
+}

src/Events/FeatureAccessed.php

@@ -2,12 +2,14 @@
 
 namespace YlsIdeas\FeatureFlags\Events;
 
+use YlsIdeas\FeatureFlags\Support\ActionDebugLog;
+
 /**
  * @see \YlsIdeas\FeatureFlags\Tests\Events\FeatureAccessedTest
  */
 class FeatureAccessed
 {
-    public function __construct(public string $feature, public ?bool $result)
+    public function __construct(public string $feature, public ?bool $result, public ?ActionDebugLog $log = null)
     {
     }
 }

src/Events/FeatureAccessing.php

@@ -2,12 +2,14 @@
 
 namespace YlsIdeas\FeatureFlags\Events;
 
+use YlsIdeas\FeatureFlags\Support\ActionDebugLog;
+
 /**
  * @see \YlsIdeas\FeatureFlags\Tests\Events\FeatureAccessingTest
  */
 class FeatureAccessing
 {
-    public function __construct(public string $feature)
+    public function __construct(public string $feature, public ?ActionDebugLog $log = null)
     {
     }
 }

src/Exceptions/FeatureExpired.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace YlsIdeas\FeatureFlags\Exceptions;
+
+class FeatureExpired extends \RuntimeException
+{
+    public function __construct(
+        protected string $feature,
+        string $message = "",
+        int $code = 0,
+        ?\Throwable $previous = null
+    ) {
+        parent::__construct($message, $code, $previous);
+    }
+
+    protected function feature(): string
+    {
+        return $this->feature;
+    }
+}

src/ExpiredFeaturesHandler.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace YlsIdeas\FeatureFlags;
+
+use YlsIdeas\FeatureFlags\Contracts\ExpiredFeaturesHandler as ExpiredFeaturesHandlerContract;
+
+/**
+ * @see \YlsIdeas\FeatureFlags\Tests\ExpiredFeaturesHandlerTest
+ */
+class ExpiredFeaturesHandler implements ExpiredFeaturesHandlerContract
+{
+    /**
+     * @var callable
+     */
+    protected mixed $handler;
+
+    public function __construct(protected array $features, callable $handler)
+    {
+        $this->handler = $handler;
+    }
+
+    public function isExpired(string $feature): void
+    {
+        if (in_array($feature, $this->features)) {
+            call_user_func($this->handler, $feature);
+        }
+    }
+}

src/Facades/Features.php

@@ -3,29 +3,47 @@
 namespace YlsIdeas\FeatureFlags\Facades;
 
 use Illuminate\Support\Facades\Facade;
+use YlsIdeas\FeatureFlags\Contracts\ExpiredFeaturesHandler;
+use YlsIdeas\FeatureFlags\Contracts\Features as FeaturesContract;
 use YlsIdeas\FeatureFlags\Manager;
+use YlsIdeas\FeatureFlags\Support\FeatureFake;
 
 /**
  * @see \YlsIdeas\FeatureFlags\Manager
  *
  * @method static bool accessible(string $feature)
- * @method static turnOn(string $gateway, string $feature)
- * @method static turnOff(string $gateway, string $feature)
+ * @method static void turnOn(string $gateway, string $feature)
+ * @method static void turnOff(string $gateway, string $feature)
  * @method static bool usesValidations()
  * @method static bool usesScheduling()
  * @method static bool usesBlade()
  * @method static bool usesCommands()
  * @method static bool usesMiddlewares()
+ * @method static bool usesQueryBuilderMixin()
  * @method static Manager noValidations()
  * @method static Manager noScheduling()
  * @method static Manager noBlade()
  * @method static Manager noCommands()
  * @method static Manager noMiddleware()
+ * @method static Manager noQueryBuilderMixin()
+ * @method static Manager callOnExpiredFeatures(array $features, callable $handler)
+ * @method static Manager applyOnExpiredHandler(ExpiredFeaturesHandler $handler)
  */
 class Features extends Facade
 {
+    /**
+     * Replace the bound instance with a fake.
+     * @param array<string, bool|array> $flagsToFake
+     */
+    public static function fake(array $flagsToFake): FeatureFake
+    {
+        static::swap($fake = new FeatureFake(static::getFacadeRoot(), $flagsToFake));
+
+        return $fake;
+    }
+
     protected static function getFacadeAccessor(): string
     {
-        return Manager::class;
+        return FeaturesContract::class;
     }
 }

src/FeatureFlagsServiceProvider.php

@@ -3,14 +3,16 @@
 namespace YlsIdeas\FeatureFlags;
 
 use Illuminate\Console\Scheduling\Event;
+use Illuminate\Database\Query\Builder;
 use Illuminate\Routing\Router;
 use Illuminate\Support\Facades\Blade;
 use Illuminate\Support\Facades\Validator;
 use Illuminate\Support\ServiceProvider;
-use YlsIdeas\FeatureFlags\Contracts\Gateway;
+use YlsIdeas\FeatureFlags\Contracts\Features as FeaturesContract;
 use YlsIdeas\FeatureFlags\Facades\Features;
 use YlsIdeas\FeatureFlags\Middlewares\GuardFeature;
 use YlsIdeas\FeatureFlags\Rules\FeatureOnRule;
+use YlsIdeas\FeatureFlags\Support\QueryBuilderMixin;
 
 /**
  * @see \YlsIdeas\FeatureFlags\Tests\FeatureFlagsServiceProviderTest
@@ -62,6 +64,10 @@ public function boot()
             $this->app->make(Router::class)
                 ->aliasMiddleware('feature', GuardFeature::class);
         }
+
+        if (Features::usesQueryBuilderMixin()) {
+            $this->queryBuilder();
+        }
     }
 
     /**
@@ -73,9 +79,9 @@ public function register()
         $this->mergeConfigFrom(__DIR__.'/../config/features.php', 'features');
 
         if (method_exists($this->app, 'scoped')) {
-            $this->app->scoped(Gateway::class, Manager::class);
+            $this->app->scoped(FeaturesContract::class, Manager::class);
         } else {
-            $this->app->singleton(Gateway::class, Manager::class);
+            $this->app->singleton(FeaturesContract::class, Manager::class);
         }
     }
 
@@ -109,4 +115,9 @@ protected function validator()
     {
         Validator::extendImplicit('requiredWithFeature', FeatureOnRule::class);
     }
+
+    protected function queryBuilder()
+    {
+        Builder::mixin(new QueryBuilderMixin());
+    }
 }