PHP: полный мануал с примерами, функциями и ООП

<?php
declare(strict_types=1);

function portalLine(string $portal, array $deal): string
{
    return '[' . $portal . '] ' . $deal['TITLE'];
}

class PortalReport
{
    private string $portal;

    public function __construct(string $portal)
    {
        $this->portal = $portal;
    }

    public function line(array $deal): string
    {
        return portalLine($this->portal, $deal);
    }
}

$deal = ['TITLE' => 'Учебная поставка'];
echo portalLine('north', $deal), "\n";

$report = new PortalReport('north');
echo $report->line($deal), "\n";

[north] Учебная поставка
[north] Учебная поставка

Две строки совпали: способ организации не изменил отчёт. Вызов функции передал north прямо сейчас; конструктор объекта запомнил north для следующих line. Сам алгоритм строки остаётся одним — portalLine. Здесь доверенный массив с одним известным полем, а не проверка произвольного ответа CRM; её добавят следующие самостоятельные примеры.

<?php
declare(strict_types=1);

function validatePortalSettings(array $settings): array
{
    $portal = $settings['portal'] ?? null;
    $timeout = $settings['timeoutSeconds'] ?? null;
    if (!is_string($portal) || !in_array($portal, ['north', 'south'], true)) {
        throw new InvalidArgumentException('Неизвестный учебный портал');
    }
    if (!is_int($timeout) || $timeout < 1 || $timeout > 10) {
        throw new InvalidArgumentException('Таймаут от 1 до 10 секунд');
    }
    return ['portal' => $portal, 'timeoutSeconds' => $timeout];
}

function decodeDeals(string $json): array
{
    if (strlen($json) > 10000) {
        throw new LengthException('Учебный ответ слишком большой');
    }
    $response = json_decode($json, true, 16, JSON_THROW_ON_ERROR);
    $rows = is_array($response) ? ($response['result'] ?? null) : null;
    if (!is_array($rows) || !array_is_list($rows)) {
        throw new UnexpectedValueException('Ожидался список result');
    }
    foreach ($rows as $row) {
        if (!is_array($row) || !is_string($row['ID'] ?? null) || !is_string($row['TITLE'] ?? null)) {
            throw new UnexpectedValueException('Некорректная учебная сделка');
        }
    }
    return $rows;
}

// Внутренний общий алгоритм получает уже проверенные настройки.
function requestList(array $settings, string $method, array $parameters, callable $transport): array
{
    if ($method !== 'crm.deal.list') {
        throw new InvalidArgumentException('Метод не разрешён в этом учебном клиенте');
    }
    $json = $transport($settings['portal'], $method, $parameters, $settings['timeoutSeconds']);
    return decodeDeals($json);
}

// Небольшие фикстуры вместо сети. Контракт ответов намеренно ограничен.
$fixtures = [
    'north' => '{"result":[{"ID":"N-101","TITLE":"Учебная поставка"}]}',
    'south' => '{"result":[{"ID":"S-201","TITLE":"Учебная подписка"}]}',
];
$transport = static function (string $portal, string $method, array $parameters, int $timeoutSeconds) use ($fixtures): string {
    if (!isset($fixtures[$portal])) {
        throw new RuntimeException('Для портала нет фикстуры');
    }
    return $fixtures[$portal];
};


// В копии обработчика для south забыли изменить имя портала.
function copiedSouthList(callable $transport): array
{
    return decodeDeals($transport('north', 'crm.deal.list', [], 2));
}
echo 'Копия для south вернула: ', copiedSouthList($transport)[0]['ID'], "\n";

// Исправление не требует класса: настройки стали явным аргументом.
function listMethod(array $settings, array $parameters, string $method, callable $transport): array
{
    return requestList(validatePortalSettings($settings), $method, $parameters, $transport);
}

$north = ['portal' => 'north', 'timeoutSeconds' => 2];
$south = ['portal' => 'south', 'timeoutSeconds' => 5];
$northDeals = listMethod($north, [], 'crm.deal.list', $transport);
$southDeals = listMethod($south, [], 'crm.deal.list', $transport);
echo 'Функция north: ', $northDeals[0]['ID'], ' — ', $northDeals[0]['TITLE'], "\n";
echo 'Функция south: ', $southDeals[0]['ID'], ' — ', $southDeals[0]['TITLE'], "\n";

