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

Why Build a Framework?

Frameworks are useful for many reasons. Below is a short list of some of the most common benefits of developing a business objects framework.  For an exhaustive presentation on the rationale for using frameworks as well as a complete discussion of the design of a complete framework, I recommend Expert C# 2008 Business Objects.

• Separation of Concerns – Code for the business logic and persistence details may exist in one or more layers.  This keeps database concerns and business logic out of the UI code.  A layered architecture makes it easier to build a variety of user interfaces for the same code base.
• Specialization of Tasks -   The layered architecture allows people on a team to work on the programming tasks for which they are most suited.  I am a terrible web developer.  I like the fact that I can build a robust core and let the people with black turtlenecks put a slick user interface on top of it.  It is also a relief to designers that they can concentrate on the interface and use a simple, clean API which has been prepared for them by the core programmers.
• Coding Standards – Frameworks set a good example by helping to establish coding style and methods for all of the developers on a team.  Even when working alone, the establishment of styles and patterns is very helpful and increases productivity.
• Collaboration – All of the above items result in better collaboration in a team environment.  It is easy to get help from others when you have a clean and easy to follow code base.  New trainees also get up to speed a lot faster in the presence of a framework.  This builds confidence very early for new people and it also means that they are actually helping out on day one.
• Code Generation – Established style and methodology make it easy to generate a significant percentage of your boring, boiler plate, error prone work using a code generation tool.  It is fairly easy to write code generation tools and there are a few really nice free tools to do the job as well.  We’ll get in to this in other articles.

What Will Our Framework Do?

The framework we are going to design will take care of the following tasks.

• CRUD - Creation, Retrieval, Update and Deletion of records in the database.
• Validation – Our objects will be self validating.  All validation rules for fields and business logic for the entities will be represented as classes.

Our framework will be implemented in one layer.  I am creating the framework for use with the Wordpress blogging system, so I’ll make use of some of the nice database features built in to Wordpress.  The framework may be used outside the Wordpress environment by including the proper files which allow use of $wpdb.  For more information of $wpdb, go here.  Of course, you could use another database.  It is also possible to separate the actual data access code into another suite of classes.  This takes a lot of extra work, but it does allow you to swap out your database technology without changing the rest of your code. This approach makes sense if you might switch database platforms.

Before we continue and actually build the framework, we should give it a name. I am tired of typing “the framework”.  For a working title, let’s call it Monkey Wrench. My wife, Jana, is rather fond of monkeys, so I’m sure she would approve.

Coming Up. Building Monkey Wrench

In the next article, we will begin building the Monkey Wrench framework.  See you next time!

Also Available in This Series

• Building Monkey Wrench – The Rule Classes
• Creating a String Range Rule with Monkey Wrench