One-Time Operations for Laravel

https://github.com/timokoerber/laravel-one-time-operations
Admin
A Laravel package that enables running one-time operations after deployment, similar to migrations,...
Tokens:43,166
Snippets:335
Trust Score:8
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Sample output of operations:show

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/operations-show-command.md

Example console output showing two-column detail lines with operation name, tag, timestamp, and status.

```shell
# sample output (two-column detail lines)
2025_01_15_103000_awesome_operation (before-migrations) 2015-10-21 07:28:00 PROCESSED
2025_01_15_103000_cleanup  PENDING
2022_01_01_000000_old_op   DISPOSED
```

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

### Usage examples

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/operations-make-command.md

Shows the command with the full stub, the essential stub via `--essential` or `-e`, and the alias `make:operation`.

```shell
# full stub ($async, $queue, $tag)
php artisan operations:make <operation_name>

# essential stub (only process())
php artisan operations:make <operation_name> --essential
php artisan operations:make <operation_name> -e

# command alias
php artisan make:operation <operation_name>
```

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

### Usage examples for operations:show

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/operations-show-command.md

Shell commands showing how to list all operations or filter by status. Includes all, pending, processed, disposed, and combined filters.

```shell
# all operations
php artisan operations:show

# filtered
php artisan operations:show pending
php artisan operations:show processed
php artisan operations:show disposed
php artisan operations:show pending disposed
```

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

### Create required database table with artisan migrate

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/README.md

Creates the table the package needs in your database. Run after installing the package.

```shell
php artisan migrate
```

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

### Output / exit code example

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/operations-make-command.md

Shell commands and their expected output, including success, failure with 'File already exists' warning, and the alias with `-e` option.

```shell
$ php artisan operations:make AwesomeOperation
One-time operation [2025_01_15_103000_awesome_operation] created successfully.

$ php artisan operations:make AwesomeOperation
# warning: File already exists: /app/operations/2025_01_15_103000_awesome_operation.php
# exit code 1

$ php artisan make:operation MyOp -e
One-time operation [2025_01_15_103000_my_op] created successfully.
```

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

### Basic operation file (default stub)

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation.md

Shows the default structure of a one-time operation file. It includes an async flag, queue name, optional tag, and a process method. The example updates user statuses.

```php
<?php
// operations/2025_01_15_103000_awesome_operation.php

use TimoKoerber\LaravelOneTimeOperations\OneTimeOperation;

return new class extends OneTimeOperation
{
    /**
     * Determine if the operation is being processed asynchronously.
     */
    protected bool $async = true;

    /**
     * The queue that the job will be dispatched to.
     */
    protected string $queue = 'default';

    /**
     * A tag name, that this operation can be filtered by.
     */
    protected ?string $tag = null;

    /**
     * Process the operation.
     */
    public function process(): void
    {
        User::where('active', 1)->update(['status' => 'awesome']);
    }
};
```

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

### Install package with Composer

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/README.md

Requires the timokoerber/laravel-one-time-operations package via Composer. Run this in your project root to add the package as a dependency.

```shell
composer require timokoerber/laravel-one-time-operations
```

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

### operations:process command usage examples

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/operations-process-command.md

Shows various ways to invoke the `operations:process` Artisan command, including options for sync/async, test mode, queue, tags, isolated execution, and re-running a single operation.

```shell
# process all unprocessed operations (async per each operation's $async)
php artisan operations:process

# force sync / async
php artisan operations:process --sync
php artisan operations:process --async

# test mode — never tags operations as processed
php artisan operations:process --test

# force a queue
php artisan operations:process --queue=redis

# tags (repeatable)
php artisan operations:process --tag=awesome --tag=foobar

# isolated execution on multi-server
php artisan operations:process --isolated

# re-run a single operation (confirmation prompt if already processed)
php artisan operations:process 2025_01_15_103000_awesome_operation
php artisan operations:process 2025_01_15_103000_awesome_operation.php
```

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

### Environment-driven configuration in config/one-time-operations.php

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/configuration.md

Example configuration file for the laravel-one-time-operations package. It maps environment variables to the 'directory', 'table', and 'connection' settings, with defaults for 'directory' and 'table'. Use this to enable environment-driven configuration.

```php
return [
    'directory' => env('ONE_TIME_OPERATIONS_DIRECTORY', 'operations'),
    'table' => env('ONE_TIME_OPERATIONS_TABLE', 'operations'),
    'connection' => env('ONE_TIME_OPERATIONS_CONNECTION'),
];
```

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

### Custom re-run logic for an existing file

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-file.md

Retrieve a specific operation file by name using getOperationFileByName(). The example shows how to access the operation name, class object (loaded once and cached), async status, queue, tag, and whether it has been processed.

```php
use TimoKoerber\LaravelOneTimeOperations\OneTimeOperationManager;

$file = OneTimeOperationManager::getOperationFileByName('2025_01_15_103000_awesome_operation');

echo $file->getOperationName();            // 2025_01_15_103000_awesome_operation
$class = $file->getClassObject();          // loads the file once; cached afterwards
echo $class->isAsync() ? 'async' : 'sync';
echo $class->getQueue();                   // e.g. 'default'
echo $class->getTag() ?? 'no tag';         // e.g. 'before-migrations'

if ($file->getModel()) {
    // operation was already processed
}
```

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

