Weave Code
Operations Laravel Package
directorytree/operations
DirectoryTree Operations is a Laravel package for encapsulating business logic in reusable operation classes. Generate operations, validate and authorize input, run them synchronously or queue them, and keep controllers and jobs thin, focused, and easy to test.
Run one-time deployment operations in Laravel.
Frequently asked questions about Operations
- What is DirectoryTree Operations used for in a Laravel app?
- It encapsulates one-time deployment logic as reusable operation classes. Migrations own schema, seeders own repeatable data, and Operations owns idempotent run-once work such as backfills, legacy record normalization, third-party ID remapping, or cache and queue reconfiguration after a flag removal. Each operation is a container-resolved class recorded as executed, so it never runs twice.
- How do I install directorytree/operations?
- Install it with Composer, publish the config and migration files, and run one migrate. Then add the package's artisan entrypoint to your deploy script right after migrations. There is no daemon, no queue worker, and no external service or credential surface required for the base install.
- How do I create and run an operation?
- You generate an operation class with the package's generator, then implement your business logic inside it. The package supports validating and authorizing input before the work runs, and operations are resolved from the Laravel container so dependencies can be injected. You execute them through the provided artisan command, either synchronously or queued.
- Can operations be queued instead of run synchronously?
- Yes. Operations can be run inline during deployment or pushed onto a queue for longer-running work. Queueing is useful for heavy backfills that would otherwise slow a deploy, but it means you need a working queue worker when the operation executes. Keeping controllers and jobs thin is the main reason to move that logic into an operation class in the first place.
- What are checkpoints in Operations v1.2.0 and should I use them?
- Checkpoints are an opt-in feature that let an operation save its progress so it can resume after a failure instead of restarting from the beginning. They add a per-operation progress state on top of the existing has-this-run record, so the operation author must choose checkpoint granularity and make sure work between checkpoints is idempotent, because a resume replays from the last checkpoint boundary. If you do not need resumability, you can skip checkpoints entirely and use the package exactly as before.
- Which Laravel and PHP versions does directorytree/operations support?
- Support is defined by the constraints in the package's composer.json, so check those against your application's Laravel and PHP versions before pinning. It follows standard Laravel package conventions: a service provider, a publishable config, and a tracking-table migration. Verify compatibility on the exact tagged version you intend to deploy rather than assuming the latest release matches your stack.
- How do I test operations in my test suite?
- Because operations are resolved from the container and keep their logic in a single class, you can unit test them like any other service by injecting fakes for their dependencies. That is the main testing benefit: controllers and jobs stay thin while the actual logic is exercised directly. You can also assert against the package's tracking table when you need to confirm an operation was recorded as executed.
- Is directorytree/operations safe to use in production?
- The main architectural cost is that it introduces a second source of deployment state in the database, parallel to the migrations table. Execution records are environment-local, so staging and production diverge, and a restored or cloned database can silently carry stale done records or stale partial-progress checkpoints. That is manageable for a handful of operations but becomes a governance problem as the operations directory grows, so review the tracking table as part of your deploy contract.
- How is this different from migrations and seeders?
- Migrations handle schema changes and seeders handle repeatable data, but neither is designed for one-time application logic that must never run again. Operations fills that gap by recording each executed operation in its own table, so a deploy can safely re-run the command without repeating completed work. If you already treat php artisan migrate as a deployment gate, adding an operations step after it is a conceptual extension rather than a new paradigm.
- What are the alternatives to directorytree/operations and is it well maintained?
- The common alternative is a hand-rolled artisan command backed by your own flag or history table, or logic embedded in a one-off migration, both of which you maintain yourself. DirectoryTree Operations standardizes that pattern with generators, validation, authorization, queueing, and now opt-in checkpoints. Maintenance is a consideration: it has a bus factor of one, low adoption at review time, and v1.2.0 came from an external pull request, which is a positive signal but not yet a trend. Pin the version you audit and read the source for checkpoint semantics, since the release notes do not document them in depth.
Weaver
How can I help you explore Laravel packages today?