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`	текущий ID песочницы
`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_CLI_COMMAND` (по умолчанию `rudel`)

`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, в виде массива: состояние bootstrap, текущая песочница, каталог песочниц и их количество, значения 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`

Удаляет таблицы песочницы, ее каталог и связанные рабочие деревья, а также запись о ней. Возвращает false, если такого ID нет. Проверка защиты не выполняется: защищенные песочницы тоже удаляются.

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

Применяет правила истечения срока, возраста и периода бездействия. Параметры: dry_run (логическое значение), 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.

Инициализация вне WordPress

`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 сбрасывает автономное подключение и кешированное состояние.