wip

Author: riccardodallavia

README.md

@@ -6,7 +6,8 @@
 [![GitHub Code Style Action Status](https://img.shields.io/github/workflow/status/maize-tech/laravel-prunable-fields/Check%20&%20fix%20styling?label=code%20style)](https://github.com/maize-tech/laravel-prunable-fields/actions?query=workflow%3A"Check+%26+fix+styling"+branch%3Amain)
 [![Total Downloads](https://img.shields.io/packagist/dt/maize-tech/laravel-prunable-fields.svg?style=flat-square)](https://packagist.org/packages/maize-tech/laravel-prunable-fields)
 
-This package aims to reproduce the Prunable core feature of Laravel to clean column values instead of entire rows.
+This package allows you to clean model fields with an easy command.
+The feature is highly inspired by Laravel's Prunable core feature, allowing you to easily adapt all your existing models.
 
 ## Installation
 
@@ -16,11 +17,167 @@ You can install the package via composer:
 composer require maize-tech/laravel-prunable-fields
 ```
 
-## Usage
+You can publish the config file with:
+
+```bash
+php artisan vendor:publish --tag="prunable-fields-config"
+```
+
+This is the contents of the published config file:
 
 ```php
-$prunableFields = new Maize\PrunableFields();
-echo $prunableFields->echoPhrase('Hello, Maize!');
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | Prunable models
+    |--------------------------------------------------------------------------
+    |
+    | Here you may specify the list of fully qualified class names of prunable
+    | models.
+    | All models listed here will be pruned when executing the model:prune-fields
+    | command without passing the --model option.
+    |
+    */
+
+    'models' => [
+        // \App\Models\User::class,
+    ],
+
+];
+```
+
+## Usage
+
+### Prunable models
+
+To use the package, simply add the `Maize\PrunableFields\PrunableFields` trait to all models you want to clean.
+
+Once done, you can define the list of attributes who should be cleaned up by implementing the `$prunable` class property.
+The array key should be the attribute name, whereas the array value should be the value you want the attribute to be updated to.
+
+After that, implement the `prunableFields` method which should return an Eloquent query builder that resolves the models that should be cleaned up.
+
+If needed, you can also override the `pruningFields` and `prunedFields` methods (which are empty by default) to execute some actions before and after the model is being updated.
+
+Here's an example model including the `PrunableFields` trait:
+
+``` php
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Maize\PrunableFields\PrunableFields;
+
+class User extends Model
+{
+    use PrunableFields;
+
+    protected $fillable = [
+        'first_name',
+        'last_name',
+        'email',
+    ];
+
+    protected $prunable = [
+        'first_name' => null,
+        'last_name' => null,
+    ];
+    
+    public function prunableFields(): Builder
+    {
+        return static::query()
+            ->whereDate('created_at', '<=', now()->subDay());
+    }
+    
+    protected function pruningFields(): void
+    {
+        logger()->warning("User {$this->getKey()} is being pruned");
+    }
+
+    protected function prunedFields()
+    {
+        logger()->warning("User {$this->getKey()} has been pruned");
+    }
+}
+```
+
+All you have to do now is including the model's class name in `models` attribute under `config/prunable-fields.php`:
+
+``` php
+'models' => [
+    \App\Models\User::class,
+],
+```
+
+That's it! From now on, the `model:prune-fields` command will do all the magic.
+
+In our example, all users created before the current day will be updated with a null value for both `first_name` and `last_name` attributes.
+
+### Mass prunable models
+
+When using the `MassPrunableFields` trait all models will be updated with a raw database query.
+
+In this case, `pruningFields` and `prunedFields` methods will not be invoked, and models will not fire the `updating` or `updated` events.
+
+This way there is no need to retrieve all models before updating them, making the command execution way faster when working with a large number of entries.
+
+``` php
+<?php
+
+namespace App\Models;
+
+use Illuminate\Database\Eloquent\Model;
+use Maize\PrunableFields\MassPrunableFields;
+
+class User extends Model
+{
+    use MassPrunableFields;
+
+    protected $fillable = [
+        'first_name',
+        'last_name',
+        'email',
+    ];
+
+    protected $prunable = [
+        'first_name' => null,
+        'last_name' => null,
+    ];
+    
+    public function prunableFields(): Builder
+    {
+        return static::query()
+            ->whereDate('created_at', '<=', now()->subDay());
+    }
+}
+```
+
+### Scheduling models cleanup
+
+The package is pretty useful when you automatize the execution of the `model:prune-fields` command, using Laravel's scheduling.
+All you have to do is add the following instruction to the `schedule` method of the console kernel (usually located under the `App\Console` directory):
+
+``` php
+$schedule->command('model:prune-fields')->daily();
+```
+
+By default, when executing the `model:prune-fields` command the package will take all prunable models specified in `models` attribute under `config/prunable-fields.php`.
+
+If you want to restrict the model list you want to automatically clean up, you can pass the `--model` option to the command:
+
+``` php
+$schedule->command('model:prune-fields', [
+    '--model' => [User::class],
+])->daily();
+```
+
+Alternatively, you can clean up all models listed in your config and exclude some of them with the `--execpt` command option:
+
+``` php
+$schedule->command('model:prune-fields', [
+    '--except' => [PleaseLetMeCleanThisModelByHandsThankYou::class],
+])->daily();
 ```
 
 ## Testing

config/prunable-fields.php

@@ -0,0 +1,20 @@
+<?php
+
+return [
+    /*
+    |--------------------------------------------------------------------------
+    | Prunable models
+    |--------------------------------------------------------------------------
+    |
+    | Here you may specify the list of fully qualified class names of prunable
+    | models.
+    | All models listed here will be pruned when executing the model:prune-fields
+    | command without passing the --model option.
+    |
+    */
+
+    'models' => [
+        // \App\Models\User::class,
+    ],
+
+];

phpstan.neon.dist

@@ -5,6 +5,7 @@ parameters:
     level: 4
     paths:
         - src
+        - config
         - database
     tmpDir: build/phpstan
     checkOctaneCompatibility: true

src/Commands/PruneFieldsCommand.php

@@ -6,11 +6,10 @@
 use Illuminate\Database\Eloquent\SoftDeletes;
 use Illuminate\Support\Collection;
 use Illuminate\Support\Facades\Event;
-use Illuminate\Support\Str;
 use Maize\PrunableFields\Events\ModelsFieldsPruned;
 use Maize\PrunableFields\MassPrunableFields;
 use Maize\PrunableFields\PrunableFields;
-use Symfony\Component\Finder\Finder;
+use Maize\PrunableFields\Support\Config;
 
 class PruneFieldsCommand extends Command
 {
@@ -71,29 +70,13 @@ protected function models(): Collection
 
         $except = $this->option('except');
 
-        return collect((new Finder())->in($this->getDefaultPath())->files()->name('*.php'))
-            ->map(function ($model) {
-                $namespace = $this->laravel->getNamespace();
-
-                return $namespace.str_replace(
-                    ['/', '.php'],
-                    ['\\', ''],
-                    Str::after($model->getRealPath(), realpath(app_path()).DIRECTORY_SEPARATOR)
-                );
-            })
-            ->when(! empty($except), function ($models) use ($except) {
-                return $models->reject(fn ($model) => in_array($model, $except));
-            })
-            ->filter(fn ($model) => $this->isPrunable($model))
+        return collect(Config::getPrunableModels())
+            ->reject(fn ($model) => in_array($model, $except))
             ->filter(fn ($model) => class_exists($model))
+            ->filter(fn ($model) => $this->isPrunable($model))
             ->values();
     }
 
-    protected function getDefaultPath(): string
-    {
-        return app_path('Models');
-    }
-
     protected function isPrunable(string $model): bool
     {
         $uses = class_uses_recursive($model);

src/MassPrunableFields.php

@@ -5,11 +5,12 @@
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\Collection;
 use Illuminate\Database\Eloquent\SoftDeletes;
-use LogicException;
 use Maize\PrunableFields\Events\ModelsFieldsPruned;
 
 trait MassPrunableFields
 {
+    abstract public function prunableFields(): Builder;
+
     public function prunable(): array
     {
         return property_exists($this, 'prunable')
@@ -37,9 +38,4 @@ public function pruneAllFields(int $chunkSize = 1000): int
 
         return $total;
     }
-
-    public function prunableFields(): Builder
-    {
-        throw new LogicException('Please implement the prunable method on your model.');
-    }
 }

src/PrunableFields.php

@@ -4,11 +4,12 @@
 
 use Illuminate\Database\Eloquent\Builder;
 use Illuminate\Database\Eloquent\SoftDeletes;
-use LogicException;
 use Maize\PrunableFields\Events\ModelsFieldsPruned;
 
 trait PrunableFields
 {
+    abstract public function prunableFields(): Builder;
+
     public function prunable(): array
     {
         return property_exists($this, 'prunable')
@@ -37,20 +38,24 @@ public function pruneAllFields(int $chunkSize = 1000): int
         return $total;
     }
 
-    public function prunableFields(): Builder
-    {
-        throw new LogicException('Please implement the prunable method on your model.');
-    }
-
     public function pruneFields(): bool
     {
         $this->pruningFields();
 
-        return $this->update($this->prunable());
+        $total = $this->update($this->prunable());
+
+        $this->prunedFields();
+
+        return $total;
     }
 
     protected function pruningFields(): void
     {
         //
     }
+
+    protected function prunedFields()
+    {
+        //
+    }
 }

src/PrunableFieldsServiceProvider.php

@@ -12,6 +12,7 @@ public function configurePackage(Package $package): void
     {
         $package
             ->name('laravel-prunable-fields')
+            ->hasConfigFile()
             ->hasCommand(PruneFieldsCommand::class);
     }
 }

src/Support/Config.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Maize\PrunableFields\Support;
+
+class Config
+{
+    public static function getPrunableModels(): array
+    {
+        return config('prunable-fields.models', []);
+    }
+}

tests/PruneFieldsCommandTest.php

@@ -20,3 +20,9 @@
         '--pretend' => true,
     ])->expectsOutput("1 [{$model->getMorphClass()}] records will be pruned.");
 })->with('user_with_prunable_fields');
+
+test('should print no models found with empty list', function () {
+    pruneFields([
+        //
+    ])->expectsOutput("No prunable models found.");
+});