PHP API

Ver como Markdown Editar no GitHub Documentação em 2cc7b2b

Tudo em Queuety pode ser acessado pela classe estática Queuety\Queuety. Ela é o ponto de entrada único para despachar tarefas, criar fluxos de trabalho, controlar máquinas de estado, gerenciar filas e acessar subsistemas internos.

PHP

use Queuety\Queuety;

Acesso independente ao núcleo

O runtime de Queuety com suporte a DB pode ser inicializado fora do WordPress.

Esse caminho independente é destinado ao núcleo de orquestração:

tarefas e workers (os pools de workers também precisam das constantes DB_HOST, DB_NAME, DB_USER e DB_PASSWORD; veja abaixo)
fluxos de trabalho e sinais
máquinas de estado e eventos
artefatos, logs, métricas e agendamentos

Ele não substitui o adaptador WordPress. Queuety::on_action(), replace_wp_cron(), a inicialização do plugin e o caminho de registro real de wp queuety ... ainda exigem WordPress.

`Queuety::init( Connection $conn )`

Inicialize Queuety com uma conexão direta com suporte a 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 );

O argumento opcional table_prefix altera a parte Queuety dos nomes das tabelas do runtime por conexão:

PHP

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

Isso resolve tabelas como queuety_jobs para wp_themequeue_jobs.

`Queuety::ensure_schema()`

Garanta que as tabelas de runtime Queuety existam para a conexão ativa.

PHP

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

Para ver o modelo completo e o limite de WordPress, consulte Uso independente.

Tarefas

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

Despacha uma tarefa. Aceita uma string com o nome do handler ou uma instância de Contracts\Job. Retorna um builder de PendingJob para encadear opções.

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();

Quando uma instância de Contracts\Job é passada, o serializador extrai o FQCN como nome do handler e as propriedades públicas como payload. O parâmetro $payload é ignorado quando $handler é uma instância de Job.

Métodos de `PendingJob`

Método	Descrição
`on_queue( string $queue )`	Define a fila de destino
`with_priority( Priority $priority )`	Define o nível de prioridade
`delay( int $seconds )`	Atraso antes de a tarefa ficar disponível
`max_attempts( int $max )`	Número máximo de tentativas
`rate_limit( int $max, int $window )`	Limite de taxa: máximo de execuções por janela de segundos
`unique()`	Impede despachos duplicados
`after( int $job_id )`	Aguarda a conclusão de outra tarefa primeiro
`concurrency_group( string $group, int $limit )`	Coloca a tarefa em um grupo compartilhado de admissão de workers
`cost_units( int $units )`	Anexa metadados de custo relativo de execução ao despacho
`id()`	Força o despacho e retorna o ID da tarefa

concurrency_group() e cost_units() alimentam o modelo mais amplo de Gerenciamento de recursos, permitindo que o mesmo despacho participe de limites de concorrência baseados em contagem, orçamentos ponderados de fila ou provedor e heurísticas de admissão de workers.

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

Executa uma tarefa de forma síncrona no processo atual, sem adicioná-la à fila.

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' ] );

O método handle() da tarefa é chamado diretamente. Nenhuma linha é criada no banco de dados, nenhum worker é envolvido e o middleware não é aplicado.

`Queuety::batch( $jobs )`

