This guide will help you install Spout and teach you how to use it.

Requirements

  • PHP version 7.2 or higher
  • PHP extension ext-zip enabled
  • PHP extension ext-xmlreader enabled

Installation

Spout can be installed directly from Composer.

Run the following command:

$ composer require box/spout

Manual installation

If you can’t use Composer, no worries! You can still install Spout manually.

Before starting, make sure your system meets the requirements.

  1. Download the source code from the Releases page
  2. Extract the downloaded content into your project.
  3. Add this code to the top controller (e.g. index.php) or wherever it may be more appropriate:
// don't forget to change the path!
require_once '[PATH/TO]/src/Spout/Autoloader/autoload.php';

Basic usage

Reader

Regardless of the file type, the interface to read a file is always the same:


use Box\Spout\Reader\Common\Creator\ReaderEntityFactory;

$reader = ReaderEntityFactory::createReaderFromFile('/path/to/file.ext');

$reader->open($filePath);

foreach ($reader->getSheetIterator() as $sheet) {
    foreach ($sheet->getRowIterator() as $row) {
        // do stuff with the row
        $cells = $row->getCells();
        ...
    }
}

$reader->close();

If there are multiple sheets in the file, the reader will read all of them sequentially.

Note that Spout guesses the reader type based on the file extension. If the extension is not standard (.csv, .ods, .xlsx - lower/uppercase), a specific reader can be created directly:

use Box\Spout\Reader\Common\Creator\ReaderEntityFactory;

$reader = ReaderEntityFactory::createXLSXReader();
// $reader = ReaderEntityFactory::createODSReader();
// $reader = ReaderEntityFactory::createCSVReader();

Writer

As with the reader, there is one common interface to write data to a file:

use Box\Spout\Writer\Common\Creator\WriterEntityFactory;
use Box\Spout\Common\Entity\Row;

$writer = WriterEntityFactory::createXLSXWriter();
// $writer = WriterEntityFactory::createODSWriter();
// $writer = WriterEntityFactory::createCSVWriter();

$writer->openToFile($filePath); // write data to a file or to a PHP stream
//$writer->openToBrowser($fileName); // stream data directly to the browser

$cells = [
    WriterEntityFactory::createCell('Carl'),
    WriterEntityFactory::createCell('is'),
    WriterEntityFactory::createCell('great!'),
];

/** add a row at a time */
$singleRow = WriterEntityFactory::createRow($cells);
$writer->addRow($singleRow);

/** add multiple rows at a time */
$multipleRows = [
    WriterEntityFactory::createRow($cells),
    WriterEntityFactory::createRow($cells),
];
$writer->addRows($multipleRows); 

/** Shortcut: add a row from an array of values */
$values = ['Carl', 'is', 'great!'];
$rowFromValues = WriterEntityFactory::createRowFromArray($values);
$writer->addRow($rowFromValues);

$writer->close();

Similar to the reader, if the file extension of the file to be written is not standard, specific writers can be created this way:

use Box\Spout\Writer\Common\Creator\WriterEntityFactory;
use Box\Spout\Common\Entity\Row;

$writer = WriterEntityFactory::createXLSXWriter();
// $writer = WriterEntityFactory::createODSWriter();
// $writer = WriterEntityFactory::createCSVWriter();

For XLSX and ODS files, the number of rows per sheet is limited to 1,048,576. By default, once this limit is reached, the writer will automatically create a new sheet and continue writing data into it.

Advanced usage

You can do a lot more with Spout! Check out the full documentation to learn about all the features.