class to read and write comma-separated-value files.

url with examples: http://www.blueshoes.org/en/framework/util/csv_util/
download: http://www.blueshoes.org/download/Bs_CsvUtil.class.php
phpdoc: http://developer.blueshoes.org/phpdoc/Bs_CsvUtil.html

Features:
supports any separator char sequence, default is semicolon ";".
supports separator characters in the values. eg you use a ; as separator, your line may look like
blah;hello world;"foo";"foo;bar";"this is a ""string""";got it?;foo
as you can see, the values can be in "quotes". if your text uses quotes itself as in the "string"
example, they are escaped in ms-style with 2 quotes. and by using quotes we can even have your
separator inside the text (example "foo;bar").
line breaks. a csv line may spread over multiple lines using crlf in a field value.
see the checkMultiline param and the _checkMultiline() method.
this class is part of the blueshoes php application framework, see blueshoes.org.


By : blueshoes

<?php
define('BS_CSVUTIL_VERSION', '4.0.$x$');


/**
* csv util class. csv = comma separated value.
*
* features:
* - supports any separator char sequence, default is semicolon ";"
* - supports separator characters in the values. eg you use a ; as separator, your line may look like
* blah;hello world;"foo";"foo;bar";"this is a ""string""";got it?;foo
* as you can see, the values can be in "quotes". if your text uses quotes itself as in the "string"
* example, they are escaped in ms-style with 2 quotes. and by using quotes we can even have your
* separator inside the text (example "foo;bar").
* - line breaks. a csv line may spread over multiple lines using crlf in a field value.
* see the checkMultiline param and the _checkMultiline() method.
*
* missing:
* - option to change quote char (") to something else
*
* thanks to: steffen at hung dot ch
*
* dependencies: none.
*
* @author andrej arn <andrej at blueshoes dot org>
* @copyright blueshoes.org
* @version 4.2.$id$
* @package util
* @access pseudostatic
*/
class Bs_CsvUtil {


/**
* Constructor.
*/
function Bs_CsvUtil() {
}


/**
* reads in a cvs-file and returns it as a 2-dim vector.
* @param string $fullPath (fullpath to the cvs file)
* @param bool $checkMultiline (default is FALSE, see _checkMultiline())
* @see csvArrayToArray()
*/
function csvFileToArray($fullPath, $separator=';', $trim='none', $removeHeader=FALSE, $removeEmptyLines=FALSE, $checkMultiline=FALSE) {
$fileContent = @file($fullPath);
if (!$fileContent) return FALSE;

//hrm, having similar prob as in csvStringToArray() here except this time i need it for \n not \r.
//so let's remove that aswell ... --andrej
while (list($k) = each($fileContent)) {
if ((substr($fileContent[$k], -1) == "\r") || (substr($fileContent[$k], -1) == "\n")) {
$fileContent[$k] = substr($fileContent[$k], 0, -1);
}
}
reset($fileContent);

if ($checkMultiline) $fileContent = $this->_checkMultiline($fileContent);
return $this->csvArrayToArray($fileContent, $separator, $trim, $removeHeader, $removeEmptyLines);
}


/**
* takes a csv-string and returns it as a 2-dim vector.
* @param string $string
* @param bool $checkMultiline (default is FALSE, see _checkMultiline())
* @see csvArrayToArray()
*/
function csvStringToArray($string, $separator=';', $trim='none', $removeHeader=FALSE, $removeEmptyLines=FALSE, $checkMultiline=FALSE) {
if (empty($string)) return array();
$array = explode("\n", $string);

//short hack: on windows we should explode by "\r\n". if not, the elements in $array still end with \r.
//so let's remove that ... --andrej
while (list($k) = each($array)) {
if (substr($array[$k], -1) == "\r") {
$array[$k] = substr($array[$k], 0, -1);
}
}
reset($array);

if ((!is_array($array)) || empty($array)) return array();
if ($checkMultiline) $array = $this->_checkMultiline($array);
return $this->csvArrayToArray($array, $separator, $trim, $removeHeader, $removeEmptyLines);
}


/**
*
* reads in a cvs array and returns it as a 2-dim vector.
*
* cvs = comma separated value. you can easily export that from
* an excel file for example. it looks like:
*
* headerCellOne;headerCellTwo;headerCellThree
* dataCellOne;dataCellTwo;dataCellThree
* apple;peach;banana;grapefruit
* linux;windows;mac
* 1;2;3
*
* note I: all returned array elements are strings even if the values were numeric.
* note II: it may be that one array has another array-length than another. in the example
* above, the fruits have 4 elements while the others just have 3. this is not
* catched. ideally every sub-array would have 4 elements. this would have to be
* added when needed, maybe with another param in the function call.
*
* @access public pseudostatic
* @param string $fullPath (fullpath to the cvs file)
* @param array $array (hash or vector where the values are the csv lines)
* @param string $separator (cell separator, default is ';')
* @param string $trim (if we should trim the cells, default is 'none', can also be 'left', 'right' or 'both'. 'none' kinda makes it faster, omits many function calls, remember that.)
* @param bool $removeHeader (default is FALSE. would remove the first line which usually is the title line.)
* @param bool $removeEmptyLines (default is FALSE. would remove empty lines, that is, lines where the cells are empty. white spaces count as empty aswell.)
* @return array (2-dim vector. it may be an empty array if there is no data.)
* @throws bool FALSE on any error.
* @see csvStringToArray()
*/
function csvArrayToArray($array, $separator=';', $trim='none', $removeHeader=FALSE, $removeEmptyLines=FALSE) {
switch ($trim) {
case 'none':
$trimFunction = FALSE;
break;
case 'left':
$trimFunction = 'ltrim';
break;
case 'right':
$trimFunction = 'rtrim';
break;
default: //'both':
$trimFunction = 'trim';
break;
}

$sepLength = strlen($separator);

if ($removeHeader) {
array_shift($array);
}

$ret = array();
reset($array);
while (list(,$line) = each($array)) {
$offset = 0;
$lastPos = 0;
$lineArray = array();
do {
//find the next separator
$pos = strpos($line, $separator, $offset);
if ($pos === FALSE) {
//no more separators.
$lineArray[] = substr($line, $lastPos);
break;
}
//now let's see if it is inside a field value (text) or it is a real separator.
//it can only be a separator if the number of quotes (") since the last separator
//is straight (not odd).
$currentSnippet = substr($line, $lastPos, $pos-$lastPos);
$numQuotes = substr_count($currentSnippet, '"');
if ($numQuotes % 2 == 0) {
//that's good, we got the next field. the separator was a real one.
$lineArray[] = substr($line, $lastPos, $pos-$lastPos);
$lastPos = $pos + $sepLength;
} else {
//have to go on, separator was inside a field value.
}
$offset = $pos + $sepLength;
} while (TRUE);

//trim if needed
if ($trimFunction !== FALSE) {
while (list($k) = each($lineArray)) {
$lineArray[$k] = $trimFunction($lineArray[$k]);
}
reset($lineArray);
}

//remove quotes around cell values, and unescape other quotes.
while (list($k) = each($lineArray)) {
if ((substr($lineArray[$k], 0, 1) == '"') && (substr($lineArray[$k], 1, 1) != '"') && (substr($lineArray[$k], -1) == '"')) {
//string has to look like "hello world" and may not look like ""hello.
//if two quotes are together, it's an escaped one. csv uses ms-escape style.
$lineArray[$k] = substr($lineArray[$k], 1, -1);
}
//now un-escape the other quotes
$lineArray[$k] = str_replace('""', '"', $lineArray[$k]);
}
reset($lineArray);

//removeEmptyLines
$addIt = TRUE;
if ($removeEmptyLines) {
do {
while (list($k) = each($lineArray)) {
if (!empty($lineArray[$k])) break 2;
}
$addIt = FALSE;
} while (FALSE);
reset($lineArray);
}

if ($addIt) {
$ret[] = $lineArray;
}
}

return $ret;
}


/**
* takes an array and creates a csv string from it.
*
* the given param $array may be a simple 1-dim array like this:
* $arr = array('madonna', 'alanis morisette', 'falco');
* that will result in the string: "madonna;alanis morisette;falco"
*
* if the param is a 2-dim array, it goes like this:
* $arr = array(
* array('madonna', 'pop', 'usa'),
* array('alanis morisette', 'rock', 'canada'),
* array('falco', 'pop', 'austria'),
* );
* result: madonna;pop;usa
* alanis morisette;rock;canada
* falco;pop;austria
*
* todo: add param "fill to fit max length"?
*
* @access public
* @param array $array (see above)
* @param string $separator (default is ';')
* @param string $trim (if we should trim the cells, default is 'none', can also be 'left', 'right' or 'both'. 'none' kinda makes it faster, omits many function calls, remember that.)
* @param bool $removeEmptyLines (default is TRUE. removes "lines" that have no value, would come out empty.)
* @return string (empty string if there is nothing at all)
*/
function arrayToCsvString($array, $separator=';', $trim='none', $removeEmptyLines=TRUE) {
if (!is_array($array) || empty($array)) return '';

switch ($trim) {
case 'none':
$trimFunction = FALSE;
break;
case 'left':
$trimFunction = 'ltrim';
break;
case 'right':
$trimFunction = 'rtrim';
break;
default: //'both':
$trimFunction = 'trim';
break;
}

$ret = array();
reset($array);
if (is_array(current($array))) {
while (list(,$lineArr) = each($array)) {
if (!is_array($lineArr)) {
//could issue a warning ...
$ret[] = array();
} else {
$subArr = array();
while (list(,$val) = each($lineArr)) {
$val = $this->_valToCsvHelper($val, $separator, $trimFunction);
$subArr[] = $val;
}
}
$ret[] = join($separator, $subArr);
}
return join("\n", $ret);
} else {
while (list(,$val) = each($array)) {
$val = $this->_valToCsvHelper($val, $separator, $trimFunction);
$ret[] = $val;
}
return join($separator, $ret);
}
}


/**
* works on a string to include in a csv string/file.
* @access private
* @param string $val
* @param string $separator
* @param mixed $trimFunction (bool FALSE or 'rtrim' or so.)
* @return string
* @see arrayToCsvString() and others.
*/
function _valToCsvHelper($val, $separator, $trimFunction) {
if ($trimFunction) $val = $trimFunction($val);
//if there is a separator (;) or a quote (") or a linebreak in the string, we need to quote it.
$needQuote = FALSE;
do {
if (strpos($val, '"') !== FALSE) {
$val = str_replace('"', '""', $val);
$needQuote = TRUE;
break;
}
if (strpos($val, $separator) !== FALSE) {
$needQuote = TRUE;
break;
}
if ((strpos($val, "\n") !== FALSE) || (strpos($val, "\r") !== FALSE)) { // \r is for mac
$needQuote = TRUE;
break;
}
} while (FALSE);
if ($needQuote) {
$val = '"' . $val . '"';
}
return $val;
}



/**
* takes an array and combines elements (lines) if needed.
* @access private
* @param array $in
* @return array
*/
function _checkMultiline($in) {
$ret = array();

$stack = FALSE;
reset($in);
while (list(,$line) = each($in)) {
$c = substr_count($line, '"');
if ($c % 2 == 0) {
if ($stack === FALSE) {
$ret[] = $line;
} else {
$stack .= "\n" . $line;
}
} else {
//odd number
if ($stack === FALSE) {
$stack = $line;
} else {
$ret[] = $stack . "\n" . $line;
$stack = FALSE;
}
}
}
return $ret;
}


} // end Class



