Vtiful\Kernel\Excel — Klasse · PHP-Referenz

Signatur

class Excel

Beschreibung

Vtiful\Kernel\Excel ist die zentrale Klasse der PECL-Extension php-xlswriter. Sie ermöglicht das hochperformante Erzeugen und Lesen von XLSX-Dateien direkt in PHP, ohne externe Bibliotheken wie PhpSpreadsheet zu benötigen. Die Klasse ist in C implementiert und daher deutlich schneller als reine PHP-Lösungen, insbesondere bei großen Datenmengen.

Mit Excel lassen sich Arbeitsmappen anlegen, Tabellenblätter hinzufügen, einzelne Zellen oder ganze Datensätze schreiben, Formate (über Vtiful\Kernel\Format) zuweisen, Bilder einfügen sowie Daten wieder einlesen. Die Klasse arbeitet intern mit einer temporären Datei und gibt den Pfad der fertigen XLSX-Datei zurück.

Typische Einsatzgebiete sind Datenexporte (z. B. aus Datenbanken), Berichte und Downloads in Webanwendungen. Durch den Streaming-Ansatz kann auch mit Millionen von Zeilen gearbeitet werden, ohne den PHP-Speicher zu sprengen.

Voraussetzung: PECL-Extension xlswriter muss installiert und in der php.ini aktiviert sein.
Namespace: Vtiful\Kernel
XLSX-only: Nur das .xlsx-Format (Office Open XML) wird unterstützt, kein .xls oder .csv.

Parameter

Name	Typ	Default	Beschreibung
$config Pflicht	array		Konfigurationsarray für die Instanz. Pflichtschlüssel ist `path` (string) — das Verzeichnis, in das die XLSX-Datei geschrieben wird. Beispiel: `['path' => '/tmp/']`.

Rückgabewert

Typ

Beispiele

Einfache XLSX-Datei erstellen und befüllen

<?php
use Vtiful\Kernel\Excel;

$config = ['path' => '/tmp/'];
$excel  = new Excel($config);

// Neue Datei anlegen, erstes Sheet 'Umsätze' öffnen
$filePath = $excel->fileName('umsaetze.xlsx', 'Umsätze')
    ->header(['Artikel', 'Menge', 'Preis'])
    ->data([
        ['Schreibtisch', 3, 299.90],
        ['Stuhl',        5,  89.00],
        ['Monitor',      2, 349.00],
    ])
    ->output();

echo 'Datei gespeichert unter: ' . $filePath;

Datei gespeichert unter: /tmp/umsaetze.xlsx

Einzelne Zellen mit Format beschreiben und Datei zum Download senden

<?php
use Vtiful\Kernel\Excel;
use Vtiful\Kernel\Format;

$config = ['path' => '/tmp/'];
$excel  = new Excel($config);

$fileObject = $excel->fileName('bericht.xlsx', 'Bericht');

// Format für Überschrift erzeugen
$format = new Format($fileObject->getHandle());
$boldFormat = $format->bold()->toResource();

$filePath = $fileObject
    ->setCellValue('A1', 'Monatsbericht', $boldFormat)
    ->setCellValue('A2', 'Januar')
    ->setCellValue('B2', 42000)
    ->setCellValue('A3', 'Februar')
    ->setCellValue('B3', 38500)
    ->output();

// Datei als Download ausliefern
header('Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet');
header('Content-Disposition: attachment; filename="bericht.xlsx"');
header('Content-Length: ' . filesize($filePath));
readfile($filePath);
unlink($filePath); // Temporäre Datei aufräumen

Bestehende XLSX-Datei einlesen

<?php
use Vtiful\Kernel\Excel;

$config = ['path' => '/tmp/'];
$excel  = new Excel($config);

// Datei öffnen und alle Zeilen des ersten Sheets lesen
$data = $excel->openFile('umsaetze.xlsx')
              ->openSheet('Umsätze')
              ->getSheetData();

foreach ($data as $row) {
    echo implode(' | ', $row) . PHP_EOL;
}

Artikel | Menge | Preis Schreibtisch | 3 | 299.9 Stuhl | 5 | 89 Monitor | 2 | 349

// Wichtig · Fallstricke

Wichtige Methoden im Überblick:

fileName(string $fileName, string $sheetName = 'Sheet1'): static — Legt den Dateinamen und das erste Sheet fest.
addSheet(string $sheetName): static — Fügt ein weiteres Tabellenblatt hinzu.
header(array $header): static — Schreibt eine Kopfzeile.
data(array $data): static — Schreibt mehrzeilige Daten (Array of Arrays).
setCellValue(string $cell, mixed $value, ?resource $format = null): static — Setzt den Wert einer einzelnen Zelle.
output(): string — Schließt die Datei und gibt den absoluten Pfad zurück.
openFile(string $fileName): static — Öffnet eine vorhandene XLSX-Datei zum Lesen.
openSheet(string $sheetName): static — Wählt ein Sheet zum Lesen aus.
getSheetData(): array — Liest alle Zeilen des aktiven Sheets.
getHandle(): resource — Gibt das interne libxlsxwriter-Handle zurück (wird für Format benötigt).

Speicherverwaltung: Nach dem Download oder der Verarbeitung sollte die temporäre Datei mit unlink() gelöscht werden, da output() die Datei nur schreibt, aber nicht bereinigt.

Threadinghinweis: Die Extension ist nicht thread-safe (nicht ZTS-kompatibel). In PHP-FPM-Umgebungen ist sie problemlos einsetzbar.

Siehe auch

Vtiful\Kernel\Format Vtiful\Kernel\Chart