Feature Arrays

🗃️ Массивы (Arr)

← Возможности · Главная · Сравнение

CloudCastle\Support\Arr — статические утилиты для массивов: точечная нотация доступа, выборка полей, уплощение вложенных структур. Функциональный аналог Illuminate\Support\Arr с прицелом на производительность (точечный get в ~2× быстрее illuminate).

Принцип работы

«Точечная» нотация ('a.b.c') навигирует по вложенным массивам без исключений: при отсутствии сегмента возвращается значение по умолчанию (fail-safe). Уплощение (dot) и обратная сборка (undot) обратимы. Все методы, изменяющие массив по ссылке (set/forget), также возвращают его для fluent-стиля.

use CloudCastle\Support\Arr;

$config = ['app' => ['db' => ['host' => 'localhost', 'port' => 5432]]];

// Точечный доступ (fail-safe)
Arr::get($config, 'app.db.host');       // 'localhost'
Arr::get($config, 'app.db.pass', '—');  // '—'  (нет ключа → default)
Arr::has($config, 'app.db.port');       // true
Arr::set($config, 'app.db.ssl', true);  // добавит app.db.ssl
Arr::forget($config, 'app.db.port');    // удалит по точечному ключу

// Выборка
Arr::only(['a' => 1, 'b' => 2, 'c' => 3], ['a', 'c']); // ['a' => 1, 'c' => 3]
Arr::pluck([['id' => 1], ['id' => 2]], 'id');          // [1, 2]

// Уплощение / сборка
Arr::dot(['a' => ['b' => 1]]);          // ['a.b' => 1]
Arr::undot(['a.b' => 1]);               // ['a' => ['b' => 1]]
Arr::flatten([1, [2, [3]]]);            // [1, 2, 3]
Arr::collapse([[1, 2], [3, 4]]);        // [1, 2, 3, 4]

Плюсы

• Fail-safe доступ: отсутствующий путь возвращает default, а не бросает исключение и не «протекает» соседними ключами.
• Точечный get заметно быстрее аналога illuminate.
• dot/undot обратимы — удобно для плоских конфигов и диффов.
• Строгая типизация (Psalm level 1): корректная работа со смешанными значениями.

Минусы

• Работа с копиями/ссылками массивов (не ленивые коллекции) — для цепочек трансформаций и ленивых потоков используйте cloudcastle/collection (отдельный пакет).

✅ Рекомендуется

• Читать конфиги точечным ключом с дефолтом: Arr::get($cfg, 'mail.host', '127.0.0.1').
• Приводить вложенный конфиг к плоскому для сравнения/логирования: Arr::dot($cfg).

❌ Антипаттерны

• Ручная навигация $cfg['a']['b']['c'] с риском Undefined key — используйте Arr::get.
• Хранить ПД в плоских логах после Arr::dot без маскирования значений.

Схема точечного доступа

flowchart TD
    K["ключ 'a.b.c'"] --> S{"строка с точкой?"}
    S -->|нет| DIR["прямой доступ / default"]
    S -->|да| SEG["разбить на сегменты"]
    SEG --> LOOP{"следующий сегмент есть в массиве?"}
    LOOP -->|нет| DEF["вернуть default (fail-safe)"]
    LOOP -->|да| NEXT["спуститься глубже"]
    NEXT --> LOOP
    LOOP -->|сегменты кончились| VAL["вернуть значение"]

Loading

Сравнение с аналогами

Возможность	Support	illuminate	symfony	nette	voku	doctrine	🏆 Победитель
Точечный get/set/has/forget	✅	✅	❌	⚠️	❌	❌	Support, illuminate
Выборка only/except/pluck	✅	✅	❌	⚠️	❌	❌	Support, illuminate
flatten/collapse/dot/undot	✅	✅	❌	⚠️	❌	❌	Support, illuminate
Скорость точечного get	✅	⚠️	—	⚠️	—	—	Support