# API

`Rudel\Rudel` واجهة ثابتة. كل طريقة في هذه الصفحة هي طريقة عامة ثابتة في ذلك الصنف.

```php
use Rudel\Rudel;

if ( Rudel::is_sandbox() ) {
    error_log( 'Running in sandbox ' . Rudel::id() );
}
```

تتطلب طرق دورة الحياة التي تستنسخ الجداول أو تحذفها (`create()`، `create_from_git()`، `destroy()`، `cleanup()`، `cleanup_merged()`) طلب WordPress نشطًا مع `$wpdb`. وتُصدر `RuntimeException` إذا استُدعيت بعد `Rudel::init()` خارج WordPress. راجع [الاستخدام المستقل](https://rudel.inline0.dev/ar/docs/features/standalone-use).

## سياق وقت التشغيل

تصف هذه الطرق الطلب الحالي. وخارج بيئة العزل، تُرجع `false` أو `null`.

| الطريقة | القيمة المُعادة |
|--------|---------|
| `is_sandbox(): bool` | `true` عندما يعمل الطلب الحالي داخل بيئة عزل |
| `id(): ?string` | معرّف بيئة العزل الحالية |
| `path(): ?string` | دليل بيئة العزل الحالية |
| `engine(): ?string` | `overlay` داخل بيئة عزل |
| `table_prefix(): ?string` | بادئة جداول بيئة العزل، مثل `wp_b65338d_` |
| `url(): ?string` | URL الخاصة ببيئة العزل؛ وتتشارك بيئات العزل المتراكبة URL المضيف |
| `exit_url(): string` | URL المضيف |
| `is_email_disabled(): bool` | `true` عند حظر البريد الصادر للطلب |
| `log_path(): ?string` | `{sandbox directory}/debug.log` |
| `version(): ?string` | إصدار Rudel المثبّت |
| `cli_command(): string` | أمر WP-CLI الأساسي، `rudel` ما لم يُحدّد `RUDEL_CLI_COMMAND` |

### `Rudel::context(): array`

تُرجع كل ما سبق في مصفوفة واحدة:

```php
[
    'is_sandbox'     => true,
    'id'             => 'alpha-3be7',
    'path'           => '/var/www/html/wp-content/rudel-environments/alpha-3be7',
    'engine'         => 'overlay',
    'table_prefix'   => 'wp_b65338d_',
    'url'            => 'http://localhost/',
    'exit_url'       => 'http://localhost/',
    'email_disabled' => true,
    'log_path'       => '/var/www/html/wp-content/rudel-environments/alpha-3be7/debug.log',
    'version'        => '0.10.0',
    'cli_command'    => 'rudel',
]
```

### `Rudel::status(): array`

تُرجع ملخص وقت التشغيل نفسه الذي تُرجعه `wp rudel status` في مصفوفة: حالة التهيئة، وبيئة العزل الحالية، ودليل بيئات العزل وعددها، وقيم `rudel_config`، وما إذا كانت الأتمتة مجدولة.

## سجلات بيئات العزل

تُرجع بيئات العزل ككائنات `Rudel\Environment`. تشمل الخصائص المفيدة للقراءة فقط `id` و`name` و`path` و`created_at` و`status` و`template` و`owner` و`labels` و`purpose` و`expires_at` و`last_used_at` و`theme_slug` و`table_prefix` و`clone_source`. وتشمل الطرق `is_protected()` و`get_url()` و`get_table_prefix()` و`get_size()` و`to_array()`.

### `Rudel::all(): array`

تُرجع كل بيئات العزل كمصفوفة من كائنات `Environment`. ولا تقبل أي عوامل تصفية.

```php
foreach ( Rudel::all() as $sandbox ) {
    echo $sandbox->id . ' ' . $sandbox->status . "\n";
}
```

### `Rudel::get( string $id ): ?Environment`

تُحمّل بيئة عزل واحدة حسب المعرّف، أو تُرجع `null`.

```php
$sandbox = Rudel::get( 'alpha-3be7' );
```

### `Rudel::environments_dir(): string`

تُرجع الدليل الذي يحتوي على أدلة بيئات العزل.

## دورة الحياة

### `Rudel::create( string $name, array $options = [] ): Environment`

تنشئ بيئة عزل وتُرجعها. يُنشأ المعرّف من الاسم متبوعًا بأربعة أحرف سداسية عشرية.

```php
$sandbox = Rudel::create( 'alpha', [
    'theme'    => 'twentytwentyfour',
    'owner'    => 'dennis',
    'labels'   => [ 'qa', 'agent' ],
    'ttl_days' => 7,
] );
```

الخيارات:

| المفتاح | المعنى |
|-----|---------|
| `theme` | معرّف القالب المراد نسخه إلى بيئة العزل؛ والافتراضي هو القالب النشط للمضيف |
| `clone_from` | معرّف بيئة عزل موجودة لاستنساخها بدلًا من المضيف |
| `owner`، `purpose` | بيانات وصفية نصية حرة |
| `labels` | مصفوفة أو سلسلة مفصولة بفواصل |
| `protected` | `true` لاستبعاد بيئة العزل من التنظيف |
| `ttl_days` | مدة انتهاء الصلاحية من وقت الإنشاء |
| `expires_at` | طابع زمني صريح لانتهاء الصلاحية |
| `template` | تسمية مخزنة في السجل؛ ولا تحمّل قالبًا محفوظًا |
| `site_options` | أسماء الخيارات والقيم المفردة المكتوبة في جدول خيارات بيئة العزل |
| `skip_limits` | `true` لتجاوز `max_sandboxes` و`max_disk_mb` |

### `Rudel::create_from_git( string $remote_url, array $options = [] ): array`

تنشئ بيئة عزل، ثم تستنسخ `$remote_url` فيها. تقبل خيارات `create()` إضافة إلى `name` (الافتراضي هو اسم المستودع) و`type` (`theme` أو `plugin`). تُرجع `[ 'environment' => Environment, 'git' => [...] ]`. لا يؤدي فشل الاستنساخ إلى التراجع عن إنشاء بيئة العزل؛ ويُعاد الخطأ في `git.error`. راجع [Git](https://rudel.inline0.dev/ar/docs/features/git).

### `Rudel::update( string $id, array $changes ): Environment`

تحدّث البيانات الوصفية لدورة الحياة وتُرجع سجل بيئة العزل المحدّث. تشمل المفاتيح المقبولة `owner` و`labels` و`purpose` و`protected` و`ttl_days` (من الآن) و`expires_at` و`clear_expiry` و`name` و`site_options`.

```php
Rudel::update( 'alpha-3be7', [ 'protected' => true, 'ttl_days' => 3 ] );
```

### `Rudel::destroy( string $id ): bool`

تحذف جداول بيئة العزل، وتزيل دليلها وأشجار العمل المرتبطة بها، وتحذف سجلها. تُرجع `false` إذا لم يكن المعرّف موجودًا. لا تتحقق من الحماية؛ إذ تُدمّر بيئات العزل المحمية أيضًا.

### `Rudel::cleanup( array $options = [] ): array`

تطبّق سياسة انتهاء الصلاحية والعمر والخمول. الخيارات: `dry_run` (قيمة منطقية) و`max_age_days` و`max_idle_days` (تتجاوز `rudel_config` عندما لا تساوي صفرًا). تُرجع `removed` و`skipped` و`errors` و`reasons` (المعرّف إلى `expired` أو `age` أو `idle` أو `protected`). راجع [التنظيف](https://rudel.inline0.dev/ar/docs/features/cleanup).

### `Rudel::cleanup_merged( array $options = [] ): array`

تزيل بيئات العزل التي دُمجت فروع أشجار عمل Git المرتبطة بها في الفرع الافتراضي للمستودع. الخيار: `dry_run`.

### `Rudel::touch_current_environment(): void`

تسجّل النشاط (`last_used_at`) لبيئة العزل الحالية. تستدعي Rudel هذه الطريقة في كل طلب لبيئة عزل.

## السجلات

### `Rudel::read_log( string $id, int $lines = 50 ): array`

تُرجع الأسطر الأخيرة من `debug.log` الخاص ببيئة العزل كـ `path` و`exists` و`empty` و`total_lines` و`lines`.

### `Rudel::clear_log( string $id ): array`

تُفرغ `debug.log` الخاص ببيئة العزل وتُرجع `path` و`existed` و`cleared`.

## اللقطات

### `Rudel::snapshot( string $id, string $name ): array`

تنشئ لقطة وتُرجع بياناتها الوصفية (`name` و`created_at` و`sandbox_id`).

### `Rudel::restore( string $id, string $name ): void`

تستعيد لقطة. عند استخدام إعداد `auto_snapshot_before_restore` الافتراضي، تحفظ Rudel لقطة `pre-restore-...` أولًا.

### `Rudel::snapshots( string $id ): array`

تعرض بيانات اللقطات الوصفية، بدءًا بالأحدث. راجع [اللقطات](https://rudel.inline0.dev/ar/docs/features/snapshots).

## القوالب

- `Rudel::save_template( string $id, string $name, string $description = '' ): array`
- `Rudel::templates(): array`
- `Rudel::delete_template( string $name ): bool`

القوالب المحفوظة نسخ للملفات فقط. لا تُنشئ API ولا أي أمر بيئة عزل من قالب. راجع [القوالب](https://rudel.inline0.dev/ar/docs/features/templates).

## Git

### `Rudel::push( string $id, string $remote_url = '', string $message = 'Update from Rudel', string $subdir = '' ): ?string`

تُجري commit وpush لنسخة عمل داخل دليل بيئة العزل إلى الفرع `rudel/{id}`. تستخدم `$remote_url` و`$subdir` القيم المخزنة في بيئة العزل افتراضيًا. تُرجع SHA للالتزام، أو `null` عند عدم وجود تغييرات.

## الأتمتة

- `Rudel::run_automation(): array` يشغّل مهام الأتمتة المجدولة الآن.
- `Rudel::run_scheduled_cleanup(): array` يفعل الشيء نفسه.

راجع [الأتمتة](https://rudel.inline0.dev/ar/docs/features/automation).

## الخطافات وفهرس الأوامر

- `Rudel::hooks(): array` يُرجع فهرس الخطافات الموثّق، مرتبًا حسب اسم الخطاف. راجع [الخطافات](https://rudel.inline0.dev/ar/docs/features/hooks).
- `Rudel::cli_command_map(): array` يُرجع وصفًا قابلًا للتسلسل لكل أمر `wp rudel` والطريقة PHP التي تقف وراءه.
- `Rudel::resolve_cli_command( $path, array $args = [], array $assoc_args = [] ): array` يحوّل أمرًا محللًا إلى خطة تنفيذ من دون تشغيله.

```php
$plan = Rudel::resolve_cli_command( 'wp rudel destroy', [ 'alpha-3be7' ] );
// $plan['callable']           => 'Rudel\Rudel::destroy'
// $plan['arguments']          => [ 'alpha-3be7' ]
// $plan['needs_confirmation'] => true
```

تستخدم معظم الخطط وسيلة النقل `php`. يُحل `logs --follow` إلى خطة `shell` تعمل `tail -f`.

## التهيئة المستقلة

### `Rudel::init( Connection $connection, array $context = [] ): void`

توجّه الواجهة إلى اتصال MySQL مباشر لاستخدامها خارج WordPress. تقبل `$context` `environments_dir`.

```php
use Rudel\Connection;
use Rudel\Rudel;

Rudel::init(
    new Connection( '127.0.0.1', 'wordpress', 'root', 'root', 'wp_' ),
    [ 'environments_dir' => '/var/www/html/wp-content/rudel-environments' ]
);
```

- `Rudel::ensure_schema(): void` ينشئ جداول Rudel للاتصال النشط.
- `Rudel::reset(): void` يمسح الاتصال المستقل والحالة المخزنة مؤقتًا.