Despacha várias tarefas em um único INSERT com várias linhas.

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 )`

Cria um BatchBuilder para despachar um grupo de tarefas com callbacks e acompanhamento do progresso. Consulte Agrupamento para ver todos os detalhes.

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();

Métodos de `BatchBuilder`

Método	Retorna	Descrição
`name( string $name )`	`self`	Define um nome para o lote
`on_queue( string $queue )`	`self`	Define a fila de todas as tarefas do lote
`then( string $handler_class )`	`self`	Handler chamado quando o lote é concluído com sucesso
`catch( string $handler_class )`	`self`	Handler chamado quando a primeira tarefa do lote falha
`finally( string $handler_class )`	`self`	Handler chamado quando o lote termina (com sucesso ou falha)
`allow_failures()`	`self`	Permite que o callback `then` seja executado mesmo em caso de falhas
`dispatch()`	`Batch`	Cria a linha do lote e todas as tarefas; retorna o objeto de valor `Batch`

`Queuety::find_batch( $id )`

Localiza um lote pelo ID. Retorna um objeto de valor Batch ou null.

PHP

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

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

Controle de workers

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

Executa diretamente o loop de um worker.

PHP

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

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

Executa diretamente um pool de workers de tamanho fixo. Requer as extensões pcntl e posix. O pool lê as constantes WordPress DB_HOST, DB_NAME, DB_USER e DB_PASSWORD para as conexões filhas (somente os prefixos das tabelas vêm da conexão inicializada), então defina-as ao executar um pool fora do WordPress (#5).

PHP

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

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

Executa diretamente um pool adaptável de workers. Os requisitos são os mesmos de run_worker_pool().

PHP

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

Objeto de valor `Batch`

Método/propriedade	Tipo	Descrição
`$id`	`int`	ID do lote
`$name`	`string\|null`	Nome opcional do lote
`$total_jobs`	`int`	Número total de tarefas no lote
`$pending_jobs`	`int`	Tarefas ainda pendentes
`$failed_jobs`	`int`	Número de tarefas com falha
`$failed_job_ids`	`array`	IDs das tarefas com falha
`$created_at`	`DateTimeImmutable`	Data de criação do lote
`$finished_at`	`DateTimeImmutable\|null`	Data de conclusão do lote
`$cancelled_at`	`DateTimeImmutable\|null`	Data de cancelamento do lote
`progress()`	`int`	Percentual de conclusão (0-100)
`finished()`	`bool`	Indica se o lote foi concluído
`has_failures()`	`bool`	Indica se alguma tarefa falhou
`cancelled()`	`bool`	Indica se o lote foi cancelado

`Queuety::chain( $jobs )`

Cria um ChainBuilder para executar tarefas em sequência. Cada tarefa depende da conclusão bem-sucedida da anterior.

PHP

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

Métodos de `ChainBuilder`

Método	Retorna	Descrição
`on_queue( string $queue )`	`self`	Define a fila de todas as tarefas da cadeia
`catch( string $handler_class )`	`self`	Handler chamado quando qualquer tarefa da cadeia é enterrada permanentemente
`dispatch()`	`int`	Cria todas as tarefas com dependências sequenciais; retorna o ID da primeira tarefa

`Queuety::retry( $job_id )`

Tenta novamente uma tarefa específica. Redefine seu status para pending.

PHP

Queuety::retry( 42 );

`Queuety::retry_buried()`

Tenta novamente todas as tarefas enterradas. Retorna a quantidade de tarefas repetidas.

PHP

$count = Queuety::retry_buried();

`Queuety::purge( $older_than_days )`

Remove tarefas concluídas. Retorna a quantidade de tarefas removidas.

PHP

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

Filas

`Queuety::stats( $queue )`

Obtém a contagem de tarefas agrupadas por 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 )`

Obtém todas as tarefas enterradas.

PHP

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

`Queuety::pause( $queue )`

Pausa uma fila para que os workers a ignorem.

PHP

Queuety::pause( 'emails' );

`Queuety::resume( $queue )`

Retoma uma fila pausada.

PHP

Queuety::resume( 'emails' );

`Queuety::is_paused( $queue )`

Verifica se uma fila está pausada.

PHP

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

Fluxos de trabalho

`Queuety::workflow( $name )`

Comece a criar um fluxo de trabalho. Retorna um WorkflowBuilder.

PHP

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

Métodos de `WorkflowBuilder`

