# PHP API

يمكن الوصول إلى كل شيء في Queuety عبر الفئة الثابتة `Queuety\Queuety`. وهي نقطة الدخول الوحيدة لإرسال المهام، وبناء مسارات العمل، وتشغيل آلات الحالة، وإدارة قوائم الانتظار، والوصول إلى الأنظمة الفرعية الداخلية.

```php
use Queuety\Queuety;
```

## الوصول المستقل إلى النواة

يمكن تهيئة بيئة التشغيل المدعومة بقاعدة بيانات الخاصة بـ Queuety خارج WordPress.

هذا المسار المستقل مخصص لنواة التنسيق:

- المهام والعاملون (تحتاج مجموعات العاملين أيضًا إلى الثوابت `DB_HOST` و`DB_NAME` و`DB_USER` و`DB_PASSWORD`، راجع أدناه)
- تدفقات العمل والإشارات
- آلات الحالات والأحداث
- العناصر الأثرية والسجلات والمقاييس والجداول الزمنية

لا يُعد بديلًا عن المحوّل WordPress. لا يزال كل من `Queuety::on_action()` و`replace_wp_cron()` وتهيئة الإضافة ومسار تسجيل `wp queuety ...` الفعلي يتطلب WordPress.

### `Queuety::init( Connection $conn )`

هيّئ Queuety باتصال مباشر مدعوم بقاعدة بيانات.

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

تغيّر الوسيطة الاختيارية `table_prefix` الجزء Queuety من أسماء جداول بيئة التشغيل لكل اتصال:

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

يحوّل ذلك جداول مثل `queuety_jobs` إلى `wp_themequeue_jobs`.

### `Queuety::ensure_schema()`

تأكد من وجود جداول بيئة التشغيل Queuety للاتصال النشط.

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

