CSV Toolkit

⚠️ Experimental Status: This library is currently in experimental phase. While it works correctly and passes all tests, please use with caution in production environments. We recommend thorough testing in your specific use case before deployment.

A modern, high-performance CSV processing library for PHP that automatically selects the best available implementation. CsvToolkit provides a unified interface for reading and writing CSV files, with automatic fallback between the FastCSV extension (when available) and PHP's built-in SplFileObject.

Features

• Automatic Implementation Selection: Automatically uses FastCSV extension when available, falls back to SplFileObject
• Unified Interface: Same API regardless of underlying implementation
• High Performance: FastCSV extension provides significant performance improvements
• Flexible Configuration: Support for custom delimiters, enclosures, escape characters, and headers
• Factory Pattern: Simple factory methods for creating readers and writers
• Action Classes: Convenient action classes for quick CSV operations
• Comprehensive Testing: Full test suite with 146+ tests covering both implementations
• Type Safety: Full type declarations and PHPDoc documentation

Installation

Install via Composer:

composer require csvtoolkit/csv-helper

Optional: FastCSV Extension

For enhanced performance, install the FastCSV PHP extension:

# The library will automatically detect and use it when available
# Falls back to SplFileObject when not available

Quick Start

Using Factory (Recommended)

use CsvToolkit\Factories\CsvFactory;

// Create reader (automatically selects best implementation)
$reader = CsvFactory::createReader('data.csv');

// Read all records
while (($record = $reader->nextRecord()) !== false) {
    print_r($record);
}

// Create writer
$writer = CsvFactory::createWriter('output.csv');
$writer->write(['Name', 'Age', 'Email']); // Header
$writer->write(['John Doe', '30', '[email protected]']);

Using Action Classes

use CsvToolkit\Actions\CsvReaderAction;
use CsvToolkit\Actions\CsvWriterAction;

// Quick reader creation
$reader = CsvReaderAction::create('data.csv');

// Quick writer creation  
$writer = CsvWriterAction::create('output.csv');

Manual Implementation Selection

use CsvToolkit\Readers\CsvReader;      // FastCSV implementation
use CsvToolkit\Readers\SplCsvReader;   // SplFileObject implementation
use CsvToolkit\Writers\CsvWriter;      // FastCSV implementation
use CsvToolkit\Writers\SplCsvWriter;   // SplFileObject implementation
use CsvToolkit\Configs\CsvConfig;

// Configure CSV settings
$config = new CsvConfig();
$config->setDelimiter(';')
       ->setEnclosure('"')
       ->setHasHeader(true);

// Use specific implementation
$reader = new SplCsvReader('data.csv', $config);

Configuration

use CsvToolkit\Configs\CsvConfig;

$config = new CsvConfig();
$config->setDelimiter(',')           // Field delimiter
       ->setEnclosure('"')           // Field enclosure
       ->setEscape('\\')             // Escape character
       ->setHasHeader(true);         // First row is header

Reading CSV Files

use CsvToolkit\Factories\CsvFactory;

$reader = CsvFactory::createReader('data.csv');

// Get header (if configured)
$header = $reader->getHeader();

// Read records sequentially
while (($record = $reader->nextRecord()) !== false) {
    // Process record
}

// Or seek to specific position
$record = $reader->seek(5); // Get 6th record (0-based)

// Check if more records available
if ($reader->hasNext()) {
    $nextRecord = $reader->nextRecord();
}

// Get total record count
$totalRecords = $reader->getRecordCount();

Writing CSV Files

use CsvToolkit\Factories\CsvFactory;

$writer = CsvFactory::createWriter('output.csv');

// Write single record
$writer->write(['John Doe', '30', '[email protected]']);

// Write multiple records at once
$records = [
    ['Name', 'Age', 'Email'],
    ['John Doe', '30', '[email protected]'],
    ['Jane Smith', '25', '[email protected]']
];
$writer->writeAll($records);

Implementation Detection

use CsvToolkit\Factories\CsvFactory;

