Spatie пакеты для PHP: полное руководство с примерами

Что это за библиотека и зачем нужна

Spatie — это не одна библиотека, а целая экосистема высококачественных PHP-пакетов, разрабатываемая одноименной бельгийской компанией. Spatie известна своим подходом к созданию чистого, тестируемого и хорошо документированного кода. Их пакеты охватывают широкий спектр задач: от работы с медиа-файлами и кэшированием запросов до управления ролями и разрешениями.

Коллекция утилит Spatie (spatie/collection-utilities) — это набор вспомогательных функций и классов, которые расширяют стандартные возможности массивов и коллекций в PHP. Она предоставляет удобные методы для фильтрации, сортировки, трансформации и анализа данных, делая код более читаемым и лаконичным.

Зачем это нужно? В современной PHP-разработке (особенно в фреймворках вроде Laravel) работа с коллекциями данных — повседневная задача. Spatie Collection Utilities избавляет от необходимости писать однотипные циклы и условия, предлагая готовые, хорошо протестированные решения. Это ускоряет разработку, уменьшает количество ошибок и повышает поддерживаемость кода.

Установка

Установка пакетов Spatie производится через Composer — стандартный менеджер зависимостей для PHP.

composer require spatie/collection-utilities

Если вы используете Laravel, пакет автоматически регистрируется благодаря автозагрузке Composer. Для других фреймворков или чистого PHP, просто добавьте require 'vendor/autoload.php'; в ваш скрипт.

Быстрый старт с примером кода

После установки вы можете сразу начать использовать утилиты. Основной класс, с которым вы будете работать — Spatie\CollectionUtilities\Collection. Он расширяет стандартный класс Illuminate\Support\Collection (из Laravel) или может использоваться как самостоятельный класс.

<?php
require 'vendor/autoload.php';

use Spatie\CollectionUtilities\Collection;

