Стандарт разработки сайтов на 1С-Битрикс и WordPress

/local/
├── components/          собственные компоненты
│   └── project/
│       └── order.form/
│           ├── class.php         логика компонента
│           ├── .parameters.php   параметры
│           ├── lang/ru/          языковые фразы
│           └── templates/.default/
├── templates/           шаблоны сайта и компонентов
├── modules/             собственные модули
│   └── project.exchange/
├── php_interface/       проектные обработчики и настройки
│   ├── init.php
│   └── include/events/
├── classes/             прикладные классы (PSR-4)
│   └── Project/
└── migrations/          миграции структуры данных

use Bitrix\Main\Loader;

// Автозагрузка проектных классов: пространство имён Project\
// отображается на /local/classes/Project/ по правилам PSR-4.
Loader::registerAutoLoadClasses(null, []);

spl_autoload_register(static function (string $class): void {
    $prefix = 'Project\\';

    if (strpos($class, $prefix) !== 0) {
        return;
    }

    $relative = substr($class, strlen($prefix));
    $path     = $_SERVER['DOCUMENT_ROOT'] . '/local/classes/Project/'
        . str_replace('\\', '/', $relative) . '.php';

    if (is_readable($path)) {
        require_once $path;
    }
});

// Обработчики подключаются отдельными файлами по назначению,
// а не сваливаются в init.php одним списком.
require_once __DIR__ . '/include/events/catalog.php';
require_once __DIR__ . '/include/events/sale.php';

namespace Project\Catalog;

use Bitrix\Iblock\Elements\ElementCatalogTable;
use Bitrix\Main\Loader;
use Bitrix\Main\LoaderException;

final class ElementRepository
{
    /**
     * Активные элементы раздела: одна выборка, только нужные поля,
     * жёсткий лимит и заранее подготовленная сортировка по индексу.
     *
     * @return array<int,array<string,mixed>>
     * @throws LoaderException
     */
    public function findBySection(int $sectionId, int $limit = 50): array
    {
        Loader::includeModule('iblock');

        return ElementCatalogTable::getList([
            'select' => ['ID', 'NAME', 'CODE', 'PREVIEW_PICTURE'],
            'filter' => [
                '=IBLOCK_SECTION_ID' => $sectionId,
                '=ACTIVE'            => 'Y',
            ],
            'order'  => ['SORT' => 'ASC', 'ID' => 'DESC'],
            'limit'  => $limit,
            'cache'  => ['ttl' => 3600],
        ])->fetchAll();
    }
}

use Bitrix\Main\Engine\Contract\Controllerable;
use Bitrix\Main\Localization\Loc;

class ProjectCatalogListComponent extends CBitrixComponent implements Controllerable
{
    /**
     * Входящие параметры проверяются и приводятся к типу здесь,
     * а не в шаблоне и не в местах использования.
     */
    public function onPrepareComponentParams($params): array
    {
        $params['SECTION_ID']  = (int) ($params['SECTION_ID'] ?? 0);
        $params['COUNT']       = max(1, min(100, (int) ($params['COUNT'] ?? 20)));
        $params['CACHE_TIME']  = isset($params['CACHE_TIME']) ? (int) $params['CACHE_TIME'] : 3600;

        return $params;
    }

    public function executeComponent(): void
    {
        // Кеш зависит от всех параметров, влияющих на результат,
        // иначе разные разделы получат одинаковый вывод.
        $cacheKeys = [$this->arParams['SECTION_ID'], $this->arParams['COUNT']];

        if ($this->startResultCache($this->arParams['CACHE_TIME'], $cacheKeys)) {
            $repository = new \Project\Catalog\ElementRepository();

            $this->arResult['ITEMS'] = $repository->findBySection(
                $this->arParams['SECTION_ID'],
                $this->arParams['COUNT']
            );

            // Тегированный кеш: сбросится сам при изменении инфоблока.
            $this->includeComponentTemplate();
        }

        $this->setResultCacheKeys(['ITEMS']);
    }

    /** Действия AJAX объявляются явно и проверяют права. */
    public function configureActions(): array
    {
        return [];
    }
}

use Bitrix\Main\EventManager;
use Bitrix\Main\ModuleManager;

class project_exchange extends CModule
{
    public $MODULE_ID = 'project.exchange';

    public function DoInstall(): bool
    {
        // Зависимости проверяются до установки, а не в момент работы.
        if (!ModuleManager::isModuleInstalled('sale')) {
            $GLOBALS['APPLICATION']->ThrowException('Требуется модуль «Интернет-магазин»');

            return false;
        }

        ModuleManager::registerModule($this->MODULE_ID);

        $this->installDatabase();
        $this->installEvents();

        return true;
    }

