README

• Overview
• Install
• Quickstart
• Options
• Output CSV
• Append Data

Overview

pop-csv provides a streamlined way to work with PHP data and the CSV format.

It is a component of the Pop PHP Framework.

Install

Install pop-csv using Composer.

composer require popphp/pop-csv

Or, require it in your composer.json file

"require": {
    "popphp/pop-csv" : "^4.2.1"
}

Top

Quickstart

Create a CSV string

$phpData = [
    [
        'first_name' => 'Bob',
        'last_name'  => 'Smith'
    ],
    [
        'first_name' => 'Jane',
        'last_name'  => 'Smith'
    ]
];

$data      = new Pop\Csv\Csv($phpData);
$csvString = $data->serialize();

The $csvString variable now contains:

first_name,last_name
Bob,Smith
Jane,Smith

Create data from a CSV string

You can either pass the data object a direct string of serialized data or a file containing a string of serialized data. It will detect which one it is and parse it accordingly.

$csv     = new Pop\Csv\Csv($csvString);
$phpData = $csv->unserialize();

Top

Options

Where serializing or unserializing CSV data, there are a set of options available to tailor the process:

$options = [
    'exclude'   => ['id'],    // An array of fields to exclude
    'include'   => ['email'], // An array of fields to explicitly include, omitting all others
    'delimiter' => ',',       // Delimiter defaults to ',' - could be "\t" or something else
    'enclosure' => '"',       // Default string enclosure, i.e. "my data","other data"
    'escape'    => '"',       // String character to escape in the data, i.e. "my ""data"" here"
    'fields'    => true,      // Include the field names in the first row 
    'newline'   => true,      // Allow newlines in a data cell. Set as false to trim them
    'limit'     => 0,         // Character limit of a data cell. 0 means no limit
    'map'       => [],        // Array key of a single array value to map to the data cell value
    'columns'   => [],        // Array key of a multidimensional array value to map and join into the data cell value
];

Map/Columns Example

$users = [
    'id'       => 1,
    'username' => 'testuser',
    'country'  => [
        'name' => 'United States',
        'code' => 'US'
    ],
    'roles'    => [
        ['id' => 1, 'name' => 'Admin'],
        ['id' => 2, 'name' => 'Staff'],
    ]
];

$options = [
    'map' => [
        'country' => 'code'
    ],
    'columns' => [
        'roles' => 'name'
    ]
]

Pass the options array to constructor method:

$data      = new Pop\Csv\Csv($users, $options);
$csvString = $data->serialize();
echo $csvString;

The above will output the following CSV data:

id,username,country,roles
1,testuser,US,"Admin,Staff"

Top

Output CSV

Write to File

$phpData = [
    [
        'first_name' => 'Bob',
        'last_name'  => 'Smith'
    ],
    [
        'first_name' => 'Jane',
        'last_name'  => 'Smith'
    ]
];

$data = new Pop\Csv\Csv($phpData);
$data->writeToFile('/path/to/file.csv');

Output to HTTP

$phpData = [
    [
        'first_name' => 'Bob',
        'last_name'  => 'Smith'
    ],
    [
        'first_name' => 'Jane',
        'last_name'  => 'Smith'
    ]
];

$data = new Pop\Csv\Csv($phpData);
$data->outputToHttp('my-file.csv');

Force download of file

Pass a true boolean as the second parameter, which forces attachment for the Content-Disposition header.

$data->outputToHttp('my-file.csv', true);

Additional HTTP headers

Additional HTTP headers can be passed to the third parameter:

$data->outputToHttp('my-file.csv', false, ['X-Header' => 'some-header-value']);

Top

Append Data

In the case of working with large data sets, you can append CSV data to an existing file on disk. This prevents loading large amounts of data into memory that may exceed the PHP environment's limits.

us Pop\Csv\Csv;

$phpData = [
    [
        'first_name' => 'Bob',
        'last_name'  => 'Smith'
    ],
    [
        'first_name' => 'Jane',
        'last_name'  => 'Smith'
    ]
];

Csv::appendDataToFile('my-file.csv', $data);

Top