try {
    listMethod(['portal' => 'north', 'timeoutSeconds' => 0], [], 'crm.deal.list', $transport);
} catch (InvalidArgumentException $error) {
    echo "Неверная настройка отклонена\n";
}

Копия для south вернула: N-101
Функция north: N-101 — Учебная поставка
Функция south: S-201 — Учебная подписка
Неверная настройка отклонена

Получены обычные PHP-массивы со сделками. Ошибка была в зашитой настройке скопированного обработчика; общая функция её устраняет без ООП. В примере нет реального B24-запроса: transport возвращает маленький локальный JSON и не реализует фильтры, пагинацию или таймаут. Его сигнатура показывает, что понадобится настоящему адаптеру. Это учебная оболочка, а не официальный SDK.

<?php
declare(strict_types=1);

function validatePortalSettings(array $settings): array
{
    $portal = $settings['portal'] ?? null;
    $timeout = $settings['timeoutSeconds'] ?? null;
    if (!is_string($portal) || !in_array($portal, ['north', 'south'], true)) {
        throw new InvalidArgumentException('Неизвестный учебный портал');
    }
    if (!is_int($timeout) || $timeout < 1 || $timeout > 10) {
        throw new InvalidArgumentException('Таймаут от 1 до 10 секунд');
    }
    return ['portal' => $portal, 'timeoutSeconds' => $timeout];
}

function decodeDeals(string $json): array
{
    if (strlen($json) > 10000) {
        throw new LengthException('Учебный ответ слишком большой');
    }
    $response = json_decode($json, true, 16, JSON_THROW_ON_ERROR);
    $rows = is_array($response) ? ($response['result'] ?? null) : null;
    if (!is_array($rows) || !array_is_list($rows)) {
        throw new UnexpectedValueException('Ожидался список result');
    }
    foreach ($rows as $row) {
        if (!is_array($row) || !is_string($row['ID'] ?? null) || !is_string($row['TITLE'] ?? null)) {
            throw new UnexpectedValueException('Некорректная учебная сделка');
        }
    }
    return $rows;
}

// Внутренний общий алгоритм получает уже проверенные настройки.
function requestList(array $settings, string $method, array $parameters, callable $transport): array
{
    if ($method !== 'crm.deal.list') {
        throw new InvalidArgumentException('Метод не разрешён в этом учебном клиенте');
    }
    $json = $transport($settings['portal'], $method, $parameters, $settings['timeoutSeconds']);
    return decodeDeals($json);
}

// Небольшие фикстуры вместо сети. Контракт ответов намеренно ограничен.
$fixtures = [
    'north' => '{"result":[{"ID":"N-101","TITLE":"Учебная поставка"}]}',
    'south' => '{"result":[{"ID":"S-201","TITLE":"Учебная подписка"}]}',
];
$transport = static function (string $portal, string $method, array $parameters, int $timeoutSeconds) use ($fixtures): string {
    if (!isset($fixtures[$portal])) {
        throw new RuntimeException('Для портала нет фикстуры');
    }
    return $fixtures[$portal];
};


class B24
{
    private array $settings;
    private Closure $transport;

    public function __construct(array $settings, callable $transport)
    {
        $this->settings = validatePortalSettings($settings);
        $this->transport = Closure::fromCallable($transport);
    }

    public function listMethod(array $parameters, string $method): array
    {
        return requestList($this->settings, $method, $parameters, $this->transport);
    }
}

$northSettings = ['portal' => 'north', 'timeoutSeconds' => 2];
$north = new B24($northSettings, $transport);
$south = new B24(['portal' => 'south', 'timeoutSeconds' => 5], $transport);

$northDeals = $north->listMethod([], 'crm.deal.list');
$southDeals = $south->listMethod([], 'crm.deal.list');
echo 'Клиент north: ', $northDeals[0]['ID'], ' — ', $northDeals[0]['TITLE'], "\n";
echo 'Клиент south: ', $southDeals[0]['ID'], ' — ', $southDeals[0]['TITLE'], "\n";

