Работа с Excel-файлами в Wepps Platform: класс Excel для импорта и экспорта данных

Введение

Класс Excel предоставляет удобный интерфейс для работы с Excel-файлами (формат XLSX) в платформе Wepps. Основан на библиотеке PhpOffice\PhpSpreadsheet и позволяет создавать форматированные Excel-файлы из массивов данных, а также читать данные из существующих файлов с поддержкой многолистовых документов.

Зачем использовать Excel?

Проблемы, которые решает класс Excel

1. Экспорт данных - выгрузка списков товаров, заказов, пользователей в удобном формате
2. Импорт данных - загрузка массовых данных из внешних источников
3. Отчетность - формирование отчетов с автоматической отправкой по почте
4. Обмен данными - стандартизированный формат для обмена с другими системами

Когда использовать

• Выгрузка данных из списков админ-панели
• Генерация отчетов для пользователей
• Массовый импорт товаров/контента
• Отправка прайс-листов по почте
• Создание документов для печати

Расположение класса

packages/
  WeppsExtensions/
    Addons/
      Docs/
        Excel/
          Excel.php

Основные методы

Создание Excel-файлов - метод create()

Метод принимает массив ассоциативных массивов и создает форматированный Excel-файл. Ключи первого элемента массива используются как заголовки таблицы.

use WeppsExtensions\Addons\Docs\Excel\Excel;

$excel = new Excel($_GET);

$data = [
    ['Id' => 1, 'Name' => 'Товар 1', 'Price' => '1000', 'Quantity' => '10'],
    ['Id' => 2, 'Name' => 'Товар 2', 'Price' => '2000', 'Quantity' => '5'],
    ['Id' => 3, 'Name' => 'Товар 3', 'Price' => '1500', 'Quantity' => '8']
];

// Сохранить в файл
$excel->create($data, 'files/export/products.xlsx');

// Получить содержимое для отправки по почте
$content = $excel->create($data);

Параметры метода:

• array $data - массив ассоциативных массивов (ключи первого элемента станут заголовками)
• string $filename - путь для сохранения файла (опционально)

Возвращаемое значение:

• Если $filename указан - файл сохраняется на диск, возвращается null
• Если $filename пустой - возвращается бинарное содержимое файла

Особенности форматирования:

• Заголовки выделены жирным шрифтом
• Цвет заголовков: #0080C0 (синий)
• Фон заголовков: #f1f1f1 (светло-серый)
• Автоматическая ширина колонок: 12 единиц
• Все значения сохраняются как текст (тип 's')

Чтение Excel-файлов - метод read()

Метод загружает Excel-файл и возвращает структурированные данные со списком всех листов и содержимым выбранного листа.

use WeppsExtensions\Addons\Docs\Excel\Excel;

$excel = new Excel($_GET);

// Прочитать первый лист (по умолчанию)
$result = $excel->read('files/import/products.xlsx');

// Прочитать второй лист
$result = $excel->read('files/import/products.xlsx', 1);

Параметры метода:

• string $filename - путь к Excel-файлу
• int $sheetIndex - индекс листа для чтения (по умолчанию 0)

Возвращаемое значение:

[
    'sheets' => ['Товары', 'Заказы', 'Клиенты'],  // Названия всех листов
    'data' => [                                      // Данные из выбранного листа
        ['ID', 'Название', 'Цена'],                 // Заголовки
        ['1', 'Товар 1', '1000'],                   // Строка 1
        ['2', 'Товар 2', '2000']                    // Строка 2
    ]
]

Обработка ошибок:

• Выбрасывает исключение, если файл не найден
• Выбрасывает исключение, если указанный лист не существует
• Содержит валидацию индекса листа

Практические примеры

Пример 1: Экспорт списка товаров

namespace WeppsExtensions\Products;

use WeppsCore\Extension;
use WeppsCore\Connect;
use WeppsExtensions\Addons\Docs\Excel\Excel;

