Laravel Archivable

https://github.com/joelbutcher/laravel-archivable
Admin
A simple package for making Laravel Eloquent models 'archivable' by providing macros for easy...
Tokens:20,794
Snippets:325
Trust Score:9.3
License:MIT
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install Laravel Archivable

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/README.md

Install the package via Composer.

```bash
composer require joelbutcher/laravel-archivable
```

--------------------------------

### Archivable Service Provider Usage Example

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/service-provider.md

Demonstrates using the provided macros for migrations, model traits, and route resolution.

```php
// 1. Create a migration using the archivedAt() macro
Schema::create('articles', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('content');
    $table->timestamps();
    $table->archivedAt(); // Provided by service provider
});

// 2. Create the model with Archivable trait
class Article extends Model
{
    use Archivable;
}

// 3. Archive an article
$article = Article::find(1);
$article->archive();

// 4. Define a route that can resolve archived articles
Route::get('/articles/{article}', function (Article $article) {
    return $article;
})->withArchived(); // Macro provided by service provider

// 5. Rollback the migration
Schema::table('articles', function (Blueprint $table) {
    $table->dropArchivedAt(); // Provided by service provider
});
```

--------------------------------

### Basic Model Setup and Usage

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/00-START-HERE.txt

Steps to integrate the Archivable trait and perform basic archiving operations.

```php
1. Add trait to model: use Archivable;
2. Add column to migration: $table->archivedAt();
3. Archive: $model->archive();
4. Query: Model::onlyArchived()->get();
```

--------------------------------

### Usage of Blueprint::archivedAt() in migrations

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/service-provider.md

Examples showing default usage, custom column names, and precision settings for the archivedAt migration macro.

```php
// Migration
Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->string('email');
    $table->timestamps();
    $table->archivedAt(); // Creates nullable 'archived_at' timestamp column
});

// With custom column name
Schema::create('posts', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->timestamps();
    $table->archivedAt('deleted_at'); // Custom column name
});

// With precision (for databases that support it)
Schema::create('orders', function (Blueprint $table) {
    $table->id();
    $table->timestamps();
    $table->archivedAt(precision: 6); // High precision timestamp
});
```

--------------------------------

### Apply archivedAt() in migrations

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/configuration.md

Examples of using the archivedAt() macro with custom column names and precision settings.

```php
// Default column name
$table->archivedAt();

// Custom column name
$table->archivedAt('deleted_at');

// With precision
$table->archivedAt(precision: 6);

// Both custom name and precision
$table->archivedAt('deleted_at', 6);
```

--------------------------------

### Usage of Route::allowsArchivedBindings()

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/service-provider.md

Examples demonstrating how to check the archived binding status of a route instance.

```php
// Typically used internally by the framework
$route = Route::get('/users/{user}', 'UserController@show')->withArchived();

if ($route->allowsArchivedBindings()) {
    // Route allows archived user binding
}

$route2 = Route::get('/posts/{post}', 'PostController@show');

if (!$route2->allowsArchivedBindings()) {
    // Route excludes archived post binding
}
```

--------------------------------

### Migrate SoftDeletes to Archivable

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/QUICK_START.md

Example migration class to rename the deleted_at column to archived_at for existing data.

```php
class MigrateToArchivable extends Migration
{
    public function up()
    {
        Schema::table('posts', function (Blueprint $table) {
            $table->renameColumn('deleted_at', 'archived_at');
        });
    }
    
    public function down()
    {
        Schema::table('posts', function (Blueprint $table) {
            $table->renameColumn('archived_at', 'deleted_at');
        });
    }
}
```

--------------------------------

### Usage of Blueprint::dropArchivedAt() in migrations

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/service-provider.md

Examples showing how to drop the archived timestamp column during a rollback.

```php
// In a rollback migration
Schema::table('users', function (Blueprint $table) {
    $table->dropArchivedAt(); // Drops 'archived_at' column
});

// With custom column name
Schema::table('posts', function (Blueprint $table) {
    $table->dropArchivedAt('deleted_at');
});
```

--------------------------------

### Archive Relationships

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/QUICK_START.md

Example of archiving a parent model and its associated child records.

```php
// Archive a user and their posts
$user = User::find(1);

$user->posts()->archive(); // Archive all posts
$user->archive(); // Archive user
```

--------------------------------

### Boot method definition

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/service-provider.md

The boot method is called after all services are registered to configure and register package macros.

```php
public function boot(): void
```

--------------------------------

### Run Tests

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/README.md

Execute the test suite using composer.

```bash
composer test
```

--------------------------------

### Execute Batch Archive Operations

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/ARCHITECTURE.md

Demonstrates the difference between direct database updates via macros and event-driven model updates.

```php
User::where('inactive', true)->archive(); // Direct UPDATE, no events
User::where('id', 1)->get()->each(fn($u) => $u->archive()); // Events fired
```

--------------------------------

### Triggering Model Events with Archivable

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-scope.md

Demonstrates the difference between bulk query macros that bypass events and instance methods that trigger them.

```php
// No events triggered
User::where('status', 'inactive')->archive();

// Events triggered for each user
User::where('status', 'inactive')->get()->each(fn($user) => $user->archive());
```

--------------------------------

### Get the qualified archived column name

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-trait.md

Retrieves the fully qualified name of the archived column, including the table prefix.

```php
$user = User::first();
echo $user->getQualifiedArchivedAtColumn(); // 'users.archived_at'
```

--------------------------------