//remove this (it shows the source code):
if (basename($_SERVER['PHP_SELF']) == 'Bs_CsvUtil.class.php') {
###################################################################################################
highlight_string(join('', file(__FILE__)));
}

?>

DISCLAIMER: The content provided in this article is not warranted or guaranteed by Developer Shed, Inc. The content provided is intended for entertainment and/or educational purposes in order to introduce to the reader key ideas, concepts, and/or product reviews. As such it is incumbent upon the reader to employ real-world tactics for security and implementation of best practices. We are not liable for any negative consequences that may result from implementing any information covered in our articles or tutorials. If this is a hardware review, it is not recommended to open and/or modify your hardware.

More File Manipulation Code Articles
More By Codewalkers

 

developerWorks - FREE Tools!

NEW! Download IBM Data Studio V1.1 Visit IBM developerWorks to download the latest trial version of IBM Data Studio V1.1 at no cost. IBM Data Studio is a comprehensive data management solution that helps you effectively design, develop, deploy and manage your data, databases, and database applications throughout the data management life cycle utilizing a consistent and integrated user interface. Unlike other client-side data management solutions that focus on only one aspect of the application lifecycle or database administration, Data Studio complements the Rational Software Delivery platform, providing unparalleled flexibility for a heterogeneous data server environment across platforms. FREE! Go There Now!