Método	Descrição
`then( string $handler_class, ?string $name = null )`	Adiciona uma etapa sequencial. Nome opcional para ramificação condicional.
`parallel( array $handler_classes )`	Adiciona um grupo de etapas paralelas.
`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 )`	Adiciona uma etapa dinâmica de iteração que expande uma tarefa por item no estado do fluxo de trabalho.
`repeat_while( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )`	Volta a uma etapa nomeada anterior enquanto uma chave de estado pública ou uma classe `RepeatCondition` corresponder.
`repeat_until( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )`	Volta a uma etapa nomeada anterior até que uma chave de estado pública ou uma classe `RepeatCondition` corresponda.
`run_workflow( string $workflow_name, WorkflowBuilder $sub_builder )`	Adiciona uma etapa de execução de fluxo de trabalho.
`delay( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )`	Adiciona uma etapa de espera durável. Todas as durações são somadas.
`wait_for_signal( string $name, ?string $result_key = null, ?string $step_name = null, array $match_payload = [], ?string $correlation_key = null )`	Adiciona uma etapa de espera por sinal. `match_payload` e `correlation_key` opcionais permitem ignorar eventos não relacionados.
`wait_for_signals( array $signal_names, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	Aguarda todos ou qualquer um de vários sinais, com correspondência opcional de conteúdo e correlação.
`wait_for_approval( string $signal_name = 'approval', ?string $result_key = 'approval', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	Aguarda um sinal de aprovação humana.
`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 )`	Aguarda aprovação ou rejeição e armazena um conteúdo de decisão estruturado.
`wait_for_input( string $signal_name = 'input', ?string $result_key = 'input', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )`	Aguarda um sinal de entrada humana.
`wait_for_workflow( int\|string $workflow, ?string $result_key = null, ?string $name = null )`	Aguarda a conclusão de um ID de fluxo de trabalho ou de um ID armazenado no estado público.
`wait_for_workflows( array\|string $workflows, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, ?int $quorum = null )`	Aguarda a conclusão de todos, de qualquer um ou de um quórum de vários fluxos de trabalho.
`wait_for_workflow_group( string $group_key, WaitMode $mode = WaitMode::All, ?int $quorum = null, ?string $result_key = null, ?string $name = null )`	Aguarda um grupo de fluxos de trabalho iniciado anteriormente por chave interna do grupo.
`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 )`	Inicia um fluxo de trabalho de nível superior por item de execução, com a opção de marcar o conjunto iniciado com uma chave de grupo durável.
`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 voltado a agentes para `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 voltado a agentes para `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 voltado a agentes para `wait_for_workflow_group()`.
`version( string $version )`	Marca a definição do fluxo de trabalho com uma versão no nível da aplicação para inspeção e exportações.
`idempotency_key( string $key )`	Torna durável a iniciação do fluxo de trabalho para uma chave fornecida pelo chamador. Iniciá-lo novamente com a mesma chave retorna o ID original do fluxo de trabalho.
`max_transitions( int $max )`	Falha o fluxo de trabalho se mais de `$max` transições de etapa forem concluídas.
`max_for_each_items( int $max )`	Falha o fluxo de trabalho se uma etapa `for_each()` tentar expandir mais de `$max` itens.
`max_state_bytes( int $bytes )`	Falha o fluxo de trabalho se o estado público exceder `$bytes`.
`max_cost_units( int $max )`	Falha o fluxo de trabalho se as etapas concluídas consumirem mais de `$max` unidades de custo.
`max_started_workflows( int $max )`	Falha o fluxo de trabalho antes de iniciar mais de `$max` fluxos de trabalho filhos.
`compensate_with( string $handler_class )`	Anexa um manipulador de compensação à etapa adicionada mais recentemente.
`compensate_on_failure()`	Executa automaticamente as compensações das etapas concluídas quando o fluxo de trabalho falha.
`on_queue( string $queue )`	Define a fila de todas as etapas.
`with_priority( Priority $priority )`	Define a prioridade de todas as etapas.
`max_attempts( int $max )`	Define o número máximo de tentativas por etapa.
`on_cancel( string $handler_class )`	Registra uma classe de manipulador de limpeza para cancelamento. Consulte Cancelamento.
`prune_state_after( int $steps = 2 )`	Ativa a poda automática do estado. Remove saídas de etapas mais antigas que o limite. Consulte Poda do estado.
`must_complete_within( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )`	Define um prazo para o fluxo de trabalho. Todas as durações são somadas. Consulte Prazos.
`on_deadline( string $handler_class )`	Registra um manipulador chamado quando o prazo do fluxo de trabalho é excedido. Consulte Prazos.
`dispatch( array $initial_payload = [] )`	Inicia o fluxo de trabalho. Retorna o ID do fluxo de trabalho.

`Queuety::workflow_status( $workflow_id )`

Obtém o status do fluxo de trabalho. Retorna um objeto WorkflowState ou 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 também expõe:

waiting_for: os nomes dos sinais ou IDs dos fluxos de trabalho que estão bloqueando a execução
current_step_name: o nome configurado da etapa atual, se houver
wait_mode: o modo de espera atual (all, any ou quorum) enquanto bloqueado
wait_details: dados adicionais de inspeção, como bloqueadores correspondentes e restantes
definition_version: o valor definido por version(), se houver
definition_hash: um hash determinístico da definição do fluxo de trabalho
idempotency_key: a chave durável de iniciação, se houver
budget: limites configurados e uso atual, se as proteções estiverem ativadas
artifact_count: número de artefatos armazenados para o fluxo de trabalho
artifact_keys: chaves dos artefatos armazenados para inspeção rápida

`Queuety::retry_workflow( $workflow_id )`

Tenta novamente um fluxo de trabalho com falha a partir da etapa que falhou.

PHP

Queuety::retry_workflow( $workflow_id );

Lança RuntimeException se o fluxo de trabalho já tiver sido compensado após uma falha.

`Queuety::pause_workflow( $workflow_id )`

Pausa um fluxo de trabalho em execução. O trabalho já enfileirado para a etapa atual ainda pode terminar, mas as etapas seguintes não serão enfileiradas até que o fluxo de trabalho seja retomado.

PHP

Queuety::pause_workflow( $workflow_id );

`Queuety::resume_workflow( $workflow_id )`

Retoma um fluxo de trabalho pausado.

PHP

Queuety::resume_workflow( $workflow_id );

`Queuety::cancel_workflow( $workflow_id )`

Cancela um fluxo de trabalho e executa os manipuladores de limpeza registrados. Define o status como cancelled e enterra todos os trabalhos pendentes e em processamento do fluxo de trabalho.

PHP

Queuety::cancel_workflow( $workflow_id );

Lança RuntimeException se o fluxo de trabalho já estiver completed ou cancelled. Consulte Cancelamento para obter detalhes.

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

Retrocede um fluxo de trabalho até uma etapa anterior e o reexecuta a partir dali. O estado é restaurado do registro de eventos state_after da etapa indicada, e a próxima etapa é enfileirada.

PHP

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

Lança RuntimeException se não houver estado registrado para a etapa de destino. Requer o Registro de eventos do fluxo de trabalho. Consulte Viagem no tempo para obter detalhes.

`Queuety::fork_workflow( $workflow_id )`

Cria uma ramificação de um fluxo de trabalho em execução como cópia independente no estado atual. Retorna o novo ID do fluxo de trabalho.

PHP

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

O fluxo de trabalho ramificado recebe seu próprio ID e opera independentemente do original. Consulte Ramificações para obter detalhes.

`Queuety::export_workflow( $workflow_id )`

Exporta o histórico completo de execução de um fluxo de trabalho como um array serializável em JSON. Inclui a linha do fluxo de trabalho, todos os trabalhos, eventos do fluxo de trabalho e entradas de registro.

PHP

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

Consulte Exportação e reprodução para conhecer a estrutura JSON e os casos de uso.

`Queuety::replay_workflow( $data )`

Reproduz um fluxo de trabalho exportado no ambiente atual. Cria um novo fluxo de trabalho a partir dos dados exportados e retorna o novo ID do fluxo de trabalho.

PHP

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

Consulte Exportação e reprodução para obter detalhes.

`Queuety::replace_wp_cron()`

Substitui o sistema integrado de WordPress cron pelo agendador de Queuety. Intercepta wp_schedule_event(), wp_unschedule_event() e wp_get_scheduled_event() e encaminha eventos recorrentes pelo worker Queuety.

PHP

Queuety::replace_wp_cron();

Só funciona quando WordPress está carregado. Consulte WP-Cron Substituição para obter detalhes.

`Queuety::restore_wp_cron()`

Restaura o comportamento padrão de WordPress cron removendo os hooks de integração de Queuety cron.

PHP

Queuety::restore_wp_cron();

Consulte WP-Cron Substituição para conhecer as limitações.

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

Envia um sinal para um fluxo de trabalho. Se o fluxo estiver aguardando esse sinal, ele será retomado imediatamente. Caso contrário, o sinal será armazenado e processado quando o fluxo de trabalho chegar à etapa wait_for_signal correspondente.

PHP

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

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

Consulte Sinais de fluxo de trabalho para obter detalhes.

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

Wrapper semântico em torno de signal() para fluxos de aprovação.

PHP

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

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

Wrapper semântico em torno de signal() para fluxos de rejeição.

PHP

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

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

Wrapper semântico em torno de signal() para entrada humana estruturada.

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 = [] )`

Armazena um artefato durável para um fluxo de trabalho.

PHP

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

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

Armazena um artefato para a etapa do fluxo de trabalho em execução.

PHP

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

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

Busca um artefato armazenado para um fluxo de trabalho.

PHP

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

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

Lista os artefatos de um fluxo de trabalho.

PHP

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

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

Exclui um artefato de um fluxo de trabalho.

PHP

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

Máquinas de estado

`Queuety::machine( $name )`

Comece a criar uma máquina de estado. Retorna um 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 ] );

