Darin Boyd Dot Com

This is Part II in a series of articles dedicated to building a business objects framework for the Wordpress environment.  If you haven’t read Part I of the series, please check it out.  Part I introduces the concept of a framework.

Monkey Wrench Core Classes

The following UML diagram shows the basic class structure for the earliest version of our framework.  I’ll go over each class in detail over the next several articles.  This article will focus on dealing with validation rules.

Monkey Wrench Class Diagram

The above diagram isn’t perfect UML.  I have simplified the classes to basic properties and operations for the sake of clarity.  The actual implementation will be more elaborate.  The green classes are abstract.  The blue classes are concrete classes built by inheriting from the base classes.

The Abstract Rule Class

As mentioned in Part I of this series of articles, part of Monkey Wrench’s charter is to provide built in validation of our business objects.  We will need a way to represent a validation rule for our objects.  Validation may take on many forms, so it would be clunky to try and create a one-size-fits-all rule class.  Instead, let’s create an abstract base class from which to create rule classes that will do their own work.  Over time, you can build a nice library of validators and use them in your projects.  Custom one-off rule classes may be created for elaborate, specific validation tasks that are unique to a specific object.

Our Rule object should inform the user about the particulars of a validation or business rule.  It should also take in some parameters and evaluate the object.

Properties of the Rule Class

• Name - A unique name to identify the Rule instance in a list.  Example:  “Last Name Length”
• DisplayText – A full description of the Rule to be displayed in the User Interface at run time.  Example:  “Last Name must be at least 5 characters in length.”
• PropertyName - Name of the property of our business object to which the validation rule instance is attached.  Example:  “LastName”.

Operations of the Rule Class

• IsValid() – Returns the result of the validation.
• SetRuleValue() – Allows for the manual setting of the IsValid() value.  We’ll need this sometimes, but most often our Rule subclass will take care of setting this value.
• Validate() – An abstract method to be implemented by the subclasses.  This is where the object performs the actual validation.  The object to validate is passed in as a parameter to the Validate() method.

The Rule Class Implementation

The source file for the the entire framework may be downloaded here.  We’ll be looking at the Rule.php file.

This following section of code defines our abstract base class and a few protected member variables which may be accessed by our concrete subclasses.  All of the variables were explained earlier with the exception of the m_PropertyValue variable.  The m_PropertyValue variable is used to contain the actual data represented by the PropertyName on the object which is being validated.  So, if you have an object called Person with a LastName property, our subclass would fetch the value stored in Person->LastName and store that value in m_PropertyValue.

Notice that I am using JavaDoc style comments here.  The Doygen documentation tool can generate API documents from these comments.  This is a personal preference, but a useful artifact in your code if you want good documentation.  IDE’s such as PHPEclipse read these comments in real time and give you more feedback as to what your functions do with tooltips and prompts.

Also, I preface the class level variables with an “m_”.  I do this so that it is easy to tell the scope of the variable when you are down in a function.  Modern IDE’s like PHPEclipse make it easier to track down where a variable is declared.  Having a convention for scope is very handy when you don’t have a fancy IDE.

1
2
3
4
5
6
7
8
9
10
11
12

<?php
/**
 * Class representing a business or validation rule. *
 */
abstract class Rule
{
	// Member Variables
	protected $m_Name = '';
	protected $m_DisplayText = '';
	protected $m_PropertyName = '';
	protected $m_PropertyValue = '';
	protected $m_IsValid = false;

The next section has  the “getters” and “setters” one would expect in Java and other curly brace languages.  It is times like these when I really miss C#.  Maybe one day PHP will have properties.  For the Rule class, this is not required, but I’m trying to keep reasonable form here.

15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

	// Public State Methods
 
	/**
	 * Unique Name for the rule.
	 *
	 * @return string
	 */
	public function GetName()
	{
		return $this->m_Name;
	}
 
	/**
	 * Sets unique Name for the rule.
	 *
	 * @param string $value
	 */
	public function SetName($value)
	{
		$this->m_Name = $value;
	}
 
	/**
	 * Name of the Property to be validated.
	 *
	 * @return string
	 */
	public function GetPropertyName()
	{
		return $this->m_PropertyName;
	}
 
	/**
	 * Sets the name of the Property to be validated.
	 *
	 * @param string $value
	 */
	public function SetPropertyName($value)
	{
		$this->m_PropertyName = $value;
	}
 
	/**
	 * Display text for the rule.
	 * Used to notify the user of the exact purpose of the rule.
	 *
	 * @return string
	 */
	public function GetDisplayText()
	{
		return $this->m_DisplayText;
	}
 
	/**
	 * Sets Display text for the rule.
	 *
	 * @param string $value
	 */
	public function SetDisplayText($value)
	{
		$this->m_DisplayText = $value;
	}

In the last bit of code, we have the IsValid() and SetRuleValue() methods described earlier in the article.  There is also a constructor and an abstract declaration for the Validate() method.

78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

	/**
	 * Indicates whether or not the rule has passed validation.
	 *
	 * @return boolean
	 */
	public function IsValid()
	{
		return $this->m_IsValid;
	}
 
	/**
	 * Sets the value of the IsBroken member variable
	 * to the parameter value
	 *
	 * @param  boolean $value
	 */
	public function SetRuleValue($value)
	{
		$this->m_IsValid = $value;
	}
 
	// Constructors
 
	/**
	 * Constructor: sets name and display text.
	 *
	 * @param  string $_name;
	 * @param  string $_displayText;
	 * @param  string $_propertyName;
	 */
	public function __construct($_name, $_propertyName, $_displayText)
	{
		$this->m_Name = $_name;
		$this->m_PropertyName = $_propertyName;
		$this->m_DisplayText = $_displayText;		
	}
 
 
	// Abstract Methods
 
	public abstract function Validate($_objectToValidate);
 
}
?>

Although our code doesn’t do very much, we have laid a reasonable foundation from which to build validators.  In the next article, we will use the Rule class to build a validator for string ranges.  Frameworks aren’t the most exciting things to read about, but I promise that you’ll be able to see the payoff if you hang in there with me.

Also Available in This Series

• A Business Objects Framework for Wordpress
• Creating a String Range Rule with Monkey Wrench

Programming, Wordpress Monkeywrench, Programming, Wordpress