Validation Rules in your Schema
Created by Everett Griffiths on Oct 25, 2013.
Overview
Your XML schema can define validation rules using nodes in the XML that follow this pattern
<validation> <rule field="$name_of_field" name="$name_of_rule" type="callback|preg_match|xPDOValidationRule" rule="$various" value="$optional_parameter" message="string" /> </validation>
The rule may have have these attributes:
- field: the field's name. (required)
- name: a unique name for this validation rule. You can have multiple validation rules for each field. (required)
- type: can be "callback", "preg_match" or "xPDOValidationRule" (required)
- rule: varies depending on the type. For type=callback, this will be the name of the callback function. For type=preg_match, this will be the regular expression. For type=xPDOValidationRule, a valid child class must be supplied. (required)
- value: an optional argument to pass to the validation functions, e.g. when the type is
xPDOValidationRule
and the rule is a class that extends it. (optional) - message: this is a string describing the the validation rule if it fails. (required)
In MODX 2+, the message field contains a lexicon string which can provide language specific message translations.
<rule field="category" name="preventBlank" type="xPDOValidationRule" rule="xPDOMinLengthValidationRule" value="1" message="category_err_ns_name" />
Regex Validation
Let's take this example from the modChunk schema:
<object class="modChunk" table="site_htmlsnippets" extends="modElement"> <field key="name" dbtype="varchar" precision="50" phptype="string" null="false" default="" index="unique" /> <!-- ... more fields here --> <validation> <rule field="name" name="invalid" type="preg_match" rule="/^(?!\s)[a-zA-Z0-9\x2d-\x2f\x7f-\xff_-\s]+(?!\s)$/" message="chunk_err_invalid_name" /> </validation> </object>
Callback Validation
You can use your own functions for validation purposes by using "callback" as the type -- this relies on PHP's
call_user_func() function. Because the function name is defined in XML where it is impossible to reference an object instance, you can only reference a regular PHP function like my_function
or a static class method, e.g. MyClass::myFunction
. Likewise, you cannot pass parameters to these functions (?).
xPDOValidationRule Validation
This is how you can tie-into the built-in MODX validation rules. See the classes available inside the
core/xpdo/validation/xpdovalidator.class.php
file:
- xPDOMinLengthValidationRule
- xPDOMaxLengthValidationRule
- xPDOMinValueValidationRule
- xPDOMaxValueValidationRule
- xPDOObjectExistsValidationRule
- xPDOForeignKeyConstraint
For example, look a the the rule defined for the
modContentType
<object class="modContentType" table="content_type" extends="xPDOSimpleObject"> <field key="name" dbtype="varchar" precision="255" phptype="string" null="false" index="unique" /> <!-- ... more fields here ... --> <validation> <rule field="name" name="name" type="xPDOValidationRule" rule="xPDOMinLengthValidationRule" value="1" message="content_type_err_ns_name" /> </validation> </object>
Using xPDOValidator
You can use the xPDOValidator to pre-validate the current state of an xPDOObject
or you can allow save()
to call validation (see xPDO::OPT_VALIDATE_ON_SAVE
) itself and fail if validation fails.
An example of pre-validation from MODX Revolution's modObjectCreateProcessor
class:
/* run object validation */ if (!$this->object->validate()) { /** @var modValidator $validator */ $validator = $this->object->getValidator(); if ($validator->hasMessages()) { foreach ($validator->getMessages() as $message) { $this->addFieldError($message['field'],$this->modx->lexicon($message['message'])); } } }
An example of examining the validation messages after save()
failure from MODX Revolution's modError
class:
/* save object and report validation errors */ if (!$this->object->save()) { /** @var modValidator $validator */ $validator = $this->object->getValidator(); if ($validator->hasMessages()) { foreach ($validator->getMessages() as $message) { $this->addFieldError($message['field'],$this->modx->lexicon($message['message'])); } } }
Writing Your Own Validation Rules
If you want to write your own validation rules, you need to create a PHP class file inside of your namespace's model folder for each validation rule you define, e.g. core/components/my_pkg/model/my_pkg/my_validation_rule.class.php
. The name should be all lowercase and include a .class.php
extension. This is how xPDO knows how to find your class file (this is xPDO's "autoload-like" convention).
Let's look at a Custom Resource Class (CRC) that does not want to be nested under other CRC's -- it wants as its parent only the built-in MODX classes (modDocument, a WebLink, etc). Here's its XML schema definition:
And here's the corresponding validation rule from core/components/my_pkg/model/my_pkg/normalparents.class.php
:
validator->object; $xpdo=& $obj->xpdo; $xpdo->log(1, 'Running TaxonomyParents Validation rule'); $validParentClasses = array('modDocument', 'modWebLink', 'modSymLink', 'modStaticResource'); if ($obj->get('parent') === 0 || ($obj->Parent && in_array($obj->Parent->class_key, $validParentClasses))) { $result = true; } if ($result === false) { $this->validator->addMessage($this->field, $this->name, $this->message); } return $result; } }
Suggest an edit to this page on GitHub (Requires GitHub account. Opens a new window/tab).