/**
* Returns collection_id for the collection with the specified name, regardless of specified type. If the collection does not already
* exist then it will be created with the specified name, type and locale, as well as with any specified values in the $pa_values array.
* $pa_values keys should be either valid collection fields or attributes.
*
* @param string $ps_collection_name Collection label name
* @param int $pn_type_id The type_id of the collection type to use if the collection needs to be created
* @param int $pn_locale_id The locale_id to use if the collection needs to be created (will be used for both the collection locale as well as the label locale)
* @param array $pa_values An optional array of additional values to populate newly created collection records with. These values are *only* used for newly created collections; they will not be applied if the collection named already exists. The array keys should be names of collection fields or valid collection attributes. Values should be either a scalar (for single-value attributes) or an array of values for (multi-valued attributes)
* @param array $pa_options An optional array of options, which include:
* outputErrors - if true, errors will be printed to console [default=false]
* matchOnIdno - try to match on idno if name match fails [default=false]
* dontCreate - if true then new collections will not be created [default=false]
* transaction - if Transaction object is passed, use it for all Db-related tasks [default=null]
* returnInstance = return ca_collections instance rather than collection_id. Default is false.
* generateIdnoWithTemplate = A template to use when setting the idno. The template is a value with automatically-set SERIAL values replaced with % characters. Eg. 2012.% will set the created row's idno value to 2012.121 (assuming that 121 is the next number in the serial sequence.) The template is NOT used if idno is passed explicitly as a value in $pa_values.
* importEvent = if ca_data_import_events instance is passed then the insert/update of the collection will be logged as part of the import
* importEventSource = if importEvent is passed, then the value set for importEventSource is used in the import event log as the data source. If omitted a default value of "?" is used
* log = if KLogger instance is passed then actions will be logged
*/
static function getCollectionID($ps_collection_name, $pn_type_id, $pn_locale_id, $pa_values = null, $pa_options = null)
{
if (!is_array($pa_options)) {
$pa_options = array();
}
if (!isset($pa_options['outputErrors'])) {
$pa_options['outputErrors'] = false;
}
$pb_match_on_idno = caGetOption('matchOnIdno', $pa_options, false);
$t_collection = new ca_collections();
if (isset($pa_options['transaction']) && $pa_options['transaction'] instanceof Transaction) {
$t_collection->setTransaction($pa_options['transaction']);
}
$o_event = isset($pa_options['importEvent']) && $pa_options['importEvent'] instanceof ca_data_import_events ? $pa_options['importEvent'] : null;
$vs_event_source = isset($pa_options['importEventSource']) && $pa_options['importEventSource'] ? $pa_options['importEventSource'] : "?";
$o_log = isset($pa_options['log']) && $pa_options['log'] instanceof KLogger ? $pa_options['log'] : null;
if (!($vs_idno = isset($pa_values['idno']) ? (string) $pa_values['idno'] : null)) {
if (isset($pa_options['generateIdnoWithTemplate']) && $pa_options['generateIdnoWithTemplate']) {
$vs_idno = $t_collection->setIdnoTWithTemplate($pa_options['generateIdnoWithTemplate'], array('dontSetValue' => true));
}
}
$va_find_arr = array();
if ($pn_type_id) {
$va_find_arr['type_id'] = $pn_type_id;
}
if ($pn_parent_id) {
$va_find_arr['parent_id'] = $pn_parent_id;
}
if (!($vn_id = ca_collections::find(array_merge(array('preferred_labels' => array('name' => $ps_collection_name)), $va_find_arr), array('returnAs' => 'firstId', 'transaction' => $pa_options['transaction'])))) {
if ($pb_match_on_idno && $vs_idno) {
$va_find_arr['idno'] = $vs_idno;
$vn_id = ca_collections::find($va_find_arr, array('returnAs' => 'firstId', 'transaction' => $pa_options['transaction']));
}
}
if (!$vn_id) {
if (isset($pa_options['dontCreate']) && $pa_options['dontCreate']) {
return false;
}
if ($o_event) {
$o_event->beginItem($vs_event_source, 'ca_collections', 'I');
}
$t_collection->setMode(ACCESS_WRITE);
$t_collection->set('locale_id', $pn_locale_id);
$t_collection->set('type_id', $pn_type_id);
$t_collection->set('source_id', isset($pa_values['source_id']) ? $pa_values['source_id'] : null);
$t_collection->set('access', isset($pa_values['access']) ? $pa_values['access'] : 0);
$t_collection->set('status', isset($pa_values['status']) ? $pa_values['status'] : 0);
$t_collection->set('idno', $vs_idno);
$t_collection->set('parent_id', isset($pa_values['parent_id']) ? $pa_values['parent_id'] : null);
$t_collection->insert();
if ($t_collection->numErrors()) {
if (isset($pa_options['outputErrors']) && $pa_options['outputErrors']) {
print "[Error] " . _t("Could not insert collection %1: %2", $ps_collection_name, join('; ', $t_collection->getErrors())) . "\n";
}
if ($o_log) {
$o_log->logError(_t("Could not insert collection %1: %2", $ps_collection_name, join('; ', $t_collection->getErrors())));
}
return null;
}
$vb_label_errors = false;
$t_collection->addLabel(array('name' => $ps_collection_name), $pn_locale_id, null, true);
if ($t_collection->numErrors()) {
if (isset($pa_options['outputErrors']) && $pa_options['outputErrors']) {
print "[Error] " . _t("Could not set preferred label for collection %1: %2", $ps_collection_name, join('; ', $t_collection->getErrors())) . "\n";
}
if ($o_log) {
$o_log->logError(_t("Could not set preferred label for collection %1: %2", $ps_collection_name, join('; ', $t_collection->getErrors())));
}
$vb_label_errors = true;
}
unset($pa_values['access']);
unset($pa_values['status']);
unset($pa_values['idno']);
unset($pa_values['source_id']);
$vb_attr_errors = false;
if (is_array($pa_values)) {
foreach ($pa_values as $vs_element => $va_value) {
if (is_array($va_value)) {
// array of values (complex multi-valued attribute)
$t_collection->addAttribute(array_merge($va_value, array('locale_id' => $pn_locale_id)), $vs_element);
} else {
// scalar value (simple single value attribute)
if ($va_value) {
$t_collection->addAttribute(array('locale_id' => $pn_locale_id, $vs_element => $va_value), $vs_element);
}
}
}
}
$t_collection->update();
if ($t_collection->numErrors()) {
if (isset($pa_options['outputErrors']) && $pa_options['outputErrors']) {
print "[Error] " . _t("Could not set values for collection %1: %2", $ps_collection_name, join('; ', $t_collection->getErrors())) . "\n";
}
if ($o_log) {
$o_log->logError(_t("Could not set values for collection %1: %2", $ps_collection_name, join('; ', $t_collection->getErrors())));
}
$vb_attr_errors = true;
}
$vn_collection_id = $t_collection->getPrimaryKey();
if ($o_event) {
if ($vb_attr_errors || $vb_label_errors) {
$o_event->endItem($vn_collection_id, __CA_DATA_IMPORT_ITEM_PARTIAL_SUCCESS__, _t("Errors setting field values: %1", join('; ', $t_collection->getErrors())));
} else {
$o_event->endItem($vn_collection_id, __CA_DATA_IMPORT_ITEM_SUCCESS__, '');
}
}
if ($o_log) {
$o_log->logInfo(_t("Created new collection %1", $ps_collection_name));
}
if (isset($pa_options['returnInstance']) && $pa_options['returnInstance']) {
return $t_collection;
}
} else {
if ($o_event) {
$o_event->beginItem($vs_event_source, 'ca_collections', 'U');
}
$vn_collection_id = $vn_id;
if ($o_event) {
$o_event->endItem($vn_collection_id, __CA_DATA_IMPORT_ITEM_SUCCESS__, '');
}
if ($o_log) {
$o_log->logDebug(_t("Found existing collection %1 in DataMigrationUtils::getCollectionID(); total of %2 collections were found", $ps_collection_name, sizeof($va_collection_ids) + 1));
}
if (isset($pa_options['returnInstance']) && $pa_options['returnInstance']) {
return new ca_collections($vn_collection_id);
}
}
return $vn_collection_id;
}