### Use Migration Macros

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/ARCHITECTURE.md

Simplify database schema definitions by using the provided migration macro for the archive column.

```php
$table->archivedAt(); // Instead of: $table->timestamp('archived_at')->nullable()
```

--------------------------------

### Project Directory Structure

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/ARCHITECTURE.md

Overview of the file organization within the laravel-archivable package.

```text
laravel-archivable/
├── src/
│   ├── Archivable.php                    # Main trait providing archive methods
│   ├── LaravelArchivableServiceProvider.php  # Service provider registering macros
│   └── Scopes/
│       └── ArchivableScope.php           # Global scope for query filtering
└── tests/
    ├── ArchivableTest.php                # Core functionality tests
    ├── ArchivableRouteTest.php           # Route binding tests
    └── TestClasses/
```

--------------------------------

### Configure Route Implicit Binding

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/QUICK_START.md

Demonstrates default behavior where archived models return 404, and how to enable resolution using withArchived().

```php
Route::get('/posts/{post}', function (Post $post) {
    return $post; // 404 if post is archived
});
```

```php
Route::get('/posts/{post}/edit', function (Post $post) {
    return view('posts.edit', ['post' => $post]); // Resolves archived posts
})->withArchived();
```

--------------------------------

### Configure Route Binding with Archivable

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-trait.md

Demonstrates using the withArchived() macro to include archived models in route resolution.

```php
// In routes/web.php
Route::get('/users/{user}', function (User $user) {
    return $user->email;
})->withArchived(); // Allow archived users to be resolved

// In routes/api.php
Route::get('/users/{user}', function (User $user) {
    return $user->email;
}); // Only non-archived users can be resolved
```

--------------------------------

### Implementing the Observer Pattern

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Encapsulate archiving logic within a dedicated observer class and register it using the observe method.

```php
class PostObserver
{
    public function archiving(Post $post)
    {
        // Prevent archiving pinned posts
        if ($post->is_pinned) {
            return false;
        }
    }
    
    public function archived(Post $post)
    {
        // Update search index
        SearchIndex::remove('posts', $post->id);
    }
    
    public function unArchiving(Post $post)
    {
        // Validate post can be restored
        if ($post->author->archived_at !== null) {
            return false; // Cannot restore if author is archived
        }
    }
    
    public function unArchived(Post $post)
    {
        // Reindex
        SearchIndex::index('posts', $post);
    }
}

// Register observer
Post::observe(PostObserver::class);
```

--------------------------------

### Archive exception scenario

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/errors.md

Demonstrates the conditions under which the primary key exception is triggered versus a successful archive operation.

```php
// This will throw an exception
$model = new Post(); // Not saved to database, so primary key is null
$model->archive(); // Exception: "No primary key defined on model."

// This works fine
$model = Post::find(1); // Has primary key from database
$model->archive(); // Succeeds
```

--------------------------------

### Migration Blueprint Methods

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/INDEX.md

Schema builder macros for adding or removing the archive column in database migrations.

```php
$table->archivedAt()                     // Add archive column
$table->archivedAt('custom_column')      // With custom name
$table->archivedAt(precision: 6)         // With precision
$table->dropArchivedAt()                 // Drop archive column
```

--------------------------------

### ConfigureMacros method definition

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/service-provider.md

This protected method registers macros for Schema Blueprint and Route classes during the boot phase.

```php
protected function configureMacros(): void
```

--------------------------------

### Querying Archivable Models

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-scope.md

Demonstrates standard query scopes for filtering archived records and performing batch operations.

```php
// Default behavior: non-archived only
$activeUsers = User::all(); // excludes archived

// Include archived
$everyone = User::withArchived()->get();

// Only archived
$archived = User::onlyArchived()->get();

// Complex query with archive control
$results = User::where('role', 'admin')
    ->withArchived()
    ->where('created_at', '>', '2023-01-01')
    ->onlyArchived()
    ->get();

// Batch operations
User::where('inactive_days', '>', 365)->archive();
User::onlyArchived()->where('archived_at', '<', now()->subYear())->forceDelete();
```

--------------------------------

### Documentation Directory Structure

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/README.md

The file structure of the project documentation.

```text
output/
├── INDEX.md                    Main index and navigation
├── QUICK_START.md              Getting started (5 min)
├── ARCHITECTURE.md             System design
├── EXAMPLES.md                 Comprehensive usage examples
├── README.md                   This file
├── types.md                    Type reference
├── configuration.md            Configuration guide
├── errors.md                   Error handling
└── api-reference/
    ├── archivable-trait.md     Trait documentation
    ├── archivable-scope.md     Scope documentation
    └── service-provider.md     Provider documentation
```

--------------------------------

### Defining Archive Events

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/README.md

Shows how to hook into the archiving process to perform custom logic or prevent the action.

```php
User::archiving(function ($user) {
    return false; // Prevent archiving
});
```

--------------------------------

### Register Archiving Event Callbacks

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/types.md

Demonstrates passing a closure or a string listener class to the archiving event registration method.

```php
User::archiving(function ($user) {
    // Handle archiving logic
});
```

```php
User::archiving('UserArchivingListener');
```

--------------------------------

### Implement Model Observers

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/configuration.md

Use a dedicated observer class to handle model events and register it using the observe method.

```php
class UserObserver
{
    public function archiving(User $user)
    {
        // Listener logic
    }
    
    public function archived(User $user)
    {
        // Listener logic
    }
    
    public function unArchiving(User $user)
    {
        // Listener logic
    }
    
    public function unArchived(User $user)
    {
        // Listener logic
    }
}

// Register observer
User::observe(UserObserver::class);
```