### ColoredOutput trait signature examples (bold and gray methods)

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/base-command-and-utils.md

Shows the protected bold() and gray() methods from the ColoredOutput trait, which wrap messages in Symfony console markup. Used inside string templates for components like twoColumnDetail.

```php
protected function bold(string $message): string
{
    return sprintf('<options=bold>%s</>', $message);
}

protected function gray(string $message): string
{
    return sprintf('<fg=gray>%s</>', $message);
}
```

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

### handle() method

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/operations-process-command.md

The main entry point for the command. It reads options, validates them (empty tags and conflicting sync/async flags), and either processes a single operation by name or the next pending operations. Returns self::SUCCESS or self::FAILURE.

```php
public function handle(): int
{
    $this->displayTestmodeWarning();

    $this->forceAsync = (bool) $this->option('async');
    $this->forceSync = (bool) $this->option('sync');
    $this->queue = $this->option('queue');
    $this->tags = $this->option('tag');

    if (! $this->tagOptionsAreValid()) {
        $this->components->error('Abort! Do not provide empty tags!');

        return self::FAILURE;
    }

    if (! $this->syncOptionsAreValid()) {
        $this->components->error('Abort! Process either with --sync or --async.');

        return self::FAILURE;
    }

    if ($operationName = $this->argument('name')) {
        return $this->proccessSingleOperation($operationName);
    }

    return $this->processNextOperations();
}
```

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

### handle() method implementation

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/operations-show-command.md

Main entry point for the command. Validates filters, retrieves and filters operation lines, outputs them or an info message if none, and returns SUCCESS or FAILURE on exception.

```php
public function handle(): int
{
    try {
        $this->validateFilters();
        $this->newLine();

        $operationOutputLines = $this->getOperationLinesForOutput();
        $operationOutputLines = $this->filterOperationLinesByStatus($operationOutputLines);

        if ($operationOutputLines->isEmpty()) {
            $this->components->info('No operations found.');
        }

        /** @var OperationsLineElement $lineElement */
        foreach ($operationOutputLines as $lineElement) {
            $lineElement->output($this->components);
        }

        $this->newLine();

        return self::SUCCESS;
    } catch (Throwable $e) {
        $this->components->error($e->getMessage());

        return self::FAILURE;
    }
}
```

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

### Reference status label from OneTimeOperationsCommand

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/base-command-and-utils.md

Use the status label constants on OneTimeOperationsCommand to filter rows by status. The example shows LABEL_DISPOSED which equals 'DISPOSED'.

```php
use TimoKoerber\LaravelOneTimeOperations\Commands\OneTimeOperationsCommand;

// filter rows by status label
$status = OneTimeOperationsCommand::LABEL_DISPOSED; // 'DISPOSED'
```

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

### Run synchronously and handle a failure

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-process-job.md

Demonstrates using dispatchSync() to run the job inline, catching FileNotFoundException for a missing operation file and Throwable for errors inside process(). The comment suggests that deployment should abort on process() errors.

```php
use TimoKoerber\LaravelOneTimeOperations\Jobs\OneTimeOperationProcessJob;
use Illuminate\Contracts\Filesystem\FileNotFoundException;
use Throwable;

try {
    OneTimeOperationProcessJob::dispatchSync('2025_01_15_103000_awesome_operation');
} catch (FileNotFoundException $e) {
    // operation file was deleted/disposed
    report($e);
} catch (Throwable $e) {
    // error inside process() — deployment should abort
    throw $e;
}
```

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

### createFile() method implementation

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-creator.md

Creates a new operation file at the operations directory with the given name. Throws an ErrorException if the file already exists. Uses a stub file determined by getStubFilepath().

```php
/**
 * @throws \Throwable
 */
public function createFile(): \SplFileInfo
{
    $path = $this->getPath();
    $stub = $this->getStubFilepath();
    $this->ensureDirectoryExists();

    throw_if(File::exists($path), ErrorException::class, sprintf('File already exists: %s', $path));

    File::put($path, $stub);

    return new \SplFileInfo($path);
}
```

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

### Create a full operation file with OneTimeOperationCreator::createOperationFile

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-creator.md

Creates an operation file named 'AwesomeOperation' and outputs the generated operation name. The name is timestamped and snake_cased.

```php
use TimoKoerber\LaravelOneTimeOperations\OneTimeOperationCreator;

$operationFile = OneTimeOperationCreator::createOperationFile('AwesomeOperation');

echo $operationFile->getOperationName();
// 2025_01_15_103000_awesome_operation
```

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

### Create an essential file and handle duplicate-file error

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-creator.md

Creates an operation file with the attribute-less stub (async=true, queue='default', tag=null). Throws ErrorException if the file already exists, with message 'File already exists: /app/operations/2025_01_15_103000_awesome_operation.php'.