    public function DoUninstall(): bool
    {
        // Удаление — зеркало установки: снимаем обработчики,
        // убираем таблицы, снимаем регистрацию модуля.
        $this->uninstallEvents();
        $this->uninstallDatabase();

        ModuleManager::unRegisterModule($this->MODULE_ID);

        return true;
    }

    private function installEvents(): void
    {
        EventManager::getInstance()->registerEventHandler(
            'sale',
            'OnSaleOrderSaved',
            $this->MODULE_ID,
            '\Project\Exchange\Queue',
            'onOrderSaved'
        );
    }
}

namespace Project\Catalog;

final class PriceHandler
{
    /** Защита от рекурсии: обновление элемента внутри обработчика
     *  снова вызовет это же событие. */
    private static bool $inProgress = false;

    public static function onElementUpdate(array &$fields): void
    {
        if (self::$inProgress) {
            return;
        }

        self::$inProgress = true;

        try {
            // В обработчике — только быстрая операция.
            // Тяжёлое (обмен, письма, пересчёт каталога) ставим в очередь.
            Queue::push('recalculate', ['id' => (int) $fields['ID']]);
        } catch (\Throwable $e) {
            // Ошибка фоновой задачи не должна ломать сохранение элемента.
            \Bitrix\Main\Diag\Debug::writeToFile(
                $e->getMessage(),
                'PriceHandler',
                '/local/logs/catalog.log'
            );
        } finally {
            self::$inProgress = false;
        }
    }
}

use Bitrix\Main\Application;
use Bitrix\Main\Data\Cache;

$cache      = Cache::createInstance();
$cacheTime  = 86400;
$cacheDir   = '/project/catalog-menu';

// Ключ включает всё, что влияет на результат: сайт, язык,
// группы пользователя и раздел. Иначе один посетитель увидит
// содержимое, подготовленное для другого.
$cacheKey = implode('|', [
    SITE_ID,
    LANGUAGE_ID,
    implode(',', \CUser::GetUserGroup($USER->GetID())),
    $sectionId,
]);

if ($cache->initCache($cacheTime, $cacheKey, $cacheDir)) {
    $items = $cache->getVars();
} elseif ($cache->startDataCache()) {
    $taggedCache = Application::getInstance()->getTaggedCache();
    $taggedCache->startTagCache($cacheDir);
    $taggedCache->registerTag('iblock_id_' . IBLOCK_CATALOG);

    $items = (new ElementRepository())->findBySection($sectionId);

    $taggedCache->endTagCache();
    $cache->endDataCache($items);
}

namespace Project\Exchange;

use Bitrix\Main\Config\Option;

final class Agent
{
    private const BATCH  = 200;   // порция за один запуск
    private const LOCK   = 'project_exchange_lock';
    private const EXPIRE = 900;   // «протухание» блокировки, сек

    /** Возвращает строку перезапуска — так требует планировщик агентов. */
    public static function run(): string
    {
        $self = '\Project\Exchange\Agent::run();';

        // Один процесс за раз: параллельный запуск обработал бы
        // одни и те же записи дважды.
        $lockedAt = (int) Option::get('project.exchange', self::LOCK, 0);

        if ($lockedAt > 0 && (time() - $lockedAt) < self::EXPIRE) {
            return $self;
        }

        Option::set('project.exchange', self::LOCK, (string) time());

        try {
            // Данные обрабатываются частями: ограничения времени
            // и памяти не зависят от объёма очереди.
            $processed = Queue::process(self::BATCH);
            Logger::info('Обработано записей: ' . $processed);
        } catch (\Throwable $e) {
            Logger::error($e->getMessage());
        } finally {
            Option::set('project.exchange', self::LOCK, '0');
        }

        return $self;
    }
}

use Bitrix\Main\Application;
use Bitrix\Main\Loader;

Loader::includeModule('project.exchange');

$request = Application::getInstance()->getContext()->getRequest();

// 1. Право на модуль: 'D' — доступ запрещён.
if ($APPLICATION->GetGroupRight('project.exchange') < 'W') {
    $APPLICATION->AuthForm('Доступ запрещён');
}

if ($request->isPost() && $request->getPost('action') === 'run') {
    // 2. Защита изменяющего запроса.
    if (!check_bitrix_sessid()) {
        ShowError('Сессия истекла, повторите действие');

        return;
    }

    // 3. Входящие параметры: тип, диапазон, белый список.
    $limit = min(1000, max(1, (int) $request->getPost('limit')));
    $mode  = (string) $request->getPost('mode');

    if (!in_array($mode, ['orders', 'stocks'], true)) {
        ShowError('Неизвестный режим обмена');

        return;
    }

    $count = \Project\Exchange\Queue::process($limit, $mode);

    // 4. Безопасный вывод: данные экранируются по контексту.
    echo 'Обработано: ' . htmlspecialcharsbx((string) $count);
}