--------------------------------

### Configure Model Event Listeners

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/configuration.md

Define archiving lifecycle hooks within the boot method of an Eloquent model using the Archivable trait.

```php
class User extends Model
{
    use Archivable;
    
    protected static function boot()
    {
        parent::boot();
        
        static::archiving(function ($user) {
            Log::info('User ' . $user->id . ' is being archived');
        });
        
        static::archived(function ($user) {
            Cache::forget('user_' . $user->id);
            event(new UserArchived($user));
        });
        
        static::unArchiving(function ($user) {
            // Prevent unarchiving deleted accounts
            if ($user->permanently_deleted) {
                return false;
            }
        });
        
        static::unArchived(function ($user) {
            Log::info('User ' . $user->id . ' was restored');
        });
    }
}
```

--------------------------------

### Migration Methods

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/INDEX.md

Schema builder macros for adding or removing archive columns in migrations.

```APIDOC
## Migration Methods

### $table->archivedAt($column = 'archived_at', $precision = null)
Adds the archive column to the table schema.

### $table->dropArchivedAt()
Drops the archive column from the table schema.
```

--------------------------------

### Configure SQL Schema for Archivable

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/configuration.md

Add a nullable timestamp column to the database table to support archiving functionality.

```sql
-- For default configuration
ALTER TABLE users ADD COLUMN archived_at TIMESTAMP NULL;

-- For custom ARCHIVED_AT
ALTER TABLE users ADD COLUMN deleted_at TIMESTAMP NULL;
```

--------------------------------

### Use Archivable Extensions

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/README.md

Perform archive operations and query archived models using the provided extensions.

```php
$user = User::first();
$user->archive();
$user->unArchive();

// Check Archive status
$user->isArchived();

$usersWithArchived = User::query()->withArchived();
$onlyArchivedUsers = User::query()->onlyArchived();
```

--------------------------------

### Register Global Scope in Trait

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/ARCHITECTURE.md

Boot the Archivable trait to automatically apply the global scope to model queries.

```php
// In Archivable trait
public static function bootArchivable()
{
    static::addGlobalScope(new ArchivableScope);
}
```

--------------------------------

### Perform Batch Operations

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/QUICK_START.md

Archive or restore multiple records at once using query builder methods.

```php
// Archive multiple posts
Post::where('author_id', 1)->archive();

// Restore multiple archived posts
Post::onlyArchived()->where('created_at', '<', now()->subYear())->unArchive();
```

--------------------------------

### Test Archivable Models

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/QUICK_START.md

Demonstrates archiving models, using factory states, and asserting archived status in PHPUnit tests.

```php
// Archive a model in tests
$post = Post::factory()->create();
$post->archive();

// Factory with pre-archived model
$archived = Post::factory()->archived()->create();
// Requires factory state, see docs

// Assert archived status
$this->assertTrue($post->fresh()->isArchived());
```

--------------------------------

### Implement Observer for Archive Events

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/ARCHITECTURE.md

Defines a dedicated observer class to handle archiving and archived lifecycle events.

```php
class MyObserver {
    public function archiving(Model $model) { }
    public function archived(Model $model) { }
}

Model::observe(MyObserver::class);
```

--------------------------------

### Register method definition

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/service-provider.md

The register method is intentionally empty as the package does not require service container registration.

```php
public function register(): void
```

--------------------------------

### Archivable Feature Reference

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/README.md

Quick reference table for common methods and features provided by the Archivable trait.

```php
$model->archive()
$model->unArchive()
$model->isArchived()
Model::withArchived()->get()
Model::onlyArchived()->get()
Model::where(...)->archive()
Model::archiving(fn($m) => ...)
Route::get(...)->withArchived()
```

--------------------------------

### Enabling Route Binding

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/README.md

Allows archived models to be resolved via route implicit binding.

```php
Route::get('/users/{user}', ...)->withArchived();
```

--------------------------------

### Querying with Global Scopes

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/README.md

Demonstrates how to include or exclude archived records from Eloquent queries.

```php
User::all()                 // Excludes archived
User::withArchived()->all() // Includes archived
```

--------------------------------

### Event Methods

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/INDEX.md

Lifecycle hooks for models to execute logic before or after archiving/restoring.

```APIDOC
## Event Methods

### archiving($callback)
Registers a callback to run before a model is archived. Returning false in the callback can prevent the archive action.

### archived($callback)
Registers a callback to run after a model is archived.

### unArchiving($callback)
Registers a callback to run before a model is restored. Returning false in the callback can prevent the restore action.

### unArchived($callback)
Registers a callback to run after a model is restored.
```

--------------------------------

### Logging and Notifications via Events

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Attach listeners to archiving, archived, unArchiving, and unArchived events to trigger side effects like logging, emails, or cache clearing.

```php
User::archiving(function ($user) {
    Log::info("User {$user->id} ({$user->email}) is being archived");
});

User::archived(function ($user) {
    Log::info("User {$user->id} archived at {$user->archived_at}");
    
    Mail::send(new UserArchivedNotification($user));
    
    event(new UserArchived($user));
});

User::unArchiving(function ($user) {
    Log::info("User {$user->id} is being restored");
});

User::unArchived(function ($user) {
    Log::info("User {$user->id} has been restored");
    
    Cache::forget('user_' . $user->id);
});
```