```php
use TimoKoerber\LaravelOneTimeOperations\OneTimeOperationCreator;
use ErrorException;

try {
    $operationFile = OneTimeOperationCreator::createOperationFile('AwesomeOperation', true);
    // uses the attribute-less stub; $async=true, $queue='default', $tag=null inherited
} catch (ErrorException $e) {
    // "File already exists: /app/operations/2025_01_15_103000_awesome_operation.php"
    $this->warn($e->getMessage());
}
```

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

### createFile(): \SplFileInfo

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-creator.md

Creates the operation file using the appropriate stub and returns the SplFileInfo for the written file. Throws an ErrorException if the file already exists.

```APIDOC
## createFile(): \SplFileInfo

### Description
Creates the operation file at `<operationsDirectory>/<operationName>.php` using the appropriate stub. Returns the SplFileInfo for the written file.

### Method
createFile

### Return
- **Type:** `\SplFileInfo`
- **Description:** The file info for the written file at `<operationsDirectory>/<operationName>.php`.

### Throws
- **ErrorException** - with message `File already exists: <path>` when the file already exists.

### Stub Precedence
1. Custom stub at `base_path('stubs/one-time-operation.stub')` if present
2. Essential stub if `$essential` is true
3. Default stub

### Source
`src/OneTimeOperationCreator.php` line 40
```

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

### createOperationFile static factory method

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-creator.md

Creates a new one-time operation file. Throws ErrorException if the file already exists, and any Throwable from filesystem operations. The $essential parameter selects between the essential stub and the full stub with async, queue, and tag attributes.

```php
/**
 * @throws \Throwable
 */
public static function createOperationFile(string $name, bool $essential = false): OneTimeOperationFile
{
    $instance = new self();
    $instance->setProvidedName($name);
    $instance->setEssential($essential);

    return OneTimeOperationFile::make($instance->createFile());
}
```

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

### Force async or sync dispatch with operations:process

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/README.md

Use --async to force dispatch() or --sync to force dispatchSync(), overriding the $async attribute in the operation file. Processing synchronously during deployment is not recommended because an error could fail the whole deployment.

```shell
php artisan operations:process --async  // force dispatch()
php artisan operations:process --sync   // force dispatchSync()  
```

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

### Publish config with vendor:publish

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/configuration.md

Publishes the package's configuration file to the application's config directory. The output shows the published file path.

```shell
php artisan vendor:publish --provider="TimoKoerber\LaravelOneTimeOperations\Providers\OneTimeOperationsServiceProvider"
# → config/one-time-operations.php
```

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

### operations:process command outputs and errors

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/operations-process-command.md

Shows sample output for a successful run with tags, and error messages for conflicting sync/async flags and empty tags, each with exit code 1.

```shell
# outputs
$ php artisan operations:process --tag=awesome
Processing operations with tags (awesome)
2025_01_15_103000_awesome_operation ......... DONE
Processing finished.

$ php artisan operations:process --sync --async
Abort! Process either with --sync or --async.   # exit 1

$ php artisan operations:process --tag=
Abort! Do not provide empty tags!               # exit 1
```

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

### getOperationFileByName: Build file object from operation name

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Resolves an operation file by name and returns a OneTimeOperationFile instance. Throws FileNotFoundException with message 'File <name>.php does not exist' if the file is missing.

```php
/**
 * @throws \Throwable
 */
public static function getOperationFileByName(string $operationName): OneTimeOperationFile
{
    $filepath = self::pathToFileByName($operationName);

    throw_unless(File::exists($filepath), FileNotFoundException::class, sprintf('File %s does not exist', self::buildFilename($operationName)));

    return OneTimeOperationFile::make(new SplFileInfo($filepath));
}
```

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

### Using the factory

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/operation-model.md

Creates an Operation model instance with the factory, overriding the name attribute. The factory's definition sets dispatched to 'async' and processed_at to a date string.

```php
use TimoKoerber\LaravelOneTimeOperations\Models\Operation;

$operation = Operation::factory()->make([
    'name' => '2025_01_15_103000_awesome_operation',
]);
```

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

### Using the Dispatchable trait with chain options

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-process-job.md

Shows how to chain queue connection, queue name, and delay options when dispatching the job. This uses the Dispatchable trait's dispatch() method and the Queueable trait's chain methods.

```php
use TimoKoerber\LaravelOneTimeOperations\Jobs\OneTimeOperationProcessJob;

OneTimeOperationProcessJob::dispatch('2025_01_15_103000_awesome_operation')
    ->onConnection('redis')
    ->onQueue('operations')
    ->delay(now()->addMinutes(5));
```

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

### make(SplFileInfo $file): self

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-file.md

Static factory method that creates a new OneTimeOperationFile instance wrapping the given SplFileInfo object.

```APIDOC
## make(SplFileInfo $file): self

### Description
Creates a new `OneTimeOperationFile` instance that wraps the provided filesystem info object for an operation file.

### Method
`make` (static)

### Parameters
#### Path Parameters
- `$file` (`SplFileInfo`) - Required - The filesystem info object for the operation file.

### Return
- `OneTimeOperationFile` - A new instance wrapping `$file`.

### Source
`src/OneTimeOperationFile.php` line 16
```

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