$northSettings['portal'] = 'south';
echo 'После изменения внешнего массива: ', $north->listMethod([], 'crm.deal.list')[0]['ID'], "\n";
try {
    new B24(['portal' => 'north', 'timeoutSeconds' => 0], $transport);
} catch (InvalidArgumentException $error) {
    echo "Неверный клиент не создан\n";
}

Клиент north: N-101 — Учебная поставка
Клиент south: S-201 — Учебная подписка
После изменения внешнего массива: N-101
Неверный клиент не создан

Оба объекта вызывают тот же requestList, что процедурная версия. Отличается место хранения проверенных настроек: каждый клиент сохраняет свой небольшой массив и транспорт. Изменение внешнего массива не перенастраивает уже созданный объект. Время ожидания лишь передаётся фиктивному транспорту; реальное соблюдение таймаута нужно отдельно реализовать и проверить в HTTP-адаптере.

<?php
declare(strict_types=1);

function buildReport(array $rows, callable $formatRow): string
{
    if (count($rows) > 100) {
        throw new LengthException('Учебный отчёт ограничен ста строками');
    }
    $lines = [];
    foreach ($rows as $row) {
        if (!is_array($row) || !is_string($row['ID'] ?? null) || !is_string($row['TITLE'] ?? null)) {
            throw new UnexpectedValueException('Нужны ID и TITLE');
        }
        $line = $formatRow($row);
        if (!is_string($line)) {
            throw new UnexpectedValueException('Форматтер должен вернуть строку');
        }
        $lines[] = $line;
    }
    return implode(' | ', $lines);
}

abstract class AbstractDealReport
{
    final public function build(array $rows): string
    {
        return buildReport($rows, fn (array $row): string => $this->formatRow($row));
    }

    abstract protected function formatRow(array $row): string;
}

class DealIdReport extends AbstractDealReport
{
    protected function formatRow(array $row): string
    {
        return $row['ID'];
    }
}

class DealTitleReport extends AbstractDealReport
{
    protected function formatRow(array $row): string
    {
        return $row['TITLE'];
    }
}

$rows = [
    ['ID' => 'N-101', 'TITLE' => 'Поставка'],
    ['ID' => 'N-102', 'TITLE' => 'Подписка'],
];
echo 'Callback: ', buildReport($rows, static fn (array $row): string => $row['TITLE']), "\n";
echo 'Отчёт ID: ', (new DealIdReport())->build($rows), "\n";
echo 'Отчёт TITLE: ', (new DealTitleReport())->build($rows), "\n";
try {
    (new DealTitleReport())->build([['ID' => 'N-103']]);
} catch (UnexpectedValueException $error) {
    echo "Общая проверка обнаружила отсутствующий TITLE\n";
}

Callback: Поставка | Подписка
Отчёт ID: N-101 | N-102
Отчёт TITLE: Поставка | Подписка
Общая проверка обнаружила отсутствующий TITLE

Обход и проверка строк находятся только в buildReport и используются обоими подходами. Наследники меняют одну конкретную операцию formatRow; общую обработку не копируют. Процедурный callback даёт такой же результат и часто проще для разового отчёта. Здесь создаётся обычный текст; перед помещением результата в HTML его экранируют для выбранного контекста.

{
    "autoload": {
        "psr-4": {"Demo\\": "src/"},
        "files": ["src/Integration/functions.php"]
    }
}

Это фрагмент конфигурации отдельного проекта, а не PHP-код. После подготовки файлов выполните composer dump-autoload из корня проекта. Сеть для собственных правил автозагрузки не нужна; установка Composer и зависимости проекта рассматриваются в отдельной главе.

<?php
declare(strict_types=1);

use Demo\Integration\B24;

require dirname(__DIR__) . '/vendor/autoload.php';

// $portalSettings и $transport подготовлены доверенной сборкой приложения.
$b24 = new B24($portalSettings, $transport);
$deals = $b24->listMethod([], 'crm.deal.list');

Это схема точки входа, а не самостоятельный файл: нужны разнесённые по namespace классы/функции, сгенерированный vendor/autoload.php и явно подготовленные настройки с транспортом. Без них фрагмент не следует запускать как готовую интеграцию.