Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current  |   View Page History

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Zend_Validate_Builder, Zend_Filter_Builder Component Proposal

Proposed Component Name Zend_Validate_Builder, Zend_Filter_Builder
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/Zend_Validate_Builder, Zend_Filter_Builder
Proposers Bryce Lohr
Revision 0.2 (wiki revision: 42)

Table of Contents

1. Overview

I'd like to propose an alternative to the Zend_Filter_Input proposal. Bill Karwin and others have put a lot of time and energy into that work, and I'd like to take this opportunity to thank them. This work is built upon those, and I'd like to acknowledge that up front.

This proposal is inspired by Christopher Thompson's original Zend_FilterChain proposal, and provides a similar interface. This is quite a different tact than the array-based structure used by Zend_Filter_Input; some people may find this interface preferable.

I actually propose quite a bit of change here. Here's a quick rundown to get started:

  • Zend_Filter_Builder and Zend_Validate_Builder classes
  • Facades providing a fluent interface for both Builder classes
  • An Error Manager class to faciliate configuring error messages for many validators at once

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • Zend_Validate_Builder manages exactly one responsibility: validating sets of data in arrays
  • Zend_Filter_Builder manages exactly one responsibility: filtering sets of data in arrays
  • Zend_Validate_Builder_ErrorManager is responsible for defining and reporting error messages for validators
  • Neither component handles any other aspect of form processing
  • No mechanism for statically calling filters or validators is provided (out of scope)
  • The solution in this proposal is not designed to make using the existing filters and validators more convenient for quickly checking one value; it's geared toward easily handling a lot of data at once
  • Thanks to the pre-1.0 changes to the Zend_Validate_* classes with regards to error messages, this proposal works with the existing validation API as-is.

4. Dependencies on Other Framework Components

  • Zend_Validate_Interface
  • Zend_Filter_Interface
  • Zend_Validate_*
  • Zend_Filter_*
  • Zend_Validate_Exception

5. Theory of Operation

Essentially, Zend_Validate_Builder and Zend_Filter_Builder use the Builder and Composite patterns to construct a recursive tree structure of Zend_Validate_* or Zend_Filter_* instances, which is then applied wholesale to an array of input data. In the case of Zend_Filter_Builder, the result is the original input array after having each of the constituent filters applied to each input array element. In the case of Zend_Validate_Builder, the result is a boolean value indicating whether any single element in the input data was deemed invalid by any of the constituent Zend_Validate_* instances.

In addition to the Builder classes, I also propose Zend_Validate_Builder_FluentFacade and Zend_Filter_Builder_FluentFacade. These classes provide a very elegant and easy to use fluent interface to the Builder classes, and their use is totally optional. The Builder classes in no way depend on these.

Error messages are a vital part of data validation. If your code decides that something the user entered is not acceptable, you must be able to tell the user why. To that end, I propose a Zend_Validate_Builder_ErrorManager class. This class provides a way for the Zend_Validate_* classes, Zend_Validate_Builder, and your application code to define and communicate errors. The Zend_Validate_* classes all have built-in error messages which, for a variety of reasons, are often not suitable to display directly to users. Therefore, the error messages for validators can be overridden. However, this can only be done on an individual, validator-by-validator basis. Zend_Validate_Builder_ErrorManager allows you to define all the error messages for any arbitrary set of validators, by data field. This way, you can easily set up each error message for a field, and also easily retreive any error messages by field for display.

6. Milestones / Tasks

  • Milestone 1: [DONE] Design interface and test feasibility
  • Milestone 2: [DONE] Write proposal
  • Milestone 3: [IN PROGRESS] Gather feedback and revise design as necessary
  • Milestone 4: [IN PROGRESS] Develop full implementation and unit tests
  • Milestone 5: Write documentation

7. Class Index

  • Zend_Validate_Builder
  • Zend_Validate_Builder_FluentFacade
  • Zend_Validate_Builder_FluentAdder
  • Zend_Validate_Builder_ValidatorFactory
  • Zend_Validate_Builder_ValidatorFactory_Interface
  • Zend_Validate_Builder_ErrorManager
  • Zend_Validate_Builder_ErrorManager_Interface
  • Zend_Filter_Builder
  • Zend_Filter_Builder_FluentFacade
  • Zend_Filter_Builder_FluentAdder
  • Zend_Filter_Builder_FilterFactory
  • Zend_Filter_Builder_FilterFactory_Interface

8. Use Cases

For all of these use cases, assume that the code shown is extracted from a valid Action Controller method that is processing a form with the intention of saving the data to the database. Assume that methods referenced after $this-> exist and are valid. In most of these examples, I refer to Zend_Validate_* classes that don't currently exist; for now assume that they do. I plan to add a separate proposal for some new validators that would work well with this proposal, as well as being useful in general.

