Primeiros passos

Instalação

Requisitos

• PHP 8.2 ou posterior e WordPress 6.4 ou posterior
• MySQL 8.0+ ou MariaDB 10.6+. Os workers reivindicam jobs e agendamentos vencidos com SELECT ... FOR UPDATE SKIP LOCKED, que servidores mais antigos rejeitam com um erro de sintaxe.
• mysqli ou pdo_mysql (veja abaixo)
• WP-CLI no servidor se você executar workers dedicados com wp queuety work
• As extensões pcntl e posix PHP se você executar pools de workers com --workers ou --min-workers/--max-workers

Queuety requer mysqli ou pdo_mysql no runtime PHP que carrega WordPress e WP-CLI. Ele escolhe o driver automaticamente, dando preferência a mysqli em runtimes WordPress e mantendo pdo_mysql disponível para uso direto/independente do runtime.

Se você quiser usar o runtime com suporte a DB sem a camada de plugin WordPress, consulte Uso independente. Esse caminho usa a mesma conexão e as mesmas tabelas do runtime, mas não inclui as pontes de hooks WordPress nem o registro WP-CLI.

Do arquivo zip da versão

Cada versão GitHub tem um artefato queuety.zip: o plugin com suas dependências Composer já instaladas. Instale a versão mais recente com WP-CLI:

wp plugin install https://github.com/inline0/queuety/releases/latest/download/queuety.zip --activate

Ou baixe o zip e envie-o em Plugins > Adicionar novo > Enviar plugin. Esse é o caminho mais simples para um site WordPress comum.

Via Composer para Composer gerenciado por WordPress

composer require queuety/queuety

Em seguida, ative o plugin:

wp plugin activate queuety

O tipo do pacote é wordpress-plugin. Composer o coloca no diretório de plugins somente quando o projeto exige composer/installers e mapeia esse tipo para um caminho de instalação, como Bedrock faz; além disso, o projeto deve carregar seu próprio vendor/autoload.php (Bedrock também faz isso). Sem composer/installers, Composer o instala em vendor/queuety/queuety, onde WordPress não o encontra. Portanto, use o arquivo zip da versão em uma instalação simples de WordPress.

Do código-fonte durante o desenvolvimento

Coloque o repositório em wp-content/plugins/queuety e instale as dependências PHP:

composer install
wp plugin activate queuety

Na ativação, Queuety cria suas tabelas de banco de dados (queuety_jobs, queuety_workflows, queuety_logs, queuety_schedules, queuety_queue_states, queuety_webhooks, queuety_locks, queuety_signals, queuety_workflow_dependencies, queuety_workflow_dispatch_keys, queuety_batches, queuety_chunks, queuety_workflow_events, queuety_artifacts, queuety_state_machines, queuety_state_machine_events) para que os workers possam reivindicar jobs diretamente de MySQL.