// Создаем коллекцию
$collection = new Collection([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

// Используем метод filter для получения четных чисел
$evenNumbers = $collection->filter(fn($item) => $item % 2 === 0);

// Используем метод map для умножения каждого элемента на 2
$doubled = $evenNumbers->map(fn($item) => $item * 2);

// Используем метод toArray для преобразования обратно в массив
print_r($doubled->toArray());
// Вывод: Array ( [0] => 4 [1] => 8 [2] => 12 [3] => 16 [4] => 20 )
?>

Этот простой пример демонстрирует цепочку методов, которая является ключевой особенностью работы с коллекциями Spatie.

Основные методы/функции

1. filter()

Что делает: Фильтрует коллекцию, используя callback-функцию. Возвращает только те элементы, для которых callback вернул true.

Параметры:

• callback (callable): Функция, которая получает текущий элемент и его ключ. Должна вернуть true или false.
• mode (int): Необязательный. Режим фильтрации (по умолчанию ARRAY_FILTER_USE_BOTH).

Рабочий пример кода:

$users = new Collection([
    ['name' => 'Alice', 'age' => 25],
    ['name' => 'Bob', 'age' => 17],
    ['name' => 'Charlie', 'age' => 30],
]);

$adults = $users->filter(fn($user) => $user['age'] >= 18);
// Результат: Collection с Alice и Charlie

2. map()

Что делает: Применяет callback-функцию к каждому элементу коллекции и возвращает новую коллекцию с преобразованными элементами.

Параметры:

• callback (callable): Функция, которая получает текущий элемент и его ключ. Должна вернуть преобразованное значение.

Рабочий пример кода:

$prices = new Collection([100, 200, 300]);
$withTax = $prices->map(fn($price) => $price * 1.2);
// Результат: Collection [120, 240, 360]

3. reduce()

Что делает: Итеративно сводит коллекцию к одному значению, используя callback-функцию. Идеально подходит для суммирования, конкатенации и других агрегатных операций.

Параметры:

• callback (callable): Функция, которая получает "аккумулятор" и текущий элемент. Должна вернуть новое значение аккумулятора.
• initial (mixed): Начальное значение аккумулятора.

Рабочий пример кода:

$numbers = new Collection([1, 2, 3, 4, 5]);
$sum = $numbers->reduce(fn($carry, $item) => $carry + $item, 0);
// Результат: 15

4. sortBy()

Что делает: Сортирует коллекцию по указанному ключу или callback-функции. Возвращает новую отсортированную коллекцию.

Параметры:

• callback (callable|string): Имя ключа для сортировки или функция, возвращающая значение для сравнения.
• options (int): Флаги сортировки (по умолчанию SORT_REGULAR).
• descending (bool): Сортировать по убыванию (true) или возрастанию (false).

Рабочий пример кода:

$products = new Collection([
    ['name' => 'Laptop', 'price' => 1500],
    ['name' => 'Mouse', 'price' => 25],
    ['name' => 'Monitor', 'price' => 300],
]);

$sortedByPrice = $products->sortBy('price');
// Результат: Mouse (25), Monitor (300), Laptop (1500)

5. groupBy()

Что делает: Группирует элементы коллекции по указанному ключу или callback-функции. Возвращает коллекцию коллекций.

Параметры:

• groupBy (callable|string): Ключ для группировки или функция, возвращающая значение группы.
• preserveKeys (bool): Сохранять ли исходные ключи внутри групп.

Рабочий пример кода:

$employees = new Collection([
    ['name' => 'Alice', 'department' => 'IT'],
    ['name' => 'Bob', 'department' => 'HR'],
    ['name' => 'Charlie', 'department' => 'IT'],
]);

$byDepartment = $employees->groupBy('department');
// Результат: ['IT' => [Alice, Charlie], 'HR' => [Bob]]

6. first()

Что делает: Возвращает первый элемент коллекции, удовлетворяющий условию. Если условие не указано — возвращает просто первый элемент.

Параметры:

• callback (callable|null): Необязательная функция-условие.
• default (mixed): Значение, возвращаемое, если ни один элемент не найден.

Рабочий пример кода:

$numbers = new Collection([5, 10, 15, 20]);
$firstEven = $numbers->first(fn($item) => $item % 2 === 0);
// Результат: 10

$firstElement = $numbers->first();
// Результат: 5

7. pluck()

Что делает: Извлекает значения указанного ключа из всех элементов коллекции. Возвращает новую коллекцию с этими значениями.

Параметры:

• value (string): Имя ключа, значения которого нужно извлечь.
• key (string|null): Необязательный. Имя ключа, который будет использоваться в качестве ключей в результирующей коллекции.

Рабочий пример кода:

$users = new Collection([
    ['id' => 1, 'name' => 'Alice'],
    ['id' => 2, 'name' => 'Bob'],
]);

$names = $users->pluck('name');
// Результат: Collection ['Alice', 'Bob']

$namesById = $users->pluck('name', 'id');
// Результат: Collection [1 => 'Alice', 2 => 'Bob']

8. chunk()

Что делает: Разбивает коллекцию на несколько меньших коллекций заданного размера. Полезно для пакетной обработки данных.

Параметры:

• size (int): Размер каждого "куска" (кроме последнего, который может быть меньше).

Рабочий пример кода:

$items = new Collection([1, 2, 3, 4, 5, 6, 7]);
$chunks = $items->chunk(3);
// Результат: Collection из трех коллекций: [1,2,3], [4,5,6], [7]

9. unique()

Что делает: Возвращает коллекцию, содержащую только уникальные элементы. Может работать с callback для определения уникальности.

Параметры:

• key (string|null): Имя ключа, по которому проверяется уникальность.
• strict (bool): Строгое сравнение (===) или нет (==).

Рабочий пример кода:

$duplicates = new Collection([1, 2, 2, 3, 3, 3, 4]);
$unique = $duplicates->unique();
// Результат: Collection [1, 2, 3, 4]

10. each()

Что делает: Итерирует по коллекции, передавая каждый элемент в callback. Используется для побочных эффектов (например, логирование, отправка email). Возвращает исходную коллекцию.

Параметры:

• callback (callable): Функция, получающая текущий элемент и его ключ.

Рабочий пример кода:

$logs = new Collection(['error1', 'error2', 'warning1']);
$logs->each(function($log) {
    echo "Processing: " . $log . "\n";
    // Здесь может быть запись в файл или базу данных
});
// Вывод:
// Processing: error1
// Processing: error2
// Processing: warning1

Реальный практический пример использования

Представьте, что вы разрабатываете интернет-магазин и вам нужно сформировать отчет по заказам за месяц. Давайте используем Spatie Collection Utilities для обработки данных.

<?php
require 'vendor/autoload.php';

use Spatie\CollectionUtilities\Collection;

// Данные