class Products extends Extension
{
    public function exportToExcel()
    {
        // Получаем список товаров из БД с русскими названиями колонок
        $products = Connect::$instance->fetch(
            "SELECT Id as 'ID', Name as 'Наименование', Price as 'Цена', Quantity as 'Остаток' 
             FROM Products WHERE IsHidden = 0"
        );

        // Массив уже в правильном формате (ассоциативные массивы)
        // Ключи первой строки станут заголовками: ID, Наименование, Цена, Остаток
        $data = $products;

        // Создаем Excel-файл
        $excel = new Excel($this->get);
        $content = $excel->create($data);

        // Отправляем файл пользователю
        header('Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
        header('Content-Disposition: attachment;filename="products_' . date('Y-m-d') . '.xlsx"');
        header('Cache-Control: max-age=0');

        echo $content;
        exit;
    }
}

Пример 2: Импорт товаров из Excel

namespace WeppsExtensions\Products;

use WeppsCore\Extension;
use WeppsExtensions\Addons\Docs\Excel\Excel;

class Products extends Extension
{
    public function importFromExcel()
    {
        if (!isset($_FILES['excel_file'])) {
            return ['status' => 400, 'message' => 'Файл не загружен'];
        }

        $tmpFile = $_FILES['excel_file']['tmp_name'];

        try {
            $excel = new Excel($this->get);
            $result = $excel->read($tmpFile);

            // Показываем пользователю доступные листы
            $sheets = $result['sheets'];
            $data = $result['data'];

            // Пропускаем заголовки (первая строка)
            array_shift($data);

            // Импортируем данные
            $imported = 0;

            foreach ($data as $row) {
                if (empty($row[0])) continue; // Пропускаем пустые строки

                Connect::$instance->query(
                    "INSERT INTO Products (Name, Price, Quantity) 
                     VALUES (?, ?, ?) 
                     ON DUPLICATE KEY UPDATE Price = ?, Quantity = ?",
                    [
                        $row[1], // Name
                        $row[2], // Price
                        $row[3], // Quantity
                        $row[2], // Price для UPDATE
                        $row[3]  // Quantity для UPDATE
                    ]
                );

                $imported++;
            }

            return [
                'status' => 200,
                'message' => "Импортировано товаров: {$imported}",
                'sheets' => $sheets
            ];

        } catch (\Exception $e) {
            return [
                'status' => 500,
                'message' => 'Ошибка импорта: ' . $e->getMessage()
            ];
        }
    }
}

Пример 3: Отправка отчета по почте

namespace WeppsExtensions\Reports;

use WeppsCore\Extension;
use WeppsCore\Connect;
use WeppsExtensions\Addons\Docs\Excel\Excel;
use WeppsExtensions\Addons\Mail\Mail;

class Reports extends Extension
{
    public function sendMonthlyReport()
    {
        // Формируем данные отчета с русскими названиями колонок
        $stats = Connect::$instance->fetch(
            "SELECT DATE(OrderDate) as 'Дата', 
                    COUNT(*) as 'Заказов', 
                    SUM(Total) as 'Выручка' 
             FROM Orders 
             WHERE MONTH(OrderDate) = MONTH(CURRENT_DATE())
             GROUP BY DATE(OrderDate)"
        );

        // Создаем Excel-файл
        $excel = new Excel($this->get);
        $excelContent = $excel->create($stats);

        // Добавляем Excel как вложение к письму
        $mail = new Mail('html');
        $mail->setAttachInput([
            [
                'content' => $excelContent,
                'title' => 'report_' . date('Y-m') . '.xlsx'
            ]
        ]);

        // Отправляем письмо (метод mail() возвращает результат)
        return $mail->mail(
            'manager@example.com',
            'Ежемесячный отчет за ' . date('F Y'),
            'Отчет по заказам за текущий месяц во вложении.'
        );
    }
}

Пример 4: Работа с многолистовыми документами

namespace WeppsExtensions\Analytics;

use WeppsCore\Extension;
use WeppsExtensions\Addons\Docs\Excel\Excel;

class Analytics extends Extension
{
    public function analyzeMultiSheetFile()
    {
        $excel = new Excel($this->get);
        $filePath = 'files/import/full_report.xlsx';

        // Читаем первый лист
        $result = $excel->read($filePath, 0);

        echo "Доступные листы:\n";
        foreach ($result['sheets'] as $index => $sheetName) {
            echo "[$index] $sheetName\n";
        }

        echo "\nДанные из листа '{$result['sheets'][0]}':\n";
        print_r($result['data']);

        // Обрабатываем каждый лист
        $allData = [];
        foreach ($result['sheets'] as $index => $sheetName) {
            $sheetResult = $excel->read($filePath, $index);
            $allData[$sheetName] = $sheetResult['data'];
        }

        return $allData;
    }
}

Интеграция с другими компонентами

Экспорт из списков админ-панели

namespace WeppsAdmin\Lists;

use WeppsExtensions\Addons\Docs\Excel\Excel;

class Lists
{
    public function exportList($tableName)
    {
        // Получаем данные списка
        $data = $this->getListData($tableName);

        // Конвертируем в формат для Excel
        $excelData = [];
        if (!empty($data)) {
            // Первая строка - заголовки
            $excelData[] = array_keys($data[0]);

            // Остальные строки - данные
            foreach ($data as $row) {
                $excelData[] = array_values($row);
            }
        }

        // Создаем файл
        $excel = new Excel($_GET);
        $content = $excel->create($excelData);

        // Отправляем клиенту
        header('Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
        header('Content-Disposition: attachment;filename="' . $tableName . '_' . date('Y-m-d') . '.xlsx"');
        echo $content;
        exit;
    }
}

AJAX-запрос на экспорт

// В шаблоне списка
document.getElementById('exportBtn').addEventListener('click', function() {
    const tableName = 'Products';

    // Формируем URL для скачивания
    const url = `/?weppsurl=admin/lists/export&table=${tableName}`;

    // Скачиваем файл
    window.location.href = url;
});

Технические детали

Зависимости

Класс использует библиотеку PhpOffice\PhpSpreadsheet, которая установлена через Composer:

{
    "require": {
        "phpoffice/phpspreadsheet": "^1.0"
    }
}

Поддерживаемые форматы

• Чтение: XLSX, XLS, ODS, CSV
• Запись: XLSX (Office 2007+)

Производительность

Рекомендации:

• Для файлов > 10 000 строк используйте пакетную обработку
• При экспорте больших данных увеличьте memory_limit в PHP
• Для импорта используйте транзакции БД

// Пример оптимизированного импорта с транзакциями
$db = Connect::$db;
$db->beginTransaction();

try {
    foreach ($data as $row) {
        // Импорт данных
        Connect::$instance->query(
            "INSERT INTO Products (Name, Price) VALUES (?, ?)",
            [$row[1], $row[2]]
        );
    }
    $db->commit();
} catch (\Exception $e) {
    $db->rollBack();
    throw $e;
}

Кодировка

Класс автоматически работает с UTF-8. Все данные сохраняются и читаются с правильной кодировкой.

Обработка ошибок

try {
    $excel = new Excel($this->get);
    $result = $excel->read('files/import/data.xlsx');

} catch (\Exception $e) {
    // Обработка ошибок
    if (strpos($e->getMessage(), 'не найден') !== false) {
        return ['status' => 404, 'message' => 'Файл не найден'];
    }

    if (strpos($e->getMessage(), 'не существует') !== false) {
        return ['status' => 400, 'message' => 'Неверный номер листа'];
    }

    return ['status' => 500, 'message' => 'Ошибка чтения файла: ' . $e->getMessage()];
}

Заключение

Класс Excel предоставляет простой и мощный инструмент для работы с Excel-файлами в платформе Wepps. Основные преимущества:

✅ Простой API для создания и чтения файлов
✅ Автоматическое форматирование экспортируемых данных
✅ Поддержка многолистовых документов
✅ Возможность отправки файлов по почте
✅ Обработка ошибок и валидация

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