### Run tests with composer test

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/README.md

Use this command to execute the package's test suite. It is the standard way to run tests for this Laravel package.

```bash
composer test
```

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

### Vendor publish command for OneTimeOperationsServiceProvider

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operations-service-provider.md

Command to publish the config file for this provider. Used to customize directory, table, and connection settings.

```shell
php artisan vendor:publish --provider="TimoKoerber\LaravelOneTimeOperations\Providers\OneTimeOperationsServiceProvider"
```

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

### Custom stub file for one-time operations

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-creator.md

Place this stub at stubs/one-time-operation.stub in the project root. It is read via File::get and used verbatim as the file body when it exists.

```php
<?php

use TimoKoerber\LaravelOneTimeOperations\OneTimeOperation;

return new class extends OneTimeOperation
{
    protected bool $async = false;

    public function process(): void
    {
        // team-specific default body
    }
};
```

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

### getAllOperationFiles(): Collection

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Returns a collection of OneTimeOperationFile instances for all .php files in the operations directory, whether processed or not. It maps getAllFiles() through OneTimeOperationFile::make().

```php
/**
 * @return Collection<SplFileInfo>
 */
public static function getAllOperationFiles(): Collection
```

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

### getAllOperationFiles(): Collection

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Returns a collection of OneTimeOperationFile instances for all .php files in the operations directory, processed or not.

```APIDOC
## getAllOperationFiles(): Collection

### Description
Returns a collection of OneTimeOperationFile instances for all .php files in the operations directory, processed or not.

### Method
`getAllOperationFiles`

### Return
- **Type:** `Collection` of `OneTimeOperationFile`
- **Description:** All `.php` files in the operations directory, processed or not.

### Source
`src/OneTimeOperationManager.php` line 30
```

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

### Class state properties

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/operations-process-command.md

Declares the protected properties used to store command options: forceAsync, forceSync, queue, and tags. These are initialized with default values and later populated in handle().

```php
// src/Commands/OneTimeOperationsProcessCommand.php (lines 25–31)
protected bool $forceAsync = false;

protected bool $forceSync = false;

protected ?string $queue = null;

protected array $tags = [];
```

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

### getAllOperationFiles()

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Returns a collection of OneTimeOperationFile instances for all operation files in the configured directory.

```APIDOC
## getAllOperationFiles()

### Description
Returns a collection of OneTimeOperationFile instances for all operation files in the configured directory.

### Method
Static method

### Returns
`Collection<OneTimeOperationFile>`
```

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

### getOperationName(): string

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-creator.md

Lazily builds the operation name with a date prefix and snake_case conversion. Returns the full filename including the .php extension.

```APIDOC
## getOperationName(): string

### Description
Lazily builds the operation name as `Y_m_d_His`-prefixed `Str::snake($providedName)` + `.php`. The date prefix is generated using `Carbon::now()->format('Y_m_d_His')`.

### Method
getOperationName

### Return
- **Type:** `string`
- **Description:** The operation filename, e.g., `2025_01_15_103000_awesome_operation.php`.

### Source
`src/OneTimeOperationCreator.php` line 72
```

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

### createOperationFile(string $name, bool $essential = false): OneTimeOperationFile

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-creator.md

Static factory method that creates a new one-time operation file. It sets the provided name and essential flag, then delegates to OneTimeOperationFile::make to return a wrapper around the created file.

```APIDOC
## createOperationFile(string $name, bool $essential = false): OneTimeOperationFile

### Description
Creates a new one-time operation file with a timestamped filename based on the provided name. If essential is true, uses the attribute-less stub; otherwise uses the full stub with async, queue, and tag properties.

### Method
Static factory method

### Signature
```php
public static function createOperationFile(string $name, bool $essential = false): OneTimeOperationFile
```

### Parameters
- **$name** (string) - Required - The name of the operation; used for the filename (`Y_m_d_His` prefix + `Str::snake($name)`).
- **$essential** (bool) - Optional - Default: `false` - When `true`, use the attribute-less stub (`one-time-operation-essential.stub`); when `false`, the full stub with `$async`, `$queue`, `$tag`.

### Return Value
- **OneTimeOperationFile** - Wraps the newly created `SplFileInfo`.

### Throws
- **ErrorException** - With message `File already exists: <path>` if the target file already exists.
- **\Throwable** - Any throwable from filesystem operations (`File::put`, `ensureDirectoryExists`), per the `@throws \Throwable` annotation.

### Example
```php
$operationFile = OneTimeOperationCreator::createOperationFile('my_operation', true);
```
```

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

### getDirectoryName(): string

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Returns the configured directory name for one-time operations.

```APIDOC
## getDirectoryName(): string

### Description
Returns the configured directory name for one-time operations.

### Method
`getDirectoryName`

### Signature
```php
public static function getDirectoryName(): string
```

### Return Value
- (string) - Value of `config('one-time-operations.directory')` (default `'operations'`). No fallback default is applied here.

### Source
`src/OneTimeOperationManager.php` line 106
```

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

