PHP API

Lihat sebagai Markdown Edit di GitHub Dokumentasi di 2cc7b2b

Semua yang ada di Queuety dapat diakses melalui kelas statis Queuety\Queuety. Kelas ini adalah satu-satunya titik masuk untuk mendistribusikan job, membangun alur kerja, menjalankan mesin status, mengelola antrean, dan mengakses subsistem internal.

PHP

use Queuety\Queuety;

Akses inti mandiri

Runtime berbasis DB milik Queuety dapat diinisialisasi di luar WordPress.

Jalur mandiri ini ditujukan untuk inti orkestrasi:

job dan worker (pool worker juga memerlukan konstanta DB_HOST, DB_NAME, DB_USER, dan DB_PASSWORD, lihat di bawah)
alur kerja dan sinyal
mesin status dan peristiwa
artefak, log, metrik, dan jadwal

Ini bukan pengganti adaptor WordPress. Queuety::on_action(), replace_wp_cron(), bootstrap plugin, dan jalur pendaftaran wp queuety ... yang sebenarnya masih memerlukan WordPress.

`Queuety::init( Connection $conn )`

Inisialisasi Queuety dengan koneksi langsung berbasis DB.

PHP

use Queuety\Connection;
use Queuety\Queuety;

$conn = new Connection(
    host: '127.0.0.1:3306',
    dbname: 'wordpress',
    user: 'root',
    password: 'secret',
    prefix: 'wp_',
);

Queuety::init( $conn );

Argumen table_prefix opsional mengubah bagian Queuety pada nama tabel runtime per koneksi:

PHP

$conn = new Connection(
    host: '127.0.0.1:3306',
    dbname: 'wordpress',
    user: 'root',
    password: 'secret',
    prefix: 'wp_',
    table_prefix: 'themequeue_',
);

Dengan demikian, tabel seperti queuety_jobs dipetakan ke wp_themequeue_jobs.

`Queuety::ensure_schema()`

Pastikan tabel runtime Queuety tersedia untuk koneksi aktif.

PHP

Queuety::init( $conn );
Queuety::ensure_schema();

Untuk model lengkap dan batas WordPress, lihat Penggunaan Mandiri.

Job

`Queuety::dispatch( $handler, $payload )`

Distribusikan sebuah job. Menerima string nama handler atau instans Contracts\Job. Mengembalikan builder PendingJob untuk merangkai opsi.

PHP

// Handler name + payload (original API)
Queuety::dispatch( 'send_email', [ 'to' => 'user@example.com' ] );

// Contracts\Job instance (v0.6.0+)
Queuety::dispatch( new SendEmailJob( to: 'user@example.com' ) );

// With options
Queuety::dispatch( 'send_email', [ 'to' => 'user@example.com' ] )
    ->on_queue( 'emails' )
    ->with_priority( Priority::High )
    ->delay( 300 )
    ->max_attempts( 5 )
    ->rate_limit( 10, 60 )
    ->unique()
    ->after( $other_job_id );

// Get the job ID
$job_id = Queuety::dispatch( 'send_email', $payload )->id();

Jika diberikan instans Contracts\Job, serializer mengekstrak FQCN sebagai nama handler dan properti publik sebagai payload. Parameter $payload diabaikan saat $handler berupa instans Job.

Metode `PendingJob`

Metode	Deskripsi
`on_queue( string $queue )`	Menetapkan antrean tujuan
`with_priority( Priority $priority )`	Menetapkan tingkat prioritas
`delay( int $seconds )`	Jeda sebelum job tersedia
`max_attempts( int $max )`	Jumlah percobaan ulang maksimum
`rate_limit( int $max, int $window )`	Batas laju: eksekusi maksimum per jendela detik
`unique()`	Mencegah distribusi ganda
`after( int $job_id )`	Menunggu job lain selesai terlebih dahulu
`concurrency_group( string $group, int $limit )`	Memasukkan job ke grup penerimaan worker bersama
`cost_units( int $units )`	Menyertakan metadata biaya eksekusi relatif pada distribusi
`id()`	Memaksa distribusi dan mengembalikan ID job

concurrency_group() dan cost_units() menjadi bagian dari model Manajemen Sumber Daya yang lebih luas, sehingga distribusi yang sama dapat mengikuti batas konkurensi berbasis jumlah, anggaran antrean atau penyedia berbobot, serta heuristik penerimaan worker.

`Queuety::dispatch_sync( $handler, $payload )`

Jalankan job secara sinkron dalam proses saat ini tanpa memasukkannya ke antrean.

PHP

// With a Job instance
Queuety::dispatch_sync( new SendEmailJob( to: 'user@example.com', subject: 'Hi', body: 'Hello' ) );

// With a handler name and payload
Queuety::dispatch_sync( 'send_email', [ 'to' => 'user@example.com' ] );

Metode handle() milik job dipanggil secara langsung. Tidak ada baris database yang dibuat, worker tidak dilibatkan, dan middleware tidak diterapkan.

`Queuety::batch( $jobs )`

Distribusikan beberapa job dalam satu INSERT multi-baris.

PHP

$job_ids = Queuety::batch( [
    [ 'handler' => 'send_email', 'payload' => [ 'to' => 'a@example.com' ], 'queue' => 'emails' ],
    [ 'handler' => 'send_email', 'payload' => [ 'to' => 'b@example.com' ], 'priority' => 2 ],
] );

`Queuety::create_batch( $jobs )`

Buat BatchBuilder untuk mendistribusikan sekelompok job dengan callback dan pelacakan progres. Lihat Pengelompokan untuk detail lengkap.

PHP

$batch = Queuety::create_batch( [
    new ImportUsersJob( $chunk_1 ),
    new ImportUsersJob( $chunk_2 ),
] )
    ->name( 'Import users' )
    ->then( ImportCompleteHandler::class )
    ->catch( ImportFailedHandler::class )
    ->finally( ImportCleanupHandler::class )
    ->allow_failures()
    ->on_queue( 'imports' )
    ->dispatch();

Metode `BatchBuilder`

Metode	Mengembalikan	Deskripsi
`name( string $name )`	`self`	Menetapkan nama untuk batch
`on_queue( string $queue )`	`self`	Menetapkan antrean untuk semua job dalam batch
`then( string $handler_class )`	`self`	Handler yang dipanggil saat batch berhasil diselesaikan
`catch( string $handler_class )`	`self`	Handler yang dipanggil saat job pertama dalam batch gagal
`finally( string $handler_class )`	`self`	Handler yang dipanggil saat batch selesai (berhasil atau gagal)
`allow_failures()`	`self`	Memungkinkan callback `then` dipanggil meski ada kegagalan
`dispatch()`	`Batch`	Membuat baris batch dan semua job, lalu mengembalikan objek nilai `Batch`

`Queuety::find_batch( $id )`

Cari batch berdasarkan ID. Mengembalikan objek nilai Batch atau null.

PHP

$batch = Queuety::find_batch( $batch_id );

if ( null !== $batch ) {
    echo $batch->progress() . '% complete';
}

Kontrol worker

`Queuety::run_worker( $queue = 'default', $once = false )`

Jalankan satu loop worker secara langsung.

PHP

Queuety::run_worker( 'default' );
Queuety::run_worker( 'critical,default', true );

`Queuety::run_worker_pool( $workers, $queue = 'default' )`