use Bitrix\Main\Web\HttpClient;
use Bitrix\Main\Web\Json;

/**
 * Запрос к внешнему сервису: тайм-аут, повторы с нарастающей паузой,
 * проверка формата ответа и журнал без секретных данных.
 */
public function send(string $method, array $payload): array
{
    $client = new HttpClient([
        'socketTimeout' => 5,   // соединение
        'streamTimeout' => 20,  // чтение ответа
        'waitResponse'  => true,
    ]);
    $client->setHeader('Content-Type', 'application/json');
    $client->setHeader('Authorization', 'Bearer ' . $this->token);

    for ($attempt = 1; $attempt <= self::RETRIES; $attempt++) {
        // Ключ идемпотентности: повтор не создаст второй заказ.
        $client->setHeader('Idempotency-Key', $payload['uuid']);

        $raw    = $client->post($this->url . $method, Json::encode($payload));
        $status = $client->getStatus();

        Logger::info($method, ['status' => $status, 'attempt' => $attempt]);

        if ($status === 200) {
            $data = Json::decode((string) $raw);

            // Ответ проверяется: 200 не гарантирует ожидаемую структуру.
            if (!isset($data['result'])) {
                throw new \RuntimeException('Некорректный формат ответа');
            }

            return $data['result'];
        }

        if ($status < 500) {
            break; // ошибка запроса — повторять бессмысленно
        }

        sleep($attempt * 2);
    }

    throw new \RuntimeException('Сервис недоступен: ' . $method);
}

/**
 * Дочерняя тема: свои стили подключаются зависимостью от родительских,
 * версия берётся из filemtime — правки подхватываются без ручного
 * сброса кеша браузера.
 */
add_action('wp_enqueue_scripts', 'project_child_assets', 20);

function project_child_assets(): void
{
    $path = get_stylesheet_directory() . '/assets/css/project.css';

    if (!is_readable($path)) {
        return;
    }

    wp_enqueue_style(
        'project-child',
        get_stylesheet_directory_uri() . '/assets/css/project.css',
        ['parent-style'],
        filemtime($path)
    );
}

/**
 * Plugin Name: Project Core
 * Description: Бизнес-логика проекта: интеграции, типы данных, обмены.
 * Version:     1.4.0
 * Requires at least: 6.4
 * Requires PHP: 8.1
 * Text Domain: project-core
 */

declare(strict_types=1);

namespace Project\Core;

// Прямое обращение к файлу плагина — не точка входа.
if (!defined('ABSPATH')) {
    exit;
}

const VERSION = '1.4.0';

define('PROJECT_CORE_FILE', __FILE__);
define('PROJECT_CORE_DIR', plugin_dir_path(__FILE__));

require_once PROJECT_CORE_DIR . 'vendor/autoload.php';

// Инициализация отделена от загрузки файла: так плагин можно
// подключить в тестах, не запуская его побочные эффекты.
add_action('plugins_loaded', [Plugin::class, 'boot']);

register_activation_hook(__FILE__, [Installer::class, 'activate']);
register_deactivation_hook(__FILE__, [Installer::class, 'deactivate']);

<?xml version="1.0"?>
<ruleset name="Project Core">
    <file>./src</file>
    <file>./project-core.php</file>

    <arg name="extensions" value="php"/>
    <arg value="ps"/>

    <rule ref="WordPress">
        <!-- Пространство имён вместо префикса функций -->
        <exclude name="WordPress.NamingConventions.PrefixAllGlobals"/>
    </rule>

    <rule ref="WordPress.WP.I18n">
        <properties>
            <property name="text_domain" type="array" value="project-core"/>
        </properties>
    </rule>

    <config name="minimum_wp_version" value="6.4"/>
    <config name="testVersion" value="8.1-"/>
</ruleset>

composer require --dev wp-coding-standards/wpcs dealerdirect/phpcodesniffer-composer-installer

# Отчёт по нарушениям стандарта
vendor/bin/phpcs

# Автоисправление того, что исправляется механически
vendor/bin/phpcbf

global $wpdb;

$table = $wpdb->prefix . 'project_orders';

// Прямой запрос оправдан: агрегация по миллиону строк через
// WP_Query потребовала бы выборки всех записей в память.
// Значения подставляются только через prepare().
$rows = $wpdb->get_results(
    $wpdb->prepare(
        "SELECT status, COUNT(*) AS cnt, SUM(total) AS amount
         FROM {$table}
         WHERE created_at BETWEEN %s AND %s
         GROUP BY status
         LIMIT %d",
        $from,
        $to,
        100
    ),
    ARRAY_A
);

