README

A high-performance PHP extension for reading and writing CSV files with full RFC 4180 compliance and advanced features.

Tip: For a unified API that automatically leverages this extension when available, check out PHP-CSVHelper. It provides a consistent interface that uses FastCSV for maximum performance while gracefully falling back to SplFileObject when needed.

Features

High Performance: Native C implementation with optimized memory management using Arena allocation
RFC 4180 Compliant: Full compliance with CSV standard including proper quote handling and multi-line records
Flexible API: Support for both file paths and configuration objects in constructors
Configurable Flushing: Auto-flush mode for immediate data visibility or manual flush for maximum performance
Advanced CSV Handling:
- Proper quote escaping and unescaping ("" → ")
- Multi-line quoted fields support
- Configurable delimiters, quotes, and escape characters
- CRLF and LF line ending support
- Immediate or buffered write operations
Memory Efficient: Arena-based memory management for optimal performance
Comprehensive Testing: Extensive test suite with 100% pass rate (12/12 tests passing)

Classes

FastCSVReader

High-performance CSV reader with advanced navigation capabilities.

// Create reader with file path
$reader = new FastCSVReader('/path/to/file.csv');

// Or with configuration object
$config = new FastCSVConfig();
$config->delimiter = ';';
$config->quote = '"';
$reader = new FastCSVReader($config);
$reader->open('/path/to/file.csv');

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

// Navigation methods
$reader->rewind();
$reader->seek(100);
$position = $reader->getPosition();
$count = $reader->getRecordCount();
$headers = $reader->getHeaders();

FastCSVWriter

High-performance CSV writer with proper quoting and escaping.

// Create writer with headers
$config = new FastCSVConfig();
$config->setPath('/path/to/output.csv');
$writer = new FastCSVWriter($config, ['Name', 'Age', 'City']);

// Write records (auto-flushed by default)
$writer->writeRecord(['John Doe', '30', 'New York']);
$writer->writeRecord(['Jane Smith', '25', 'Los Angeles']);

// For high-performance scenarios, disable auto-flush
$config->setAutoFlush(false);
$writer = new FastCSVWriter($config, ['ID', 'Data']);

for ($i = 0; $i < 100000; $i++) {
    $writer->writeRecord([$i, "Data$i"]);
    
    // Manual flush every 1000 records for optimal performance
    if ($i % 1000 == 0) {
        $writer->flush();
    }
}

$writer->close(); // Final flush on close

FastCSVConfig

Configuration class for customizing CSV parsing and writing behavior.

$config = new FastCSVConfig();
$config->setDelimiter(';');      // Field delimiter (default: ',')
$config->setEnclosure('"');      // Quote character (default: '"')
$config->setEscape('\\');        // Escape character (default: '\\')
$config->setHasHeader(true);     // First row contains headers (default: true)
$config->setAutoFlush(true);     // Auto-flush after each write (default: true)
$config->setStrictMode(false);   // Strict quoting mode (default: false)
$config->setSkipEmptyLines(false); // Skip empty lines (default: false)
$config->setTrimFields(false);   // Trim whitespace from fields (default: false)
$config->setWriteBOM(false);     // Write BOM for Unicode files (default: false)

Installation

Recommended: Using PIE (PHP Installer for Extensions)

The easiest way to install FastCSV is using PIE:

# Install the latest version
pie install csvtoolkit/fastcsv

# Install a specific version
pie install csvtoolkit/fastcsv:^0.0.1

For detailed PIE installation instructions, see PIE_INSTALLATION.md.

Manual Installation

Prerequisites

PHP 8.2 or higher
GCC or compatible C compiler
PHP development headers (php-dev package)

From Source

# Clone the repository
git clone <repository-url>
cd fastcsv-extension

# Initialize submodules (for the lib directory)
git submodule update --init --recursive

# Build the extension
phpize
./configure
make
make install

Enable Extension

Add to your php.ini:

extension=fastcsv

Or load dynamically:

dl('fastcsv.so'); // Linux/macOS
dl('fastcsv.dll'); // Windows

Development

Building

The extension uses an external C library located in the lib/ directory (git submodule). The build process automatically includes:

lib/arena.c - Arena memory management
lib/csv_parser.c - Core CSV parsing logic
lib/csv_reader.c - CSV reader implementation
lib/csv_writer.c - CSV writer implementation
lib/csv_utils.c - Utility functions

Testing

Run the test suite:

# Run all tests
make test

# Run specific test
php run-tests.php tests/FastCSVReader_001.phpt

# Run with verbose output
php run-tests.php -v tests/

Current Test Status

Passing: 12/12 tests (100% success rate)
Comprehensive Coverage: Edge cases, performance, memory management, and RFC 4180 compliance
Stable: All tests consistently pass across different environments

Technical Details

Architecture

The extension is built on top of a high-performance C library with the following components:

Arena Memory Management: Efficient memory allocation and cleanup
Character-by-Character Parsing: Proper handling of quoted fields and line endings
State Machine Parser: RFC 4180 compliant parsing with quote state tracking
Configurable Parameters: Flexible delimiter, quote, and escape character support

Memory Management

The extension uses Arena-based memory allocation for optimal performance:

Each reader/writer instance maintains its own arena
Automatic cleanup when objects are destroyed
Minimal memory fragmentation
Efficient bulk allocations

RFC 4180 Compliance

Full compliance with CSV standard including:

Proper quote character handling
Multi-line field support
CRLF and LF line ending support
Quote escaping ("" becomes ")
Whitespace preservation in quoted fields

Performance

The extension is optimized for high-performance CSV processing with significant improvements over PHP's native SplFileObject:

Benchmark Results (PHP 8.4.8, 1GB Memory Limit)

Read Operations Performance

Data Size	Implementation	Median Time (ms)	Throughput (records/sec)	Speed Improvement
Small (1K rows)	FastCSV	3.67	272,410	4.1x faster
	SplFileObject	15.03	66,520
Medium (100K rows)	FastCSV	176.04	568,049	3.6x faster
	SplFileObject	639.51	156,370
Large (1M rows)	FastCSV	1,987.23	503,212	4.8x faster
	SplFileObject	9,468.64	105,612

Combined Read/Write Operations

Data Size	Implementation	Median Time (ms)	Throughput (records/sec)	Speed Improvement
Small (1K rows)	FastCSV	22.76	87,870	1.6x faster
	SplFileObject	35.5	56,341
Medium (100K rows)	FastCSV	590.78	338,535	2.5x faster
	SplFileObject	1,469.31	136,118
Large (1M rows)	FastCSV	7,088.8	282,135	2.9x faster
	SplFileObject	20,513.19	97,498

Key Performance Advantages

Read Operations: 3.6x to 4.8x performance improvement over SplFileObject
Combined Operations: 1.6x to 2.9x advantage for read/write operations
Scalability: Performance advantage increases with data size
Memory Efficiency: Constant ~2MB memory usage regardless of file size
Consistency: Lower standard deviation, indicating more predictable performance

Technical Performance Features

Native C Implementation: Direct memory access and optimized algorithms
Arena Memory Management: Efficient bulk allocations and minimal fragmentation
Streaming Operations: Constant memory usage regardless of file size
RFC 4180 Optimized: Fast parsing with proper quote handling

Contributing

See CONTRIBUTING.md for development guidelines.

License

This project is licensed under the terms specified in the LICENSE file.

Changelog

Recent Updates

Arena Integration: Updated to use Arena memory management system
API Improvements: Flexible constructors accepting both strings and config objects
RFC 4180 Compliance: Complete rewrite of parser for standards compliance
Multi-line Support: Proper handling of quoted fields spanning multiple lines
Error Handling: Improved PHP error reporting and exception handling
Test Coverage: Comprehensive test suite with extensive edge case coverage

For the latest updates and bug reports, please check the project's issue tracker.

csvtoolkit / fastcsv

Maintainers

Details