GravityKit\GravityMigrate\Background\CleanupHandler
A background import holds the same import lock and temp tables a synchronous one does; a
background export leaves the same EXPORT_RECORD behind. Nothing else releases those when the job that was holding them stops outside a normal user request — canceled from the Background Jobs UI, failed, or still running when the plugin is deactivated. This class is that release valve, driven by the Foundation scheduler's own job lifecycle hooks plus a deactivation hook.
Since: %ver%
Source: src/Background/CleanupHandler.php:25
Details
- Kind:
class - Namespace:
GravityKit\GravityMigrate\Background
Methods
| Method | Description |
|---|---|
get_instance() | Returns class instance. |
__construct() | Constructor. |
util() | Resolves the utility helper on first use. |
register_hooks() | Registers this handler's Foundation scheduler hooks. Safe to call more than once: it always |
handle_job_ended() | Handles a job that ended without finishing (canceled or failed). |
handle_job_completed() | Handles a job that completed successfully. |
cleanup_import() | Releases what a background import was holding: the import lock (only if this run still |
cleanup_external_import() | Drops one batch's progress record, or every batch's. |
sweep_external_import_records() | Deletes progress records older than a cut-off. |
cleanup_export() | Releases what a background export was holding: marks its EXPORT_RECORD canceled and drops |
on_deactivate() | Cancels every pending or running gravitymigrate_* job and releases whatever they were |
cancel_live_jobs() | Cancels every live gravitymigrate_* job: pending, running, or paused, of every name. |
Method Reference
get_instance()
public static function get_instance(): CleanupHandler
Returns class instance.
Returns
CleanupHandler
Since: %ver%
Source: src/Background/CleanupHandler.php:64
__construct()
public function __construct( $gateway=null, ?Util $util=null, $import=null )
Constructor.
Dependencies resolve lazily, in the accessors below, not here: this class is constructed
(and its hooks registered) on every request, and eagerly resolving Util::get_instance()
would bootstrap WP_Filesystem -- and pull in wp-admin/includes/admin.php -- on every
front-end page load. The parameters are untyped (\SchedulerGateway is final, and a
real \Import cannot construct without $wpdb) so a duck-typed stand-in can be
injected.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$gateway | mixed | null | A \SchedulerGateway, or a stand-in exposing its public methods. |
$util | Util | null | null | Defaults to Util::get_instance(). |
$import | mixed | null | An \Import, or a stand-in exposing its public methods. Defaults to Import::get_instance(). |
Since: %ver%
Source: src/Background/CleanupHandler.php:88
util()
public function util(): Util
Resolves the utility helper on first use.
Returns
Util
Since: %ver%
Source: src/Background/CleanupHandler.php:116
register_hooks()
public function register_hooks(): void
Registers this handler's Foundation scheduler hooks. Safe to call more than once: it always
resolves to the same singleton, and WordPress de-duplicates identical (callback, priority) pairs.
Returns
void
Since: %ver%
Source: src/Background/CleanupHandler.php:148
handle_job_ended()
public function handle_job_ended( $job ): void
Handles a job that ended without finishing (canceled or failed).
$job is deliberately untyped: Foundation Scheduler hooks pass a JobInstance from whichever vendored Foundation copy is currently winning the loader election, which is not necessarily this plugin's own copy, so it is read by shape rather than by type.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$job | mixed | The job instance. |
Returns
void
Since: %ver%
Source: src/Background/CleanupHandler.php:167
handle_job_completed()
public function handle_job_completed( $job ): void
Handles a job that completed successfully.
The drivers deliberately leave their BG_*_STATE option in place on completion, so a status poll racing the job's own finish still has step and result values to read; this hook is where the option is finally deleted. (Import's lock, temp tables, and uploaded bundle are already released by the import's own normal finish.)
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$job | mixed | The job instance. |
Returns
void
Since: %ver%
Source: src/Background/CleanupHandler.php:205
cleanup_import()
public function cleanup_import(): void
Releases what a background import was holding: the import lock (only if this run still
owns it), the temp tables, the uploaded bundle, and the plugin's own state options.
Safe to call with no background import running — every step is a no-op against state that is already absent.
Returns
void
Since: %ver%
Source: src/Background/CleanupHandler.php:258
cleanup_external_import()
public function cleanup_external_import( int $job_id=0 ): void
Drops one batch's progress record, or every batch's.
The record holds that batch's per-form results, because job data cannot: Foundation
persists job data through Action Scheduler's varchar(8000) extended_args, and past
8,000 characters the write is refused silently. So this is not routine end-of-run
cleanup -- it destroys the only account of what the run did, and is called on
deactivation and by the age sweep.
Safe to call with nothing running: deleting an absent option is a no-op.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$job_id | int | 0 | The batch whose record to drop. 0 drops every batch's. |
Returns
void
Since: %ver%
Source: src/Background/CleanupHandler.php:297
sweep_external_import_records()
public function sweep_external_import_records( int $older_than_days=30 ): int
Deletes progress records older than a cut-off.
One row per batch, kept so the results screen survives a reload, which means nothing deletes them at the end of a run and they would otherwise accumulate one per migration forever. Age is the only safe discriminator: a job id says nothing about whether anybody is still looking at it.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$older_than_days | int | 30 | Records last written before this many days ago are dropped. 0 drops all of them. |
Returns
int— How many were dropped.
Since: %ver%
Source: src/Background/CleanupHandler.php:322
cleanup_export()
public function cleanup_export(): void
Releases what a background export was holding: marks its EXPORT_RECORD canceled and drops
the plugin's own state option. The export's directory is already cleared on the existing gk/gravitymigrate/cron/clear-exports schedule, same as a synchronous export's leftovers.
Safe to call with no background export running.
Returns
void
Since: %ver%
Source: src/Background/CleanupHandler.php:371
on_deactivate()
public static function on_deactivate(): void
Cancels every pending or running gravitymigrate_* job and releases whatever they were
holding, on plugin deactivation.
Returns
void
Since: %ver%
Source: src/Background/CleanupHandler.php:392
cancel_live_jobs()
public function cancel_live_jobs(): void
Cancels every live gravitymigrate_* job: pending, running, or paused, of every name.
Cancellation runs each job's job/canceled cleanup synchronously, so what a run was
holding (lock, temp tables, state options) is released with it. A no-op when the
scheduler is unavailable or nothing is live.
Returns
void
Since: %ver%
Source: src/Background/CleanupHandler.php:433