--------------------------------

### Model Instance Methods

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/INDEX.md

Methods available on models using the Archivable trait to manage individual record states.

```APIDOC
## Model Instance Methods

### archive()
Archives the current model instance.

### unArchive()
Restores the current model instance from the archive.

### isArchived()
Checks if the current model instance is archived. Returns boolean.

### getArchivedAtColumn()
Returns the name of the column used for archiving.

### getQualifiedArchivedAtColumn()
Returns the fully qualified column name used for archiving.
```

--------------------------------

### Handle Archivable Model Events

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/QUICK_START.md

Hooks for reacting to lifecycle changes during archive and unarchive operations.

```php
Post::archiving(function ($post) {
    Log::info('Post ' . $post->id . ' being archived');
    
    // Return false to prevent archiving
    if ($post->is_pinned) {
        return false;
    }
});

Post::archived(function ($post) {
    Log::info('Post ' . $post->id . ' archived');
    // Cleanup, notifications, etc.
});

Post::unArchiving(function ($post) {
    Log::info('Post ' . $post->id . ' being restored');
});

Post::unArchived(function ($post) {
    Log::info('Post ' . $post->id . ' restored');
});
```

--------------------------------

### Handle Post-Unarchiving Logic

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-trait.md

Executes logic after a model has been successfully restored.

```php
User::unArchived(function ($user) {
    Log::info('User ' . $user->id . ' was restored from archive');
});
```

--------------------------------

### Define runArchive method

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-trait.md

Internal method used to perform the database update for archiving a model.

```php
protected function runArchive(): void
```

--------------------------------

### Handle Archive Failures

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Check the return value of the archive method to handle failures or missing models.

```php
$user = User::find(1);

$result = $user->archive();

if ($result === false) {
    // Event prevented archiving
    echo 'User cannot be archived';
} elseif ($result === null) {
    // Model doesn't exist
    echo 'User not found';
} else {
    // Success
    echo 'User archived successfully';
}
```

--------------------------------

### Model Instance Methods

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/INDEX.md

Methods available on an Eloquent model using the Archivable trait to manage its archive state.

```php
$model->archive()                        // Archive the model
$model->unArchive()                      // Restore from archive
$model->isArchived()                     // Check if archived
$model->getArchivedAtColumn()            // Get column name
$model->getQualifiedArchivedAtColumn()   // Get fully qualified column name
```

--------------------------------

### Handling Archive Events

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/README.md

Logs information during the archiving process.

```php
User::archiving(function ($user) {
    Log::info('Archiving user: ' . $user->id);
    return true;
});
```

--------------------------------

### Perform Bulk Restore with Verification

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/QUICK_START.md

Retrieves archived records and conditionally restores them based on custom criteria.

```php
Post::onlyArchived()
    ->where('created_at', '>', now()->subMonth())
    ->get()
    ->each(function ($post) {
        if ($post->shouldBeRestored()) {
            $post->unArchive();
        }
    });
```

--------------------------------

### Route Binding Methods

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/INDEX.md

Methods to configure route model binding behavior regarding archived records.

```php
Route::get(...)->withArchived()          // Allow archived in binding
Route::get(...)->withArchived(false)     // Explicitly disallow
```

--------------------------------

### Replace SoftDeletes Trait

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/QUICK_START.md

Shows the transition from SoftDeletes to Archivable.

```php
// Before
use SoftDeletes;

// After
use Archivable;
```

--------------------------------

### Perform Archive Operations

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/QUICK_START.md

Use archive, isArchived, and unArchive methods to manage the archive state of a model instance.

```php
// Archive a post
$post = Post::find(1);
$post->archive();

// Check if archived
if ($post->isArchived()) {
    echo 'This post is archived';
}

// Restore from archive
$post->unArchive();
```

--------------------------------

### Hook into Archiving Events

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/ARCHITECTURE.md

Use model events to intercept the archiving process and optionally cancel it by returning false.

```php
User::archiving(function ($user) {
    return false; // Can prevent operation
});
```

--------------------------------

### Handle Missing Primary Key Exception

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/types.md

Catch the exception thrown when attempting to archive a model that lacks a primary key.

```php
try {
    $model = new Model(); // No primary key
    $model->archive();
} catch (Exception $e) {
    // Handle: "No primary key defined on model."
}
```

--------------------------------

### Usage with Custom Archive Column

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Interacting with models using custom archive columns follows the same API as default configurations.

```php
$product = Product::find(1);
$product->archive(); // Sets discontinued_at

echo $product->getArchivedAtColumn(); // 'discontinued_at'
echo $product->discontinued_at; // Carbon instance

$discontinued = Product::onlyArchived()->get();
```

--------------------------------

### Batch Archive Error Handling

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Iterate through a collection and track successful archive operations.

```php
$count = 0;

User::where('status', 'inactive')
    ->get()
    ->each(function ($user) use (&$count) {
        if ($user->archive()) {
            $count++;
        }
    });

echo "Archived $count users";
```

--------------------------------

### Default Query Behavior

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Demonstrates that standard queries exclude archived records by default.

```php
// Create 3 users: 2 active, 1 archived
User::factory()->create(['name' => 'Alice']);
User::factory()->create(['name' => 'Bob']);
User::factory()
    ->state(['archived_at' => now()])
    ->create(['name' => 'Charlie']);

User::count(); // Returns 2 (excludes archived)
User::pluck('name'); // ['Alice', 'Bob']
```

--------------------------------