NEW! Innovate don't duplicate! Asset reuse strategies for success Asset Reuse is a key strategy for companies looking to create innovative solutions to solve complex software development problems. Searching for, identifying, updating, using and deploying software assets can be a difficult challenge. Listen to this webcast, to learn about strategies and tools that you can leverage for a successful project, including Rational Asset Manager, Rational Software Architect and WebSphere Service Registry and Repository. FREE! Go There Now!

NEW! Integrating XML into Your Enterprise Using Data Federation XML has become a common way of storing business data as flat files and many data server vendors including IBM have provided ways to store this data within relational database systems. Increasingly collections of XML files are accessed like databases using an xQuery and other XML standard mechanisms. Businesses find the need to combine the traditional tabular structured data with XML formatted data. In this webcast, you’ll learn about IBM’s WebSphere Federation Server technology, which provides users with the ability to integrate these two data formats. FREE! Go There Now!

NEW! Rational Testing eKits Discover how Rational tools and best practices for testing can make your job easier. The new Rational Testing eKits provide you with valuable resources – including demos, webcasts, tutorials, and articles – that help you address your specific testing needs across the software lifecycle. Five new eKits are available covering the topics of Requirements and Test Management, Functional Testing, Performance Testing, Code Quality and Embedded Systems, and SOA and Web Services Testing. FREE! Go There Now!