للاطلاع على النموذج الكامل وحدود WordPress، راجع [الاستخدام المستقل](https://queuety.inline0.dev/ar/docs/features/standalone-use).

## المهام

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

أرسل مهمة. يقبل اسم معالج كسلسلة نصية أو مثيلًا من `Contracts\Job`. ويُرجع منشئًا `PendingJob` لتسلسل الخيارات.

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

عند تمرير مثيل من `Contracts\Job`، يستخرج المُسلسِل FQCN بوصفه اسم المعالج والخصائص العامة بوصفها الحمولة. ويتم تجاهل المعامل `$payload` عندما تكون `$handler` مثيلًا من `Job`.

### طرق `PendingJob`

| الطريقة | الوصف |
|---|---|
| `on_queue( string $queue )` | تعيين قائمة الانتظار المستهدفة |
| `with_priority( Priority $priority )` | تعيين مستوى الأولوية |
| `delay( int $seconds )` | التأخير قبل إتاحة المهمة |
| `max_attempts( int $max )` | الحد الأقصى لمحاولات إعادة المحاولة |
| `rate_limit( int $max, int $window )` | تحديد المعدل: الحد الأقصى للتنفيذات خلال نافذة زمنية بالثواني |
| `unique()` | منع الإرسال المكرر |
| `after( int $job_id )` | انتظار اكتمال مهمة أخرى أولًا |
| `concurrency_group( string $group, int $limit )` | وضع المهمة ضمن مجموعة مشتركة لقبول العاملين |
| `cost_units( int $units )` | إرفاق بيانات وصفية للتكلفة النسبية للتنفيذ بعملية الإرسال |
| `id()` | فرض الإرسال وإرجاع معرّف المهمة |

يدعم كل من `concurrency_group()` و`cost_units()` نموذج [إدارة الموارد](https://queuety.inline0.dev/ar/docs/features/resource-management) الأوسع، ما يتيح لعملية الإرسال نفسها المشاركة في حدود التزامن القائمة على العدد، وميزانيات قوائم الانتظار أو مزوّدي الخدمة الموزونة، وأساليب الاستدلال لقبول العاملين.

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

نفّذ مهمة بشكل متزامن في العملية الحالية دون إضافتها إلى قائمة الانتظار.

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

يُستدعى أسلوب `handle()` الخاص بالمهمة مباشرة. لا يُنشأ أي سجل في قاعدة البيانات، ولا يُستخدم أي عامل، ولا تُطبّق البرمجيات الوسيطة.

### `Queuety::batch( $jobs )`

أرسل عدة مهام في تعليمة INSERT واحدة متعددة الصفوف.

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

أنشئ `BatchBuilder` لإرسال مجموعة من المهام مع عمليات الاستدعاء وتتبع التقدم. راجع [التجميع](https://queuety.inline0.dev/ar/docs/features/batching) للاطلاع على التفاصيل الكاملة.

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

### طرق `BatchBuilder`

| الطريقة | القيمة المُعادة | الوصف |
|---|---|---|
| `name( string $name )` | `self` | تعيين اسم للمجموعة |
| `on_queue( string $queue )` | `self` | تعيين قائمة الانتظار لجميع مهام المجموعة |
| `then( string $handler_class )` | `self` | معالج يُستدعى عند اكتمال المجموعة بنجاح |
| `catch( string $handler_class )` | `self` | معالج يُستدعى عند فشل أول مهمة في المجموعة |
| `finally( string $handler_class )` | `self` | معالج يُستدعى عند انتهاء المجموعة، سواء بالنجاح أو الفشل |
| `allow_failures()` | `self` | السماح باستدعاء `then` حتى عند وجود إخفاقات |
| `dispatch()` | `Batch` | إنشاء سجل المجموعة وجميع المهام، وإرجاع كائن القيمة `Batch` |

### `Queuety::find_batch( $id )`

اعثر على مجموعة حسب المعرّف. يُرجع كائن قيمة `Batch` أو `null`.

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

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

## التحكم بالعاملين

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

شغّل حلقة عامل واحدة مباشرة.

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

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

شغّل مجموعة عاملين مباشرة بحجم ثابت. يتطلب امتدادي `pcntl` و`posix`. تقرأ المجموعة ثوابت WordPress و`DB_HOST` و`DB_NAME` و`DB_USER` و`DB_PASSWORD` لاتصالاتها الفرعية (ولا تأتي من الاتصال المُهيّأ سوى بادئات الجداول)، لذا عرّفها عند تشغيل مجموعة خارج WordPress ([#5](https://github.com/inline0/queuety/issues/5)).

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

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

شغّل مجموعة عاملين تكيفية مباشرة. تنطبق المتطلبات نفسها على `run_worker_pool()`.

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

### كائن القيمة `Batch`

| الطريقة/الخاصية | النوع | الوصف |
|---|---|---|
| `$id` | `int` | معرّف المجموعة |
| `$name` | `string\|null` | اسم المجموعة، اختياري |
| `$total_jobs` | `int` | إجمالي عدد المهام في المجموعة |
| `$pending_jobs` | `int` | المهام التي لا تزال قيد الانتظار |
| `$failed_jobs` | `int` | عدد المهام الفاشلة |
| `$failed_job_ids` | `array` | معرّفات المهام الفاشلة |
| `$created_at` | `DateTimeImmutable` | وقت إنشاء المجموعة |
| `$finished_at` | `DateTimeImmutable\|null` | وقت انتهاء المجموعة |
| `$cancelled_at` | `DateTimeImmutable\|null` | وقت إلغاء المجموعة |
| `progress()` | `int` | نسبة الاكتمال (0-100) |
| `finished()` | `bool` | ما إذا كانت المجموعة قد انتهت |
| `has_failures()` | `bool` | ما إذا كانت أي مهمة قد فشلت |
| `cancelled()` | `bool` | ما إذا كانت المجموعة قد أُلغيت |

### `Queuety::chain( $jobs )`

أنشئ `ChainBuilder` لتنفيذ المهام بالتتابع. تعتمد كل مهمة على اكتمال المهمة السابقة بنجاح.

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

### طرق `ChainBuilder`

| الطريقة | القيمة المُعادة | الوصف |
|---|---|---|
| `on_queue( string $queue )` | `self` | تعيين قائمة الانتظار لجميع مهام السلسلة |
| `catch( string $handler_class )` | `self` | معالج يُستدعى عند دفن أي مهمة في السلسلة نهائيًا |
| `dispatch()` | `int` | إنشاء جميع المهام مع تبعيات متسلسلة، وإرجاع معرّف المهمة الأولى |

### `Queuety::retry( $job_id )`

أعِد محاولة مهمة محددة. وتُعاد حالتها إلى `pending`.

```php
Queuety::retry( 42 );
```

### `Queuety::retry_buried()`

أعِد محاولة جميع المهام المدفونة. يُرجع عدد المهام التي أُعيدت محاولتها.

```php
$count = Queuety::retry_buried();
```

### `Queuety::purge( $older_than_days )`

احذف المهام المكتملة. يُرجع عدد المهام المحذوفة.

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

## قوائم الانتظار

### `Queuety::stats( $queue )`

احصل على أعداد المهام مجمّعة حسب الحالة.

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

احصل على جميع المهام المدفونة.

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

### `Queuety::pause( $queue )`

أوقف قائمة انتظار مؤقتًا كي يتجاوزها العاملون.

```php
Queuety::pause( 'emails' );
```

### `Queuety::resume( $queue )`

استأنف قائمة انتظار متوقفة مؤقتًا.

```php
Queuety::resume( 'emails' );
```

### `Queuety::is_paused( $queue )`

تحقق مما إذا كانت قائمة الانتظار متوقفة مؤقتًا.

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

## تدفقات العمل

### `Queuety::workflow( $name )`

ابدأ إنشاء تدفق عمل. يُرجع `WorkflowBuilder`.

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

### طرق `WorkflowBuilder`

| الطريقة | الوصف |
|---|---|
| `then( string $handler_class, ?string $name = null )` | إضافة خطوة متسلسلة. اسم اختياري للتفرع الشرطي. |
| `parallel( array $handler_classes )` | إضافة مجموعة خطوات متوازية. |
| `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 )` | إضافة خطوة ديناميكية للتكرار على العناصر، تنشئ مهمة فرعية لكل عنصر في حالة تدفق العمل. |
| `repeat_while( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )` | الرجوع إلى خطوة مسماة سابقة ما دام مفتاح حالة عام أو صنف `RepeatCondition` مطابقًا. |
| `repeat_until( string $target_step, ?string $state_key = null, mixed $expected = true, ?string $name = null, ?string $condition_class = null, ?int $max_iterations = null )` | الرجوع إلى خطوة مسماة سابقة إلى أن يطابق مفتاح حالة عام أو صنف `RepeatCondition`. |
| `run_workflow( string $workflow_name, WorkflowBuilder $sub_builder )` | إضافة خطوة لتشغيل تدفق عمل. |
| `delay( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )` | إضافة خطوة تأخير دائم. تُجمع مدد التأخير كلها. |
| `wait_for_signal( string $name, ?string $result_key = null, ?string $step_name = null, array $match_payload = [], ?string $correlation_key = null )` | إضافة خطوة انتظار إشارة. يتيح لك كل من `match_payload` و`correlation_key` اختياريًا تجاهل الأحداث غير المرتبطة. |
| `wait_for_signals( array $signal_names, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, array $match_payload = [], ?string $correlation_key = null )` | انتظار كل الإشارات أو بعضها، مع مطابقة اختيارية للحمولة وربطها. |
| `wait_for_approval( string $signal_name = 'approval', ?string $result_key = 'approval', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )` | انتظار إشارة موافقة بشرية. |
| `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 )` | انتظار الموافقة أو الرفض، وتخزين حمولة قرار منظّمة. |
| `wait_for_input( string $signal_name = 'input', ?string $result_key = 'input', ?string $name = null, array $match_payload = [], ?string $correlation_key = null )` | انتظار إشارة إدخال بشري. |
| `wait_for_workflow( int\|string $workflow, ?string $result_key = null, ?string $name = null )` | انتظار اكتمال معرّف تدفق عمل واحد أو معرّف مخزّن في الحالة العامة. |
| `wait_for_workflows( array\|string $workflows, WaitMode $mode = WaitMode::All, ?string $result_key = null, ?string $name = null, ?int $quorum = null )` | انتظار اكتمال جميع تدفقات العمل أو بعضها أو النصاب المطلوب منها. |
| `wait_for_workflow_group( string $group_key, WaitMode $mode = WaitMode::All, ?int $quorum = null, ?string $result_key = null, ?string $name = null )` | انتظار مجموعة تدفقات عمل بدأت سابقًا باستخدام مفتاح المجموعة الداخلي. |
| `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 )` | إرسال تدفق عمل رئيسي واحد لكل عنصر في بيئة التشغيل، مع خيار وسم المجموعة التي بدأ تشغيلها بمفتاح مجموعة دائم. |
| `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 )` | اسم بديل موجّه للوكلاء لـ `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 )` | اسم بديل موجّه للوكلاء لـ `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 )` | اسم بديل موجّه للوكلاء لـ `wait_for_workflow_group()`. |
| `version( string $version )` | وسم تعريف تدفق العمل بإصدار على مستوى التطبيق لتسهيل الفحص والتصدير. |
| `idempotency_key( string $key )` | جعل إرسال تدفق العمل دائمًا باستخدام مفتاح يقدمه المستدعي. يؤدي الإرسال مجددًا بالمفتاح نفسه إلى إرجاع معرّف تدفق العمل الأصلي. |
| `max_transitions( int $max )` | إخفاق تدفق العمل إذا اكتمل أكثر من `$max` انتقالات للخطوات. |
| `max_for_each_items( int $max )` | إخفاق تدفق العمل إذا حاولت خطوة `for_each()` توسيع أكثر من `$max` عنصرًا. |
| `max_state_bytes( int $bytes )` | إخفاق تدفق العمل إذا تجاوز حجم الحالة العامة `$bytes`. |
| `max_cost_units( int $max )` | إخفاق تدفق العمل إذا استهلكت الخطوات المكتملة أكثر من `$max` وحدة تكلفة. |
| `max_started_workflows( int $max )` | إخفاق تدفق العمل قبل إرسال أكثر من `$max` من تدفقات العمل الفرعية. |
| `compensate_with( string $handler_class )` | إرفاق معالج تعويض بآخر خطوة أُضيفت. |
| `compensate_on_failure()` | تشغيل عمليات تعويض الخطوات المكتملة تلقائيًا عند إخفاق تدفق العمل. |
| `on_queue( string $queue )` | تعيين قائمة الانتظار لجميع الخطوات. |
| `with_priority( Priority $priority )` | تعيين الأولوية لجميع الخطوات. |
| `max_attempts( int $max )` | تعيين الحد الأقصى لمحاولات إعادة المحاولة لكل خطوة. |
| `on_cancel( string $handler_class )` | تسجيل صنف معالج للتنظيف عند الإلغاء. راجع [الإلغاء](https://queuety.inline0.dev/ar/docs/workflows/cancellation). |
| `prune_state_after( int $steps = 2 )` | تفعيل تشذيب الحالة تلقائيًا. يزيل مخرجات الخطوات الأقدم من الحد الزمني. راجع [تشذيب الحالة](https://queuety.inline0.dev/ar/docs/features/state-pruning). |
| `must_complete_within( int $seconds = 0, int $minutes = 0, int $hours = 0, int $days = 0 )` | تعيين موعد نهائي لتدفق العمل. تُجمع مدد التأخير كلها. راجع [المواعيد النهائية](https://queuety.inline0.dev/ar/docs/workflows/deadlines). |
| `on_deadline( string $handler_class )` | تسجيل معالج يُستدعى عند تجاوز الموعد النهائي لتدفق العمل. راجع [المواعيد النهائية](https://queuety.inline0.dev/ar/docs/workflows/deadlines). |
| `dispatch( array $initial_payload = [] )` | إرسال تدفق العمل. يُرجع معرّفه. |

### `Queuety::workflow_status( $workflow_id )`

احصل على حالة تدفق العمل. يُرجع كائنًا `WorkflowState` أو `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` أيضًا عن:

- `waiting_for`: أسماء الإشارات أو معرّفات تدفقات العمل التي تعيق التشغيل حاليًا
- `current_step_name`: الاسم المُعدّ للخطوة الحالية، إن وُجد
- `wait_mode`: وضع الانتظار الحالي (`all` أو `any` أو `quorum`) أثناء التعليق
- `wait_details`: بيانات فحص إضافية، مثل العوائق المطابقة والمتبقية
- `definition_version`: القيمة التي عيّنها `version()`، إن وُجدت
- `definition_hash`: تجزئة حتمية لتعريف تدفق العمل
- `idempotency_key`: مفتاح الإرسال الدائم، إن وُجد
- `budget`: الحدود المُعدّة والاستخدام الحالي، إذا كانت ضوابط الحماية مفعّلة
- `artifact_count`: عدد العناصر الأثرية المخزّنة لتدفق العمل
- `artifact_keys`: مفاتيح العناصر الأثرية المخزّنة لسرعة الفحص

### `Queuety::retry_workflow( $workflow_id )`

أعِد محاولة تدفق عمل فاشل بدءًا من الخطوة التي أخفقت.

```php
Queuety::retry_workflow( $workflow_id );
```

يرمي `RuntimeException` إذا كان قد تم تعويض تدفق العمل بالفعل بعد إخفاق.

### `Queuety::pause_workflow( $workflow_id )`

أوقف تدفق عمل قيد التشغيل مؤقتًا. قد يكتمل العمل المُدرج مسبقًا للخطوة الحالية، لكن لن تُدرج خطوات لاحقة حتى تستأنف تدفق العمل.

```php
Queuety::pause_workflow( $workflow_id );
```

### `Queuety::resume_workflow( $workflow_id )`

استأنف تدفق عمل متوقفًا مؤقتًا.

```php
Queuety::resume_workflow( $workflow_id );
```

### `Queuety::cancel_workflow( $workflow_id )`

ألغِ تدفق عمل وشغّل أي معالجات تنظيف مسجلة. يعيّن الحالة إلى `cancelled` ويدفن جميع المهام المعلّقة وقيد المعالجة الخاصة بتدفق العمل.

```php
Queuety::cancel_workflow( $workflow_id );
```

يرمي `RuntimeException` إذا كان تدفق العمل بالفعل `completed` أو `cancelled`. راجع [الإلغاء](https://queuety.inline0.dev/ar/docs/workflows/cancellation) للاطلاع على التفاصيل.

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

أعِد تدفق العمل إلى خطوة سابقة وأعِد تشغيله من هناك. تُستعاد الحالة من سجل الأحداث `state_after` للخطوة المحددة، وتُدرج الخطوة التالية في قائمة الانتظار.

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

يرمي `RuntimeException` إذا لم توجد حالة مسجلة للخطوة المستهدفة. يتطلب [سجل أحداث تدفق العمل](https://queuety.inline0.dev/ar/docs/workflows/event-log). راجع [السفر عبر الزمن](https://queuety.inline0.dev/ar/docs/workflows/time-travel) للاطلاع على التفاصيل.

### `Queuety::fork_workflow( $workflow_id )`

أنشئ نسخة مستقلة من تدفق عمل قيد التشغيل عند حالته الحالية. يُرجع معرّف تدفق العمل الجديد.

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

يحصل تدفق العمل المتفرّع على معرّف خاص به ويعمل بشكل مستقل عن التدفق الأصلي. راجع [التفرّع](https://queuety.inline0.dev/ar/docs/workflows/forking) للاطلاع على التفاصيل.

### `Queuety::export_workflow( $workflow_id )`

صدّر سجل التنفيذ الكامل لتدفق العمل كمصفوفة قابلة للتسلسل بصيغة JSON. تتضمن سجل تدفق العمل وجميع المهام وأحداث تدفق العمل ومدخلات السجل.

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

راجع [التصدير وإعادة التشغيل](https://queuety.inline0.dev/ar/docs/workflows/export-replay) للاطلاع على بنية JSON وحالات الاستخدام.

### `Queuety::replay_workflow( $data )`

أعِد تشغيل تدفق عمل مُصدّر في البيئة الحالية. ينشئ تدفق عمل جديدًا من بيانات التصدير ويُرجع معرّفه.

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

راجع [التصدير وإعادة التشغيل](https://queuety.inline0.dev/ar/docs/workflows/export-replay) للاطلاع على التفاصيل.

### `Queuety::replace_wp_cron()`

استبدل نظام WordPress cron المدمج بجدول المواعيد الخاص بـ Queuety. يعترض `wp_schedule_event()` و`wp_unschedule_event()` و`wp_get_scheduled_event()`، ويوجّه الأحداث المتكررة عبر العامل Queuety.

```php
Queuety::replace_wp_cron();
```

لا يعمل إلا عند تحميل WordPress. راجع [استبدال WP-Cron](https://queuety.inline0.dev/ar/docs/features/wp-cron) للاطلاع على التفاصيل.

### `Queuety::restore_wp_cron()`

استعد السلوك الافتراضي لـ WordPress cron بإزالة خطّافات الجسر Queuety cron.

```php
Queuety::restore_wp_cron();
```

راجع [استبدال WP-Cron](https://queuety.inline0.dev/ar/docs/features/wp-cron) لمعرفة القيود.

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

أرسل إشارة إلى تدفق عمل. إذا كان تدفق العمل ينتظر هذه الإشارة حاليًا، فسيُستأنف فورًا. وإلا، تُخزّن الإشارة وتُلتقط عندما يصل تدفق العمل إلى خطوة `wait_for_signal` المقابلة.

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

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

راجع [إشارات تدفق العمل](https://queuety.inline0.dev/ar/docs/workflows/signals) للاطلاع على التفاصيل.

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

غلاف دلالي حول `signal()` لتدفقات الموافقة.

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

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

غلاف دلالي حول `signal()` لتدفقات الرفض.

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

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

غلاف دلالي حول `signal()` للإدخال البشري المنظّم.

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

خزّن عنصرًا أثريًا دائمًا واحدًا لتدفق عمل.

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

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

خزّن عنصرًا أثريًا واحدًا لخطوة تدفق العمل الجاري تنفيذها.

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

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

اجلب عنصرًا أثريًا مخزّنًا واحدًا لتدفق عمل.

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

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

اعرض قائمة العناصر الأثرية لتدفق عمل.

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

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

احذف عنصرًا أثريًا واحدًا لتدفق عمل.

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

## آلات الحالات

### `Queuety::machine( $name )`

ابدأ إنشاء آلة حالات. يُرجع `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 ] );
```

### طرق `StateMachineBuilder`

| الطريقة | الوصف |
|---|---|
| `initial( string $state_name )` | تعيين الحالة الأولية صراحةً. |
| `state( string $state_name, ?StateMachineStatus $terminal_status = null )` | بدء إعداد حالة واحدة. |
| `action( string\|array $action_class )` | تسجيل إجراء دخول إلى الحالة الحالية في قائمة الانتظار. مرّر اسم صنف أو تعريفًا منظّمًا يتضمن `class` و`payload` و`config`؛ وتصل `payload` إلى `StateAction::handle()` بصفتها `$payload`. |
| `on( string $event, string $target, string\|array\|null $guard_class = null, ?string $name = null )` | تسجيل انتقال واحد لحدث من الحالة الحالية. يقبل شرط الحراسة الصيغة المنظّمة نفسها التي يقبلها `action()`. |
| `on_queue( string $queue )` | تعيين قائمة الانتظار المستخدمة لإجراءات الحالة المؤجلة. |
| `with_priority( Priority $priority )` | تعيين أولوية إجراءات الحالة المؤجلة. |
| `max_attempts( int $max_attempts )` | تعيين حد إعادة المحاولة لإجراءات الحالة المؤجلة. |
| `version( string $version )` | إرفاق إصدار على مستوى التطبيق بتعريف الآلة. |
| `idempotency_key( string $key )` | جعل الإرسال دائمًا لمفتاح يقدمه المستدعي. يؤدي الإرسال مجددًا بالمفتاح نفسه إلى إرجاع معرّف الآلة الأصلي. |
| `dispatch( array $initial_state = [] )` | إرسال الآلة وإرجاع معرّفها. |

يمكن لأصناف إجراءات دخول الحالة أيضًا توفير طريقة اختيارية `config()` بمفاتيح سياسة الموارد نفسها التي تدعمها خطوات سير العمل: `concurrency_group` و`concurrency_limit` و`cost_units`.

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

إرسال حزمة تعريف آلة حالات متسلسلة. ينبغي لمعظم تعليمات التطبيق البرمجية استخدام `machine()->dispatch()`. أُنشئت هذه الطريقة منخفضة المستوى كي تتمكن المحوّلات من بدء آلة دون الاعتماد مباشرةً على أداة الإنشاء.

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

### `Queuety::machine_status( $machine_id )`

الحصول على حالة الآلة الحالية. تُرجع كائن `StateMachineState` أو `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` أيضًا:

- `definition_version`
- `definition_hash`
- `idempotency_key`
- `error_message`
- `current_action`
- `terminal_status`

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

إرسال حدث خارجي واحد إلى آلة في حالة انتظار.

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

تكون الحمولة متاحة لشروط الانتقال، وتُدمج في حالة الآلة العامة عند قبول الحدث.

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

عرض صفوف الآلات المحفوظة لفحصها.

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

يتضمن كل صف معرّف الآلة واسمها وحالتها والحالة الراهنة وإصدار التعريف وبصمة التعريف ومفتاح منع التكرار والطوابع الزمنية لدورة الحياة.

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

الحصول على سجل الأحداث الدائم لآلة واحدة.

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

يحتوي كل صف حدث على: `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` و`created_at`.

### `Queuety::machine_trace( $machine_id )`

الحصول على حزمة تتبّع موحّدة لمصحّح آلة الحالات UI.

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

يحتوي التتبّع على `machine` و`states` مجمّعة و`events` خام و`jobs` للإجراء المرتبط و`logs` و`artifacts` و`chunks`.

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

الحصول على الحالة العامة بعد حدث تتبّع محدد للآلة، أو `null` إذا لم يُعثر عليه.

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

راجع [آلات الحالات](https://queuety.inline0.dev/ar/docs/state-machines) للاطلاع على نموذج دورة الحياة وأنماط الاستخدام.

## قوالب سير العمل

### `Queuety::define_workflow( $name )`

إنشاء أداة إنشاء سير عمل لاستخدامها قالبًا.

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

### `Queuety::register_workflow_template( $builder )`

تسجيل قالب سير عمل.

```php
Queuety::register_workflow_template( $builder );
```

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

إرسال قالب سير عمل مسجّل باسمه. يُرجع معرّف سير العمل.

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

يُطلق `RuntimeException` إذا لم يكن القالب مسجّلًا.

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

إرسال سير عمل انطلاقًا من حزمة تعريف وقت التشغيل.

ينبغي لمعظم تعليمات التطبيق البرمجية استخدام `run_workflow()` أو `workflow()->dispatch()`. أُنشئت هذه الطريقة منخفضة المستوى كي تتمكن المحوّلات القابلة لإعادة الاستخدام من إرسال تعريف سير عمل متسلسل دون الاعتماد على الطرق الداخلية لمدير سير العمل.

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

تسجيل إجراء WordPress يرسل سير عمل.

```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` أحد ما يلي:

- اسم قالب سير عمل مسجّل
- `WorkflowBuilder` مضمن

يعمل `map` و`when` و`idempotency_key` بشكل متزامن ضمن طلب WordPress الحالي. وحدها خطوات سير العمل نفسها تعمل بشكل غير متزامن بعد الإرسال.

راجع [مشغّلات الإجراءات](https://queuety.inline0.dev/ar/docs/features/action-triggers) للاطلاع على الدليل الكامل.

### `Queuety::workflow_templates()`

الحصول على سجل قوالب سير العمل.

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

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

تحميل جميع ملفات سير العمل من دليل وتسجيلها. ينبغي لكل ملف `.php` إرجاع `WorkflowBuilder`. تُرجع الطريقة عدد مسارات العمل المسجّلة.

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

### `Queuety::load_workflow_file( $file_path )`

تحميل ملف سير عمل واحد وتسجيله. تُرجع `WorkflowTemplate` أو `null` إذا لم يُرجع الملف أداة إنشاء.

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

## الجدولة

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

إنشاء جدول متكرر. تُرجع أداة إنشاء `PendingSchedule`.

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

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

### طرق `PendingSchedule`

| الطريقة | الوصف |
|---|---|
| `every( string $interval )` | تعيين تعبير فترة زمنية (e.g، `1 hour`، `30 minutes`) |
| `cron( string $expression )` | تعيين تعبير cron من 5 حقول |
| `overlap( OverlapPolicy $policy )` | تعيين سياسة التداخل (الافتراضي: `Allow`). راجع [الجدولة](https://queuety.inline0.dev/ar/docs/features/scheduling). |
| `on_queue( string $queue )` | تعيين قائمة الانتظار المستهدفة (الافتراضي: `default`) |
| `id()` | فرض الإرسال وإرجاع معرّف الجدول |

### `Queuety::scheduler()`

الحصول على مثيل `Scheduler` الداخلي.

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

## تسجيل المعالجات

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

تسجيل صنف معالج باسم.

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

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

اكتشاف أصناف المعالجات في دليل وتسجيلها تلقائيًا. تُرجع الطريقة عدد المعالجات المسجّلة.

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

### `Queuety::registry()`

الحصول على سجل المعالجات.

```php
$registry = Queuety::registry();
```

## قابلية المراقبة

### `Queuety::logger()`

الحصول على مثيل `Logger` للاستعلام عن إدخالات السجل.

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

الحصول على مثيل `Metrics`.

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

### `Queuety::webhook_notifier()`

الحصول على مثيل `WebhookNotifier`.

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

### `Queuety::rate_limiter()`

الحصول على مثيل `RateLimiter`.

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

## التخزين المؤقت

### `Queuety::cache()`

الحصول على مثيل خلفية التخزين المؤقت النشطة.

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

### `Queuety::set_cache( $cache )`

تجاوز خلفية التخزين المؤقت. استدعِ هذه الطريقة قبل `Queuety::init()` لاستخدام تنفيذ مخصص.

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

### `QUEUETY_CACHE_TTL`

مدة البقاء الافتراضية للتخزين المؤقت بالثواني (الافتراضي: `5`). عيّن هذا الثابت في `wp-config.php` لتغيير مدة البقاء الافتراضية التي تستخدمها عمليات التخزين المؤقت الداخلية.

```php
define( 'QUEUETY_CACHE_TTL', 10 );
```

راجع [التخزين المؤقت](https://queuety.inline0.dev/ar/docs/features/caching) لمعرفة التفاصيل حول الخلفيات والاكتشاف التلقائي.

## سجل أحداث آلة الحالات

### `Queuety::machine_events()`

الحصول على مثيل `StateMachineEventLog`.

```php
$log = Queuety::machine_events();
```

## سجل أحداث سير العمل

### `Queuety::workflow_events()`

الحصول على مثيل `WorkflowEventLog`.

```php
$log = Queuety::workflow_events();
```

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

الحصول على التسلسل الزمني الكامل لأحداث سير العمل. تُرجع الطريقة مصفوفة من صفوف الأحداث مرتبة حسب المعرّف.

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

يحتوي كل صف حدث على: `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` (منسوخ من `error.message`) و`duration_ms` و`created_at`.

### `Queuety::workflow_trace( $workflow_id )`

الحصول على حزمة تتبّع موحّدة لمصحّح سير العمل UI.

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

يحتوي التتبّع على `workflow` و`steps` مجمّعة و`events` خام و`jobs` و`logs` و`artifacts` و`chunks` و`signals` و`wait_dependencies`.

### `Queuety::trace_input( $input )`

تعيين مدخل على مستوى التطبيق لخطوة سير العمل الجاري تنفيذها.

### `Queuety::trace_output( $output )`

تعيين مخرج على مستوى التطبيق لخطوة سير العمل الجاري تنفيذها.

### `Queuety::trace_context( array $context )`

دمج سياق على مستوى التطبيق في خطوة سير العمل الجاري تنفيذها.

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

الحصول على الحالة العامة بعد إكمال خطوة محددة من سير العمل أو استئنافها، أو `null` إذا لم يُعثر عليها.

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

راجع [سجل أحداث سير العمل](https://queuety.inline0.dev/ar/docs/workflows/event-log) للاطلاع على حالات الاستخدام وأوامر CLI.

## المثيلات الداخلية

تُرجع هذه الطرق مثيلات داخلية لحالات الاستخدام المتقدمة.

| الطريقة | تُرجع | الوصف |
|---|---|---|
| `Queuety::queue()` | `Queue` | عمليات قائمة الانتظار (المطالبة، والتحرير، والدفن) |
| `Queuety::worker()` | `Worker` | التحكم في عملية العامل |
| `Queuety::workflow_manager()` | `Workflow` | تنسيق سير العمل |
| `Queuety::machines()` | `StateMachine` | إدارة دورة حياة آلة الحالات |
| `Queuety::connection()` | `Connection` | اتصال قاعدة البيانات |
| `Queuety::batch_manager()` | `BatchManager` | إدارة دورة حياة الدفعات (الإلغاء، والتقليم) |
| `Queuety::chunk_store()` | `ChunkStore` | حفظ الأجزاء لخطوات البث |
| `Queuety::machine_events()` | `StateMachineEventLog` | أحداث تتبّع آلة الحالات وحزم التتبّع الموحّدة |
| `Queuety::workflow_events()` | `WorkflowEventLog` | أحداث تتبّع سير العمل وحزم التتبّع الموحّدة |
| `Queuety::resource_manager()` | `ResourceManager` | ملفات قبول العامل، والميزانيات الموزونة، وفحص ذاكرة النظام |
| `Queuety::cache()` | `Cache` | مثيل خلفية التخزين المؤقت |

## الاختبار

### `Queuety::fake()`

استبدال قائمة الانتظار بمحاكاة زائفة داخل الذاكرة للاختبار. تُرجع الطريقة مثيل `QueueFake` يسجّل المهام المرسلة دون الاتصال بقاعدة البيانات. يسجّل `create_batch()` أيضًا بيانات وصفية زائفة للدفعات؛ ويُتحقق من السلاسل عبر المهام الفردية التي ترسلها.

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

### `Queuety::reset()`

إعادة ضبط كل الحالة الداخلية، بما فيها محاكاة قائمة الانتظار الزائفة. استدعِها في `tearDown()`.

```php
Queuety::reset();
```

### طرق `QueueFake`

| الطريقة | الوصف |
|---|---|
| `assert_pushed( string $class, ?Closure $callback )` | التحقق من إرسال صنف مهمة. يرشّح ردّ النداء الاختياري بيانات المهمة. |
| `assert_pushed_times( string $class, int $count )` | التحقق من إرسال المهمة N مرة بالضبط. |
| `assert_not_pushed( string $class )` | التحقق من عدم إرسال أي مهمة. |
| `assert_nothing_pushed()` | التحقق من عدم إرسال أي مهام على الإطلاق. |
| `assert_batched( ?Closure $callback )` | التحقق من إرسال دفعة. يرشّح ردّ النداء الاختياري بيانات الدفعة. |
| `pushed( string $class )` | الحصول على كل عمليات الإرسال المسجّلة لصنف. تُرجع مصفوفة. |
| `batches()` | الحصول على كل الدفعات المسجّلة. تُرجع مصفوفة. |
| `reset()` | مسح كل المهام والدفعات المسجّلة. |

راجع [الاختبار](https://queuety.inline0.dev/ar/docs/features/testing) للاطلاع على أمثلة كاملة.

## الواجهات

### `Handler`

واجهة لمعالجات المهام البسيطة.

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

يمكن أن تُرجع `config()` أيًا من `queue` و`max_attempts` و`backoff` و`rate_limit` و`concurrency_group` و`concurrency_limit` و`cost_units`.

### `Step`

واجهة لمعالجات خطوات سير العمل.

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

يمكن أن تُرجع `config()` أيًا من `max_attempts` و`backoff` و`concurrency_group` و`concurrency_limit` و`cost_units`.

### `Contracts\ForEachHandler`

واجهة لمعالجات فروع التكرار الديناميكية.

```php
namespace Queuety\Contracts;

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

يمكن أن تُرجع `config()` أيًا من `max_attempts` و`backoff` و`rate_limit` و`concurrency_group` و`concurrency_limit` و`cost_units`.

### `Contracts\ForEachReducer`

مُخفِّض اختياري لنتائج التكرار.

```php
namespace Queuety\Contracts;

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

### `Contracts\Compensation`

واجهة لمعالجات التعويض عن الخطوات.

```php
namespace Queuety\Contracts;

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

### `Contracts\RepeatCondition`

واجهة لشروط الحلقات المستخدمة بواسطة `repeat_until()` و`repeat_while()` عندما تكون مقارنة مفاتيح الحالة محدودة أكثر من اللازم.

```php
namespace Queuety\Contracts;

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

### `Contracts\StateAction`

واجهة لإجراءات دخول الحالة الموضوعة في قائمة الانتظار.

```php
namespace Queuety\Contracts;

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

يتلقى `$payload` قيمة `payload` المنظّمة من تعريف الإجراء، إذا كانت الآلة معرّفة بها. أرجِع تحديثات الحالة العامة. أدرج `_event` و`_event_payload` اختياريًا عندما ينبغي للإجراء تنفيذ انتقال فوري.

يمكن لإجراءات الحالة أيضًا تعريف طريقة اختيارية `config()`. يقرأ Queuety منها `concurrency_group` و`concurrency_limit` و`cost_units` عند وضع إجراء الدخول في قائمة الانتظار.

### `Contracts\StateGuard`

واجهة لشروط الحراسة الخاصة بانتقالات آلة الحالات.

```php
namespace Queuety\Contracts;

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

### `Contracts\Job`

واجهة لأصناف المهام القابلة للإرسال المستقلة. تخزّن أصناف المهام حمولتها كخصائص عامة ومنطق التنفيذ في `handle()`.

```php
namespace Queuety\Contracts;

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

يمكن لأصناف المهام اختياريًا تعريف طريقة `middleware()` تُرجع مصفوفة من مثيلات `Contracts\Middleware`.

### `Contracts\Cache`

واجهة لخلفيات التخزين المؤقت. راجع [التخزين المؤقت](https://queuety.inline0.dev/ar/docs/features/caching) للاطلاع على عمليات التنفيذ المضمّنة والخلفيات المخصصة.

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

| الطريقة | تُرجع | الوصف |
|---|---|---|
| `get( $key )` | `mixed` | استرجاع قيمة. تُرجع `null` إذا لم يُعثر عليها أو انتهت صلاحيتها. |
| `set( $key, $value, $ttl )` | `void` | تخزين قيمة. تعني مدة بقاء قدرها 0 عدم انتهاء الصلاحية. |
| `delete( $key )` | `void` | إزالة قيمة. |
| `has( $key )` | `bool` | التحقق من وجود مفتاح وعدم انتهاء صلاحيته. |
| `add( $key, $value, $ttl )` | `bool` | تعيين ذري إذا لم يكن المفتاح موجودًا. تُرجع `true` إذا عُيّنت القيمة. |
| `flush()` | `void` | إزالة جميع العناصر من التخزين المؤقت. |

### `WorkflowEventLog`

يسجّل انتقالات خطوات سير العمل مع سياق التتبّع الكامل. يُتاح عبر `Queuety::workflow_events()`.

| الطريقة | تُرجع | الوصف |
|---|---|---|
| `record_event( array $event )` | `void` | تسجيل حدث تتبّع خام |
| `record_step_started( ... )` | `void` | تسجيل حدث step_started مع المدخل والحالة قبل التنفيذ |
| `record_step_completed( ... )` | `void` | تسجيل حدث step_completed مع المدخل والمخرج والحالة قبل التنفيذ وبعده |
| `record_step_failed( ... )` | `void` | تسجيل حدث step_failed مع سياق التتبّع وتفاصيل الخطأ المنظّمة |
| `get_timeline( int $workflow_id, ?int $limit = 100, int $offset = 0 )` | `array` | الحصول على أحداث تتبّع سير العمل بالترتيب، مع إمكانية تقسيم النتائج إلى صفحات |
| `get_trace( int $workflow_id )` | `array` | الحصول على حزمة تتبّع موحّدة |
| `get_state_at_step( int $workflow_id, int $step_index )` | `array\|null` | الحصول على الحالة العامة بعد إكمال خطوة محددة أو استئنافها |
| `prune( int $older_than_days )` | `int` | حذف الأحداث الأقدم من عدد الأيام المحدد. تُرجع عدد الصفوف المحذوفة. |

### `StateMachineEventLog`

يسجّل دورة حياة آلة الحالات وإجراءاتها وانتقالاتها وأحداث شروط الحراسة، باستخدام حقول التتبّع نفسها لأحداث سير العمل.

| الطريقة | تُرجع | الوصف |
|---|---|---|
| `record_event( array $event )` | `void` | تسجيل حدث تتبّع خام للآلة |
| `get_timeline( int $machine_id, ?int $limit = 100, int $offset = 0 )` | `array` | الحصول على أحداث تتبّع الآلة بالترتيب، مع إمكانية تقسيم النتائج إلى صفحات |
| `get_trace( int $machine_id )` | `array` | الحصول على حزمة تتبّع موحّدة للآلة |
| `get_state_at_event( int $machine_id, int $event_id )` | `array\|null` | الحصول على الحالة العامة بعد حدث تتبّع محدد للآلة |
| `prune( int $older_than_days )` | `int` | حذف الأحداث الأقدم من عدد الأيام المحدد. تُرجع عدد الصفوف المحذوفة. |

### `Contracts\StreamingStep`

واجهة لمعالجات خطوات سير العمل التي تنتج تدفقًا من الأجزاء. يُحفظ كل عنصر مولّد في قاعدة البيانات فورًا. راجع [خطوات البث](https://queuety.inline0.dev/ar/docs/workflows/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;
}
```

| الطريقة | الوصف |
|---|---|
| `stream( $state, $existing_chunks )` | مولّد ينتج أجزاء نصية. يؤدي كل إنتاج إلى كتابة فورية في قاعدة البيانات. عند إعادة المحاولة، يحتوي `$existing_chunks` على الأجزاء المحفوظة سابقًا. |
| `on_complete( $chunks, $state )` | يُستدعى بعد انتهاء التدفق. يُرجع بيانات لدمجها في حالة سير العمل. |
| `config()` | إعداد اختياري. يدعم `max_attempts` و`backoff` و`concurrency_group` و`concurrency_limit` و`cost_units`. |

### `ChunkStore`

يدير حفظ الأجزاء لخطوات البث. يُتاح عبر `Queuety::chunk_store()`.

| الطريقة | تُرجع | الوصف |
|---|---|---|
| `get_chunks( int $job_id )` | `string[]` | جلب كل أجزاء مهمة بترتيب فهرس الجزء |
| `append_chunk( int $job_id, int $chunk_index, string $content, ?int $workflow_id, ?int $step_index )` | `void` | إلحاق جزء واحد |
| `clear_chunks( int $job_id )` | `void` | حذف كل أجزاء مهمة |
| `chunk_count( int $job_id )` | `int` | عدّ أجزاء مهمة |
| `get_accumulated( int $job_id )` | `string` | ضم كل الأجزاء في سلسلة نصية واحدة |

### `Heartbeat`

مساعد ثابت لإرسال نبضات النشاط من داخل معالجات الخطوات وخطوات البث. راجع [نبضات النشاط](https://queuety.inline0.dev/ar/docs/features/heartbeats).

| الطريقة | الوصف |
|---|---|
| `Heartbeat::init( int $job_id, Connection $conn )` | تعيين سياق المهمة. يستدعيها العامل تلقائيًا. |
| `Heartbeat::beat( array $progress = [] )` | إرسال نبضة نشاط. تحدّث `reserved_at` وتخزّن بيانات التقدّم اختياريًا في `heartbeat_data`. |
| `Heartbeat::clear()` | مسح سياق المهمة. يستدعيها العامل تلقائيًا. |
| `Heartbeat::current_job_id()` | الحصول على معرّف المهمة الحالي (للاختبار). |

### `Contracts\Middleware`

واجهة للبرمجيات الوسيطة الخاصة بالمهام. تحيط البرمجيات الوسيطة بتنفيذ المهمة ضمن مسار يشبه طبقات البصلة.

```php
namespace Queuety\Contracts;

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

## السمات

### `Dispatchable`

توفّر طرق إرسال ثابتة لأصناف المهام التي تنفّذ `Contracts\Job`. وتُمرّر وسيطات المُنشئ لإنشاء مثيل المهمة.

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

| الطريقة | تُرجع | الوصف |
|---|---|---|
| `dispatch( ...$args )` | `PendingJob` | إنشاء مثيل وإرساله |
| `dispatch_if( bool $condition, ...$args )` | `PendingJob\|null` | الإرسال فقط إذا كانت `$condition` صحيحة |
| `dispatch_unless( bool $condition, ...$args )` | `PendingJob\|null` | الإرسال فقط إذا كانت `$condition` خاطئة |
| `with_chain( array $jobs )` | `ChainBuilder` | بدء سلسلة من صنف المهمة هذا |

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

### خصائص المهمة

يمكن لأصناف المهام تعريف خصائص عامة يقرأها العامل عبر الاستبطان لتجاوز سلوك إعادة المحاولة والمهلة الزمنية.

| الخاصية | النوع | الوصف |
|---|---|---|
| `$tries` | `int` | الحد الأقصى للمحاولات قبل دفن المهمة |
| `$timeout` | `int` | الحد الأقصى لوقت التنفيذ بالثواني (يتطلب `pcntl`) |
| `$backoff` | `array` | قيم التأخير المتزايدة بالثواني لكل محاولة إعادة |

```php
class ImportProductsJob implements Job {
    use Dispatchable;

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

    // ...
}
```

### خطاف `failed()`

عندما تُدفن مهمة بعد استنفاد جميع محاولات الإعادة، يستدعي العامل طريقة `failed()` على مثيل المهمة إذا كانت معرّفة.

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

## البرمجيات الوسيطة المضمّنة

تنفّذ جميع أصناف البرمجيات الوسيطة `Contracts\Middleware`، وتقع ضمن مساحة الأسماء `Queuety\Middleware`.

| الفئة | الوصف |
|---|---|
| `RateLimited( int $max, int $window )` | فرض حد لمعدل `$max` عملية تنفيذ لكل `$window` ثانية |
| `Timeout( int $seconds )` | إنهاء المهمة بعد `$seconds` ثانية (يتطلب `pcntl`) |
| `UniqueJob( ?string $key )` | منع التنفيذ المتزامن باستخدام قفل قاعدة بيانات |
| `WithoutOverlapping( string $key, int $release_after )` | منع تداخل عمليات التنفيذ مع انتهاء صلاحية القفل تلقائيًا |
| `ThrottlesExceptions( int $max_attempts, int $decay_minutes )` | الحد من الاستثناءات لمنع تدفق المهام عند تعطل خدمة خارجية |

اطّلع على [Middleware](https://queuety.inline0.dev/ar/docs/features/middleware) لمعرفة تفاصيل الاستخدام والأمثلة.

## التعدادات

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

اطّلع على [Scheduling](https://queuety.inline0.dev/ar/docs/features/scheduling) لمعرفة تفاصيل آلية عمل كل سياسة.

## السمات

### `#[QueuetyHandler]`

سمة PHP 8 للتسجيل التلقائي. راجع [PHP Attributes](https://queuety.inline0.dev/ar/docs/features/attributes).

```php
use Queuety\Attributes\QueuetyHandler;

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

## جسر CLI

### `Queuety::cli_command()`

يعيد اسم الأمر الجذر المنشور لـ WP-CLI.

الأمر الجذر الافتراضي هو `queuety`. عرّف `QUEUETY_CLI_COMMAND` قبل بدء Queuety إذا أردت نشر الأمر تحت اسم مختلف.

### `Queuety::cli_command_map()`

يعيد فهرسًا متسلسلًا من Queuety CLI للأدوات التي تحتاج إلى معرفة سطح الأوامر المتاح دون فحص أصناف WP-CLI.

يتضمن كل إدخال:
- معرّف عملية ثابتًا
- مسار CLI نسبيًا
- صنف المعالج وطريقته في WP-CLI
- أهداف التنفيذ المحتملة
- المهايئ الذي يطبّع وسائط CLI الخام إلى خطة تنفيذ

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

يحوّل استدعاء CLI محللًا إلى خطة التنفيذ التي ينبغي للأداة تشغيلها.

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

تراعي خطط التنفيذ وسيلة النقل عمدًا:
- تُحل الأوامر إلى دوال استدعاء عامة في PHP مع وسائط مطبّعة
- يسرد الفهرس كل أهداف التنفيذ المحتملة مسبقًا، بينما يحدد `callable` و`transport` الفرع المختار للمدخل المحلل

هذا هو التنسيق المعتاد الذي تستخدمه Queuety لأدوات الوكلاء: معرّف عملية ثابت، وهدف API عام، وتطبيع يتولاه المهايئ للمسائل الخاصة بـ CLI فقط، مثل القيم الافتراضية لقوائم الانتظار، وفك ترميز حمولة JSON، والتفرع إلى مجموعة العمليات العاملة، والتعامل مع ملفات تصدير سير العمل.