### getAllFiles()

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Returns a collection of SplFileInfo objects for all operation files in the configured directory.

```APIDOC
## getAllFiles()

### Description
Returns a collection of SplFileInfo objects for all operation files in the configured directory.

### Method
Static method

### Returns
`Collection<SplFileInfo>`
```

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

### Synchronous operation with a tag and deployment script

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation.md

Shows a synchronous operation with a tag for CI/CD ordering, followed by a deployment script that processes operations with the tag before running migrations. The operation refreshes a materialized view.

```php
<?php
// operations/2025_01_15_103000_make_statistics.php

use TimoKoerber\LaravelOneTimeOperations\OneTimeOperation;

return new class extends OneTimeOperation
{
    protected bool $async = false;   // run inside operations:process, synchronously

    protected string $queue = 'default';

    protected ?string $tag = 'before-migrations';

    public function process(): void
    {
        // e.g. rebuild a materialized view before migrations run
        DB::statement('REFRESH MATERIALIZED VIEW user_summary');
    }
};
```

```shell
php artisan operations:process --tag=before-migrations
php artisan migrate
php artisan operations:process
```

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

### getDirectoryPath(): string

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Returns the absolute directory path for one-time operations, with a trailing slash.

```APIDOC
## getDirectoryPath(): string

### Description
Returns the absolute directory path for one-time operations, with a trailing slash.

### Method
`getDirectoryPath`

### Signature
```php
public static function getDirectoryPath(): string
```

### Return Value
- (string) - Absolute directory path with a trailing slash; leading slashes of the configured name are trimmed. E.g. with `'directory' => 'operations'` this returns `<app-base>/operations/` (the trailing `DIRECTORY_SEPARATOR` is appended).

### Source
`src/OneTimeOperationManager.php` line 111
```

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

### getOperationFileByName($name)

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Retrieves the operation file wrapper by name. Throws a FileNotFoundException if the file does not exist.

```APIDOC
## getOperationFileByName($name)

### Description
Returns the `OneTimeOperationFile` instance for the given operation name. Throws an exception if the file is missing.

### Parameters
- **$name** (string) - Required - The name of the operation file.

### Return Value
- **OneTimeOperationFile** - The file wrapper object.

### Exceptions
- **FileNotFoundException** - Thrown if the operation file does not exist.

### Example
```php
use TimoKoerber\LaravelOneTimeOperations\OneTimeOperationManager;

$file = OneTimeOperationManager::getOperationFileByName($name); // throws FileNotFoundException if missing
```
```

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

### buildFilename($operationName): string

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Builds the filename for an operation by appending `.php` to the operation name.

```APIDOC
## buildFilename($operationName): string

### Description
Builds the filename for an operation by appending `.php` to the operation name.

### Method
`buildFilename`

### Signature
```php
public static function buildFilename($operationName): string
```

### Parameters
- `$operationName` (mixed, untyped in source) - Required - The operation name.

### Return Value
- (string) - `$operationName . '.php'`.

### Source
`src/OneTimeOperationManager.php` line 126
```

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

### Class declaration of OneTimeOperationsMakeCommand

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/operations-make-command.md

The full class definition extending `OneTimeOperationsCommand`. It sets the signature, description, alias `make:operation`, and handles creation with success/failure output.

```php
class OneTimeOperationsMakeCommand extends OneTimeOperationsCommand
{
    protected $signature = 'operations:make
                            {name : The name of the one-time operation}
                            {--e|essential : Create file without any attributes}';

    protected $description = 'Create a new one-time operation';

    protected function configure(): void
    {
        $this->setAliases(['make:operation']);

        parent::configure();
    }

    public function handle(): int
    {
        try {
            $file = OneTimeOperationCreator::createOperationFile($this->argument('name'), $this->option('essential'));
            $this->components->info(sprintf('One-time operation [%s] created successfully.', $file->getOperationName()));

            return self::SUCCESS;
        } catch (Throwable $e) {
            $this->components->warn($e->getMessage());

            return self::FAILURE;
        }
    }
}
```

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

### Find all pending operations and print their names

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Iterates over unprocessed operation files and prints each operation name to the output. Useful for listing pending operations in a script or artisan command.

```php
use TimoKoerber\LaravelOneTimeOperations\OneTimeOperationManager;

foreach (OneTimeOperationManager::getUnprocessedOperationFiles() as $operationFile) {
    echo $operationFile->getOperationName().PHP_EOL;
}
```

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

### Essential operation (attribute-less)

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation.md

Shows the minimal operation file produced by `php artisan operations:make MyOperation --essential`. It only implements `process()` and relies on inherited defaults for `$async`, `$queue`, and `$tag`.

```php
<?php
// operations/2025_01_15_103000_my_operation.php

use TimoKoerber\LaravelOneTimeOperations\OneTimeOperation;

return new class extends OneTimeOperation
{
    public function process(): void
    {
        //
    }
};
```

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