UC-01

Some very basic examples. First, Zend_Filter_Builder:

This filters out all non-digit characters from the phone_no field, and strips HTML tags from the description field. The filter() method takes an array of data, and runs the specified filters on the matching keys.

Next, Zend_Validate_Builder:

Here, the phone_no field is checked to make sure it's numeric, and description field is checked to make sure it's less than 255 characters long. Since the Zend_Validate_* classes will usually fail an empty value, all fields are required by default. The addValidator method takes an optional third argument, which are flags for that specific field. We're passing the OPTIONAL flag for the description field, so Zend_Validate_Builder will skip over it when it's empty, and the StringLength validator will never see it unless it has a value.

Note the phone_no example: the order the validators are added to the field is preserved; that is, the IsNumeric validator will be run before the Between validator. All the validators assigned to a field will always be executed. Therefore, a single field might generate several error messages, depending on how many validators it fails. Since these error messages are built up in the Error Manager object, your application code can decide which errors to display to the user; you need not display all of them.

UC-02

This demonstrates a little more advanced usage.

Globbing:

Supported Meta-characters
I currently only have support for the '*' meta-character for globbing. However, it's fairly straight-forward to expand the support for more complex matching, including using regular expressions to pick which fields to match. In this implementation, using '*' is semantically equivilent to manually specifying every field in the top level input array.

Grouping:

UC-03

Password confirmation, catpcha validation, etc. This uses the (currently) fictional Zend_Validate_Equals, which validates that the input value is equal to the value given to the constructor. I propose that we add such a validator to the core distribution.

Password Confirmation:

Catpcha validation:

UC-O4

Since this follows the Composite pattern, you can nest validators to do some neat things. In this example, assume we're trying to validate a mailing address. Suppose, for organizational purposes, you structured the form so the mailing address was in a sub-array, something like this:

You could validate this nested structure like so:

If you have a situation where the entire address is optional (therefore if any one field is given, they must all be valid; otherwise it's valid if they're all blank), you might be temped to pass the OPTIONAL flag to the address field. However, that won't work: when the OPTIONAL flag is set, the Builder checks the value of the current field, and if it's blank, the Builder never calls the validator. In this situation, the current field would be an array with six elements; even though each element could have an empty value, the array itself won't ever be considered an empty value. Therefore, the entire address field will always be validated against the sub-validator. In this situation, what you actually need is conditionally optional fields, based on whether or not other fields are valid, which requires completely different logic.

UC-05

In order to handle a situation like the optional address mentioned above, you'd need something like this. This uses another fictional validator called Zend_Validate_AllOrNone. It allows you to do some limited conditional requirement of fields: you pass it a set of fields, and if all of them are empty, or if all of them are filled, then it considers the set valid. If only some are filled, then it considers the set invalid. The example may clarify things a bit. I plan on adding this validator to a separate validators proposal, since it seems useful for a variety of situations.

Here, the OPTIONAL flag is passed to all the validators after the AllOrNone validator. This is so those validators don't fail the field in the case when the field is omitted (the fields are still opitonal; albeit conditionally optional).

UC-06

Here are some examples that demonstrate some of the neat things that can be done with custom validators that act as Decorators for other valiators. I may add some of these to a separate proposal for additional validators. Keep in mind that a Zend_Validate_Builder instance counts as a validator that can be decorated; if you're creative, you can probably come up with some really cool things to do with this.

Zend_Validate_Array
Most validators take a scalar value to isValid(), and perform checks on that. Zend_Validate_Array takes another validator passed to the constructor, and an array value to isValid(). It will iterate over all the elements of the array, performing the given validator on each one. Obviously, you could nest these as much as you needed to, provided that you know the structure of the input array ahead of time.

Zend_Validate_Switch
Acts like a data-driven switch statement. The constructor takes an associative array of validator instances. The field value passed to its isValid() method is used as the key to look up which validator to run in the array passed to the constructor. This way you can attach different validations to fields based on what the user selects at runtime.

Zend_Validate_AtLeastNofM and Zend_Validate_AtMostNofM
These two are complements of each other, and do basically the same thing. Their constructors take three arguments: a threshold number, a total count, and a validator instance. Basically, they determine whether at least, or at most, n fields of the m total pass the given validator. It's easier to understand by seeing it:

Granted, it's hard to come up with a real-world use-case for this, but it's a good example of the creative things you can do. Also remember that you don't have to always use these two together as I have here.

UC-07

I used to build forms that mimiced my table structure, with the ability to edit multiple records for multiple tables in one form. In this example, assume we want to validate a CRUD form for a simple contact table, but the user can add multiple contacts on the form (maybe with the help of some Javascript like WForms). The form fields are laid out in a three-dimensional array, where the first key is the table name, the second key is the row number, and the third key is the field name. It would result in post data that looks something like this:

Assume that the user actually entered several contacts, so the 'contacts' array would have several sub-arrays, one for each record, just like a result set.

Here's how to set up a filter/validator that would process all of the records:

UC-08

Up to now, any field that failed a validator's test would result in the validator's built-in error message being reported. This shows how to use the Error Manager to define custom error messages and retrieve raised errors.

The Zend_Validate_Interface interface defines the methods getMessages and getErrors, which when used with the standard Zend_Validate_* classes, return either all the error messages raised by the validator, or the codes for the raised errors, respectively. Since Zend_Validate_Builder adheres to this interface, it implements these methods, which you can use to retrieve all the error messages that have been raised during the entire validation run. Internally, it delegates this work to the Error Manager; so for retrieving messages, you don't really ever need to directly touch it. You only need to access the Error Manager directly when you want to use it set up custom error messages, or want more control over which errors are returned.

Normally, calling getMessages on a validator returns a flat array of error messages. But because the Builder manages a whole collection of fields and validators, it can't be completely compatible with the return value of this method. Instead, it returns a three-dimensional array, indexed by field name, validator class name, and failure reason code. It would look something like this:

It should be mentioned that the Error Manager provides the methods getErrors and hasErrors for more granular access to the set of raised errors.

One key benefit of all this is that it allows you to completely separate your error messages from the code that does validation. You could put all your messages in a separate file, or use a Zend_Config object to load all the error messages for a form at once. Among other things, this should make I18N/L10N for your forms much easier.

Here's one possible way to store errors in an INI file, and set them via Zend_Config. The setMessages method makes this possible, since it accepts an entire array structure of error messages.

errors.ini

someController.php

UC-O9

The next two use cases are more real-world. I'm writing a financial system which consists of individual applications for General Ledger, Accounts Payable, Accounts Receiveable, etc., along with some applications, such as Privilege Licenses, which are designed for local governments. These examples are adapted from some of the Privilege Licenses code (obviously, it's not the actual application code).

In these classes, I've omitted all but the validate() method for the sake of clarity. Assume the missing methods exist and are valid.

UC-10

This is from a form that allows entry of new License Codes. There are quite a few complex validation requirements on this form. The amount and rate_schedule fields are mutually exclusive. There are seven account number fields, where each account number field actually consists of two fields: one for the Entity (Company) and one for the Account Number. Account numbers are only valid by Entity.

The seven account fields have several complex requirements. The Cash and Revenue accounts are always required. The Due To and Due From accounts are required only if the Cash Ent and Revenue Ent are different, or (if given) the Cash Ent and AR Ent are different. If present, the Cash Ent and Due To Ent must match each other, and the AR Ent, Reserve AR Ent, Due From Ent, and Prepaid Ent must all match.

UC-11

The fluent interface. This demonstrates the fluent Facade by re-writing UC-08. A lot of the "fluency" of the interface depends quite a bit on the naming of the filter and validator classes.

UC-12

This is UC-09 re-written with the fluent Facade. In order to instantiate filter and validator classes, the fluent Facades have to somehow prepend the "namespace" part of the class name to the "base name" of the class. The Facades utilize a Factory to acheive this. The Facades will automatically create the Factory themselves, if one isn't assigned. You can pass an options array to the Facades' constructors, containing a list of namespaces the Factory should search. You can also create and configure the Factory yourself, then assign the Factory to the Facade. The default Factory also puts the Zend_Validate_ namespace at the end of the list, so it never needs to be manually specified.

UC-13

And finally, the big one, re-written with the fluent Facade. A bit less big now.

Namespaces and Class names
The factories used by the fluent Facades attempt to find classes by searching through an array of namespace prefixes. If you have filter or validator classes with the same "base name" in two different namespaces, only the first one found will be returned. There's no way to pick which namespace to use on a call-by-call basis. You can easily replace the factories with your own in order to implement different instantiation rules. The standard Builder classes are not affected by this problem.

9. Class Skeletons

Zend_Validate_Builder

Zend_Validate_Builder_FluentFacade

Zend_Validate_Builder_FluentAdder

Zend_Validate_Builder_ValidatorFactory

Zend_Validate_Builder_ValidatorFactory_Interface

Zend_Validate_Builder_ErrorManager

Zend_Validate_Builder_ErrorManager_Interface

Zend_Filter_Builder

Zend_Filter_Builder_FluentFacade

Zend_Filter_Builder_FluentAdder

Zend_Filter_Builder_FilterFactory

Zend_Filter_Builder_FilterFactory_Interface

]]></ac:plain-text-body></ac:macro>

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.