### Define Archivable Column in Migrations

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/configuration.md

Use the provided migration macro or manual timestamp definition to add the archiving column.

```php
Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->string('email')->unique();
    $table->timestamps();
    
    // Using the provided macro
    $table->archivedAt();
    
    // Or manual creation
    // $table->timestamp('archived_at')->nullable();
});
```

--------------------------------

### Batch archive records with archive()

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-scope.md

Performs a direct database update to set the archived_at timestamp; note that this does not trigger model events.

```php
// Archive all users with suspended status
$archived = User::where('status', 'suspended')->archive();
echo "Archived $archived users";

// Archive all posts older than one year
$old_posts = Post::where('created_at', '<', now()->subYear())->archive();
```

--------------------------------

### Register Archiving Event Listener

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/ARCHITECTURE.md

Executes custom logic during the archiving process.

```php
Model::archiving(function ($model) {
    // Custom logic
});
```

--------------------------------

### Extend Query Builder with Macros

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-scope.md

Signature for the extend method used to register archive-related query builder macros.

```php
public function extend(Builder $builder): void
```

--------------------------------

### Register Service Provider in composer.json

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/service-provider.md

Configure the service provider in the extra.laravel.providers section of your composer.json file.

```json
{
    "extra": {
        "laravel": {
            "providers": [
                "LaravelArchivable\\LaravelArchivableServiceProvider"
            ]
        }
    }
}
```

--------------------------------

### Configure Archivable Property

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/types.md

Set the $archives property to true or false to enable or disable archive functionality on a model.

```php
class User extends Model
{
    use Archivable;
    
    public $archives = true; // Can be set to false to disable archiving
}
```

--------------------------------

### Update Migration for Archivable

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Replace the softDeletes column definition with the archivable column definition.

```php
// If using SoftDeletes
$table->softDeletes();

// Change to Archivable in new migrations
$table->archivedAt();
```

--------------------------------

### Handle Post-Archiving Logic

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-trait.md

Executes logic after a model has been successfully archived.

```php
User::archived(function ($user) {
    Log::info('User ' . $user->id . ' was archived at ' . $user->archived_at);
    
    // Send notification, update cache, etc.
    Cache::forget('user_' . $user->id);
});
```

--------------------------------

### Archive a model instance

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-trait.md

Archives a model by setting the archived timestamp. The operation can be aborted if the archiving event returns false.

```php
$user = User::find(1);
$user->archive();

// Check if archiving was prevented by event
if ($user->archive() === false) {
    // archiving event returned false
}
```

--------------------------------

### Validating Archive Schema

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/errors.md

Verify the existence of the archive column within the model's boot method to prevent runtime errors.

```php
// In model's boot method
protected static function boot()
{
    parent::boot();
    
    if (! Schema::hasColumn(static::make()->getTable(), static::make()->getArchivedAtColumn())) {
        throw new RuntimeException(
            'Archive column not found for ' . static::class
        );
    }
}
```

--------------------------------

### Batch restore records with unArchive()

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-scope.md

Performs a direct database update to set the archived_at column to null; this operation does not trigger model events.

```php
// Restore all archived users from a specific date
$restored = User::onlyArchived()
    ->where('archived_at', '>', now()->subMonth())
    ->unArchive();
    
echo "Restored $restored users";
```

--------------------------------

### Test Archiving Functionality

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Verify that a model can be successfully archived using the archive method.

```php
public function test_user_can_be_archived()
{
    $user = User::factory()->create();
    
    $user->archive();
    
    $this->assertTrue($user->fresh()->isArchived());
}
```

--------------------------------

### Extend Query Builder with Macros

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/ARCHITECTURE.md

Add custom methods to the Eloquent query builder to provide a fluent API for archive operations.

```php
protected function addArchive(Builder $builder)
{
    $builder->macro('archive', function (Builder $builder) {
        // Implementation
    });
}
```

--------------------------------

### Initialize Archivable Type Casting

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/ARCHITECTURE.md

Ensures the archived_at column is automatically cast to a Carbon instance during model initialization.

```php
public function initializeArchivable()
{
    if (!isset($this->casts[$this->getArchivedAtColumn()])) {
        $this->casts[$this->getArchivedAtColumn()] = 'datetime';
    }
}
```

--------------------------------

### Register Unarchiving Event Listener

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-trait.md

Defines the method signature for registering an unarchiving event callback.

```php
public static function unArchiving(\Closure|string $callback): void
```

--------------------------------

### Register Unarchived Event Listener

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-trait.md

Defines the method signature for registering an unarchived event callback.

```php
public static function unArchived(\Closure|string $callback): void
```

--------------------------------

### Register Archiving Event Listener

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-trait.md

Defines the method signature for registering an archiving event callback.

```php
public static function archiving(\Closure|string $callback): void
```

--------------------------------

### Verify Global Scope Application

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/errors.md

Check if the ArchivableScope is correctly registered on a model instance.

```php
$model = Post::first();
$scopes = $model->getGlobalScopes();
// Should contain ArchivableScope if trait is properly applied
```

--------------------------------

### Implement Archivable Trait and Migration

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/README.md

Add the Archivable trait to your Eloquent model and include the archived_at column in your database migration.

