README

CSV State Parser

Parses CSV files with a simple finite-state machine.

Table of Contents

Getting Started
Installation
Contributing
License
Contact

Installation

Installation is simple.

Just run composer require tii/csv-state-parser

(back to top)

Usage

Create a Parser class that extends \Tii\CsvStateParser\CsvStateParser and implement the stateStart and result methods. See below for a full example.

Every row gets passed into the current actives stateMethod (stateStart in the beginning).

You can change the state from the next row on by calling $this->state($nextState) and pass a String backed enum or a value that can be cast to string. The next row will get passed to the corresponding stateMethod. I.e. if you call $this->state('fooBar') the next row will get passed to stateFooBar(array $row).

If you need to convert every field in the CSV file beforehand you can overwrite the protected function mapValue(string $value): string method. This is i.e. useful for encoding conversions.

There are a few additional helpers that help you achieve stuff:

You are responsible for compiling the data that the parser should return at the end yourself. This data should be returned by the result() method.

Here is a full example:

/**
 * @extends \Tii\CsvStateParser\CsvStateParser<array<int, int>> 
 */
class SumParser extends \Tii\CsvStateParser\CsvStateParser
{

    protected array $sums = [];

    protected function result(): array
    {
        return $this->sums;
    }
    
    protected function stateStart(array $row): void
    {
        if ($row[0] === 'START') {
            $this->state('list');
        }
    }
    
    protected function stateList(array $row): void
    {
        if ($row[0] === 'END') {
            $this->done();
            return;
        }
        
        $this->items[] = array_reduce($row, fn($sum, $number) => $sum + $number, 0);
    }

}

You can use your parser by instantiating it, and calling the parse(string $filename) method.
If you need to adjust the separator, enclosure and escape char you can pass those to the constructor.

⚠️ Beware! In contrast to PHPs fgetcsv function this package uses ';' as the default separator character for CSV files.

$parser = new SumParser(separator: ',');
$list = $parser->parse('filename.csv');

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!