/**
* Defines a new virtual-column, or update if already defined.
*
* ### Usage:
*
* ```php
* $errors = $this->Users->addColumn('user-age', [
* 'type' => 'integer',
* 'bundle' => 'some-bundle-name',
* 'extra' => [
* 'option1' => 'value1'
* ]
* ], true);
*
* if (empty($errors)) {
* // OK
* } else {
* // ERROR
* debug($errors);
* }
* ```
*
* The third argument can be set to FALSE to get a boolean response:
*
* ```php
* $success = $this->Users->addColumn('user-age', [
* 'type' => 'integer',
* 'bundle' => 'some-bundle-name',
* 'extra' => [
* 'option1' => 'value1'
* ]
* ]);
*
* if ($success) {
* // OK
* } else {
* // ERROR
* }
* ```
*
* @param string $name Column name. e.g. `user-age`
* @param array $options Column configuration options
* @param bool $errors If set to true will return an array list of errors
* instead of boolean response. Defaults to TRUE
* @return bool|array True on success or array of error messages, depending on
* $error argument
* @throws \Cake\Error\FatalErrorException When provided column name collides
* with existing column names. And when an invalid type is provided
*/
public function addColumn($name, array $options = [], $errors = true)
{
if (in_array($name, (array) $this->_table->schema()->columns())) {
throw new FatalErrorException(__d('eav', 'The column name "{0}" cannot be used as it is already defined in the table "{1}"', $name, $this->_table->alias()));
}
$data = $options + ['type' => 'string', 'bundle' => null, 'searchable' => true, 'overwrite' => false];
$data['type'] = $this->_toolbox->mapType($data['type']);
if (!in_array($data['type'], EavToolbox::$types)) {
throw new FatalErrorException(__d('eav', 'The column {0}({1}) could not be created as "{2}" is not a valid type.', $name, $data['type'], $data['type']));
}
$data['name'] = $name;
$data['table_alias'] = $this->_table->table();
$attr = TableRegistry::get('Eav.EavAttributes')->find()->where(['name' => $data['name'], 'table_alias' => $data['table_alias'], 'bundle IS' => $data['bundle']])->limit(1)->first();
if ($attr && !$data['overwrite']) {
throw new FatalErrorException(__d('eav', 'Virtual column "{0}" already defined, use the "overwrite" option if you want to change it.', $name));
}
if ($attr) {
$attr = TableRegistry::get('Eav.EavAttributes')->patchEntity($attr, $data);
} else {
$attr = TableRegistry::get('Eav.EavAttributes')->newEntity($data);
}
$success = (bool) TableRegistry::get('Eav.EavAttributes')->save($attr);
Cache::clear(false, 'eav_table_attrs');
if ($errors) {
return (array) $attr->errors();
}
return (bool) $success;
}