Métodos de `StateMachineBuilder`

Método	Descrição
`initial( string $state_name )`	Define explicitamente o estado inicial.
`state( string $state_name, ?StateMachineStatus $terminal_status = null )`	Começa a configurar um estado.
`action( string\|array $action_class )`	Registra uma ação de entrada enfileirada para o estado atual. Passe um nome de classe ou uma definição estruturada com `class`, `payload` e `config`; `payload` chega a `StateAction::handle()` como `$payload`.
`on( string $event, string $target, string\|array\|null $guard_class = null, ?string $name = null )`	Registra uma transição de evento a partir do estado atual. A condição aceita o mesmo formato estruturado de `action()`.
`on_queue( string $queue )`	Define a fila usada para ações de estado enfileiradas.
`with_priority( Priority $priority )`	Define a prioridade das ações de estado enfileiradas.
`max_attempts( int $max_attempts )`	Define o limite de tentativas para ações de estado enfileiradas.
`version( string $version )`	Marca a definição da máquina com uma versão no nível da aplicação.
`idempotency_key( string $key )`	Torna durável a iniciação para uma chave fornecida pelo chamador. Iniciá-la novamente com a mesma chave retorna o ID original da máquina.
`dispatch( array $initial_state = [] )`	Inicia a máquina e retorna o ID da máquina.

As classes de ação de entrada de estado também podem expor um método opcional config() com as mesmas chaves de política de recursos compatíveis com as etapas do fluxo de trabalho: concurrency_group, concurrency_limit e cost_units.

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

Inicia um pacote serializado de definição de máquina de estado. A maioria do código da aplicação deve preferir machine()->dispatch(). Este método de nível inferior existe para que adaptadores possam iniciar uma máquina sem depender diretamente do construtor.

PHP

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

`Queuety::machine_status( $machine_id )`

Obtém o status atual da máquina. Retorna um objeto StateMachineState ou 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 também expõe:

definition_version
definition_hash
idempotency_key
error_message
current_action
terminal_status

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

Envia um evento externo para uma máquina em espera.

PHP

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

O conteúdo fica disponível para as condições de transição e é mesclado ao estado público da máquina quando o evento é aceito.

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

Lista os registros persistidos da máquina para inspeção.

PHP

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

Cada linha inclui o ID da máquina, o nome, o status, o estado atual, a versão da definição, o hash da definição, a chave de idempotência e os registros de data e hora do ciclo de vida.

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

Obtém a linha do tempo durável de eventos de uma máquina.

PHP

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

Cada linha de evento contém: 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 e created_at.

`Queuety::machine_trace( $machine_id )`

Obtém um pacote de rastreamento normalizado para um depurador de máquinas de estado UI.

PHP

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