if ($wpdb->last_error !== '') {
    throw new \RuntimeException('Ошибка выборки: ' . $wpdb->last_error);
}

/** Форма: nonce кладётся в разметку рядом с полями. */
function project_render_box(WP_Post $post): void
{
    wp_nonce_field('project_save_' . $post->ID, 'project_nonce');

    $value = get_post_meta($post->ID, '_project_code', true);

    printf(
        '<input type="text" name="project_code" value="%s" class="widefat">',
        esc_attr($value)
    );
}

/** Обработчик: пять проверок до единственной операции записи. */
add_action('save_post_product', 'project_save_box', 10, 2);

function project_save_box(int $post_id, WP_Post $post): void
{
    // Автосохранение и ревизии — не пользовательское действие.
    if (defined('DOING_AUTOSAVE') && DOING_AUTOSAVE) {
        return;
    }

    // Подлинность запроса…
    $nonce = isset($_POST['project_nonce']) ? sanitize_key($_POST['project_nonce']) : '';

    if (!wp_verify_nonce($nonce, 'project_save_' . $post_id)) {
        return;
    }

    // …и отдельно — право на этот конкретный объект.
    if (!current_user_can('edit_post', $post_id)) {
        return;
    }

    $code = isset($_POST['project_code']) ? sanitize_text_field(wp_unslash($_POST['project_code'])) : '';

    if ($code !== '' && !preg_match('/^[A-Z]{2}-\d{4,8}$/', $code)) {
        return; // формат не соответствует ожидаемому
    }

    update_post_meta($post_id, '_project_code', $code);
}

add_action('wp_enqueue_scripts', 'project_assets');

function project_assets(): void
{
    // Условие загрузки: калькулятор нужен только на странице услуги.
    if (!is_singular('service')) {
        return;
    }

    $file = PROJECT_CORE_DIR . 'assets/js/calculator.js';

    wp_enqueue_script(
        'project-calculator',                                  // идентификатор
        plugins_url('assets/js/calculator.js', PROJECT_CORE_FILE),
        [],                                                    // зависимости
        filemtime($file),                                      // версия
        ['in_footer' => true, 'strategy' => 'defer']           // место и стратегия
    );

    // Данные для JS передаются контролируемо: только то, что можно
    // показать посетителю. Ключи и внутренние идентификаторы — нельзя.
    wp_add_inline_script(
        'project-calculator',
        'window.projectCalc = ' . wp_json_encode([
            'ajaxUrl'  => admin_url('admin-ajax.php'),
            'nonce'    => wp_create_nonce('project_calc'),
            'currency' => '₽',
        ]) . ';',
        'before'
    );
}

/**
 * Курсы валют: внешний запрос выполняется не чаще раза в час
 * и никогда — синхронно на каждой странице.
 */
function project_get_rates(): array
{
    $cached = get_transient('project_rates');

    if (is_array($cached)) {
        return $cached;
    }

    $response = wp_remote_get('https://api.example.com/rates', [
        'timeout'     => 5,     // ограничение времени ожидания
        'redirection' => 2,
        'user-agent'  => 'project-core/1.4',
    ]);

    if (is_wp_error($response) || wp_remote_retrieve_response_code($response) !== 200) {
        // Сервис недоступен — короткий кеш, чтобы не долбить его
        // на каждом хите, и работа по последним известным данным.
        set_transient('project_rates', [], 5 * MINUTE_IN_SECONDS);

        return [];
    }

    $rates = json_decode(wp_remote_retrieve_body($response), true);
    $rates = is_array($rates) ? $rates : [];

    set_transient('project_rates', $rates, HOUR_IN_SECONDS);

    return $rates;
}

# 1. Отключаем запуск планировщика на хитах посетителей:
#    define('DISABLE_WP_CRON', true);  — в wp-config.php

# 2. Дёргаем планировщик системным cron каждые 5 минут
*/5 * * * * curl -s "https://example.com/wp-cron.php?doing_wp_cron" > /dev/null

# Альтернатива для тяжёлых задач — WP-CLI без HTTP-слоя
*/5 * * * * cd /var/www/example.com && wp cron event run --due-now --quiet

/**
 * Зависимость проверяется до использования, а не в момент падения.
 * Отсутствие WooCommerce отключает часть плагина, а не весь сайт.
 */
add_action('plugins_loaded', 'project_boot_woocommerce', 20);

function project_boot_woocommerce(): void
{
    if (!class_exists('WooCommerce')) {
        add_action('admin_notices', 'project_notice_missing_wc');

        return;
    }

    if (version_compare(WC_VERSION, '8.0', '<')) {
        add_action('admin_notices', 'project_notice_old_wc');

        return;
    }

    (new \Project\Core\Shop\Sync())->register();
}