From ddc0f72821ac499407b04e4842d60ddc05af46f4 Mon Sep 17 00:00:00 2001
From: Kieran Williames <kieran@lyrebirdhealth.com>
Date: Sat, 29 Mar 2025 11:47:54 +1100
Subject: [PATCH] docs: updated docs to include php callables config as
 preferred method

---
 docs/schema-definition.md | 84 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 78 insertions(+), 6 deletions(-)

diff --git a/docs/schema-definition.md b/docs/schema-definition.md
index d12b6fd..e1182e4 100644
--- a/docs/schema-definition.md
+++ b/docs/schema-definition.md
@@ -2,16 +2,73 @@
 title: Dump Schema Definition
 order: 2
 ---
+
 # Dump Schema Definition
 
 Your database dump configuration takes place in the `config/masked-dump.php` file.
 
 You can use the package's fluent API to define which tables should be dumped and which information should be replaced or masked during the dump process.
 
-This is the basic configuration that you'll receive after installing the package:
+## Configuration Methods
+
+There are two ways to configure your dump schema. For production applications using Laravel's config caching, the callable method is strongly recommended.
+
+### Method 1: Using PHP Callables (Recommended for Production)
+
+When using Laravel's config caching feature, the default inline configuration approach may cause serialization errors. To avoid this issue, use PHP callables in your configuration:
 
 ```php
+<?php
+
+use BeyondCode\LaravelMaskedDumper\DumpSchema;
+use App\Support\MaskedDump;
+
+return [
+    /**
+     * Use a callable class to define your dump schema
+     * This method is compatible with Laravel's config caching
+     */
+    'default' => [MaskedDump::class, 'define'],
+];
+```
+
+Then create the referenced class:
+
+```php
+<?php
+
+namespace App\Support;
+
+use BeyondCode\LaravelMaskedDumper\DumpSchema;
+use BeyondCode\LaravelMaskedDumper\TableDefinitions\TableDefinition;
+use Faker\Generator as Faker;
 
+class MaskedDump
+{
+    public static function define()
+    {
+        return DumpSchema::define()
+            ->allTables()
+            ->table('users', function (TableDefinition $table) {
+                $table->replace('name', function (Faker $faker) {
+                    return $faker->name;
+                });
+                $table->replace('email', function (Faker $faker) {
+                    return $faker->safeEmail;
+                });
+                $table->mask('password');
+            })
+            ->schemaOnly('failed_jobs')
+            ->schemaOnly('password_reset_tokens');
+    }
+}
+```
+
+### Method 2: Inline Definition
+
+This is the basic configuration that you'll receive after installing the package. While simpler for development, this method is not compatible with Laravel's config caching:
+
+```php
 use BeyondCode\LaravelMaskedDumper\DumpSchema;
 use BeyondCode\LaravelMaskedDumper\TableDefinitions\TableDefinition;
 use Faker\Generator as Faker;
@@ -19,6 +76,7 @@ use Faker\Generator as Faker;
 return [
     /**
      * Use this dump schema definition to remove, replace or mask certain parts of your database tables.
+     * NOTE: This approach is not compatible with Laravel's config caching.
      */
     'default' => DumpSchema::define()
     	->allTables()
@@ -34,7 +92,7 @@ return [
 ];
 ```
 
-## Definiting which tables to dump
+## Defining which tables to dump
 
 The dump configuration allows you to specify which tables you want to dump. The simplest form of dumping your database can be achieved by using the `allTables()` method.
 This ensures that all of your database tables will be represented in the dump. You can then go and customize how certain tables should be dumped:
@@ -116,22 +174,22 @@ When dumping your data, the dump will now contain a safe, randomly generated ema
 
 ## Optimizing large datasets
 
-The method TableDefinition::outputInChunksOf(int $chunkSize) allows for chunked inserts for large datasets, 
+The method TableDefinition::outputInChunksOf(int $chunkSize) allows for chunked inserts for large datasets,
 improving performance and reducing memory consumption during the dump process.
 
 ```php
 return [
     'default' => DumpSchema::define()
         ->allTables()
-        ->table('users', function($table) { 
-            return $table->outputInChunksOf(3); 
+        ->table('users', function($table) {
+            return $table->outputInChunksOf(3);
         });
 ];
 ```
 
 ## Specifying the database connection to use
 
-By default, this package will use your `default` database connection when dumping the tables. 
+By default, this package will use your `default` database connection when dumping the tables.
 You can pass the connection to the `DumpSchema::define` method, in order to specify your own database connection string:
 
 ```php
@@ -155,3 +213,17 @@ return [
     	->schemaOnly('custom_table'),
 ];
 ```
+
+When using the callable approach with multiple schemas, you can define separate classes for each schema:
+
+```php
+<?php
+
+use App\Support\DefaultMaskedDump;
+use App\Support\SqliteMaskedDump;
+
+return [
+    'default' => [DefaultMaskedDump::class, 'define'],
+    'sqlite' => [SqliteMaskedDump::class, 'define'],
+];
+```