NEW! Test terminal-based applications with Rational Functional Tester Regression testing -- in which code is thoroughly tested to ensure that changes have not produced unexpected results -- is an important part of any development process. But many testing environments neglect the terminal-based applications that still form the backbone of many industries. In this tutorial, you'll learn how the Rational Functional Tester Extension for Terminal-Based Applications works with other Rational Functional Tester to help test terminal-based applications quickly and easily. FREE! Go There Now!

NEW! The role of integrated requirements management in software delivery This paper is about the critical role that a discipline called integrated require­ments management can play in helping to ensure that your business goals and IT investments are continuously aligned—whether you are sourcing, integrat­ing, building or maintaining software. It also looks at ways that automated IBM Rational® products can work together to help you use requirements in the very best way. FREE! Go There Now!

NEW! Trial download: IBM Lotus Forms V3.0 Get a free trial download of IBM Lotus Forms V3.0 (formerly Workplace Forms), which provides a zero-footprint eForms solution to help you automate and move forms-based business processes off the desktop and onto the Web. With Lotus Forms, you can extend applications beyond the firewall by creating a single electronic form document ready for use in both thick and Web 2.0 thin client format. FREE! Go There Now!

NEW! Webcast: Accelerating Software Innovation with System z Attend this launch webcast with Scott Hebner, Vice President of IBM Rational Marketing and Strategy, where he will overview Rational’s new offerings and programs to help customers accelerate software innovation on System z. He will discuss how these solutions help organizations extend their core business processes toward modern architectures such as SOA and web technologies to deliver business improvements that stand the test of time. FREE! Go There Now!

NEW! Webcast: Eclipse: Empowering the universal platform The Eclipse community is constantly working to extend Eclipse's functionality. In this webcast, learn about some of the most important and feature-rich projects under development. From multi-language support to plug-in development, tune in to see what Eclipse is capable of now. FREE! Go There Now!

NEW! Whitepaper: Delivering SOA solutions: service lifecycle management The unprecedented scope of a service-oriented architecture (SOA) initiative brings to the forefront a number of management and governance issues that were sidestepped in the past. The key to a successful SOA implementation is managing and governing activities throughout the entire SOA delivery lifecycle by ensuring that services conform to the needs of all of the business’s stakeholders. Learn how service lifecycle management allows the business to ensure that the process by which services are defined, created, tested, deployed, optimized and retired is manageable, repeatable and auditable. FREE! Go There Now!

All FREE IBM® developerWorks Tools!