В коде CMS: Как правильно типизировать параметры плагинов (public ?string $plugins_settings) и настройки капчи в 2026 году?

Типизация параметров плагинов и настроек капчи в CMS — один из ключевых аспектов написания надёжного, поддерживаемого кода. В 2026 году стандарты PHP 8.3+ и современные CMS-фреймворки предлагают несколько подходов, которые стоит учитывать.

## Nullable-типы и union-типы для параметров плагинов

Конструкция `public ?string $plugins_settings` означает, что свойство может содержать строку или `null`. Это корректный подход, однако в 2026 году рекомендуется более точная типизация:

php
// Устаревший подход
public ?string $plugins_settings;

// Современный подход с union-типами
public string|null $plugins_settings = null;

// Если настройки — структурированные данные
public array|null $plugins_settings = null;

Для сложных конфигураций плагинов предпочтительнее использовать Value Objects или DTO:

php
final readonly class PluginSettings
{
public function __construct(
public string $name,
public bool $enabled = true,
public array $options = []
) {}
}

public ?PluginSettings $plugins_settings = null;

## Типизация настроек капчи

Настройки капчи (reCAPTCHA, hCaptcha, Turnstile) обычно содержат ключи, пороговые значения и флаги. Правильная типизация:

php
final readonly class CaptchaConfig
{
public function __construct(
public string $provider, // ‘recaptcha’ | ‘hcaptcha’ | ‘turnstile’
public string $siteKey,
public string $secretKey,
public float $threshold = 0.5,
public bool $enabled = true,
public ?string $version = null // ‘v2’ | ‘v3’
) {}
}

## Использование Enums вместо строк

В PHP 8.1+ и далее рекомендуется заменять строковые константы на перечисления:

php
enum CaptchaProvider: string
{
case ReCaptcha = ‘recaptcha’;
case HCaptcha = ‘hcaptcha’;
case Turnstile = ‘turnstile’;
}

public CaptchaProvider $provider = CaptchaProvider::ReCaptcha;

## Валидация через атрибуты

В 2026 году широко применяются PHP-атрибуты для валидации:

php
use SymfonyComponentValidatorConstraints as Assert;

class PluginConfiguration
{
#[AssertNotBlank]
#[AssertLength(min: 2, max: 100)]
public string $pluginName;

#[AssertRange(min: 0.0, max: 1.0)]
public float $captchaThreshold = 0.5;
}

## Общие рекомендации

1. **Избегайте `mixed`** — используйте конкретные типы или union-типы.
2. **Предпочитайте `readonly`-свойства** для конфигурационных объектов.
3. **Используйте строгую типизацию** (`declare(strict_types=1)`) в каждом файле.
4. **Документируйте через PHPDoc** там, где нативная типизация недостаточна.
5. **Сериализация/десериализация** настроек из БД или JSON должна проходить через типизированные DTO с валидацией.

Следование этим принципам обеспечивает совместимость с современными IDE, статическими анализаторами (PHPStan, Psalm) и упрощает поддержку CMS-кода в долгосрочной перспективе.