// Check if FastCSV is available
if (CsvFactory::isFastCsvAvailable()) {
    echo "Using high-performance FastCSV extension";
} else {
    echo "Using SplFileObject fallback";
}

// Get detailed implementation info
$info = CsvFactory::getImplementationInfo();
print_r($info);
// Array
// (
//     [implementation] => FastCSV
//     [extension_loaded] => 1
//     [version] => 0.0.1
// )

Exception Handling

The library provides specific exceptions for different error conditions:

use CsvToolkit\Exceptions\FileNotFoundException;
use CsvToolkit\Exceptions\DirectoryNotFoundException;
use CsvToolkit\Exceptions\CsvReaderException;
use CsvToolkit\Exceptions\CsvWriterException;
use CsvToolkit\Exceptions\EmptyFileException;

try {
    $reader = CsvFactory::createReader('nonexistent.csv');
} catch (FileNotFoundException $e) {
    echo "File not found: " . $e->getMessage();
} catch (CsvReaderException $e) {
    echo "Reader error: " . $e->getMessage();
}

Performance

When the FastCSV extension is available, CsvToolkit provides significant performance improvements over PHP's native SplFileObject:

🚀 Benchmark Results (PHP 8.4.8, 1GB memory limit)

Read Operations:

• Small datasets (1K rows): 4.1x faster - 272K vs 67K records/sec
• Medium datasets (100K rows): 3.6x faster - 568K vs 156K records/sec
• Large datasets (1M rows): 4.8x faster - 503K vs 106K records/sec

Combined Read/Write Operations:

• Small datasets: 1.6x faster - 88K vs 56K records/sec
• Medium datasets: 2.5x faster - 339K vs 136K records/sec
• Large datasets: 2.9x faster - 282K vs 98K records/sec

💾 Memory Efficiency

• Constant memory usage: ~2MB regardless of file size
• Streaming operations: No memory accumulation with large files
• Real memory usage: Minimal (0 bytes) due to efficient streaming

📊 Performance Characteristics

• FastCSV: Optimized C extension with direct memory access
• SplFileObject: Pure PHP implementation with additional overhead
• Scaling: Performance advantage increases with data size
• Consistency: FastCSV shows lower standard deviation for predictable performance

🎯 Real-world Impact

• Lower development costs: Reduce time spent on CSV processing optimization
• Reduce infrastructure costs: More efficient processing means lower server resources
• Better scalability: Handle larger datasets without performance degradation

The library automatically selects the best available implementation without any code changes required.

Benchmark Details: Comprehensive performance validation available at benchmarking-php-fastcsv

Testing

Run the test suite:

# Test with SplFileObject (fallback)
./vendor/bin/phpunit

# Test with FastCSV extension (if available)
php -d extension=path/to/fastcsv.so ./vendor/bin/phpunit

Contributing

We welcome contributions! Please follow these guidelines:

• Respect all modern PHP coding standards and best practices
• Ensure that all methods include type declarations
• Pass all unit tests before committing your changes
• Tests are required for any new features or bug fixes
• Maintain compatibility with both FastCSV and SplFileObject implementations

Roadmap

Current Features ✅

• FastCSV extension integration with automatic fallback
• Factory pattern for implementation selection
• Action classes for convenient usage
• Comprehensive exception handling
• Full type safety and documentation

Requirements

• PHP 8.3 or higher
• Optional: FastCSV extension for enhanced performance

Support the Project

If you find CSV Toolkit useful for your projects, please consider sponsoring the development! Your support helps maintain and improve this high-performance CSV library while reducing development and infrastructure costs.

Why sponsor?

• 🚀 Accelerate development of new features
• 🐛 Faster bug fixes and improvements
• 📚 Better documentation and examples
• 🎯 Priority support for feature requests
• 💡 Fund research into even faster CSV processing techniques
• 💰 Lower development costs - Reduce your team's time spent on CSV processing optimization
• 🏗️ Reduce infrastructure costs - More efficient processing means lower server resources needed

License

This project is open source and available under the MIT License. See the LICENSE file for more information.