How to validate Magento configuration values format?

Magento provides a very easy way to use API to set up configurations values. But really often, in additionnal packages you may develop, expected format is not checked before submitting configuration. You added a text field to allow entereing a webservice URL and can enter only numerics in this field ? Why ?

How to set up a validator for my configuration text field?

This is very easy: we must only add the appropriate css class to our configuration field. All is done in the system.xml file. Take a look at the example: Here’s an example in Magento configuration which validates a field value as an email value:

If we provide an unexpected value, we have an error before submitting post:

Here’s an example of an email format validation for the trans_email/ident_custom1/email configuration value: we must only define <validate> XML node and set up the validation class we want for our field

After rendering, we have the following output:

A new css has been added to our input field. Before submitting, Magento will check this CSS and run the appropriate validation.

It’s fine isn’t it? But how can we define our validator?

Embbeded configurations values validator in Magento

First, let’s look at the embedded validators. They are numerous. You can fiund them in the js/prototype/validation.js file

  • validate-select
  • required-entry
  • validate-number
  • validate-digits
  • validate-digits-range
  • validate-alpha
  • validate-code
  • validate-alphanum
  • validate-street
  • validate-phoneStrict
  • validate-phoneLax
  • validate-fax
  • validate-date
  • validate-email
  • validate-emailSender
  • validate-password
  • validate-admin-password
  • validate-cpassword
  • validate-url
  • validate-clean-url
  • validate-identifier
  • validate-xml-identifier
  • validate-ssn
  • validate-zip
  • validate-zip-international
  • validate-date-au
  • validate-currency-dollar
  • validate-one-required
  • validate-one-required-by-name
  • validate-not-negative-number
  • validate-new-password
  • validate-greater-than-zero
  • validate-zero-or-greater
  • validate-cc-number
  • validate-cc-type-select
  • validate-cc-exp
  • validate-cc-cvn
  • validate-ajax
  • validate-css-length
  • validate-length
  • validate-percents
  • validate-cc-ukss

Very interesting list isn’t it?

Can we use multiples validators for one field?

The answer is yes. If we check the class which convert your system.xml in a pretty form (Mage_Adminhtml_Block_System_Config_Form), this class takes the <validate> field content and appends its value to the CSS class field.

So if you want to add multiples validators to one field, you must separate them by one space

Limitations of validation usage in Magento admin configuration panel

The problem is that we can’t do what we want with the validate XML node:

Only some validators can be used to administrate your configuration values

Yes it’s a shame, but you cannot use all the validators listed above when you set up an administrable configuration value: You can only used those which take one parameter. I let you check which one you can use in admin. The other ones are used in templates and more expected parameters are provided manually

Define its own validator

Damned, my validator is not in the embedded list. I have to define my own validator. No problem, it’s very easy; I’ll take for example what I’ve done for the criteo module MExplained_Criteo (published soon) to validate some Criteo specific variables

Write it’s own validator

Here’s what I’ve done to define my own validators:

First, all these validators must have the following syntax: an identifier, an error message if field value doesn’t validate, and a function which runs the validation.When done, they must be added to global Validation javascript object (loaded by Magento). When javascript is loaded in the page, these validator definitions will be added to the available validation methods and so can be used in submission form if they are defined

Load validator in config admin page

So we just need to load our javascript file in admin configuration page. Very easily with layout:

With that, we have defined our specific validators, loaded them in configuration page and we have provided their usage in our system.xml file. It should work fine 🙂

Just note that you cannot load your new validations methods only for one section or group: if you load js with layout syntax, your new validators can be used in each section / group


Don’t forget to organize correctly your code: if you define some generic validators, perhaps it could be interesting to organize them in one dedicated module to ensure that you can reuse them when you want

This is the client side validation. This does not do the server-side validation. I’ll probably do a little post on this subject in the next few weeks. But with that, we should have the expected submitted data format

Yes I agree with you, these validations are not mandatory. But it improves your administrative panel no? And honestly, how long do you take to write a validator and load it? 5 minutes? 10? Is it comparable to the time spent to resolve a support ticket linked to a wrong configuration value?