O rastreamento contém machine, states agrupados, events brutos, ação correlacionada jobs, logs, artifacts e chunks.

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

Obtém o estado público após um evento específico do rastreamento da máquina, ou null se não for encontrado.

PHP

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

Consulte Máquinas de estado para conhecer o modelo do ciclo de vida e os padrões de uso.

Modelos de fluxo de trabalho

`Queuety::define_workflow( $name )`

Cria um construtor de fluxo de trabalho para usar como modelo.

PHP

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

`Queuety::register_workflow_template( $builder )`

Registra um modelo de fluxo de trabalho.

PHP

Queuety::register_workflow_template( $builder );

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

Inicia um modelo de fluxo de trabalho registrado pelo nome. Retorna o ID do fluxo de trabalho.

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' ],
);

Lança RuntimeException se o modelo não estiver registrado.

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

Inicia um fluxo de trabalho a partir de um pacote de definição em tempo de execução.

A maioria do código da aplicação deve preferir run_workflow() ou workflow()->dispatch(). Este método de nível inferior existe para que adaptadores reutilizáveis possam iniciar uma definição serializada de fluxo de trabalho sem depender de métodos internos do gerenciador de fluxos de trabalho.

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 )`

Registra uma ação WordPress que inicia um fluxo de trabalho.

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 pode ser:

o nome de um modelo de fluxo de trabalho registrado
um WorkflowBuilder em linha

map, when e idempotency_key são executados de forma síncrona dentro da solicitação atual de WordPress. Somente as etapas do fluxo de trabalho são executadas de forma assíncrona após a iniciação.

Consulte Gatilhos de ação para ver o guia completo.

`Queuety::workflow_templates()`

Obtém o registro de modelos de fluxo de trabalho.

PHP

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

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

Carrega e registra todos os arquivos de fluxo de trabalho de um diretório. Cada arquivo .php deve retornar um WorkflowBuilder. Retorna o número de fluxos de trabalho registrados.

PHP

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

`Queuety::load_workflow_file( $file_path )`

Carrega e registra um único arquivo de fluxo de trabalho. Retorna o WorkflowTemplate ou null se o arquivo não retornar um construtor.

PHP

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

Agendamento

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

Cria um agendamento recorrente. Retorna um construtor PendingSchedule.

PHP

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

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

Métodos de `PendingSchedule`

Método	Descrição
`every( string $interval )`	Define uma expressão de intervalo (e.g. `1 hour`, `30 minutes`)
`cron( string $expression )`	Define uma expressão cron de 5 campos
`overlap( OverlapPolicy $policy )`	Define a política de sobreposição (padrão: `Allow`). Consulte Agendamento.
`on_queue( string $queue )`	Define a fila de destino (padrão: `default`)
`id()`	Força a iniciação e retorna o ID do agendamento

`Queuety::scheduler()`

Obtém a instância interna de Scheduler.

PHP

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

Registro de manipuladores

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

Registra uma classe de manipulador sob um nome.

PHP

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

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

Descobre automaticamente e registra classes de manipulador de um diretório. Retorna o número de manipuladores registrados.

PHP

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

`Queuety::registry()`

Obtém o registro de manipuladores.

PHP

$registry = Queuety::registry();

Observabilidade

`Queuety::logger()`

Obtém a instância de Logger para consultar entradas de registro.

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()`

Obtém a instância de Metrics.

PHP

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

`Queuety::webhook_notifier()`

Obtém a instância de WebhookNotifier.

PHP

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

`Queuety::rate_limiter()`

Obtém a instância de RateLimiter.

PHP

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

Cache

`Queuety::cache()`

Obtém a instância do backend de cache ativo.

PHP

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

`Queuety::set_cache( $cache )`

Substitui o backend de cache. Chame antes de Queuety::init() para usar uma implementação personalizada.

PHP

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

`QUEUETY_CACHE_TTL`

TTL padrão do cache em segundos (padrão: 5). Defina essa constante em wp-config.php para alterar o TTL padrão usado pelas operações internas de cache.

PHP

define( 'QUEUETY_CACHE_TTL', 10 );

Consulte Armazenamento em cache para obter detalhes sobre backends e detecção automática.

Registro de eventos da máquina de estado

`Queuety::machine_events()`

Obtém a instância de StateMachineEventLog.

PHP

$log = Queuety::machine_events();

Registro de eventos do fluxo de trabalho

`Queuety::workflow_events()`

Obtém a instância de WorkflowEventLog.

PHP

$log = Queuety::workflow_events();

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

Obtém a linha do tempo completa dos eventos de um fluxo de trabalho. Retorna um array de linhas de evento ordenadas por ID.

PHP

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

Cada linha de evento contém: 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 (copiado de error.message), duration_ms e created_at.

`Queuety::workflow_trace( $workflow_id )`

Obtenha um pacote de rastreamento normalizado para um depurador de fluxos de trabalho UI.

PHP

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

O rastreamento contém workflow, agrupados steps, brutos events, jobs, logs, artifacts, chunks, signals e wait_dependencies.

`Queuety::trace_input( $input )`

Defina a entrada no nível da aplicação para a etapa do fluxo de trabalho em execução no momento.

