spout/docs/_pages/getting-started.md

layout	title	permalink
doc	Getting Started	/getting-started/

This guide will help you install {{ site.spout_html }} and teach you how to use it.

Requirements

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

Installation

Composer (recommended)

{{ site.spout_html }} 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 {{ site.spout_html }} 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;
use Box\Spout\Common\Type;

$reader = ReaderEntityFactory::createReader(Type::XLSX); // for XLSX files
// $reader = ReaderEntityFactory::createReader(Type::ODS); // for ODS files
// $reader = ReaderEntityFactory::createReader(Type::CSV); // for CSV files

$reader->open($filePath);

foreach ($reader->getSheetIterator() as $sheet) {
    foreach ($sheet->getRowIterator() as $row) {
        // do stuff with the row
    }
}

$reader->close();

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

---

In addition to passing a reader type to ReaderEntityFactory::createReader, it is also possible to provide a path to a file and create the reader.

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

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

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;
use Box\Spout\Common\Type;

$writer = WriterEntityFactory::createWriter(Type::XLSX);
// $writer = WriterEntityFactory::createWriter(Type::ODS);
// $writer = WriterEntityFactory::createWriter(Type::CSV);

$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); 

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

$writer->close();

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 {{ site.spout_html }}! Check out the [full documentation]({{ site.github.url }}/docs/) to learn about all the features.