### setEssential(bool $essential): void

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-creator.md

Sets the essential flag, which selects the stub used by createFile().

```APIDOC
## setEssential(bool $essential): void

### Description
Sets the essential flag, which determines which stub is used by `createFile()`.

### Method
setEssential

### Parameters
- **$essential** (bool) - Required - When true, the essential stub is used; otherwise the default stub is used.

### Return
- **Type:** `void`

### Source
`src/OneTimeOperationCreator.php` line 101
```

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

### getAllFiles(): Collection

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Returns a collection of SplFileInfo for each file in the operations directory, or an empty collection when the directory does not exist. It catches DirectoryNotFoundException internally.

```php
/**
 * @return Collection<SplFileInfo>
 */
public static function getAllFiles(): Collection
{
    try {
        return collect(File::files(self::getDirectoryPath()));
    } catch (DirectoryNotFoundException $e) {
        return collect();
    }
}
```

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

### Error handling on a re-run with FileNotFoundException

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-file.md

Wrap getOperationFileByName() and process() in a try-catch to handle a missing operation file. The catch block receives FileNotFoundException and reports the error.

```php
use TimoKoerber\LaravelOneTimeOperations\OneTimeOperationManager;
use Illuminate\Contracts\Filesystem\FileNotFoundException;

try {
    $file = OneTimeOperationManager::getOperationFileByName('2025_01_15_103000_gone_operation');
    $file->getClassObject()->process();
} catch (FileNotFoundException $e) {
    // File 2025_01_15_103000_gone_operation.php does not exist
    report($e);
}
```

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

### Publish config file for one-time operations

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/README.md

Publishes the package configuration so you can customize the operations directory and database table. Run this artisan command to create config/one-time-operations.php.

```shell
php artisan vendor:publish --provider="TimoKoerber\LaravelOneTimeOperations\.Providers\OneTimeOperationsServiceProvider"
```

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

### Force queue for all operations with --queue option

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/README.md

Provide the --queue option to use the given queue for all operations, ignoring the $queue attribute in the class.

```shell
php artisan operations:process --queue=redis  // force redis queue 
```

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

### getOperationFileByModel: Build file object from operation model

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Used when re-running a processed operation (see operations:process <name>). Throws FileNotFoundException with the default empty message if no file matches the model's name attribute.

```php
public static function getOperationFileByModel(Operation $operationModel): OneTimeOperationFile
{
    $filepath = self::pathToFileByName($operationModel->name);

    throw_unless(File::exists($filepath), FileNotFoundException::class);

    return OneTimeOperationFile::make(new SplFileInfo($filepath));
}
```

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

### Dispatch an operation to the queue manually

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-process-job.md

Shows how to manually dispatch a OneTimeOperationProcessJob to a specific queue using the dispatch() method and onQueue(). The operation name is the file name without the .php extension.

```php
use TimoKoerber\LaravelOneTimeOperations\Jobs\OneTimeOperationProcessJob;

OneTimeOperationProcessJob::dispatch('2025_01_15_103000_awesome_operation')->onQueue('redis');
```

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

### Default config/one-time-operation.php content

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/README.md

Default configuration returned by the published config file. The `directory` key sets the project root directory for operations and `table` sets the database table name.

```php
// config/one-time-operation.php

return [
    'directory' => 'operations',
    'table' => 'operations',
];
```

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

### buildFilename() method

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Builds the filename for an operation by appending `.php` to the given operation name. The parameter is untyped in the source and is required.

```php
public static function buildFilename($operationName): string
{
    return $operationName.'.php';
}
```

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

### Deployment script: run migrations and process operations

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/README.md

Add these commands to your deployment script after code deployment and after migrations have been migrated. The operations:process command runs the one-time operations, mirroring how Laravel Migrations are processed.

```shell
...
 - php artisan migrate
 - php artisan operations:process
...
```

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

### pathToFileByName() method

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Returns the absolute path to an operation file by combining the directory path and the filename built from the operation name. The result is like `<operations-directory>/<operationName>.php`, e.g. `/app/operations/2025_01_15_103000_awesome_operation.php`.

```php
public static function pathToFileByName(string $operationName): string
{
    return self::getDirectoryPath().self::buildFilename($operationName);
}
```

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

### getDirectoryPath() method

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Returns the absolute directory path with a trailing slash. Leading slashes of the configured name are trimmed; with `'directory' => 'operations'` it returns `<app-base>/operations/`.

```php
public static function getDirectoryPath(): string
{
    return App::basePath(Str::of(self::getDirectoryName())->rtrim('/')).DIRECTORY_SEPARATOR;
}
```

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

### getAllFiles(): Collection

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Returns a collection of SplFileInfo for all files in the operations directory, or an empty collection if the directory does not exist.

```APIDOC
## getAllFiles(): Collection

### Description
Returns a collection of SplFileInfo for all files in the operations directory, or an empty collection if the directory does not exist.

### Method
`getAllFiles`

### Return
- **Type:** `Collection` of `SplFileInfo`
- **Description:** One per file in the directory, or empty collection when directory does not exist.

### Source
`src/OneTimeOperationManager.php` line 54
```

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