Jalankan pool worker berukuran tetap secara langsung. Memerlukan ekstensi pcntl dan posix. Pool membaca konstanta WordPress DB_HOST, DB_NAME, DB_USER, dan DB_PASSWORD untuk koneksi anaknya (hanya awalan tabel yang berasal dari koneksi yang diinisialisasi), jadi definisikan konstanta tersebut saat menjalankan pool di luar WordPress (#5).

PHP

Queuety::run_worker_pool( 4, 'providers' );

`Queuety::run_auto_scaling_worker_pool( $min_workers, $max_workers, $queue = 'default' )`

Jalankan pool worker adaptif secara langsung. Persyaratannya sama seperti run_worker_pool().

PHP

Queuety::run_auto_scaling_worker_pool( 2, 6, 'providers' );

Objek nilai `Batch`

Metode/Properti	Tipe	Deskripsi
`$id`	`int`	ID batch
`$name`	`string\|null`	Nama batch opsional
`$total_jobs`	`int`	Jumlah total job dalam batch
`$pending_jobs`	`int`	Job yang masih tertunda
`$failed_jobs`	`int`	Jumlah job yang gagal
`$failed_job_ids`	`array`	ID job yang gagal
`$created_at`	`DateTimeImmutable`	Waktu batch dibuat
`$finished_at`	`DateTimeImmutable\|null`	Waktu batch selesai
`$cancelled_at`	`DateTimeImmutable\|null`	Waktu batch dibatalkan
`progress()`	`int`	Persentase penyelesaian (0-100)
`finished()`	`bool`	Apakah batch sudah selesai
`has_failures()`	`bool`	Apakah ada job yang gagal
`cancelled()`	`bool`	Apakah batch dibatalkan

`Queuety::chain( $jobs )`

Buat ChainBuilder untuk eksekusi job berurutan. Setiap job bergantung pada keberhasilan job sebelumnya.

PHP

$first_job_id = Queuety::chain( [
    new FetchDataJob( $url ),
    new ProcessDataJob(),
    new NotifyCompleteJob(),
] )
    ->on_queue( 'pipeline' )
    ->catch( ChainFailedHandler::class )
    ->dispatch();

Metode `ChainBuilder`

Metode	Mengembalikan	Deskripsi
`on_queue( string $queue )`	`self`	Menetapkan antrean untuk semua job dalam rangkaian
`catch( string $handler_class )`	`self`	Handler yang dipanggil saat job mana pun dalam rangkaian dikubur secara permanen
`dispatch()`	`int`	Membuat semua job dengan dependensi berurutan, lalu mengembalikan ID job pertama

`Queuety::retry( $job_id )`

Coba lagi job tertentu. Mengatur ulang statusnya menjadi pending.

PHP

Queuety::retry( 42 );

`Queuety::retry_buried()`

Coba lagi semua job yang dikubur. Mengembalikan jumlah job yang dicoba ulang.

PHP

$count = Queuety::retry_buried();

`Queuety::purge( $older_than_days )`

Hapus job yang sudah selesai. Mengembalikan jumlah job yang dihapus.

PHP

$count = Queuety::purge();     // uses QUEUETY_RETENTION_DAYS
$count = Queuety::purge( 30 ); // purge jobs older than 30 days

Antrean

`Queuety::stats( $queue )`

Dapatkan jumlah job yang dikelompokkan berdasarkan status.

PHP

$stats = Queuety::stats();          // all queues
$stats = Queuety::stats( 'emails' ); // specific queue
// ['pending' => 12, 'processing' => 3, 'completed' => 150, 'failed' => 2, 'buried' => 1]

`Queuety::buried( $queue )`

Dapatkan semua job yang dikubur.

PHP

$jobs = Queuety::buried();
$jobs = Queuety::buried( 'emails' );

`Queuety::pause( $queue )`

Jeda antrean agar worker melewatinya.

PHP

Queuety::pause( 'emails' );

`Queuety::resume( $queue )`

Lanjutkan antrean yang dijeda.

PHP

Queuety::resume( 'emails' );

`Queuety::is_paused( $queue )`

Periksa apakah antrean dijeda.

PHP

if ( Queuety::is_paused( 'emails' ) ) {
    // Queue is paused
}

Alur kerja

`Queuety::workflow( $name )`

Mulai membuat alur kerja. Mengembalikan WorkflowBuilder.

PHP

$workflow_id = Queuety::workflow( 'generate_report' )
    ->then( FetchDataHandler::class )
    ->then( CallLLMHandler::class )
    ->then( FormatOutputHandler::class )
    ->dispatch( [ 'user_id' => 42 ] );

metode `WorkflowBuilder`

Metode	Deskripsi
`then( string $handler_class, ?string $name = null )`	Tambahkan langkah berurutan. Nama bersifat opsional untuk percabangan kondisional.
`parallel( array $handler_classes )`	Tambahkan grup langkah paralel.
`for_each( string $items_key, string $handler_class, ?string $result_key = null, ForEachMode $mode = ForEachMode::All, ?int $quorum = null, ?string $reducer_class = null, ?string $name = null )`	Tambahkan langkah for-each dinamis yang memperluas satu tugas cabang untuk setiap item dalam status alur kerja.
`repeat_while( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )`	Kembali ke langkah bernama sebelumnya selama kunci status publik atau kelas `RepeatCondition` cocok.
`repeat_until( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )`	Kembali ke langkah bernama sebelumnya sampai kunci status publik atau kelas `RepeatCondition` cocok.
`run_workflow( string $workflow_name, WorkflowBuilder $sub_builder )`	Tambahkan langkah untuk menjalankan alur kerja.
`delay( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )`	Tambahkan langkah jeda yang persisten. Semua durasi dijumlahkan.
`wait_for_signal( string $name, ?string $result_key = null, ?string $step_name = null, array $match_payload = [], ?string $correlation_key = null )`	Tambahkan langkah menunggu sinyal. `match_payload` dan `correlation_key` bersifat opsional dan memungkinkan Anda mengabaikan peristiwa yang tidak terkait.
`wait_for_signals( array $signal_names, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	Tunggu beberapa sinyal hingga semuanya atau salah satunya diterima, dengan pencocokan payload dan korelasi opsional.
`wait_for_approval( string $signal_name = 'approval', ?string $result_key = 'approval', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	Tunggu sinyal persetujuan manusia.
`wait_for_decision( string $approve_signal = 'approved', string $reject_signal = 'rejected', ?string $result_key = 'decision', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	Tunggu persetujuan atau penolakan, lalu simpan payload keputusan terstruktur.
`wait_for_input( string $signal_name = 'input', ?string $result_key = 'input', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	Tunggu sinyal masukan manusia.
`wait_for_workflow( int\|string $workflow, ?string $result_key = null, ?string $name = null )`	Tunggu hingga satu ID alur kerja, atau ID alur kerja yang tersimpan dalam status publik, selesai.
`wait_for_workflows( array\|string $workflows, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, ?int $quorum = null )`	Tunggu hingga semua, salah satu, atau kuorum dari beberapa alur kerja selesai.
`wait_for_workflow_group( string $group_key, WaitMode $mode = WaitMode::All, ?int $quorum = null, ?string $result_key = null, ?string $name = null )`	Tunggu grup alur kerja yang telah dimulai sebelumnya berdasarkan kunci grup internal.
`start_workflows( string $items_key, WorkflowBuilder $workflow_builder, string $result_key = 'started_workflow_ids', string $payload_key = 'item', bool $inherit_state = true, ?string $name = null, ?string $group_key = null )`	Jalankan satu alur kerja tingkat atas untuk setiap item runtime, dengan opsi memberi tag kunci grup persisten pada kumpulan yang dimulai.
`start_agents( string $items_key, WorkflowBuilder $workflow_builder, string $result_key = 'agent_workflow_ids', string $payload_key = 'agent_task', bool $inherit_state = true, ?string $name = null, ?string $group_key = null )`	Alias berorientasi agen untuk `start_workflows()`.
`wait_for_agents( array\|string $workflows = 'agent_workflow_ids', WaitMode $mode = WaitMode::All, ?string $result_key = 'agent_results', ?string $name = null, ?int $quorum = null )`	Alias berorientasi agen untuk `wait_for_workflows()`.
`wait_for_agent_group( string $group_key = 'agents', WaitMode $mode = WaitMode::All, ?int $quorum = null, ?string $result_key = 'agent_results', ?string $name = null )`	Alias berorientasi agen untuk `wait_for_workflow_group()`.
`version( string $version )`	Beri tag versi tingkat aplikasi pada definisi alur kerja untuk pemeriksaan dan ekspor.
`idempotency_key( string $key )`	Jadikan pengiriman alur kerja persisten dengan kunci yang diberikan pemanggil. Pengiriman ulang dengan kunci yang sama mengembalikan ID alur kerja awal.
`max_transitions( int $max )`	Gagalkan alur kerja jika lebih dari `$max` transisi langkah selesai.
`max_for_each_items( int $max )`	Gagalkan alur kerja jika langkah `for_each()` mencoba memperluas lebih dari `$max` item.
`max_state_bytes( int $bytes )`	Gagalkan alur kerja jika status publik bertambah melebihi `$bytes`.
`max_cost_units( int $max )`	Gagalkan alur kerja jika langkah yang selesai menghabiskan lebih dari `$max` unit biaya.
`max_started_workflows( int $max )`	Gagalkan alur kerja sebelum mengirim lebih dari `$max` alur kerja turunan.
`compensate_with( string $handler_class )`	Lampirkan penangan kompensasi ke langkah yang terakhir ditambahkan.
`compensate_on_failure()`	Jalankan kompensasi langkah yang selesai secara otomatis saat alur kerja gagal.
`on_queue( string $queue )`	Tetapkan antrean untuk semua langkah.
`with_priority( Priority $priority )`	Tetapkan prioritas untuk semua langkah.
`max_attempts( int $max )`	Tetapkan jumlah maksimum percobaan ulang per langkah.
`on_cancel( string $handler_class )`	Daftarkan kelas penangan pembersihan untuk pembatalan. Lihat Pembatalan.
`prune_state_after( int $steps = 2 )`	Aktifkan pemangkasan status otomatis. Menghapus keluaran langkah yang lebih lama dari ambang batas. Lihat Pemangkasan Status.
`must_complete_within( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )`	Tetapkan tenggat waktu untuk alur kerja. Semua durasi dijumlahkan. Lihat Tenggat Waktu.
`on_deadline( string $handler_class )`	Daftarkan penangan yang dipanggil saat tenggat waktu alur kerja terlampaui. Lihat Tenggat Waktu.
`dispatch( array $initial_payload = [] )`	Kirim alur kerja. Mengembalikan ID alur kerja.

`Queuety::workflow_status( $workflow_id )`

Dapatkan status alur kerja. Mengembalikan objek WorkflowState atau null.

PHP

$state = Queuety::workflow_status( $workflow_id );
echo $state->name;          // 'generate_report'
echo $state->status->value; // 'running'
echo $state->current_step;  // 1
echo $state->total_steps;   // 3
print_r( $state->state );   // accumulated public state array
echo $state->wait_type;     // 'signal' or 'workflow' while blocked
echo $state->wait_mode;     // 'all', 'any', or 'quorum'
echo $state->definition_version; // 'research.v2'
echo $state->definition_hash;    // '4c7a...'
echo $state->idempotency_key;    // 'brief:42:research'
echo $state->artifact_count;     // 2
print_r( $state->budget );       // configured workflow budget + current usage
print_r( $state->wait_details ); // matched/remaining blockers, result key, correlation info
print_r( $state->artifact_keys ); // ['draft', 'citations']

WorkflowState juga menampilkan:

waiting_for: nama sinyal atau ID alur kerja yang saat ini menghalangi proses
current_step_name: nama yang dikonfigurasi untuk langkah saat ini, jika ada
wait_mode: mode tunggu saat ini (all, any, atau quorum) saat terhalang
wait_details: data pemeriksaan tambahan, seperti penghalang yang cocok dibandingkan dengan yang tersisa
definition_version: nilai yang ditetapkan oleh version(), jika ada
definition_hash: hash deterministik dari definisi alur kerja
idempotency_key: kunci pengiriman persisten, jika ada
budget: batas yang dikonfigurasi beserta penggunaan saat ini, jika pagar pengaman diaktifkan
artifact_count: jumlah artefak tersimpan untuk alur kerja
artifact_keys: kunci artefak tersimpan untuk pemeriksaan cepat

`Queuety::retry_workflow( $workflow_id )`

Coba ulang alur kerja yang gagal dari langkah yang gagal.

PHP

Queuety::retry_workflow( $workflow_id );

Melempar RuntimeException jika alur kerja sudah dikompensasi setelah kegagalan.

`Queuety::pause_workflow( $workflow_id )`

Jeda alur kerja yang sedang berjalan. Pekerjaan yang sudah diantrekan untuk langkah saat ini mungkin tetap selesai, tetapi langkah berikutnya tidak akan diantrekan sampai Anda melanjutkan alur kerja.

PHP

Queuety::pause_workflow( $workflow_id );

`Queuety::resume_workflow( $workflow_id )`

Lanjutkan alur kerja yang dijeda.

PHP

Queuety::resume_workflow( $workflow_id );

`Queuety::cancel_workflow( $workflow_id )`

Batalkan alur kerja dan jalankan penangan pembersihan yang terdaftar. Tetapkan status ke cancelled dan kubur semua pekerjaan yang tertunda dan sedang diproses untuk alur kerja tersebut.

PHP

Queuety::cancel_workflow( $workflow_id );

Melempar RuntimeException jika alur kerja sudah completed atau cancelled. Lihat Pembatalan untuk detail.

`Queuety::rewind_workflow( $workflow_id, $to_step )`

Kembalikan alur kerja ke langkah sebelumnya dan jalankan ulang dari sana. Status dipulihkan dari log peristiwa state_after untuk langkah yang diberikan, lalu langkah berikutnya diantrekan.

PHP

Queuety::rewind_workflow( $workflow_id, to_step: 1 );

Melempar RuntimeException jika tidak ada status tercatat untuk langkah target. Memerlukan Log Peristiwa Alur Kerja. Lihat Perjalanan Waktu untuk detail.

`Queuety::fork_workflow( $workflow_id )`

Cabangkan alur kerja yang sedang berjalan menjadi salinan independen pada statusnya saat ini. Mengembalikan ID alur kerja baru.

PHP

$forked_id = Queuety::fork_workflow( $workflow_id );

Alur kerja hasil pencabangan memiliki ID sendiri dan beroperasi secara independen dari alur kerja asli. Lihat Pencabangan untuk detail.

`Queuety::export_workflow( $workflow_id )`

Ekspor seluruh riwayat eksekusi alur kerja sebagai larik yang dapat diserialisasi dengan JSON. Mencakup baris alur kerja, semua pekerjaan, peristiwa alur kerja, dan entri log.

PHP

$data = Queuety::export_workflow( $workflow_id );

Lihat Ekspor dan Pemutaran Ulang untuk struktur JSON dan contoh penggunaannya.

`Queuety::replay_workflow( $data )`

Putar ulang alur kerja yang diekspor di lingkungan saat ini. Membuat alur kerja baru dari data ekspor dan mengembalikan ID alur kerja baru.

PHP

$new_id = Queuety::replay_workflow( $data );

Lihat Ekspor dan Pemutaran Ulang untuk detail.

`Queuety::replace_wp_cron()`

Ganti sistem WordPress cron bawaan dengan penjadwal milik Queuety. Mencegat wp_schedule_event(), wp_unschedule_event(), dan wp_get_scheduled_event(), lalu mengarahkan peristiwa berulang melalui worker Queuety.

PHP

Queuety::replace_wp_cron();

Hanya berfungsi jika WordPress dimuat. Lihat WP-Cron Penggantian untuk detail.

`Queuety::restore_wp_cron()`

Pulihkan perilaku default WordPress cron dengan menghapus hook bridge Queuety cron.

PHP

Queuety::restore_wp_cron();

Lihat WP-Cron Penggantian untuk batasan.

`Queuety::signal( $workflow_id, $name, $data )`

Kirim sinyal ke alur kerja. Jika alur kerja sedang menunggu sinyal ini, alur tersebut langsung dilanjutkan. Jika tidak, sinyal disimpan dan digunakan saat alur kerja mencapai langkah wait_for_signal yang sesuai.

PHP

Queuety::signal( $workflow_id, 'approved' );

// With data merged into workflow state
Queuety::signal( $workflow_id, 'approved', [
    'approved_by' => 'admin@example.com',
] );

Lihat Sinyal Alur Kerja untuk detail.

`Queuety::approve_workflow( $workflow_id, $data = [], $signal_name = 'approval' )`

Pembungkus semantik signal() untuk alur persetujuan.

PHP

Queuety::approve_workflow( $workflow_id, [
    'reviewer' => 'editor@example.com',
] );

`Queuety::reject_workflow( $workflow_id, $data = [], $signal_name = 'rejected' )`

Pembungkus semantik signal() untuk alur penolakan.

PHP

Queuety::reject_workflow( $workflow_id, [
    'reason' => 'needs citations',
] );

`Queuety::submit_workflow_input( $workflow_id, $data = [], $signal_name = 'input' )`

Pembungkus semantik signal() untuk masukan manusia yang terstruktur.

PHP

Queuety::submit_workflow_input( $workflow_id, [
    'notes' => 'Ship after legal review',
] );

`Queuety::put_artifact( $workflow_id, $artifact_key, $content, $kind = 'json', $step_index = null, $metadata = [] )`

Simpan satu artefak persisten untuk alur kerja.

PHP

Queuety::put_artifact(
    $workflow_id,
    'research_brief',
    [ 'summary' => 'done' ],
    'json',
    metadata: [ 'source' => 'agent' ],
);

`Queuety::put_current_artifact( $artifact_key, $content, $kind = 'json', $metadata = [] )`

Simpan satu artefak untuk langkah alur kerja yang sedang dijalankan.

PHP

Queuety::put_current_artifact(
    'draft',
    [ 'status' => 'ready' ],
    'json',
);

`Queuety::workflow_artifact( $workflow_id, $artifact_key )`

Ambil satu artefak tersimpan untuk alur kerja.

PHP

$artifact = Queuety::workflow_artifact( $workflow_id, 'draft' );

`Queuety::workflow_artifacts( $workflow_id, $include_content = false )`

Daftar artefak untuk alur kerja.

PHP

$artifacts = Queuety::workflow_artifacts( $workflow_id );

`Queuety::delete_workflow_artifact( $workflow_id, $artifact_key )`

Hapus satu artefak untuk alur kerja.

PHP

Queuety::delete_workflow_artifact( $workflow_id, 'draft' );

Mesin Status

`Queuety::machine( $name )`

Mulai membuat mesin status. Mengembalikan StateMachineBuilder.

PHP

use Queuety\Enums\StateMachineStatus;

$machine_id = Queuety::machine( 'agent_session' )
    ->state( 'awaiting_user' )
    ->on( 'user_message', 'planning' )
    ->state( 'planning' )
    ->action( PlanSessionAction::class )
    ->on( 'planned', 'completed' )
    ->state( 'completed', StateMachineStatus::Completed )
    ->dispatch( [ 'thread_id' => 42 ] );

metode `StateMachineBuilder`

Metode	Deskripsi
`initial( string $state_name )`	Tetapkan status awal secara eksplisit.
`state( string $state_name, ?StateMachineStatus $terminal_status = null )`	Mulai mengonfigurasi satu status.
`action( string\|array $action_class )`	Daftarkan tindakan masuk antrean untuk status saat ini. Teruskan nama kelas, atau definisi terstruktur dengan `class`, `payload`, dan `config`; `payload` diteruskan ke `StateAction::handle()` sebagai `$payload`.
`on( string $event, string $target, string\|array\|null $guard_class = null, ?string $name = null )`	Daftarkan satu transisi peristiwa dari status saat ini. Guard menerima bentuk terstruktur yang sama dengan `action()`.
`on_queue( string $queue )`	Tetapkan antrean yang digunakan untuk tindakan status yang diantrekan.
`with_priority( Priority $priority )`	Tetapkan prioritas untuk tindakan status yang diantrekan.
`max_attempts( int $max_attempts )`	Tetapkan batas percobaan ulang untuk tindakan status yang diantrekan.
`version( string $version )`	Beri tag versi tingkat aplikasi pada definisi mesin.
`idempotency_key( string $key )`	Jadikan pengiriman persisten dengan kunci yang diberikan pemanggil. Pengiriman ulang dengan kunci yang sama mengembalikan ID mesin awal.
`dispatch( array $initial_state = [] )`	Kirim mesin dan kembalikan ID mesin.

Kelas tindakan masuk status juga dapat menyediakan metode config() opsional dengan kunci kebijakan sumber daya yang sama seperti yang didukung langkah alur kerja: concurrency_group, concurrency_limit, dan cost_units.

`Queuety::dispatch_state_machine_definition( $definition, $initial_state = [], $options = [] )`

Kirim bundel definisi mesin status yang diserialisasi. Sebagian besar kode aplikasi sebaiknya menggunakan machine()->dispatch(). Metode tingkat rendah ini memungkinkan adapter memulai mesin tanpa bergantung langsung pada builder.

PHP

$machine_id = Queuety::dispatch_state_machine_definition(
    $definition,
    [ 'thread_id' => 42 ],
    [ 'idempotency_key' => 'thread:42' ],
);

`Queuety::machine_status( $machine_id )`

Dapatkan status mesin saat ini. Mengembalikan objek StateMachineState atau null.

PHP

$status = Queuety::machine_status( $machine_id );

echo $status->name;               // 'agent_session'
echo $status->status->value;      // 'waiting_event'
echo $status->current_state;      // 'awaiting_review'
print_r( $status->state );        // public machine state
print_r( $status->available_events ); // valid incoming events in the current state

StateMachineState juga menampilkan:

definition_version
definition_hash
idempotency_key
error_message
current_action
terminal_status

`Queuety::machine_event( $machine_id, $event_name, $payload = [] )`

Kirim satu peristiwa eksternal ke mesin yang sedang menunggu.

PHP

Queuety::machine_event(
    $machine_id,
    'approve',
    [
        'approved' => true,
        'reviewer' => 'editor@example.com',
    ]
);

Payload tersedia bagi guard transisi dan digabungkan ke status mesin publik saat peristiwa diterima.

`Queuety::list_machines( $limit = 50, $status = null )`

Daftar baris mesin yang tersimpan untuk diperiksa.

PHP

$machines = Queuety::list_machines();
$waiting  = Queuety::list_machines( status: 'waiting_event' );

Setiap baris mencakup ID mesin, nama, status, status saat ini, versi definisi, hash definisi, kunci idempotensi, dan stempel waktu siklus hidup.

`Queuety::machine_timeline( $machine_id, $limit = 100, $offset = 0 )`

Dapatkan linimasa peristiwa persisten untuk satu mesin.

PHP

$timeline = Queuety::machine_timeline( $machine_id );
$page_two = Queuety::machine_timeline( $machine_id, 100, 100 );

Setiap baris peristiwa berisi: id, machine_id, job_id, state_name, handler, event, event_name, transition_name, queue, attempt, input, output, state_before, state_after, context, artifacts, chunks, error, duration_ms, dan created_at.

`Queuety::machine_trace( $machine_id )`

Dapatkan bundel pelacakan yang dinormalisasi untuk UI debugger mesin status.

PHP

$trace = Queuety::machine_trace( $machine_id );

Pelacakan berisi machine, states yang dikelompokkan, events mentah, jobs tindakan berkorelasi, logs, artifacts, dan chunks.

`Queuety::machine_state_at( $machine_id, $event_id )`

Dapatkan status publik setelah peristiwa pelacakan mesin tertentu, atau null jika tidak ditemukan.

PHP

$state = Queuety::machine_state_at( $machine_id, $event_id );

Lihat Mesin Status untuk model siklus hidup dan pola penggunaan.

Templat alur kerja

`Queuety::define_workflow( $name )`

Buat builder alur kerja untuk digunakan sebagai templat.

PHP

$builder = Queuety::define_workflow( 'onboarding' )
    ->then( CreateAccountHandler::class )
    ->then( SendWelcomeEmailHandler::class );

`Queuety::register_workflow_template( $builder )`

Daftarkan templat alur kerja.

PHP

Queuety::register_workflow_template( $builder );

`Queuety::run_workflow( $name, $payload, $options = [] )`

Kirim templat alur kerja terdaftar berdasarkan nama. Mengembalikan ID alur kerja.

PHP

$workflow_id = Queuety::run_workflow( 'onboarding', [ 'email' => 'user@example.com' ] );

$workflow_id = Queuety::run_workflow(
    'onboarding',
    [ 'email' => 'user@example.com' ],
    [ 'idempotency_key' => 'onboarding:user@example.com' ],
);

Melempar RuntimeException jika templat tidak terdaftar.

`Queuety::dispatch_workflow_definition( $definition, $payload, $options = [] )`

Kirim alur kerja dari bundel definisi runtime.

Sebagian besar kode aplikasi sebaiknya menggunakan run_workflow() atau workflow()->dispatch(). Metode tingkat rendah ini memungkinkan adapter yang dapat digunakan ulang mengirim definisi alur kerja terserialisasi tanpa bergantung pada metode internal pengelola alur kerja.

PHP

$workflow_id = Queuety::dispatch_workflow_definition(
    $definition,
    [ 'email' => 'user@example.com' ],
    [ 'idempotency_key' => 'onboarding:user@example.com' ],
);

`Queuety::on_action( $hook, $workflow, $map = null, $when = null, $idempotency_key = null, $priority = 10, $accepted_args = null )`

Daftarkan tindakan WordPress yang mengirim alur kerja.

PHP

Queuety::on_action(
    'save_post',
    workflow: 'content_review',
    map: static fn ( int $post_id, object $post, bool $update ): array => [
        'post_id' => $post_id,
        'post_type' => $post->post_type,
        'update' => $update,
    ],
    when: static fn ( int $post_id, object $post ): bool => 'post' === $post->post_type,
    idempotency_key: static fn ( int $post_id ): string => "save_post:{$post_id}",
);

$workflow dapat berupa:

nama templat alur kerja yang terdaftar
WorkflowBuilder sebaris

map, when, dan idempotency_key dijalankan secara sinkron di dalam permintaan WordPress saat ini. Hanya langkah alur kerja yang berjalan secara asinkron setelah pengiriman.

Lihat Pemicu Tindakan untuk panduan lengkap.

`Queuety::workflow_templates()`

Dapatkan registry templat alur kerja.

PHP

$registry = Queuety::workflow_templates();
$template = $registry->get( 'onboarding' ); // WorkflowTemplate or null

`Queuety::load_workflows( $directory, $recursive )`

Muat dan daftarkan semua file alur kerja dari direktori. Setiap file .php harus mengembalikan WorkflowBuilder. Mengembalikan jumlah alur kerja yang terdaftar.

PHP

$count = Queuety::load_workflows( __DIR__ . '/workflows/' );
$count = Queuety::load_workflows( __DIR__ . '/workflows/', recursive: true );

`Queuety::load_workflow_file( $file_path )`

Muat dan daftarkan satu file alur kerja. Mengembalikan WorkflowTemplate atau null jika file tidak mengembalikan builder.

PHP

$template = Queuety::load_workflow_file( __DIR__ . '/workflows/onboard-user.php' );

Penjadwalan

`Queuety::schedule( $handler, $payload )`

Buat jadwal berulang. Mengembalikan builder PendingSchedule.

PHP

Queuety::schedule( 'cleanup_handler' )
    ->every( '1 hour' )
    ->on_queue( 'maintenance' );

Queuety::schedule( 'nightly_report' )
    ->cron( '0 3 * * *' )
    ->on_queue( 'reports' );

metode `PendingSchedule`

Metode	Deskripsi
`every( string $interval )`	Tetapkan ekspresi interval (e.g. `1 hour`, `30 minutes`)
`cron( string $expression )`	Tetapkan ekspresi cron dengan 5 bidang
`overlap( OverlapPolicy $policy )`	Tetapkan kebijakan tumpang tindih (default: `Allow`). Lihat Penjadwalan.
`on_queue( string $queue )`	Tetapkan antrean target (default: `default`)
`id()`	Paksa pengiriman dan kembalikan ID jadwal

`Queuety::scheduler()`

Dapatkan instance Scheduler internal.

PHP

$scheduler = Queuety::scheduler();
$schedules = $scheduler->list();
$scheduler->remove( 'handler_name' );
$count = $scheduler->tick(); // manually trigger

Pendaftaran penangan

`Queuety::register( $name, $class )`

Daftarkan kelas penangan dengan sebuah nama.

PHP

Queuety::register( 'send_email', SendEmailHandler::class );

`Queuety::discover_handlers( $directory, $namespace )`

Temukan dan daftarkan kelas penangan secara otomatis dari direktori. Mengembalikan jumlah penangan yang terdaftar.

PHP

$count = Queuety::discover_handlers( __DIR__ . '/handlers', 'MyPlugin\\Handlers' );

`Queuety::registry()`

Dapatkan registry penangan.

PHP

$registry = Queuety::registry();

Observabilitas

`Queuety::logger()`

Dapatkan instance Logger untuk membuat kueri entri log.

PHP

$logger = Queuety::logger();
$logs   = $logger->for_job( 42 );
$logs   = $logger->for_workflow( 7 );
$logs   = $logger->for_handler( 'send_email', 50 );
$logs   = $logger->for_event( LogEvent::Failed, 50 );
$logs   = $logger->since( new \DateTimeImmutable( '-1 hour' ), 100 );
$count  = $logger->purge( 30 );

`Queuety::metrics()`

Dapatkan instance Metrics.

PHP

$stats = Queuety::metrics()->handler_stats( 60 ); // last 60 minutes

`Queuety::webhook_notifier()`

Dapatkan instance WebhookNotifier.

PHP

$notifier = Queuety::webhook_notifier();
$id       = $notifier->register( 'job.buried', 'https://hooks.slack.com/...' );
$webhooks = $notifier->list();
$notifier->remove( $id );

`Queuety::rate_limiter()`

Dapatkan instance RateLimiter.

PHP

$limiter = Queuety::rate_limiter();
$limiter->register( 'call_openai', 60, 60 );

Cache

`Queuety::cache()`

Dapatkan instance backend cache yang aktif.

PHP

$cache = Queuety::cache();
$cache->set( 'my_key', 'my_value', 60 );
$value = $cache->get( 'my_key' );

`Queuety::set_cache( $cache )`

Ganti backend cache. Panggil ini sebelum Queuety::init() untuk menggunakan implementasi khusus.

PHP

Queuety::set_cache( new RedisCache() );
Queuety::init( $connection );

`QUEUETY_CACHE_TTL`

TTL cache default dalam detik (default: 5). Tetapkan konstanta ini di wp-config.php untuk mengubah TTL default yang digunakan oleh operasi cache internal.

PHP

define( 'QUEUETY_CACHE_TTL', 10 );

Lihat Caching untuk detail tentang backend dan deteksi otomatis.

Log peristiwa mesin status

`Queuety::machine_events()`

Dapatkan instance StateMachineEventLog.

PHP

$log = Queuety::machine_events();

Log peristiwa alur kerja

`Queuety::workflow_events()`

Dapatkan instance WorkflowEventLog.

PHP

$log = Queuety::workflow_events();

`Queuety::workflow_timeline( $workflow_id, $limit = 100, $offset = 0 )`

Dapatkan linimasa lengkap peristiwa untuk alur kerja. Mengembalikan larik baris peristiwa yang diurutkan berdasarkan ID.

PHP

$events = Queuety::workflow_timeline( $workflow_id );
$next   = Queuety::workflow_timeline( $workflow_id, 100, 100 );

Setiap baris peristiwa berisi: id, workflow_id, job_id, parent_event_id, step_index, step_name, step_type, handler, event, queue, attempt, input, output, state_before, state_after, context, artifacts, chunks, error, error_message (disalin dari error.message), duration_ms, dan created_at.

`Queuety::workflow_trace( $workflow_id )`

Dapatkan bundel jejak yang dinormalisasi untuk debugger alur kerja UI.

PHP

$trace = Queuety::workflow_trace( $workflow_id );

Jejak berisi workflow, dikelompokkan steps, mentah events, jobs, logs, artifacts, chunks, signals, dan wait_dependencies.

`Queuety::trace_input( $input )`

Tetapkan masukan tingkat aplikasi untuk langkah alur kerja yang sedang dijalankan.

`Queuety::trace_output( $output )`

Tetapkan keluaran tingkat aplikasi untuk langkah alur kerja yang sedang dijalankan.

`Queuety::trace_context( array $context )`

Gabungkan konteks tingkat aplikasi ke dalam langkah alur kerja yang sedang dijalankan.

`Queuety::workflow_state_at( $workflow_id, $step_index )`

Dapatkan status publik setelah langkah alur kerja tertentu selesai atau dilanjutkan, atau null jika tidak ditemukan.

PHP

$state = Queuety::workflow_state_at( $workflow_id, 2 );

Lihat Log Peristiwa Alur Kerja untuk kasus penggunaan dan perintah CLI.

Instans internal

Metode ini mengembalikan instans internal untuk kasus penggunaan lanjutan.

Metode	Mengembalikan	Deskripsi
`Queuety::queue()`	`Queue`	Operasi antrean (klaim, lepas, kubur)
`Queuety::worker()`	`Worker`	Kontrol proses pekerja
`Queuety::workflow_manager()`	`Workflow`	Orkestrasi alur kerja
`Queuety::machines()`	`StateMachine`	Pengelolaan siklus hidup mesin status
`Queuety::connection()`	`Connection`	Koneksi basis data
`Queuety::batch_manager()`	`BatchManager`	Pengelolaan siklus hidup batch (batalkan, pangkas)
`Queuety::chunk_store()`	`ChunkStore`	Persistensi potongan untuk langkah streaming
`Queuety::machine_events()`	`StateMachineEventLog`	Peristiwa jejak mesin status dan bundel jejak yang dinormalisasi
`Queuety::workflow_events()`	`WorkflowEventLog`	Peristiwa jejak alur kerja dan bundel jejak yang dinormalisasi
`Queuety::resource_manager()`	`ResourceManager`	Profil penerimaan pekerja, anggaran berbobot, dan pemeriksaan memori sistem
`Queuety::cache()`	`Cache`	Instans backend cache

Pengujian

`Queuety::fake()`

Ganti antrean dengan objek tiruan dalam memori untuk pengujian. Mengembalikan instans QueueFake yang mencatat pekerjaan yang dikirim tanpa menyentuh basis data. create_batch() juga mencatat metadata batch tiruan; rantai diperiksa melalui pekerjaan individual yang dikirimnya.

PHP

$fake = Queuety::fake();
SendEmailJob::dispatch( 'user@example.com', 'Hello', 'Hi!' );
$fake->assert_pushed( SendEmailJob::class );

`Queuety::reset()`

Atur ulang semua status internal, termasuk tiruan antrean. Panggil di tearDown().

PHP

Queuety::reset();

Metode `QueueFake`

Metode	Deskripsi
`assert_pushed( string $class, ?Closure $callback )`	Pastikan kelas pekerjaan telah dimasukkan ke antrean. Callback opsional memfilter berdasarkan data pekerjaan.
`assert_pushed_times( string $class, int $count )`	Pastikan pekerjaan dimasukkan ke antrean tepat N kali.
`assert_not_pushed( string $class )`	Pastikan pekerjaan tidak pernah dimasukkan ke antrean.
`assert_nothing_pushed()`	Pastikan tidak ada pekerjaan yang dimasukkan ke antrean.
`assert_batched( ?Closure $callback )`	Pastikan batch telah dikirim. Callback opsional memfilter berdasarkan data batch.
`pushed( string $class )`	Dapatkan semua pengiriman tercatat untuk suatu kelas. Mengembalikan array.
`batches()`	Dapatkan semua batch yang tercatat. Mengembalikan array.
`reset()`	Hapus semua pekerjaan dan batch yang tercatat.

Lihat Pengujian untuk contoh lengkap.

Antarmuka

`Handler`

Antarmuka untuk handler pekerjaan sederhana.

PHP

interface Handler {
    public function handle( array $payload ): void;
    public function config(): array;
}

config() dapat mengembalikan queue, max_attempts, backoff, rate_limit, concurrency_group, concurrency_limit, dan cost_units.

`Step`

Antarmuka untuk handler langkah alur kerja.

PHP

interface Step {
    public function handle( array $state ): array;
    public function config(): array;
}

config() dapat mengembalikan max_attempts, backoff, concurrency_group, concurrency_limit, dan cost_units.

`Contracts\ForEachHandler`

Antarmuka untuk handler cabang for-each dinamis.

PHP

namespace Queuety\Contracts;

interface ForEachHandler {
    public function handle_item( array $state, mixed $item, int $index ): array;
    public function config(): array;
}

config() dapat mengembalikan max_attempts, backoff, rate_limit, concurrency_group, concurrency_limit, dan cost_units.

`Contracts\ForEachReducer`

Reducer opsional untuk hasil for-each.

PHP

namespace Queuety\Contracts;

interface ForEachReducer {
    public function reduce( array $state, array $for_each ): array;
}

`Contracts\Compensation`

Antarmuka untuk handler kompensasi langkah.

PHP

namespace Queuety\Contracts;

interface Compensation {
    public function handle( array $state ): void;
}

`Contracts\RepeatCondition`

Antarmuka untuk predikat loop yang digunakan oleh repeat_until() dan repeat_while() saat perbandingan kunci status terlalu terbatas.

PHP

namespace Queuety\Contracts;

interface RepeatCondition {
    public function matches( array $state ): bool;
}

`Contracts\StateAction`

Antarmuka untuk tindakan masuk status yang diantrekan.

PHP

namespace Queuety\Contracts;

interface StateAction {
    public function handle( array $state, ?string $event = null, array $event_payload = [], array $payload = [] ): array|string;
}

$payload membawa payload terstruktur dari definisi tindakan, jika mesin ditentukan dengan definisi tersebut. Kembalikan pembaruan status publik. Sertakan _event dan, secara opsional, _event_payload jika tindakan harus segera melakukan transisi.

Tindakan status juga dapat menentukan metode config() opsional. Queuety membacanya dari concurrency_group, concurrency_limit, dan cost_units saat tindakan masuk diantrekan.

`Contracts\StateGuard`

Antarmuka untuk guard transisi mesin status.

PHP

namespace Queuety\Contracts;

interface StateGuard {
    public function allows( array $state, array $event_payload, string $event, array $payload = [] ): bool;
}

`Contracts\Job`

Antarmuka untuk kelas pekerjaan mandiri yang dapat dikirim. Kelas pekerjaan menyimpan payload sebagai properti publik dan logika eksekusi di handle().

PHP

namespace Queuety\Contracts;

interface Job {
    public function handle(): void;
}

Kelas pekerjaan dapat menentukan metode middleware() opsional yang mengembalikan array instans Contracts\Middleware.

`Contracts\Cache`

Antarmuka untuk backend cache. Lihat Caching untuk implementasi bawaan dan backend khusus.

PHP

namespace Queuety\Contracts;

interface Cache {
    public function get( string $key ): mixed;
    public function set( string $key, mixed $value, int $ttl = 0 ): void;
    public function delete( string $key ): void;
    public function has( string $key ): bool;
    public function add( string $key, mixed $value, int $ttl = 0 ): bool;
    public function flush(): void;
}

Metode	Mengembalikan	Deskripsi
`get( $key )`	`mixed`	Ambil nilai. Mengembalikan `null` jika tidak ditemukan atau kedaluwarsa.
`set( $key, $value, $ttl )`	`void`	Simpan nilai. TTL 0 berarti tidak kedaluwarsa.
`delete( $key )`	`void`	Hapus nilai.
`has( $key )`	`bool`	Periksa apakah kunci tersedia dan belum kedaluwarsa.
`add( $key, $value, $ttl )`	`bool`	Atur atomik jika belum ada. Mengembalikan `true` jika nilai berhasil diatur.
`flush()`	`void`	Hapus semua item dari cache.

`WorkflowEventLog`

Mencatat transisi langkah alur kerja dengan konteks jejak lengkap. Akses melalui Queuety::workflow_events().

Metode	Mengembalikan	Deskripsi
`record_event( array $event )`	`void`	Catat peristiwa jejak mentah
`record_step_started( ... )`	`void`	Catat peristiwa step_started dengan masukan dan status sebelum eksekusi
`record_step_completed( ... )`	`void`	Catat peristiwa step_completed dengan masukan, keluaran, status sebelum, dan status sesudah
`record_step_failed( ... )`	`void`	Catat peristiwa step_failed dengan konteks jejak dan detail kesalahan terstruktur
`get_timeline( int $workflow_id, ?int $limit = 100, int $offset = 0 )`	`array`	Dapatkan peristiwa jejak alur kerja secara berurutan, dengan paginasi opsional
`get_trace( int $workflow_id )`	`array`	Dapatkan bundel jejak yang dinormalisasi
`get_state_at_step( int $workflow_id, int $step_index )`	`array\|null`	Dapatkan status publik setelah langkah tertentu selesai atau dilanjutkan
`prune( int $older_than_days )`	`int`	Hapus peristiwa yang lebih lama dari jumlah hari yang ditentukan. Mengembalikan jumlah baris yang dihapus.

`StateMachineEventLog`

Mencatat peristiwa siklus hidup mesin status, tindakan, transisi, dan guard dengan kolom jejak yang sama seperti peristiwa alur kerja.

Metode	Mengembalikan	Deskripsi
`record_event( array $event )`	`void`	Catat peristiwa jejak mesin mentah
`get_timeline( int $machine_id, ?int $limit = 100, int $offset = 0 )`	`array`	Dapatkan peristiwa jejak mesin secara berurutan, dengan paginasi opsional
`get_trace( int $machine_id )`	`array`	Dapatkan bundel jejak mesin yang dinormalisasi
`get_state_at_event( int $machine_id, int $event_id )`	`array\|null`	Dapatkan status publik setelah peristiwa jejak mesin tertentu
`prune( int $older_than_days )`	`int`	Hapus peristiwa yang lebih lama dari jumlah hari yang ditentukan. Mengembalikan jumlah baris yang dihapus.

`Contracts\StreamingStep`

Antarmuka untuk handler langkah alur kerja yang menghasilkan aliran potongan. Setiap nilai yang dihasilkan langsung disimpan ke basis data. Lihat Langkah Streaming.

PHP

namespace Queuety\Contracts;

interface StreamingStep {
    public function stream( array $state, array $existing_chunks = [] ): \Generator;
    public function on_complete( array $chunks, array $state ): array;
    public function config(): array;
}

Metode	Deskripsi
`stream( $state, $existing_chunks )`	Generator yang menghasilkan potongan string. Setiap hasil langsung memicu penulisan ke DB. Saat dicoba ulang, `$existing_chunks` berisi potongan yang sebelumnya telah disimpan.
`on_complete( $chunks, $state )`	Dipanggil setelah aliran selesai. Mengembalikan data untuk digabungkan ke status alur kerja.
`config()`	Konfigurasi opsional. Mendukung `max_attempts`, `backoff`, `concurrency_group`, `concurrency_limit`, dan `cost_units`.

`ChunkStore`

Mengelola persistensi potongan untuk langkah streaming. Akses melalui Queuety::chunk_store().

Metode	Mengembalikan	Deskripsi
`get_chunks( int $job_id )`	`string[]`	Ambil semua potongan untuk suatu pekerjaan, diurutkan berdasarkan indeks potongan
`append_chunk( int $job_id, int $chunk_index, string $content, ?int $workflow_id, ?int $step_index )`	`void`	Tambahkan satu potongan
`clear_chunks( int $job_id )`	`void`	Hapus semua potongan untuk suatu pekerjaan
`chunk_count( int $job_id )`	`int`	Hitung jumlah potongan untuk suatu pekerjaan
`get_accumulated( int $job_id )`	`string`	Gabungkan semua potongan menjadi satu string

`Heartbeat`

Helper statis untuk mengirim heartbeat aktivitas dari dalam handler langkah dan langkah streaming. Lihat Heartbeat.

Metode	Deskripsi
`Heartbeat::init( int $job_id, Connection $conn )`	Tetapkan konteks pekerjaan. Dipanggil otomatis oleh worker.
`Heartbeat::beat( array $progress = [] )`	Kirim heartbeat. Memperbarui `reserved_at` dan secara opsional menyimpan data progres di `heartbeat_data`.
`Heartbeat::clear()`	Hapus konteks pekerjaan. Dipanggil otomatis oleh worker.
`Heartbeat::current_job_id()`	Dapatkan ID pekerjaan saat ini (untuk pengujian).

`Contracts\Middleware`

Antarmuka untuk middleware pekerjaan. Middleware membungkus eksekusi pekerjaan dalam alur bergaya bawang.

PHP

namespace Queuety\Contracts;

interface Middleware {
    public function handle( object $job, \Closure $next ): void;
}

Trait

`Dispatchable`

Menyediakan metode pengiriman statis pada kelas pekerjaan yang mengimplementasikan Contracts\Job. Argumen konstruktor diteruskan untuk membuat instans pekerjaan.

PHP

use Queuety\Contracts\Job;
use Queuety\Dispatchable;

class SendEmailJob implements Job {
    use Dispatchable;
    // ...
}

// Dispatches a new SendEmailJob instance
SendEmailJob::dispatch( 'user@example.com', 'Subject', 'Body' );

Metode	Mengembalikan	Deskripsi
`dispatch( ...$args )`	`PendingJob`	Buat instans dan kirimkan
`dispatch_if( bool $condition, ...$args )`	`PendingJob\|null`	Kirimkan hanya jika `$condition` bernilai true
`dispatch_unless( bool $condition, ...$args )`	`PendingJob\|null`	Kirimkan hanya jika `$condition` bernilai false
`with_chain( array $jobs )`	`ChainBuilder`	Mulai rantai dari kelas pekerjaan ini

PHP

// Conditional dispatch
SendEmailJob::dispatch_if( $user->wants_email, $user->email, 'Hello', 'Hi!' );
SendEmailJob::dispatch_unless( $maintenance_mode, $user->email, 'Hello', 'Hi!' );

// Chain from a job class
FetchDataJob::with_chain( [
    new ProcessDataJob(),
    new NotifyCompleteJob(),
] )->dispatch();

Properti pekerjaan

Kelas pekerjaan dapat mendeklarasikan properti publik yang dibaca worker melalui refleksi untuk mengganti perilaku percobaan ulang dan batas waktu.

Properti	Tipe	Deskripsi
`$tries`	`int`	Jumlah percobaan maksimum sebelum pekerjaan dikubur
`$timeout`	`int`	Waktu eksekusi maksimum dalam detik (memerlukan `pcntl`)
`$backoff`	`array`	Nilai jeda yang meningkat untuk setiap percobaan ulang

PHP

class ImportProductsJob implements Job {
    use Dispatchable;

    public int $tries = 5;
    public int $timeout = 120;
    public array $backoff = [ 10, 30, 60, 120 ];

    // ...
}

Hook `failed()`

Jika pekerjaan dikubur setelah semua percobaan ulang habis, worker akan memanggil metode failed() pada instans pekerjaan jika ditentukan.

PHP

public function failed( \Throwable $exception ): void {
    error_log( "Job failed: {$exception->getMessage()}" );
}

Middleware bawaan

Semua kelas middleware mengimplementasikan Contracts\Middleware dan berada di namespace Queuety\Middleware.

Kelas	Deskripsi
`RateLimited( int $max, int $window )`	Terapkan batas laju sebanyak `$max` eksekusi per `$window` detik
`Timeout( int $seconds )`	Hentikan pekerjaan setelah `$seconds` detik (memerlukan `pcntl`)
`UniqueJob( ?string $key )`	Cegah eksekusi bersamaan melalui kunci basis data
`WithoutOverlapping( string $key, int $release_after )`	Cegah eksekusi yang tumpang tindih dengan kedaluwarsa kunci otomatis
`ThrottlesExceptions( int $max_attempts, int $decay_minutes )`	Batasi pengecualian untuk mencegah lonjakan pekerjaan saat layanan eksternal mengalami gangguan

Lihat Middleware untuk detail penggunaan dan contoh.

Enum

`Priority`

PHP

enum Priority: int {
    case Low    = 0;
    case Normal = 1;
    case High   = 2;
    case Urgent = 3;
}

`JobStatus`

PHP

enum JobStatus: string {
    case Pending    = 'pending';
    case Processing = 'processing';
    case Completed  = 'completed';
    case Failed     = 'failed';
    case Buried     = 'buried';
}

`WorkflowStatus`

PHP

enum WorkflowStatus: string {
    case Running        = 'running';
    case Completed      = 'completed';
    case Failed         = 'failed';
    case Paused         = 'paused';
    case WaitingForSignal  = 'waiting_for_signal';
    case WaitingForWorkflows = 'waiting_for_workflows';
    case Cancelled      = 'cancelled';
}

`StateMachineStatus`

PHP

enum StateMachineStatus: string {
    case Running = 'running';
    case WaitingEvent = 'waiting_event';
    case Completed = 'completed';
    case Failed = 'failed';
    case Paused = 'paused';
    case Cancelled = 'cancelled';
}

`BackoffStrategy`

PHP

enum BackoffStrategy: string {
    case Fixed       = 'fixed';
    case Linear      = 'linear';
    case Exponential = 'exponential';
}

`ForEachMode`

PHP

enum ForEachMode: string {
    case All = 'all';
    case FirstSuccess = 'first_success';
    case Quorum = 'quorum';
}

`WaitMode`

PHP

enum WaitMode: string {
    case All    = 'all';
    case Any    = 'any';
    case Quorum = 'quorum';
}

`LogEvent`

PHP

enum LogEvent: string {
    case Started                  = 'started';
    case Completed                = 'completed';
    case Failed                   = 'failed';
    case Buried                   = 'buried';
    case Retried                  = 'retried';
    case WorkflowStarted          = 'workflow_started';
    case WorkflowCompleted        = 'workflow_completed';
    case WorkflowFailed           = 'workflow_failed';
    case WorkflowPaused           = 'workflow_paused';
    case WorkflowResumed          = 'workflow_resumed';
    case WorkflowCancelled        = 'workflow_cancelled';
    case WorkflowRewound          = 'workflow_rewound';
    case WorkflowForked           = 'workflow_forked';
    case WorkflowDeadlineExceeded = 'workflow_deadline_exceeded';
    case Debug                    = 'debug';
}

`OverlapPolicy`

PHP

enum OverlapPolicy: string {
    case Allow  = 'allow';
    case Skip   = 'skip';
    case Buffer = 'buffer';
}

Lihat Penjadwalan untuk mengetahui cara kerja setiap kebijakan.

Atribut

`#[QueuetyHandler]`

PHP atribut 8 untuk pendaftaran otomatis. Lihat PHP Atribut.

PHP

use Queuety\Attributes\QueuetyHandler;

#[QueuetyHandler( name: 'send_email', queue: 'emails', max_attempts: 5 )]
class SendEmailHandler implements Handler {
    // ...
}

Bridge CLI

`Queuety::cli_command()`

Mengembalikan nama perintah root WP-CLI yang dipublikasikan.

Perintah root bawaan adalah queuety. Tentukan QUEUETY_CLI_COMMAND sebelum Queuety dimulai jika perintah harus dipublikasikan dengan nama lain.

`Queuety::cli_command_map()`

Mengembalikan katalog perintah Queuety CLI yang dapat diserialisasi untuk harness yang perlu memahami permukaan perintah yang disediakan tanpa memindai kelas WP-CLI.

Setiap entri mencakup:

ID operasi yang stabil
jalur relatif CLI
kelas dan metode handler WP-CLI
target eksekusi yang mungkin
adaptor yang menormalisasi argumen CLI mentah menjadi rencana eksekusi

`Queuety::resolve_cli_command( $path, $args, $assoc_args )`

Mengubah pemanggilan CLI yang telah diuraikan menjadi rencana eksekusi yang harus dijalankan harness.

PHP

$plan = Queuety::resolve_cli_command(
    [ 'workflow', 'export' ],
    [ '42' ],
    [ 'output' => '/tmp/workflow.json' ]
);

echo $plan['callable']; // Queuety\Queuety::export_workflow_to_file
print_r( $plan['arguments'] );

Rencana eksekusi sengaja dibuat sadar akan transport:

perintah mengarah ke callable publik PHP dengan argumen yang dinormalisasi
katalog mencantumkan semua target eksekusi yang mungkin di awal, sementara callable dan transport mengidentifikasi cabang yang dipilih untuk masukan yang telah diuraikan

Inilah penggunaan standar Queuety untuk harness agen: ID operasi yang stabil, target API publik, dan normalisasi yang dikelola adaptor untuk hal-hal khusus CLI seperti nilai bawaan antrean, dekode payload JSON, percabangan kumpulan worker, dan penanganan berkas ekspor alur kerja.

PHP API

Akses inti mandiri

Queuety::init( Connection $conn )

Queuety::ensure_schema()

Job

Queuety::dispatch( $handler, $payload )

Metode PendingJob

Queuety::dispatch_sync( $handler, $payload )

Queuety::batch( $jobs )

Queuety::create_batch( $jobs )

Metode BatchBuilder

Queuety::find_batch( $id )

Kontrol worker

Queuety::run_worker( $queue = 'default', $once = false )

Queuety::run_worker_pool( $workers, $queue = 'default' )

Queuety::run_auto_scaling_worker_pool( $min_workers, $max_workers, $queue = 'default' )

Objek nilai Batch

Queuety::chain( $jobs )

Metode ChainBuilder

Queuety::retry( $job_id )

Queuety::retry_buried()

Queuety::purge( $older_than_days )

Antrean

Queuety::stats( $queue )

Queuety::buried( $queue )

Queuety::pause( $queue )

Queuety::resume( $queue )

Queuety::is_paused( $queue )

Alur kerja

Queuety::workflow( $name )

metode WorkflowBuilder

Queuety::workflow_status( $workflow_id )

Queuety::retry_workflow( $workflow_id )

Queuety::pause_workflow( $workflow_id )

Queuety::resume_workflow( $workflow_id )

Queuety::cancel_workflow( $workflow_id )

Queuety::rewind_workflow( $workflow_id, $to_step )

Queuety::fork_workflow( $workflow_id )

Queuety::export_workflow( $workflow_id )

Queuety::replay_workflow( $data )

Queuety::replace_wp_cron()

Queuety::restore_wp_cron()

Queuety::signal( $workflow_id, $name, $data )

Queuety::approve_workflow( $workflow_id, $data = [], $signal_name = 'approval' )

Queuety::reject_workflow( $workflow_id, $data = [], $signal_name = 'rejected' )

Queuety::submit_workflow_input( $workflow_id, $data = [], $signal_name = 'input' )

Queuety::put_artifact( $workflow_id, $artifact_key, $content, $kind = 'json', $step_index = null, $metadata = [] )

Queuety::put_current_artifact( $artifact_key, $content, $kind = 'json', $metadata = [] )

Queuety::workflow_artifact( $workflow_id, $artifact_key )

Queuety::workflow_artifacts( $workflow_id, $include_content = false )

Queuety::delete_workflow_artifact( $workflow_id, $artifact_key )