API

Переглянути як Markdown Редагувати на GitHub Документація для 7a44bd6

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. Якщо викликати їх після Rudel::init() поза межами WordPress, вони спричинять RuntimeException. Див. Автономне використання.

Контекст виконання

Ці методи описують поточний запит. Поза пісочницею вони повертають 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`

Завантажує одну пісочницю за ID або повертає null.

PHP

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

`Rudel::environments_dir(): string`

Повертає каталог, у якому зберігаються каталоги пісочниць.

Життєвий цикл

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

Створює пісочницю та повертає її. ID формується з назви та чотирьох шістнадцяткових символів.

PHP

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

Параметри:

Ключ	Значення
`theme`	ідентифікатор теми для копіювання в пісочницю; типово — активна тема хоста
`clone_from`	ID наявної пісочниці, яку потрібно клонувати замість хоста
`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.

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

Видаляє таблиці пісочниці, її каталог і пов’язані робочі дерева та запис. Якщо такого ID немає, повертає false. Перевірка захисту не виконується: захищені пісочниці також буде видалено.

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

Застосовує політику завершення строку дії, віку й бездіяльності. Параметри: dry_run (bool), max_age_days і max_idle_days (перевизначають rudel_config, якщо значення не дорівнює нулю). Повертає removed, skipped, errors і reasons (ID зі значенням expired, age, idle або protected). Див. Очищення.

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

Перелічує метадані знімків, починаючи з найновіших. Див. розділ Знімки стану.

Шаблони

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

Збережені шаблони — це лише копії файлів. Жоден API чи команда не створює з них пісочницю. Див. розділ Шаблони.

Git

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

Фіксує зміни та надсилає вміст робочої копії з каталогу пісочниці до гілки rudel/{id}. Типово для $remote_url і $subdir використовуються значення пісочниці. Повертає SHA коміту або null, якщо змін немає.

Автоматизація

Rudel::run_automation(): array запускає заплановані завдання автоматизації.
Rudel::run_scheduled_cleanup(): array робить те саме.

Див. розділ Автоматизація.

Хуки та каталог команд

Rudel::hooks(): array повертає задокументований каталог хуків, упорядкований за назвами хуків. Див. розділ Хуки.
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 очищує автономне з’єднання та кешований стан.