### Command signature (exact from source)

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/operations-make-command.md

The protected `$signature` property defining the command's arguments and options. The `name` argument is required and the `--e|essential` option is optional.

```php
protected $signature = 'operations:make
                        {name : The name of the one-time operation}
                        {--e|essential : Create file without any attributes}';
```

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

### getDirectoryPath()

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Returns the full path to the configured operations directory.

```APIDOC
## getDirectoryPath()

### Description
Returns the full path to the configured operations directory.

### Method
Static method

### Returns
`string`
```

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

### Configure one-time-operations.php

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/configuration.md

Default configuration file for the Laravel package. It defines the directory for operation files, the table name for operation entries, and an optional database connection for multitenancy. All values are consumed via config('one-time-operations.*') and can be overridden by publishing the config.

```php
<?php

return [

    // Directory name - the directory in which your operation files are being saved (based on root directory)
    'directory' => 'operations',

    // Table name - name of the table that stores your operation entries
    'table' => 'operations',

    // Database Connection Name - Change the model connection, support for Multitenancy
    // Only change when you want to deviate from your system default repository
    'connection' => null,
];
```

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

### Iterate pending operations with OneTimeOperationManager

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-file.md

Use getUnprocessedOperationFiles() to loop through pending operation files. For each file, call process() to execute directly and getModel() to check if it has been processed (null means not yet processed).

```php
use TimoKoerber\LaravelOneTimeOperations\OneTimeOperationManager;

foreach (OneTimeOperationManager::getUnprocessedOperationFiles() as $operationFile) {
    $operationFile->getClassObject()->process();       // execute directly
    $model = $operationFile->getModel();               // null → not yet processed
}
```

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

### buildFilename()

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Builds a filename for an operation based on the given name.

```APIDOC
## buildFilename()

### Description
Builds a filename for an operation based on the given name.

### Method
Static method

### Parameters
- **name** (string) - Required - The operation name.

### Returns
`string`
```

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

### storeOperation() method

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/operation-model.md

Static method that creates or retrieves an Operation record using firstOrCreate. Stores the operation name, dispatched status based on the $async parameter, and sets processed_at to now(). Returns the created or existing model.

```php
public static function storeOperation(string $operation, bool $async): self
{
    return self::firstOrCreate([
        'name' => $operation,
        'dispatched' => $async ? self::DISPATCHED_ASYNC : self::DISPATCHED_SYNC,
        'processed_at' => now(),
    ]);
}
```

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

### getDirectoryName()

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Returns the configured operations directory name.

```APIDOC
## getDirectoryName()

### Description
Returns the configured operations directory name.

### Method
Static method

### Returns
`string`
```

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

### Manual registration in config/app.php

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operations-service-provider.md

Add the provider class to the providers array for manual registration in older Laravel apps or explicit listing.

```php
'providers' => [
    // ...
    TimoKoerber\LaravelOneTimeOperations\Providers\OneTimeOperationsServiceProvider::class,
],
```

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

### Check operation file existence and re-run safely

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Checks whether an operation file still exists before safely re-running it. Uses fileExistsByName() to guard against deleted files, then retrieves the file and model. Note that getOperationFileByName() throws FileNotFoundException if missing, and getModelByName() returns null if never processed.

```php
use TimoKoerber\LaravelOneTimeOperations\OneTimeOperationManager;

$name = '2025_01_15_103000_awesome_operation';

if (! OneTimeOperationManager::fileExistsByName($name)) {
    // Operation file was deleted from the repository (DISPOSED in operations:show)
    return;
}

$file = OneTimeOperationManager::getOperationFileByName($name); // throws FileNotFoundException if missing
$model = OneTimeOperationManager::getModelByName($name);        // null if never processed
```

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

### Run operations:process isolated on multi-server architecture

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/README.md

Use the --isolated option to ensure only one instance of the command runs, leveraging Laravel Isolatable Commands for Multi-Server Architectures.

```shell
php artisan operations:process --isolated 
```

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

### OneTimeOperationCreator::createOperationFile

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-creator.md

Creates a new one-time operation file. Optionally uses an attribute-less stub and throws an ErrorException if the file already exists.

```APIDOC
## OneTimeOperationCreator::createOperationFile

### Description
Creates a new one-time operation file with a timestamped name. If the second parameter is true, it uses an attribute-less stub, inheriting default values for async, queue, and tag. Throws an ErrorException if the file already exists.

### Method
createOperationFile

### Signature
```php
public static function createOperationFile(string $name, bool $essential = false): OneTimeOperationFile
```

### Parameters
- **name** (string) - Required - The base name of the operation (e.g., 'AwesomeOperation').
- **essential** (bool) - Optional - If true, uses the attribute-less stub; defaults to false.

### Return Value
- **OneTimeOperationFile** - The created operation file object.

### Exceptions
- **ErrorException** - Thrown when the file already exists.

### Example
```php
use TimoKoerber\LaravelOneTimeOperations\OneTimeOperationCreator;

