Abstract handler for data writing.
Data writers focus on writing a unit of data to the database, including verifying all data to the application rules (including those set by the owner) and doing denormalized updates as necessary.
The writer may also interact with the cache, if required.
| package | XenForo_Core |
|---|
__construct(\constant $errorHandler, array $inject)
\constantError handler. See {@link ERROR_EXCEPTION} and related.
arraynullDependency injector. Array keys available: db, cache.
bulkSet(array $fields, array $options)
arrayKey-value pairs of fields and values.
arrayOptions to pass into {@link set()}. See {@link $_setOptions}.
create(string $class, \constant $errorHandler, array $inject) : \XenForo_DataWriter
The class must exist or be autoloadable or an exception will be thrown.
stringClass to load
\constantError handler. See {@link ERROR_EXCEPTION} and related.
arraynullDependencies to inject. See {@link __construct()}.
delete() : boolean
booleanTrue on successerror(string | \XenForo_Phrase $error, string | false $errorKey, boolean $specificError)
Depending on the type of error handler chosen, this may throw an exception.
stringfalseUnique key for the error. Used to prevent multiple errors from the same field being displayed.
booleanIf true and error key specified, overwrites an existing error with this name
get(string $field, string $tableName) : mixed
stringField name
stringTable name, if empty loops through tables until first match
mixedReturns null if the specified field could not be found.getError(string $errorKey) : string
string
stringgetErrors() : array
getExisting(string $field, string $tableName) : mixed
Returns null if not set.
stringField name
stringTable name, if empty loops through tables until first match
mixedgetExtraData(string $name) : mixed
string
mixedgetFieldNames($tableName)
getMergedData(string $tableName) : array
This will generally reflect what is in the database.
If no table is specified, all data will be flattened into one array. New data takes priority over existing data, and earlier tables in the list take priority over later tables.
string
arraygetMergedExistingData(string $tableName) : array
string
arraygetMergedNewData(string $tableName)
string
getModelFromCache(string $class) : \XenForo_Model
If it does not exist, it will be instantiated.
stringName of the class to load
getNew(string $field, string $tableName) : mixed
Returns null if not set.
stringField name
stringTable name, if empty loops through tables until first match
mixedgetNewData() : array
arraygetOption(string $name) : mixed
The meaning of this option is completely domain specific. If an unknown option specified, an exception will be triggered.
stringName of the option to get
mixedValue of the optiongetTablesDataFromArray(array $dataArray) : array
In order for this to work, the following must be true: 1) The input array must provide all data that this datawriter requires 2) There can be no overlapping field names in the tables that define this data, unless those fields all store the same value 3) IMPORTANT: If the input array does not include all the required data fields, it is your responsibility to provide it after this function returns.
arrayComplete data record
arraygetUpdateCondition(string $tableName) : string
If there is no existing data, this always returns an empty string, otherwise it proxies to _getUpdateCondition(), which is an abstract function.
stringName of the table to fetch the condition for
stringhasChanges() : boolean
booleanhasErrors() : boolean
booleanisChanged(string $field, string $tableName) : boolean
stringField name
stringTable name, if empty loops through tables until first match
booleanisExtraDataSet(string $name) : boolean
string
booleanisInsert() : boolean
booleanisUpdate() : boolean
booleanmergeErrors(array $errors)
array
preDelete()
Any verification or complex defaults may be set by this.
It is generally not advisable to override this function. If you just want to add pre-delete behaviors, override _preDelete().
preSave()
Any verification or complex defaults may be set by this.
It is generally not advisable to override this function. If you just want to add pre-save behaviors, override _preSave().
save() : boolean
This either updates an existing record or inserts a new one, depending whether setExistingData was called.
After a successful insert with an auto_increment field, the value will be stored into the new data array with a field marked as autoIncrement. Use get() to get access to it.
booleanTrue on successset(string $field, string $value, string $tableName, array $options) : boolean
This value will be updated when save is called.
stringName of field to update
stringValue to update with
stringTable name, if empty then all tables with that column
arrayOptions. See {@link $_setOptions).
booleansetDefaultSetOptions(array $setOptions)
setErrorHandler(integer $errorHandler)
integer
setExistingData(mixed $data, boolean $trustInputAsPrimary) : boolean
This causes the system to do an update instead of an insert. This function triggers an error if no data can be fetched from the provided data.
mixedData that can uniquely ID this item
booleanIf true, trust the passed data to be based on data in DB; if false, the data is used as is (if it's an array)
booleansetExtraData(string $name, mixed $value)
The DW should be able to function without this data.
stringName of the data
mixedValue of the data
setImportMode(\boolean$mode $mode)
When enabled, preSave, postSave, and verification functions are disabled.
\boolean$mode
setOption(string $name, mixed $value)
The meaning of this option is completely domain specific. If an unknown option specified, an exception will be triggered.
stringName of the option to set
mixedValue of the option
updateVersionId(string $versionIdField, string $versionStringField, string $addOnIdField) : integer
Th add-on ID is determined from a previously set value, so it should not be updated after this is called.
stringName of the field the version ID will be written to
stringName of the field where the version string will be written to
stringName of the field the add-on ID is kept in
integerVersion ID to use_applyFieldValueLimits(string $fieldType, mixed $value, array $extraLimits) : boolean | string
Returns true if the field meets the constraints. The passed in value will be modified by reference.
stringType of the field. See the TYPE_* constants.
mixedValue for the field.
arrayExtra constraints
booleanstringEither TRUE or an error message_beginDbTransaction()
_castValueToType(string $fieldType, mixed $value, string $fieldName, array $fieldData) : mixed
stringType to cast to
mixedValue to cast
stringName of the field being cast
arrayArray of all field data information, for extra options
mixed_checkRequiredFieldsForUpdate()
_commitDbTransaction()
_delete()
Actually does the delete.
_deleteMasterPhrase(string $title)
string
_getAutoIncrementField(string $tableName) : string | false
This field is simply the first field tagged with the autoIncrement flag.
stringName of the table to obtain the field for
stringfalseName of the field if found or false_getCache() : \Zend_Cache_Core | \Zend_Cache_Frontend | false
\Zend_Cache_Core\Zend_Cache_Frontendfalse
_getDefaultOptions() : array
This is automatically called in the constructor. If you wish to set options in your data writer, override this function. As this is handled at run time rather than compile time, you may use dynamic behaviors to set the option defaults.
array_getExistingData(mixed $data) : array | false
This data may be a scalar or an array. If it's a scalar, assume that it is the primary key (if there is one); if it is an array, attempt to extract the primary key (or some other unique identifier). Then fetch the correct data from a model.
mixedData that can uniquely ID this item
arrayfalse
_getExistingPrimaryKey(mixed $data, string $primaryKeyField, string $tableName) : string | false
mixedArray of data containing the primary field or a scalar ID
stringPrimary key field, if data is an array
stringTable name, if empty the first table defined in fields is used
stringfalse
_getFields() : array
This should return an array with each key being a table name and a further array with each key being a field in database. The value of each entry should be an array, which may have the following keys: * type - one of the TYPE_* constants, this controls the type of data in the field * autoIncrement - set to true when the field is an auto_increment field. Used to populate this field after an insert * required - if set, inserts will be prevented if this field is not set or an empty string (0 is accepted) * requiredError - the phrase title that should be used if the field is not set (only if required) * default - the default value of the field; used if the field isn't set or if the set value is outside the constraints (if a $_setOption is set) * maxLength - for string/binary types only, the maximum length of the data. For strings, in characters; for binary, in bytes. * min - for numeric types only, the minimum value allowed (inclusive) * max - for numeric types only, the maximum value allowed (inclusive) * allowedValues - an array of allowed values for this field (commonly for enums) * verification - a callback to do more advanced verification. Callback function will take params for $value and $this.
array_getPrimaryTable() : string | false
stringfalseName of the table or false_getSpecificRequiredFieldErrorText(string $tableName, string $field) : false | string | \XenForo_Phrase
Concrete DWs may override this to get nicer error messages for specific fields.
string
string
_getTableList(string $tableName) : array
stringOptional table to limit results to.
array_getUpdateCondition(string $tableName) : string
_haveErrorsPreventSave() : boolean
If the silent error handler is used, errors simply trigger a return of true (yes, we have errors); otherwise, errors trigger an exception. Generally, if errors are to be handled, save shouldn't be called.
booleanTrue if there are errors_insert()
_insertOrUpdateMasterPhrase(string $title, string $text, string $addOnId, array $extra)
Errors will be silently ignored.
string
string
string
array
_isFieldValueValid(string $fieldName, array $fieldData, mixed $value, array $options) : boolean
The value may be modified based on type, contraints, or other verification methods.
stringName of the field.
arrayData about the field (includes type, contraints, callback, etc)
mixedValue for the field
arrayOptions. Uses {@link $_setOptions}.
boolean_performLanguageRebuild()
_postDelete()
_postSave()
This is not called in import mode.
_postSaveAfterTransaction()
This is not called in import mode.
_preDelete()
_preSave()
This is not callbed in import mode.
_preSaveDefaults()
This is still called in import mode.
_renameMasterPhrase(string $oldName, string $newName)
If you get a conflict, it will be silently ignored.
string
string
_resolveDefaultsAndRequiredFieldsForInsert(boolean $checkRequired)
If a required field is not set properly, an error is thrown.
booleanIf true, checks required fields
_rollbackDbTransaction()
_runVerificationCallback(callback $callback, mixed $value, array $fieldData, $fieldName) : boolean
This callback may modify the value if it chooses to. Callback receives 2 params: the value and this object. The callback must return true if the value was valid.
Returns true if the verification was successful.
callbackCallback to run. Use an array with a string '$this' to callback to this object.
mixedValue to verify
arrayInformation about the field, including all constraints to be applied
boolean_save()
Deals with both updates and inserts.
_setAutoIncrementValue(integer $insertId, string $tableName, bool $updateAll) : boolean
If the ID passed in is 0, nothing will be updated.
integerAuto-increment value from 0.
stringName of the table set the auto increment field in
boolUpdate all tables with cross referenced auto increment fields
booleanTrue on update_setInternal(string $table, string $field, mixed $newValue, boolean $forceSet)
Use only when you're sure validation, etc isn't needed. The field will only be set if the value has changed.
stringTable the field belongs to
stringName of the field
mixedValue for the field
booleanIf true, the set always goes through
_setPostSave(string $field, string $newValue, string $tableName, array $options) : boolean
stringName of field to update
stringValue to update with
stringTable name, if empty then all tables with that column
arrayOptions. See {@link $_setOptions).
boolean_triggerInvalidExistingDataError()
This can (and generally should) be extended by concrete DWs to give an error that is more specific to their content type.
_triggerRequiredFieldError(string $tableName, string $field)
string
string
_update()
$_cache : \Zend_Cache_Core | \Zend_Cache_Frontend
$_db : \Zend_Db_Adapter_Abstract
$_errorHandler : integer
See ERROR_EXCEPTION and related.
$_errors : array
This is always populated when an error occurs, though an exception may be thrown as well.
$_existingData : array
This is only populated when updating a record.
$_existingDataErrorPhrase : string
$_extraData : array
The DW should usually function without any data in this array. Any data that DW supports should be documented in this array, preferably by the use of constants.
Required data (for example, a related phrase) can be included here if necessary.
$_fields : array
See _getFields() for more info.
$_importMode : boolean
To be used when using the DW for importing data in bulk. Note that you are responsible for manually replicating the post save effects.
$_modelCache : array
This is now a static cache to allow data to be reused between data writers, as they are often used in bulk.
$_newData : array
$_preDeleteCalled : boolean
It can only be called once.
$_preSaveCalled : boolean
It can only be called once.
$_setOptions : array
Available options are: (default value is listed in parentheses) * ignoreInvalidFields (false) - when true, an invalid field is simply ignored; otherwise an error is triggered * replaceInvalidWithDefault (false) - when true, invalid values are replaced with the default value (if there is one) * runVerificationCallback (true) - when true, verification callbacks are run when setting * setAfterPreSave (false) - when true, you may set data after preSave is called. This has very specific uses.
$_triggerLanguageRebuild : boolean
ERROR_ARRAY : integer
Use this to push errors onto an array. If you try to save while there are errors, an exception will be thrown.
ERROR_EXCEPTION : integer
Use this to trigger an exception when an error occurs.
ERROR_SILENT : integer
Use this to push errors onto an array. If you try to save while there are errors, the save will silently fail. Use this in places where you aren't interested in handling errors.
TYPE_BINARY : string
Use this for binary or ASCII-only fields. Limits will refer to bytes.
TYPE_BOOLEAN : string
Use this for 0/1 boolean integer fields.
TYPE_FLOAT : string
Use this for float fields. Limits can be applied on the range of valid values.
TYPE_INT : string
Use this for integer fields. Limits can be applied on the range of valid values.
TYPE_JSON : string
TYPE_SERIALIZED : string
Ensures that if the data is not a string, it is serialized to ne.
TYPE_STRING : string
Use this for string fields. String fields are assumed to be UTF-8 and limits will refer to characters.
TYPE_UINT : string
Use this for unsigned integer fields. Negative values will always fail to be valid. Limits can be applied on the range of valid values.
TYPE_UINT_FORCED : string
Use this for unsigned integer fields. This differs from TYPE_UINT in that negative values will be silently cast to 0. Limits can be applied on the range of valid values.
TYPE_UNKNOWN : string
Use this for fields that have a type that cannot be known statically. Use this sparingly, as you must write code to ensure that the value is a scalar before it is inserted into the DB. The behavior if you don't do this is not defined!