Author: mcantelon
Date: Tue Jan 17 13:49:47 2012
New Revision: 10699
Log:
Documented QubitFlatFile class methods.
Modified:
trunk/lib/QubitFlatfileImport.class.php
Modified: trunk/lib/QubitFlatfileImport.class.php
==============================================================================
--- trunk/lib/QubitFlatfileImport.class.php Tue Jan 17 12:18:26 2012
(r10698)
+++ trunk/lib/QubitFlatfileImport.class.php Tue Jan 17 13:49:47 2012
(r10699)
@@ -98,21 +98,51 @@
}
}
+ /**
+ * Set status variable value
+ *
+ * @param string $var name of variable
+ * @param value value of variable (could be any type)
+ *
+ * @return void
+ */
public function setStatus($var, $value)
{
$this->status[$var] = $value;
}
+ /**
+ * Get status variable value
+ *
+ * @param string $var name of variable
+ *
+ * @return value value of variable (could be any type)
+ */
public function getStatus($var)
{
return $this->status[$var];
}
+ /**
+ * Add an ad-hoc column handler
+ *
+ * @param string $column name of column
+ * @param closure $handler column handling logic
+ *
+ * @return void
+ */
public function addColumnHandler($column, $handler)
{
$this->handlers[$column] = $handler;
}
+ /**
+ * Test whether a property is set and, if so, execute it
+ *
+ * @param string $property name of property
+ *
+ * @return void
+ */
protected function executeClosurePropertyIfSet($property)
{
// attempting to directly call an object property that's a
@@ -123,6 +153,11 @@
}
}
+ /**
+ * Determine whether columns isn't handled by import logic
+ *
+ * @return boolean TRUE if column not handled by import logic
+ */
public function unhandledColumn($column)
{
return !in_array($column, $this->ignoreColumns)
@@ -135,6 +170,11 @@
&& !isset($this->arrayColumns[$column]);
}
+ /**
+ * Combine two or more arrays, eliminating any duplicates
+ *
+ * @return array combined array
+ */
protected function combineArraysWithoutDuplicates()
{
$args = func_get_args();
@@ -153,6 +193,11 @@
return $combined;
}
+ /**
+ * Return an array of import columns that aren't handled by import logic
+ *
+ * @return array array of column names
+ */
public function determineUnmatchedHandledColumns()
{
$unmatchedColumns = array();
@@ -165,6 +210,11 @@
return $unmatchedColumns;
}
+ /**
+ * Return an array of columns that are handled by import logic
+ *
+ * @return array array of column names
+ */
public function handledColumns()
{
return $this->combineArraysWithoutDuplicates(
@@ -178,6 +228,12 @@
);
}
+ /**
+ * Return an array of columns that are included in the import but not
+ * handled by logic.
+ *
+ * @return array array of column names
+ */
public function determineUnhandledColumns()
{
$ignored = array();
@@ -192,6 +248,11 @@
return $ignored;
}
+ /**
+ * Render a string description of problem columns from an array
+ *
+ * @return string description
+ */
public function renderProblemColumns($columns, $problemDescription)
{
$output = '';
@@ -207,6 +268,12 @@
return $output;
}
+ /**
+ * Render a string description of import columns that aren't handled by
+ * the import logic
+ *
+ * @return string description
+ */
public function renderUnhandledColumns()
{
return $this->renderProblemColumns(
@@ -215,6 +282,12 @@
);
}
+ /**
+ * Render a string description of columns that are handled by the import
+ * logic but don't actually exist in the import itself
+ *
+ * @return string description
+ */
public function renderUnmatchedColumns()
{
return $this->renderProblemColumns(
@@ -224,22 +297,45 @@
return $output;
}
+ /**
+ * Start import timer
+ *
+ * @return void
+ */
protected function startTimer()
{
$this->timer = new QubitTimer;
$this->timer->start();
}
+ /**
+ * Stop import timer
+ *
+ * @return void
+ */
protected function stopTimer()
{
$this->timer->stop();
}
+ /**
+ * Get time elapsed during import
+ *
+ * @return int microseconds since import began
+ */
public function getTimeElapsed()
{
return $this->timer->elapsed();
}
+ /**
+ * Pull data from a csv file and process each row
+ *
+ * @param resource $fh file handler for file containing CSV data
+ * @param integer $skipRows number of rows to skip (optional)
+ *
+ * @return void
+ */
public function csv($fh, $skipRows = 0)
{
$this->status['skippedRows'] = $skipRows;
@@ -281,6 +377,15 @@
$this->stopTimer();
}
+ /**
+ * Execute logic, defined by a closure, on each column of a row
+ *
+ * @param array $row array of column data
+ *
+ * @param closure $logic logic that should be performed on the column value
+ *
+ * @return void
+ */
protected function forEachRowColumn($row, $logic)
{
for ($index = 0; $index < count($row); $index++)
@@ -294,6 +399,15 @@
}
}
+ /**
+ * Handle mapping of column to object property
+ *
+ * @param array $mapDefinition array defining which property to map to and
+ * optional transformation logic
+ * @param string $value column value
+ *
+ * @return void
+ */
public function mappedColumnHandler($mapDefinition, $value)
{
if (isset($this->object) && is_object($this->object)) {
@@ -313,14 +427,31 @@
}
}
- public function arrayColumnHandler($column, $arrayDefinition, $value)
+ /**
+ * Handle mapping of column, containing multiple values delimitd by a
+ * character, to an array
+ *
+ * @param string $column column name
+ * @param array $delimiter delimiting character
+ * @param string $value column value
+ *
+ * @return void
+ */
+ public function arrayColumnHandler($column, $delimiter, $value)
{
if ($value)
{
- $this->rowStatusVars[$column] = explode($arrayDefinition, $value);
+ $this->rowStatusVars[$column] = explode($delimiter, $value);
}
}
+ /**
+ * Log error message if an error log has been defined
+ *
+ * @param string $message error message
+ *
+ * @return void
+ */
protected function rowProcessingBeforeObjectCreation($row)
{
// process import columns that don't produce child data
@@ -343,6 +474,14 @@
});
}
+ /**
+ * Perform row processing for before an object is saved such as setting
+ * object properties and executing ad-hoc column handlers
+ *
+ * @param array $row array of column data
+ *
+ * @return void
+ */
protected function rowProcessingBeforeSave($row)
{
// process import columns that don't produce child data
@@ -378,6 +517,14 @@
});
}
+ /**
+ * Perform row processing for after an object is saved and has an ID such
+ * as creating child properties and notes
+ *
+ * @param array $row array of column data
+ *
+ * @return void
+ */
protected function rowProcessingAfterSave($row)
{
$this->forEachRowColumn($row, function(&$self, $index, $columnName, $value)
@@ -404,6 +551,13 @@
});
}
+ /**
+ * Process a row of imported data
+ *
+ * @param array $row array of column data
+ *
+ * @return void
+ */
public function row($row = array())
{
// stash raw row data so it's accessible to closure logic
@@ -455,18 +609,37 @@
$this->rowStatusVars = array();
}
+ /**
+ * Log error message if an error log has been defined
+ *
+ * @param string $message error message
+ *
+ * @return void
+ */
public function logError($message)
{
$message = 'Row '. $this->getStatus('rows') .': '. $message ."\n";
if ($this->errorLog) file_put_contents($this->errorLog, $message,
FILE_APPEND);
}
+ /**
+ * Display error message and log it, if an error log has been defined
+ *
+ * @param string $message error message
+ *
+ * @return void
+ */
public function printAndLogError($message)
{
print $message ."\n";
$this->logError($message);
}
+ /**
+ * Output import progress, time elapsed, and memory usage
+ *
+ * @return void
+ */
public function progressDescription()
{
// return empty string if no intermittant progress display
@@ -474,9 +647,11 @@
|| !$this->rowsUntilProgressDisplay
) return '.';
- // row count isn't incremented until completion of this closure, so add
one to reflect reality
+ // row count isn't incremented until after this is displayed, so add one
to reflect reality
$rowsProcessed = $this->getStatus('rows') + 1 -
$this->getStatus('skippedRows');
$memoryUsageMB = round(memory_get_usage() / (1024 * 1024), 2);
+
+ // if this show should be displayed, display it
if (!($rowsProcessed % $this->rowsUntilProgressDisplay))
{
$elapsed = $this->getTimeElapsed();
--
You received this message because you are subscribed to the Google Groups
"Qubit Toolkit Commits" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/qubit-commits?hl=en.