`Queuety::trace_output( $output )`

Defina a saída no nível da aplicação para a etapa do fluxo de trabalho em execução no momento.

`Queuety::trace_context( array $context )`

Mescle o contexto no nível da aplicação à etapa do fluxo de trabalho em execução no momento.

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

Obtenha o estado público após a conclusão ou retomada de uma etapa específica do fluxo de trabalho, ou null se não for encontrado.

PHP

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

Consulte Log de eventos do fluxo de trabalho para ver casos de uso e comandos CLI.

Instâncias internas

Estes métodos retornam instâncias internas para casos de uso avançados.

Método	Retorna	Descrição
`Queuety::queue()`	`Queue`	Operações de fila (reivindicar, liberar, enterrar)
`Queuety::worker()`	`Worker`	Controle do processo do worker
`Queuety::workflow_manager()`	`Workflow`	Orquestração de fluxos de trabalho
`Queuety::machines()`	`StateMachine`	Gerenciamento do ciclo de vida da máquina de estados
`Queuety::connection()`	`Connection`	Conexão com o banco de dados
`Queuety::batch_manager()`	`BatchManager`	Gerenciamento do ciclo de vida de lotes (cancelar, podar)
`Queuety::chunk_store()`	`ChunkStore`	Persistência de partes para etapas de streaming
`Queuety::machine_events()`	`StateMachineEventLog`	Eventos de rastreamento de máquinas de estados e pacotes de rastreamento normalizados
`Queuety::workflow_events()`	`WorkflowEventLog`	Eventos de rastreamento de fluxos de trabalho e pacotes de rastreamento normalizados
`Queuety::resource_manager()`	`ResourceManager`	Perfis de admissão de workers, orçamentos ponderados e inspeção da memória do sistema
`Queuety::cache()`	`Cache`	Instância do backend de cache

Testes

`Queuety::fake()`

Substitua a fila por um objeto falso em memória para testes. Retorna uma instância QueueFake que registra os trabalhos enviados sem acessar o banco de dados. create_batch() também registra metadados falsos de lote; as cadeias são verificadas por meio dos trabalhos individuais enviados por elas.

PHP

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

`Queuety::reset()`

Redefina todo o estado interno, incluindo o objeto falso da fila. Chame dentro de tearDown().

PHP

Queuety::reset();

Métodos de `QueueFake`

Método	Descrição
`assert_pushed( string $class, ?Closure $callback )`	Verifica se uma classe de trabalho foi enviada. Um callback opcional filtra os dados do trabalho.
`assert_pushed_times( string $class, int $count )`	Verifica se um trabalho foi enviado exatamente N vezes.
`assert_not_pushed( string $class )`	Verifica se um trabalho nunca foi enviado.
`assert_nothing_pushed()`	Verifica se nenhum trabalho foi enviado.
`assert_batched( ?Closure $callback )`	Verifica se um lote foi despachado. Um callback opcional filtra os dados do lote.
`pushed( string $class )`	Obtém todos os despachos registrados para uma classe. Retorna uma matriz.
`batches()`	Obtém todos os lotes registrados. Retorna uma matriz.
`reset()`	Limpa todos os trabalhos e lotes registrados.

Consulte Testes para ver exemplos completos.

Interfaces

`Handler`

Interface para manipuladores de trabalhos simples.

PHP

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

config() pode retornar queue, max_attempts, backoff, rate_limit, concurrency_group, concurrency_limit e cost_units.

`Step`

Interface para manipuladores de etapas do fluxo de trabalho.

PHP

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

config() pode retornar max_attempts, backoff, concurrency_group, concurrency_limit e cost_units.

`Contracts\ForEachHandler`

Interface para manipuladores dinâmicos de ramificações for-each.

PHP

namespace Queuety\Contracts;

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

config() pode retornar max_attempts, backoff, rate_limit, concurrency_group, concurrency_limit e cost_units.

`Contracts\ForEachReducer`

Redutor opcional para resultados de for-each.

PHP

namespace Queuety\Contracts;

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

`Contracts\Compensation`

Interface para manipuladores de compensação de etapas.

PHP

namespace Queuety\Contracts;

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

`Contracts\RepeatCondition`

Interface para predicados de loop usados por repeat_until() e repeat_while() quando uma comparação de chave de estado é muito limitada.

PHP

namespace Queuety\Contracts;

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

`Contracts\StateAction`

Interface para ações enfileiradas de entrada de estado.

PHP

namespace Queuety\Contracts;

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

$payload recebe o payload estruturado da definição da ação, se a máquina tiver sido definida com um. Retorne atualizações do estado público. Inclua _event e, opcionalmente, _event_payload quando a ação deve fazer a transição imediatamente.

As ações de estado também podem definir um método config() opcional. Queuety lê concurrency_group, concurrency_limit e cost_units dele quando a ação de entrada é enfileirada.

`Contracts\StateGuard`

Interface para proteções de transição de máquinas de estados.

PHP

namespace Queuety\Contracts;

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

`Contracts\Job`

Interface para classes de trabalho independentes que podem ser despachadas. As classes de trabalho encapsulam a carga útil como propriedades públicas e a lógica de execução em handle().