```php
// 1. Add trait to model
class Post extends Model {
    use Archivable;
}

// 2. Create migration with archive column
Schema::create('posts', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->timestamps();
    $table->archivedAt(); // Adds archived_at timestamp column
});

// 3. Archive a post
$post = Post::find(1);
$post->archive();

// 4. Query archived/non-archived records
Post::all();                    // Returns only non-archived (default)
Post::withArchived()->get();    // Returns all including archived
Post::onlyArchived()->get();    // Returns only archived

// 5. Restore from archive
$post->unArchive();
```

--------------------------------

### Blueprint::archivedAt()

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/service-provider.md

Creates a nullable timestamp column suitable for storing archive timestamps in database migrations.

```APIDOC
## Blueprint::archivedAt()

### Description
Macro for creating an archived timestamp column in migrations. Internally uses `timestamp()` with the `nullable()` modifier.

### Signature
`Blueprint::archivedAt($column = 'archived_at', $precision = 0): ColumnDefinition`

### Parameters
- **column** (string) - Optional - The column name (default: 'archived_at')
- **precision** (int) - Optional - The timestamp precision (default: 0)

### Return Type
`Illuminate\Database\Schema\ColumnDefinition`
```

--------------------------------

### Archive Status Querying

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Perform counts and relationship breakdowns based on archive status.

```php
// Get count by archive status
$active = Post::count();
$archived = Post::onlyArchived()->count();
$total = Post::withArchived()->count();

// Get breakdown by user
$breakdown = User::withArchived()
    ->select('id', 'name')
    ->withCount(['posts' => fn($q) => $q->withoutArchived()])
    ->withCount(['archivedPosts' => fn($q) => $q->onlyArchived()])
    ->get();
```

--------------------------------

### Register Archived Event Listener

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-trait.md

Defines the method signature for registering an archived event callback.

```php
public static function archived(\Closure|string $callback): void
```

--------------------------------

### Common Archivable Queries

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/00-START-HERE.txt

Standard query builder methods for filtering archived records.

```php
Model::all()                    // Excludes archived (default)
Model::withArchived()->get()    // Includes archived
Model::onlyArchived()->get()    // Only archived
Model::where(...)->archive()    // Batch archive
```

--------------------------------

### Model Archiving Events

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/00-START-HERE.txt

Lifecycle hooks for performing actions before or after archiving and restoring models.

```php
Model::archiving(fn($m) => ...)  // Before archive (can prevent)
Model::archived(fn($m) => ...)   // After archive
Model::unArchiving(fn($m) => ...) // Before restore (can prevent)
Model::unArchived(fn($m) => ...)  // After restore
```

--------------------------------

### Enforcing Type Safety for Archive Operations

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/errors.md

Use type hints in repositories to ensure consistent handling of archive results.

```php
class UserRepository
{
    public function archive(User $user): bool
    {
        // Type hint ensures $user is an Eloquent model
        // with primary key
        return (bool) $user->archive();
    }
}
```

--------------------------------

### Add ArchivedAt to Migrations

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/README.md

Use the archivedAt macro within a migration to add the necessary column.

```php
Schema::create('posts', function (Blueprint $table) {
    $table->id();
    $table->unsignedBigInteger('user_id');
    $table->string('title');
    $table->timestamps();
    $table->archivedAt(); // Macro
});
```

--------------------------------

### Handling Archive Operation Results

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/errors.md

Check the return value of archive methods to distinguish between prevented operations, missing models, and successful execution.

```php
$result = $user->archive();

if ($result === false) {
    // Event prevented operation
    Log::warning('User ' . $user->id . ' could not be archived');
} elseif ($result === null) {
    // Model doesn't exist
    Log::warning('Attempted to archive non-existent model');
} else {
    // Success
    Log::info('User ' . $user->id . ' archived successfully');
}
```

--------------------------------

### Resolve Route Binding

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-trait.md

Defines the method signature for resolving route implicit binding.

```php
public function resolveRouteBinding($value, $field = null): \Illuminate\Database\Eloquent\Model|null
```

--------------------------------

### archive()

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-scope.md

Archives all records matching the query.

```APIDOC
## archive()

### Description
Performs a batch archive operation by setting the archived_at column to the current timestamp for all records matching the query. This is a direct database update and does not trigger model events.

### Signature
`Builder::archive(): int`

### Returns
- **int** - The number of records affected by the update.
```

--------------------------------

### Create Migration with Archived Column

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/QUICK_START.md

Add the archived_at timestamp column to your database table schema.

```php
Schema::create('posts', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('content');
    $table->timestamps();
    $table->archivedAt(); // Adds archived_at timestamp column
});
```

--------------------------------

### Migration for Custom Archive Column

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Use the archivedAt method in your migration to create the custom column.

```php
Schema::create('products', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->timestamps();
    $table->archivedAt('discontinued_at'); // Use custom column name
});
```

--------------------------------

### Model Lifecycle Events

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/INDEX.md

Event hooks for intercepting the archiving and restoration process on a model class.

```php
Model::archiving($callback)              // Before archive (can prevent)
Model::archived($callback)               // After archive
Model::unArchiving($callback)            // Before restore (can prevent)
Model::unArchived($callback)             // After restore
```

--------------------------------

### Query Builder Methods

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/INDEX.md

Methods for filtering or performing batch operations on archived records via the query builder.

```php
Model::withArchived()                    // Include archived records
Model::onlyArchived()                    // Only archived records
Model::withoutArchived()                 // Only non-archived (default)
Model::where(...)->archive()             // Batch archive
Model::where(...)->unArchive()           // Batch restore
```

--------------------------------

### Temporary Scope Override

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Retrieve all records including archived ones and filter them manually in memory.