$operationFile = OneTimeOperationCreator::createOperationFile('AwesomeOperation');

echo $operationFile->getOperationName();
// 2025_01_15_103000_awesome_operation
```

### Error Handling Example
```php
use TimoKoerber\LaravelOneTimeOperations\OneTimeOperationCreator;
use ErrorException;

try {
    $operationFile = OneTimeOperationCreator::createOperationFile('AwesomeOperation', true);
} catch (ErrorException $e) {
    // "File already exists: /app/operations/2025_01_15_103000_awesome_operation.php"
    $this->warn($e->getMessage());
}
```

### Custom Stub
If a file `stubs/one-time-operation.stub` exists in the project root, it is read and used verbatim as the file body when creating an operation file.
```

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

### operations:process command signature

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/operations-process-command.md

The exact PHP property definition for the `operations:process` command signature, including all arguments and options. Use this to understand the command's interface.

```php
// src/Commands/OneTimeOperationsProcessCommand.php (lines 15–21)
protected $signature = 'operations:process
                        {name? : Name of specific operation}
                        {--test : Process operation without tagging it as processed, so you can call it again}
                        {--async : Ignore setting in operation and process all operations asynchronously}
                        {--sync : Ignore setting in operation and process all operations synchronously}
                        {--queue= : Set the queue, that all jobs will be dispatched to}
                        {--tag=* : Process only operations, that have one of the given tag}';
```

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

### getTableName(): string

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Returns the configured database table name for one-time operations.

```APIDOC
## getTableName(): string

### Description
Returns the configured database table name for one-time operations.

### Method
`getTableName`

### Signature
```php
public static function getTableName(): string
```

### Return Value
- (string) - Value of `config('one-time-operations.table')`, defaulting to `'operations'`.

### Source
`src/OneTimeOperationManager.php` line 121
```

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

### Merge default config in service provider

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/configuration.md

Merges the package's default configuration into the application's config repository, ensuring defaults exist even before the user publishes the config. This is part of the service provider's register method.

```php
public function register()
{
    $this->mergeConfigFrom(
        __DIR__.'/../../config/one-time-operations.php', 'one-time-operations'
    );
}
```

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

### getDirectoryName() method

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Returns the configured operations directory name from the `one-time-operations.directory` config key. The default is `'operations'` but no fallback is applied here, so the value may be null if not set.

```php
public static function getDirectoryName(): string
{
    return Config::get('one-time-operations.directory');
}
```

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

### Catch ErrorException for existing operation file

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/errors.md

Wrap OneTimeOperationCreator::createFile() in a try/catch to handle the ErrorException thrown when the target operation file already exists. The exception message is 'File already exists: <operations-directory>/<operationName>.php'. The operations:make command catches any Throwable and prints the message as a warning, returning exit code 1.

```php
use TimoKoerber\.LaravelOneTimeOperations\OneTimeOperationCreator;
use ErrorException;

try {
    OneTimeOperationCreator::createFile();
} catch (ErrorException $e) {
    // handle
}
```

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

### newFactory() method

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/operation-model.md

Protected factory hook that returns a new OperationFactory instance, enabling Operation::factory().

```php
protected static function newFactory(): OperationFactory
{
    return new OperationFactory();
}
```

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

### setProvidedName(string $providedName): void

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-creator.md

Sets the provided name for the operation. This name is stored and used only by initOperationName().

```APIDOC
## setProvidedName(string $providedName): void

### Description
Sets the provided name for the operation. This name is stored and used only by `initOperationName()`.

### Method
setProvidedName

### Parameters
- **$providedName** (string) - Required - The name to be stored and used for generating the operation name.

### Return
- **Type:** `void`

### Source
`src/OneTimeOperationCreator.php` line 96
```

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

### pathToFileByName()

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Returns the full path to the operation file for the given operation name.

```APIDOC
## pathToFileByName()

### Description
Returns the full path to the operation file for the given operation name.

### Method
Static method

### Parameters
- **name** (string) - Required - The operation name.

### Returns
`string`
```

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

### handle() method of OneTimeOperationProcessJob

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-process-job.md

The handle method resolves the operation class via OneTimeOperationManager::getClassObjectByName() and calls process() on it. Any Throwable from process() propagates to the queue worker (async) or caller of dispatchSync() (sync). A missing operation file raises FileNotFoundException.

```php
public function handle(): void
{
    OneTimeOperationManager::getClassObjectByName($this->operationName)->process();
}
```

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

### getOperationFileByName()

Source: https://github.com/timokoerber/laravel-one-time-operations/blob/main/_autodocs/api-reference/one-time-operation-manager.md

Returns the OneTimeOperationFile instance for the given operation name.

```APIDOC
## getOperationFileByName()

### Description
Returns the OneTimeOperationFile instance for the given operation name.

### Method
Static method

### Parameters
- **name** (string) - Required - The operation name.

### Returns
`OneTimeOperationFile`
```
Tokens:
Raw