PHP

namespace Queuety\Contracts;

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

As classes de trabalho podem definir opcionalmente um método middleware() que retorna uma matriz de instâncias Contracts\Middleware.

`Contracts\Cache`

Interface para backends de cache. Consulte Armazenamento em cache para ver implementações integradas e backends personalizados.

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;
}

Método	Retorna	Descrição
`get( $key )`	`mixed`	Recupera um valor. Retorna `null` se não for encontrado ou tiver expirado.
`set( $key, $value, $ttl )`	`void`	Armazena um valor. TTL de 0 significa que não expira.
`delete( $key )`	`void`	Remove um valor.
`has( $key )`	`bool`	Verifica se uma chave existe e não expirou.
`add( $key, $value, $ttl )`	`bool`	Definição atômica somente se não existir. Retorna `true` se o valor for definido.
`flush()`	`void`	Remove todos os itens do cache.

`WorkflowEventLog`

Registra transições de etapas do fluxo de trabalho com o contexto completo do rastreamento. Acesse por meio de Queuety::workflow_events().

Método	Retorna	Descrição
`record_event( array $event )`	`void`	Registra um evento de rastreamento bruto
`record_step_started( ... )`	`void`	Registra um evento step_started com a entrada e o estado antes da execução
`record_step_completed( ... )`	`void`	Registra um evento step_completed com a entrada, a saída, o estado anterior e o estado posterior
`record_step_failed( ... )`	`void`	Registra um evento step_failed com o contexto do rastreamento e detalhes estruturados do erro
`get_timeline( int $workflow_id, ?int $limit = 100, int $offset = 0 )`	`array`	Obtém os eventos de rastreamento do fluxo de trabalho em ordem, com paginação opcional
`get_trace( int $workflow_id )`	`array`	Obtém um pacote de rastreamento normalizado
`get_state_at_step( int $workflow_id, int $step_index )`	`array\|null`	Obtém o estado público após a conclusão ou retomada de uma etapa específica
`prune( int $older_than_days )`	`int`	Exclui eventos anteriores ao número de dias indicado. Retorna o número de linhas excluídas.

`StateMachineEventLog`

Registra eventos do ciclo de vida da máquina de estados, ações, transições e proteções com os mesmos campos de rastreamento dos eventos do fluxo de trabalho.

Método	Retorna	Descrição
`record_event( array $event )`	`void`	Registra um evento bruto de rastreamento da máquina
`get_timeline( int $machine_id, ?int $limit = 100, int $offset = 0 )`	`array`	Obtém os eventos de rastreamento da máquina em ordem, com paginação opcional
`get_trace( int $machine_id )`	`array`	Obtém um pacote normalizado de rastreamento da máquina
`get_state_at_event( int $machine_id, int $event_id )`	`array\|null`	Obtém o estado público após um evento específico de rastreamento da máquina
`prune( int $older_than_days )`	`int`	Exclui eventos anteriores ao número de dias indicado. Retorna o número de linhas excluídas.

`Contracts\StreamingStep`

Interface para manipuladores de etapas do fluxo de trabalho que produzem um fluxo de partes. Cada valor produzido é persistido imediatamente no banco de dados. Consulte Etapas de 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;
}

Método	Descrição
`stream( $state, $existing_chunks )`	Gerador que produz partes de texto. Cada produção aciona uma gravação imediata no banco de dados. Em caso de nova tentativa, `$existing_chunks` contém as partes persistidas anteriormente.
`on_complete( $chunks, $state )`	Chamado após o término do fluxo. Retorna dados para mesclar ao estado do fluxo de trabalho.
`config()`	Configuração opcional. Suporta `max_attempts`, `backoff`, `concurrency_group`, `concurrency_limit` e `cost_units`.

`ChunkStore`

Gerencia a persistência de partes para etapas de streaming. Acesse por meio de Queuety::chunk_store().

Método	Retorna	Descrição
`get_chunks( int $job_id )`	`string[]`	Busca todas as partes de um trabalho, ordenadas pelo índice da parte
`append_chunk( int $job_id, int $chunk_index, string $content, ?int $workflow_id, ?int $step_index )`	`void`	Acrescenta uma única parte
`clear_chunks( int $job_id )`	`void`	Exclui todas as partes de um trabalho
`chunk_count( int $job_id )`	`int`	Conta as partes de um trabalho
`get_accumulated( int $job_id )`	`string`	Concatena todas as partes em uma única string

`Heartbeat`

Auxiliar estático para enviar batimentos de atividade dentro de manipuladores de etapas e etapas de streaming. Consulte Batimentos.

Método	Descrição
`Heartbeat::init( int $job_id, Connection $conn )`	Define o contexto do trabalho. Chamado automaticamente pelo worker.
`Heartbeat::beat( array $progress = [] )`	Envia um batimento. Atualiza `reserved_at` e, opcionalmente, armazena dados de progresso em `heartbeat_data`.
`Heartbeat::clear()`	Limpa o contexto do trabalho. Chamado automaticamente pelo worker.
`Heartbeat::current_job_id()`	Obtém o ID do trabalho atual (para testes).