```php
// Start with all records
$all = Post::withArchived()->get();

// Process only archived ones
$archived = $all->filter(fn($p) => $p->isArchived());

// Process only active ones
$active = $all->filter(fn($p) => !$p->isArchived());
```

--------------------------------

### Restoring Archived Data

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/README.md

Restores an archived model instance to an active state.

```php
$user = User::onlyArchived()->first();
$user->unArchive();
```

--------------------------------

### Preventing Archive Operations via Event Listeners

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/errors.md

Use explicit boolean false returns in pre-operation events to halt the archiving process.

```php
User::archiving(function ($user) {
    if ($user->is_protected) {
        return false; // Explicitly return false to prevent
    }
    // Implicit return of null allows operation to proceed
});
```

```php
User::archiving(function ($user) {
    if ($user->is_protected) {
        return true; // Does NOT prevent the operation
    }
});
```

--------------------------------

### Query Builder Method Usage

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/errors.md

Demonstrates valid and invalid usage of the onlyArchived query scope based on trait implementation.

```php
// Works: Model uses Archivable
$archived = Post::onlyArchived()->get();

// Error: Model does not use Archivable
$archived = RegularModel::onlyArchived()->get(); // Undefined method
```

--------------------------------

### Define Blueprint::archivedAt() signature

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/service-provider.md

The method signature for creating an archived timestamp column in migrations.

```php
Blueprint::archivedAt($column = 'archived_at', $precision = 0): ColumnDefinition
```

--------------------------------

### Implement Conditional Archiving

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/QUICK_START.md

Checks custom logic before performing an archive operation.

```php
$post = Post::find(1);

if ($post->canBeArchived()) {
    $post->archive();
}

protected function canBeArchived(): bool
{
    return !$this->is_system_post && $this->created_at->diffInDays() > 30;
}
```

--------------------------------

### Test Event Prevention

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Validate that archiving can be blocked by returning false in an archiving event listener.

```php
public function test_archiving_prevented_by_event()
{
    User::archiving(function ($user) {
        return false;
    });
    
    $user = User::factory()->create();
    $result = $user->archive();
    
    $this->assertFalse($result);
    $this->assertFalse($user->fresh()->isArchived());
}
```

--------------------------------

### Prevent Unarchiving via unArchiving Event

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/errors.md

Use the unArchiving event to return false and halt the restoration of archived models.

```php
User::unArchiving(function ($user) {
    if ($user->subscription->expired) {
        return false; // Prevent restoring users with expired subscriptions
    }
});

$user = User::onlyArchived()->first();
$result = $user->unArchive();

if ($result === false) {
    // unArchiving event returned false, unarchive was prevented
}
```

--------------------------------

### archiving()

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-trait.md

Registers a callback to be executed when a model is about to be archived.

```APIDOC
## archiving(\Closure|string $callback)

### Description
Registers a model event listener for the `archiving` event. The callback receives the model instance as its first parameter. If the callback returns `false`, the archive operation is prevented.

### Parameters
- **callback** (Closure|string) - Required - The event callback (closure or listener class method name)

### Return Type
`void`
```

--------------------------------

### Enable Archived Models in Route Binding

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/README.md

Chain the withArchived method to route definitions to allow implicit binding of archived models.

```php
use App\Models\User;
 
Route::get('/users/{user}', function (User $user) {
    return $user->email;
})->withArchived();
```

--------------------------------

### Rollback ArchivedAt Migration

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/README.md

Use the dropArchivedAt macro to remove the column during a rollback.

```php
Schema::create('posts', function (Blueprint $table) {
    $table->dropArchivedAt();
});
```

--------------------------------

### Apply ArchivableScope to Query

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-scope.md

Signature for the apply method used by Laravel to filter archived records.

```php
public function apply(Builder $builder, Model $model): void
```

--------------------------------

### Update Eloquent Queries

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Replace SoftDeletes query methods with their Archivable equivalents.

```php
// Before (SoftDeletes)
User::withTrashed()->get();
User::onlyTrashed()->get();

// After (Archivable)
User::withArchived()->get();
User::onlyArchived()->get();
```

--------------------------------

### unArchiving()

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-trait.md

Registers a callback to be executed when a model is about to be unarchived.

```APIDOC
## unArchiving(\Closure|string $callback)

### Description
Registers a model event listener for the `unArchiving` event. The callback receives the model instance. If the callback returns `false`, the unarchive operation is prevented.

### Parameters
- **callback** (Closure|string) - Required - The event callback (closure or listener class)

### Return Type
`void`
```

--------------------------------

### Register Observable Events

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/types.md

These string identifiers are used to hook into the model's event dispatcher system for archive-related lifecycle events.

```php
protected $observables = [
    'archiving',
    'archived',
    'unArchiving',
    'unArchived',
];
```

--------------------------------

### resolveRouteBinding()

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-trait.md

Resolves route implicit binding, optionally including archived models based on route configuration.

```APIDOC
## resolveRouteBinding($value, $field = null)

### Description
Overrides the default route binding resolution to respect the `withArchived()` route macro. If a route has `withArchived()` called on it, this method will include archived models in the implicit binding query.

### Parameters
- **value** (mixed) - Required - The value to bind (typically the ID)
- **field** (string|null) - Optional - The field to bind on (defaults to primary key)

### Return Type
`\Illuminate\Database\Eloquent\Model|null`
```

--------------------------------

### Add Archived Timestamp Column

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/types.md

