# Introduktion Queuety är ett WordPress-tillägg som erbjuder en snabb jobbkö, en beständig arbetsflödesmotor och en beständig körmiljö för tillståndsmaskiner. Arbetare hämtar jobb direkt från MySQL och behandlar dem i en långvarig WP-CLI-process. Körmiljön PHP som läser in WordPress och WP-CLI behöver antingen `mysqli` eller `pdo_mysql`. ## Varför Queuety? WordPress har inget riktigt system för bakgrundsjobb. `wp_cron` körs bara vid sidbesök. Standardköraren för Action Scheduler använder WP-Cron och lokala HTTP-förfrågningar, där varje omgång bearbetar jobb i högst 30 sekunder. Ett API-anrop som tar 60 sekunder avbryts av tidsgränsen på 30 sekunder i PHP. Det går inte att köra processer med flera steg som överlever krascher och fortsätter där de avbröts. Queuety löser detta med tre grundfunktioner: 1. **Jobb** för bakgrundsarbete som körs utan att invänta svar 2. **Arbetsflöden** för beständiga processer i flera steg med kvarvarande tillstånd 3. **Tillståndsmaskiner** för långlivade, händelsestyrda livscykler ## Snabbexempel Skicka iväg ett jobb med den moderna API: ```php 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!' ); ``` Eller använd den klassiska metoden med namn på hanterare: ```php use Queuety\Queuety; Queuety::dispatch( 'send_email', [ 'to' => 'user@example.com' ] ); ``` Kör ett beständigt arbetsflöde: ```php Queuety::workflow( 'generate_report' ) ->then( FetchDataHandler::class ) ->then( CallLLMHandler::class ) ->then( FormatOutputHandler::class ) ->dispatch( [ 'user_id' => 42 ] ); ``` Modellera en långvarig session med en tillståndsmaskin: ```php use Queuety\Enums\StateMachineStatus; 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 ] ); ``` Starta en arbetare: ```bash wp queuety work ``` Om du bygger ett system med agentarkitektur kan du börja med [Agentorkestrering](https://queuety.inline0.dev/sv/docs/workflows/agent-orchestration). Där visas hur planerare och utförare, granskningssteg för människor och väntan mellan arbetsflöden hänger ihop. Om systemet är händelsestyrt och långlivat kan du börja med [Tillståndsmaskiner](https://queuety.inline0.dev/sv/docs/state-machines) tillsammans med arbetsflöden. Om du vill se exempel på integration från början till slut kan du läsa [Exempel](https://queuety.inline0.dev/sv/docs/examples), som nu innehåller mönster baserade på Neuron för byte av leverantör, strömning, upprepade granskningar med minnesstöd och beroende arbetsflöden. Om du vill att arbetsflöden ska starta från domänhändelser i WordPress, till exempel `save_post`, kan du läsa [Åtgärdsutlösare](https://queuety.inline0.dev/sv/docs/features/action-triggers). Om du vill använda den databaskopplade körmiljön utanför WordPress kan du läsa [Fristående användning](https://queuety.inline0.dev/sv/docs/features/standalone-use). ## Viktiga skillnader - **Snabb exekvering.** Arbetare använder direktåtkomst till MySQL-kön och undviker cron-mönstret per begäran som gör bakgrundsarbete långsammare i WordPress. - **Beständiga arbetsflöden.** Processer i flera steg med beständigt tillstånd som överlever PHP-tidsgränser, krascher och omförsök. Varje steggräns är en atomär MySQL-transaktion. - **Explicita tillståndsmaskiner.** Modellera chattsessioner, godkännanden och andra långlivade livscykler med namngivna tillstånd, villkorade övergångar, köade åtgärder vid tillståndsinträde och beständiga händelsetidslinjer. - **Modern dispatch API.** Fristående jobbklasser med `Dispatchable`-trait, typade konstruktorsegenskaper som payload och `$tries`/`$timeout`/`$backoff` deklarerade i klassen. En `readonly`-klass kan inte ge dessa egenskaper standardvärden, så deklarera dem i en vanlig klass med readonly-promoverade konstruktorsegenskaper. - **Middleware-pipeline.** Middleware i lökliknande lager för hastighetsbegränsning, undantagsbegränsning, unika jobb och anpassad logik. Deklareras per jobb via en `middleware()`-metod. - **Strömningssteg.** Gränssnittet `StreamingStep` ger segment som sparas omedelbart i databasen. Vid omförsök skickas tidigare sparade segment med så att strömmen kan fortsätta där den avbröts. Perfekt för LLM-svar och stora nedladdningar. - **Utbytbar cache.** `CacheFactory` identifierar automatiskt APCu eller använder en cache i minnet som reserv. Anpassade backends implementerar `Contracts\Cache`. Används internt för uppslagningar av hastighetsbegränsare och köstatus. - **Batchning och kedjning.** Skicka grupper av jobb med återanropen `then`/`catch`/`finally` och följ förloppet, eller kedja jobb sekventiellt så att varje jobb väntar på att föregående jobb slutförs. - **Beständiga fördröjningar och väntelä­gen.** `delay()` lägger till fördröjningar som tål omstart av processen. `wait_for_signal()`, `wait_for_signals()`, `wait_for_approval()`, `wait_for_input()` och `wait_for_workflow()` låter arbetsflöden pausa i väntan på externa händelser eller andra arbetsflöden utan att hålla PHP vid liv. - **Dynamisk for-each.** `for_each()` utökar arbetsgrenar som upptäcks vid körning utifrån arbetsflödestillståndet och stöder slutförandelägena alla lyckas, första lyckade och kvorum. - **Asynkrona överlämningar mellan arbetsflöden.** `start_workflows()` omvandlar objekt som upptäcks vid körning till fristående arbetsflöden på toppnivå som kan inväntas senare. - **Utlösare för WordPress-åtgärder.** `on_action()` mappar åtgärdshooks från kärnan eller pluginer till beständiga arbetsflödesanrop med villkorsstyrning och idempotens. - **Beständiga artefakter.** Lagra namngivna utdata från arbetsflöden utanför den huvudsakliga tillståndssamlingen och ta med dem vid statuskontroll, inspektion med CLI, export och återuppspelning. - **Skyddsräcken för arbetsflöden.** `version()`, en deterministisk definitionshash, idempotenta dispatch-nycklar och arbetsflödesbudgetar gör agentliknande körningar enklare att granska och minskar risken för dubbletter eller att de löper iväg obemärkt. - **Resurshantering.** Samtidighetsgrupper, kostnadsenheter, arbetsflödesbudgetar och styrning av arbetaråtkomst hjälper till att hålla kostsamt agentliknande arbete inom fastställda gränser. - **Kompensering av steg.** `compensate_with()` och `compensate_on_failure()` tillhandahåller återställningshooks för slutförda steg när arbetsflöden avbryts eller misslyckas. - **Hjärtslag.** Långvariga steg skickar hjärtslag för att hindra systemet för återställning av inaktuella jobb från att ta över aktivt arbete. - **Spårning av arbetsflöden.** Varje stegövergång registreras med indata, utdata, tillstånd före och efter, kontext, artefakter, segment, fel och felsökning genom tidsresor via `workflow_state_at()`. - **Parallella steg.** Kör steg samtidigt och vänta tills alla har slutförts innan arbetsflödet går vidare. - **Villkorsstyrd förgrening.** Hoppa till namngivna steg utifrån tidigare tillstånd med `_next_step`. - **Kör arbetsflöden.** Starta underordnade arbetsflöden som skickar resultaten tillbaka till det överordnade arbetsflödet. - **Prioritetsköer.** Fyra nivåer (Low, Normal, High, Urgent) med typsäkra enum-värden i PHP. - **Arbetare med flera köer.** Behandla flera köer med strikt prioritetsordning i en och samma arbetare. - **Hastighetsbegränsning.** Begränsa körningar per hanterare med ett glidande fönster. - **Återkommande jobb.** Schemaläggning baserad på intervall och cron, med konfigurerbara principer för överlappning (Allow, Skip, Buffer). - **Avbryta arbetsflöden.** Avbryt arbetsflöden som körs och utlös registrerade rensningshanterare. - **Tillståndsrensning.** Ta automatiskt bort gamla stegutdata så att stora arbetsflödestillstånd förblir hanterbara. - **Samtidighet för arbetare.** `--workers=N` förgrenar flera processer och startar om dem automatiskt vid krasch. - **Full insyn.** Loggning i databasen, mätvärden per hanterare och webhookar för händelser. - **Testverktyg.** `QueueFake` registrerar utskickade jobb och batchar för påståenden i enhetstester. - **PHP-attribut.** `#[QueuetyHandler('name')]` för registrering av hanterare utan konfiguration. ## Så fungerar det Arbetare körs i en långlivad WP-CLI-process och hämtar jobb direkt från MySQL. K�rader, arbetsflödestillstånd, loggar, batchar, signaler och strömningssegment lagras alla i MySQL, så omstarter av arbetare gör inte att orkestreringstillstånd går förlorat. Arbetsflöden delar upp långvarigt arbete i steg. Varje steg sparar sitt resultat i en gemensam tillståndspåse i databasen. Om PHP avslutas mitt i ett steg försöker arbetaren köra om det steget med alla tidigare tillstånd intakta. Steggränsen är en enda MySQL-transaktion: tillståndsuppdatering, slutförande av jobb och köläggning av nästa steg sker atomiskt. ``` Workflow: generate_report (3 steps) Step 0: fetch_data -> state: {user_data: {...}} Step 1: call_llm -> PHP dies -> retry -> state: {user_data: {...}, llm_response: "..."} Step 2: format_output -> state: {user_data: {...}, llm_response: "...", report_url: "/reports/42.pdf"} Workflow: completed ``` ## Krav - PHP 8.2 eller senare - WordPress 6.4 eller senare - MySQL 8.0+ eller MariaDB 10.6+, eftersom arbetare hämtar jobb med `SELECT ... FOR UPDATE SKIP LOCKED` - `mysqli` eller `pdo_mysql` i körmiljön PHP som läser in WordPress och WP-CLI - WP-CLI för att köra dedikerade arbetare med `wp queuety work` - Tilläggen `pcntl` och `posix` PHP för arbetarpooler (`--workers`, `--min-workers`, `--max-workers`) Se [Kom igång](https://queuety.inline0.dev/sv/docs/getting-started) för installationen.