`Contracts\Middleware`

Interface para middleware de trabalhos. O middleware envolve a execução do trabalho em um pipeline em formato de cebola.

PHP

namespace Queuety\Contracts;

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

Traits

`Dispatchable`

Fornece métodos estáticos de despacho em classes de trabalho que implementam Contracts\Job. Os argumentos do construtor são repassados para criar a instância do trabalho.

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' );

Método	Retorna	Descrição
`dispatch( ...$args )`	`PendingJob`	Cria uma instância e a despacha
`dispatch_if( bool $condition, ...$args )`	`PendingJob\|null`	Despacha somente se `$condition` for verdadeiro
`dispatch_unless( bool $condition, ...$args )`	`PendingJob\|null`	Despacha somente se `$condition` for falso
`with_chain( array $jobs )`	`ChainBuilder`	Inicia uma cadeia a partir desta classe de trabalho

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();

Propriedades do trabalho

As classes de trabalho podem declarar propriedades públicas que o worker lê por reflexão para substituir o comportamento de novas tentativas e de tempo limite.

Propriedade	Tipo	Descrição
`$tries`	`int`	Número máximo de tentativas antes de o trabalho ser enterrado
`$timeout`	`int`	Tempo máximo de execução em segundos (requer `pcntl`)
`$backoff`	`array`	Atrasos progressivos, em segundos, para cada tentativa

PHP

class ImportProductsJob implements Job {
    use Dispatchable;

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

    // ...
}

Hook `failed()`

Quando um trabalho é enterrado após esgotar todas as tentativas, o worker chama um método failed() na instância do trabalho, se definido.

PHP

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

Middleware integrado

Todas as classes de middleware implementam Contracts\Middleware e estão localizadas no namespace Queuety\Middleware.

Classe	Descrição
`RateLimited( int $max, int $window )`	Impõe um limite de taxa de `$max` execuções a cada `$window` segundos
`Timeout( int $seconds )`	Encerra o trabalho após `$seconds` segundos (requer `pcntl`)
`UniqueJob( ?string $key )`	Impede execuções simultâneas por meio de um bloqueio no banco de dados
`WithoutOverlapping( string $key, int $release_after )`	Impede execuções sobrepostas com expiração automática do bloqueio
`ThrottlesExceptions( int $max_attempts, int $decay_minutes )`	Limita as exceções para evitar tempestades de trabalhos quando um serviço externo está fora do ar

Consulte Middleware para ver detalhes de uso e exemplos.

Enums

`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';
}

Consulte Agendamento para saber como cada política funciona.

Atributos

`#[QueuetyHandler]`

PHP atributo 8 para registro automático. Consulte PHP Atributos.

PHP

use Queuety\Attributes\QueuetyHandler;

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

Ponte de CLI

`Queuety::cli_command()`

Retorna o nome do comando raiz de WP-CLI publicado.

O comando raiz padrão é queuety. Defina QUEUETY_CLI_COMMAND antes que Queuety seja inicializado se o comando deve ser publicado com outro nome.

`Queuety::cli_command_map()`

Retorna o catálogo serializável de comandos Queuety CLI para ambientes de teste que precisam entender a superfície de comandos disponibilizada sem analisar classes WP-CLI.

Cada entrada inclui:

um ID de operação estável
o caminho relativo de CLI
a classe e o método do manipulador WP-CLI
os possíveis destinos de execução
o adaptador que normaliza os argumentos brutos CLI em um plano de execução

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

Transforma uma invocação CLI analisada no plano de execução que o ambiente de teste deve executar.

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'] );

Os planos de execução levam em conta o transporte de propósito:

os comandos são resolvidos para funções chamáveis públicas PHP com argumentos normalizados
o catálogo lista previamente todos os destinos de execução possíveis, enquanto callable e transport identificam a ramificação escolhida para a entrada analisada

Este é o padrão de uso de Queuety para ambientes de teste de agentes: ID de operação estável, destino público API e normalização sob responsabilidade do adaptador para preocupações exclusivas de CLI, como padrões de fila, decodificação de cargas úteis JSON, ramificações do pool de workers e manipulação de arquivos de exportação de fluxos de trabalho.

PHP API

Acesso independente ao núcleo

Queuety::init( Connection $conn )

Queuety::ensure_schema()

Tarefas

Queuety::dispatch( $handler, $payload )

Métodos de PendingJob

Queuety::dispatch_sync( $handler, $payload )

Queuety::batch( $jobs )

Queuety::create_batch( $jobs )

Métodos de BatchBuilder

Queuety::find_batch( $id )

Controle de workers

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' )

Objeto de valor Batch

Queuety::chain( $jobs )

Métodos de ChainBuilder

Queuety::retry( $job_id )

Queuety::retry_buried()

Queuety::purge( $older_than_days )

Filas

Queuety::stats( $queue )

Queuety::buried( $queue )

Queuety::pause( $queue )

Queuety::resume( $queue )

Queuety::is_paused( $queue )

Fluxos de trabalho

Queuety::workflow( $name )

Métodos de 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 )