Livewire Laravel Package

Getting Started

• Install with composer require (or the package’s documented require line), then run the package’s install command. In v1.1.2 the install command now auto-registers the orphan sweeper in the scheduler, so review the scheduler diff it produces rather than adding the schedule manually.
• Publish the config file if the install command does not do it automatically. The config is the first place to look: it defines which models/relationships are swept, whether soft-deleted parents count as orphans, chunk sizes, and dry-run defaults.
• Confirm the schedule actually landed:
  • Laravel 11+: check routes/console.php or bootstrap/app.php for the added Schedule::command(...) entry.
  • Laravel 10 and below: check app/Console/Kernel.php.
  • Run php artisan schedule:list to verify the sweeper is registered and see its cron expression.
• First use case: run the sweeper manually in dry-run mode against a single model/relationship before trusting the schedule. Typical flow:
  1. Configure one target model in the config.
  2. Run the sweeper command with --dry-run (or the package’s equivalent) and inspect the orphan count.
  3. Run without dry-run on a staging copy.
  4. Let the auto-registered schedule take over, or replace it with your own cadence.

Implementation Patterns

• Auto-scheduled sweeper as the default safety net. The v1.1.2 install behavior means most applications should keep the generated schedule and tune only the frequency and target list. Treat the schedule entry as application code: commit it, review it in PRs, and keep it environment-aware.
• Raw-delete cleanup pattern. The new documentation confirms the intended workflow for bulk/raw deletes: when you delete parent rows with DB::table(...)->delete() or raw SQL, model events and cascades do not fire. The sweeper is the reconciliation mechanism. Pair raw-delete code paths with a note (or a test) that the next sweep is responsible for cleaning the orphaned children.
• Manual scheduling when you need control. If the auto-registered entry conflicts with existing maintenance windows, replace it with an explicit schedule:

  Schedule::command('orphan-sweeper:run')->dailyAt('02:30')->withoutOverlapping();
  

  Keep withoutOverlapping() for large tables.
• Chunked/queued sweeps. For large datasets, configure chunk sizes and consider dispatching the sweep as a queued job so the scheduler only enqueues work. Log the number of orphans found and deleted per run.
• CI guardrail. Add a dry-run sweep to a staging/CI job after seed data is loaded. This catches code paths that create orphans (especially raw deletes) before they reach production.
• Integration with existing cleanup jobs. If you already run a nightly cleanup command, either fold the sweeper into that command or ensure the two do not target the same tables concurrently. Use withoutOverlapping() and, where possible, a shared lock.
• Extension points. Use the package’s events (before/after orphan deletion) or custom sweeper classes to add auditing, notifications, or exclusions. Prefer config overrides over forking the package.

Gotchas and Tips

• The install command modifies your scheduler. Re-running install on an already-installed app can duplicate the schedule entry. After upgrading to v1.1.2, diff the scheduler file and remove duplicates. In CI/CD, make the registration idempotent or document that install is a one-time local step.
• Deployment script removal. v1.1.2 removes the deployment script from the project structure. If your pipeline relied on that script to register the schedule or run the sweeper post-deploy, you must now handle scheduling explicitly (the install command only runs when you invoke it). Verify each environment’s schedule with schedule:list after deploy.
• Raw deletes leave orphans until the next sweep. This is expected, not a bug. The new docs make this explicit. Do not assume immediate cleanup after a raw delete; if downstream code depends on the children being gone immediately, delete them explicitly or trigger the sweeper.
• Foreign-key and relationship configuration drives accuracy. False positives usually mean the configured parent/child key or relationship name is wrong. Start with one model, verify the dry-run count against a manual query, then expand.
• Soft deletes need a deliberate choice. Confirm whether a soft-deleted parent makes its children orphans in your config. The default may not match your domain expectations.
• Performance on large tables. Ensure foreign-key columns used for orphan detection are indexed. Use chunking and avoid running the sweeper during peak traffic. A dry-run count on a large table can still be expensive.
• Laravel 11 scheduler location. The auto-registration writes to a different file than older Laravel versions. If the schedule “doesn’t run,” check schedule:list first, then the correct file for your framework version, then the server’s cron entry for schedule:run.
• Dry-run and logging before enabling deletion. Always inspect dry-run output on production-like data. Enable the package’s logging (or wrap the command) so deletions are auditable; orphan sweepers are destructive by design.
• Environment parity. If the schedule is auto-registered only in local installs, production may never run the sweeper. Treat schedule registration as deployable configuration, not a local convenience.