SQL statements to add the nullable archived_at timestamp column to existing tables.

```sql
-- MySQL / MariaDB
ALTER TABLE users ADD archived_at TIMESTAMP NULL DEFAULT NULL;

-- PostgreSQL
ALTER TABLE users ADD COLUMN archived_at TIMESTAMP NULL DEFAULT NULL;

-- SQLite
ALTER TABLE users ADD COLUMN archived_at TIMESTAMP NULL DEFAULT NULL;
```

--------------------------------

### Complex Batch Operations

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Perform batch archival or restoration on filtered datasets or relationship queries.

```php
// Archive old drafts
Post::where('status', 'draft')
    ->where('updated_at', '<', now()->subMonths(3))
    ->archive();

// Restore and re-publish archived posts
Post::onlyArchived()
    ->where('created_at', '>', '2024-01-01')
    ->unArchive();

// Archive by relationship
$department->employees()
    ->where('status', 'terminated')
    ->archive();
```

--------------------------------

### Rename or Map Archive Column

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Maintain existing column names by defining a constant or rename the database column directly.

```php
// Keep existing 'deleted_at' column by defining constant
const ARCHIVED_AT = 'deleted_at';
```

```php
Schema::table('users', function (Blueprint $table) {
    $table->renameColumn('deleted_at', 'archived_at');
});
```

--------------------------------

### Define Model Event Callback

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/types.md

The callback signature for model events. Return false in pre-operation events to cancel the action.

```php
function ($model): void|bool
```

```php
User::archiving(function ($user) {
    // $user is a User instance
    // Return false to prevent archiving
    if ($user->is_system_user) {
        return false;
    }
});
```

--------------------------------

### Archive Multiple Records

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Use the archive() method on Eloquent query builders to archive records matching specific conditions.

```php
// Archive all users with inactive status
$archived = User::where('status', 'inactive')->archive();
echo "Archived $archived users";

// Archive users not logged in for a year
User::where('last_login', '<', now()->subYear())->archive();

// Archive with complex conditions
Post::where('published', false)
    ->where('created_at', '<', now()->subMonth())
    ->archive();
```

--------------------------------

### Test Query Scoping

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Ensure archived records are excluded from default queries but accessible via withArchived.

```php
public function test_archived_users_excluded_from_default_query()
{
    User::factory()->create();
    User::factory()->create(['archived_at' => now()]);
    
    $this->assertCount(1, User::all());
    $this->assertCount(2, User::withArchived()->get());
}
```

--------------------------------

### Customize Archive Column Name

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/ARCHITECTURE.md

Define a custom column name for archiving by overriding the default constant and method.

```php
const ARCHIVED_AT = 'deleted_at';

public function getArchivedAtColumn()
{
    return defined('static::ARCHIVED_AT') ? static::ARCHIVED_AT : 'archived_at';
}
```

--------------------------------

### Relationship Scope Integration

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/EXAMPLES.md

Define custom relationship methods that apply archive scopes to filter results.

```php
class User extends Model
{
    use Archivable;
    
    public function posts()
    {
        return $this->hasMany(Post::class);
    }
    
    public function activePosts()
    {
        return $this->posts()->withoutArchived();
    }
}

$user = User::find(1);
$user->posts; // Includes archived posts (no global scope on relation)
$user->activePosts; // Only non-archived posts
```

--------------------------------

### Define model primary key

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/errors.md

Ensure models using the Archivable trait have a primary key defined to avoid exceptions.

```php
class Post extends Model
{
    use Archivable;
    
    protected $primaryKey = 'id'; // Explicit primary key (usually automatic)
    // Or use the default 'id' primary key
}
```

--------------------------------

### Define Blueprint::dropArchivedAt() signature

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/service-provider.md

The method signature for dropping an archived timestamp column in migrations.

```php
Blueprint::dropArchivedAt($column = 'archived_at'): void
```

--------------------------------

### Define Route::allowsArchivedBindings() signature

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/service-provider.md

The method signature for checking if a route allows archived models in binding.

```php
Route::allowsArchivedBindings(): bool
```

--------------------------------

### Implement Archivable Trait

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/README.md

Include the Archivable trait in your Eloquent model to enable archiving functionality.

```php
namespace App\Models;

use \Illuminate\Database\Eloquent\Model;
use \LaravelArchivable\Archivable;

class Post extends Model {

    use Archivable;
    ...
}
```

--------------------------------

### Define ARCHIVED_AT constant

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/configuration.md

Sets a custom column name for the archive timestamp on a specific model.

```php
class Post extends Model
{
    use Archivable;
    
    const ARCHIVED_AT = 'archived_date';
}
```

```php
class Article extends Model
{
    use Archivable;
    
    const ARCHIVED_AT = 'deleted_at'; // Use 'deleted_at' instead of 'archived_at'
}

// The following methods will use 'deleted_at' column:
$article = Article::first();
$article->archive(); // Sets deleted_at to current timestamp
echo $article->getArchivedAtColumn(); // Returns 'deleted_at'
```

--------------------------------

### unArchive()

Source: https://github.com/joelbutcher/laravel-archivable/blob/1.x/_autodocs/api-reference/archivable-scope.md

Unarchives all records matching the query.

```APIDOC
## unArchive()

### Description
Performs a batch restore operation by setting the archived_at column to null for all records matching the query. This is a direct database update and does not trigger model events.

### Signature
`Builder::unArchive(): int`

### Returns
- **int** - The number of records affected by the update.
```
Tokens:
Raw