Por padrão, o plugin também agenda um worker de execução única por meio de WordPress cron a cada minuto para a fila default. Isso oferece uma configuração básica sem shell para jobs e fluxos de trabalho que permanecem em default, desde que WordPress cron esteja em execução. Cada execução processa no máximo um job e não executa agendamentos recorrentes, recupera jobs obsoletos nem verifica prazos de fluxos de trabalho; essas tarefas só são executadas em um processo wp queuety work de longa duração (#14). Para filas personalizadas, agendamentos recorrentes, menor latência ou cargas mais pesadas, migre para processos wp queuety work dedicados.

Configuração

Todas as constantes são opcionais. Defina-as em wp-config.php antes de carregar o plugin ou antes de Queuety iniciar em uma instalação incorporada no estilo de tema:

As constantes de admissão de recursos e do pool adaptativo (QUEUETY_RESOURCE_*, QUEUETY_WORKER_POOL_*) estão listadas na página Workers.

QUEUETY_TABLE_PREFIX altera apenas a parte Queuety dos nomes das tabelas. O prefixo do banco de dados WordPress continua envolvendo o resultado, então $wpdb->prefix = 'wp_' e QUEUETY_TABLE_PREFIX = 'themequeue_' produzem tabelas como wp_themequeue_jobs. As constantes QUEUETY_TABLE_* explícitas ainda prevalecem para tabelas individuais.

Conexões independentes também podem definir o prefixo da tabela Queuety por conexão:

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

Isso mantém intacto o prefixo do banco de dados WordPress e altera apenas o segmento da tabela Queuety.

Seu primeiro job

Crie uma classe de manipulador que implemente a interface Handler:

use Queuety\Handler;

class SendEmailHandler implements Handler {
    public function handle( array $payload ): void {
        wp_mail( $payload['to'], $payload['subject'], $payload['body'] );
    }

    public function config(): array {
        return [
            'queue'           => 'emails',
            'max_attempts'    => 5,
        ];
    }
}

Registre-a e envie o job:

use Queuety\Queuety;

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

Queuety::dispatch( 'send_email', [
    'to'      => 'user@example.com',
    'subject' => 'Welcome',
    'body'    => 'Hello from Queuety!',
] );

Ou use a classe de job moderna que pode ser enviada:

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

readonly class SendEmailJob implements Job {
    use Dispatchable;

    public function __construct(
        public string $to,
        public string $subject,
        public string $body,
    ) {}

    public function handle(): void {
        wp_mail( $this->to, $this->subject, $this->body );
    }
}

SendEmailJob::dispatch( 'user@example.com', 'Welcome', 'Hello from Queuety!' );

Seu primeiro fluxo de trabalho

Defina manipuladores de etapas que implementem a interface Step:

use Queuety\Step;

class FetchDataHandler implements Step {
    public function handle( array $state ): array {
        $user = get_user_by( 'ID', $state['user_id'] );
        return [ 'user_name' => $user->display_name ];
    }

    public function config(): array {
        return [];
    }
}

class CallLLMHandler implements Step {
    public function handle( array $state ): array {
        $response = wp_remote_post( 'https://api.openai.com/v1/chat/completions', [
            'body' => json_encode( [ 'prompt' => "Generate report for {$state['user_name']}" ] ),
        ] );
        return [ 'llm_response' => wp_remote_retrieve_body( $response ) ];
    }

    public function config(): array {
        return [ 'max_attempts' => 5 ];
    }
}

class FormatOutputHandler implements Step {
    public function handle( array $state ): array {
        $url = save_report( $state['user_name'], $state['llm_response'] );
        return [ 'report_url' => $url ];
    }

    public function config(): array {
        return [];
    }
}

Envie o fluxo de trabalho:

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

Inicie um worker

wp queuety work

O worker verifica se há jobs pendentes, executa-os, avança os fluxos de trabalho e aguarda quando a fila está vazia. Pressione Ctrl+C para parar; isso encerra o processo imediatamente, mesmo no meio de um job (consulte Workers).

O SendEmailHandler acima envia seus jobs para a fila emails por meio de config(), portanto um worker em default não os coleta. Informe o nome de cada fila que usar:

wp queuety work --queue=emails,default

Se você não executar um worker dedicado, Queuety ainda oferece a alternativa padrão WordPress cron, executada uma vez por minuto e descrita acima, limitada à fila default e a um job por execução. O worker dedicado oferece maior capacidade de processamento e menor latência.

Em produção, execute vários workers:

wp queuety work --workers=4

Processe várias filas com ordenação por prioridade:

wp queuety work --queue=high,default,low

Próximos passos

• Jobs para o guia completo de envio e manipulação de jobs
• Workflows para cadeias, etapas paralelas, ramificações condicionais e execução de fluxos de trabalho
• Middleware para limitação de taxa, controle de fluxo e lógica de pipeline personalizada
• Processamento em lote para enviar grupos de jobs com callbacks
• Etapas em fluxo para persistir dados transmitidos em partes, uma por vez
• Agendamento para jobs recorrentes
• Cache para a camada de cache conectável
• Testes para QueueFake e asserções de teste
• ReferênciaCLI para todos os comandos disponíveis
• AcessoPHP APIprogramático