The source file for the the entire framework may be downloaded here. We will be covering StringRangeRule.php.

The StringRangeRule Class

Using the abstract base class Rule which we created last time, we will build a class to solve a common validation problem. For the sake of database integrity and business goals, it is common to enforce length restrictions on some of the text properties of an object. Our string range validator can be configured to do the following.

• Set min and max length values so that the string length must fall within the range.
• Set min to zero and provide a max so that the string may be any length not exceeding the max.
• Set max to zero and provide a min so that the string may be any length as long as it is at least min characters in length.

Our class will provide a neat package for handling the tasks on the above list.

Let’s write some code!

 
We begin by using <strong>require_once</strong> to reference the <strong>Rule.php</strong> file containing our base class.  In my setup, the <strong>Rule.php</strong> file is in the same directory as  our new class.  We inherit from <strong>Rule</strong> using the <strong>extends</strong> key word.  We declare the <strong>Min</strong> and <strong>Max</strong> member variables.  These variables are declared as protected so that you could create other classes based on our new class which would have access to the Min and Max member variables.
<pre lang="php">// Public State Methods
 
	/**
	 * Minimum length allowed for string.
	 *
	 * @return number
	 */
	public function GetMin()
	{
		return $this-&gt;m_Min;
	}
 
	/**
	 * Sets minimum allowed length for string.
	 *
	 * @param number $value
	 */
	public function SetMin($value)
	{
		$this-&gt;m_Min = $value;
	}
 
	/**
	 * Maximum length allowed for string.
	 *
	 * @return number
	 */
	public function GetMax()
	{
		return $this-&gt;m_Max;
	}
 
	/**
	 * Sets maximum allowed length for string.
	 *
	 * @param number $value
	 */
	public function SetMax($value)
	{
		$this-&gt;m_Max = $value;
	}

The code above contains “getters and setters” for our member variables. Notice that I am documenting these methods per our discussion about coding style and documentation in the first article.

	// Constructors
 
	/**
	 * Constructor
	 * @param string $_ruleName
	 * @param string $_propertyName
	 * @param string $_min
	 * @param string $_max
	 *
	 */
	public function __construct($_ruleName, $_propertyName, $_min, $_max)
	{
		parent::__construct($_ruleName, $_propertyName, '');
 
		$this->m_Min = $_min;
		$this->m_Max = $_max;
 
		// check the max and min values
		$this->CheckValues();
 
		// set the display text
		$this->CalculateDisplayText();
 
	}

The constructor above takes in the rule name and property names, as does our base class, and adds two new parameters representing the min and max values for our new class. We call the constructor on the base class in line 70 using the parent::_construct() method and passing along the rule name and property name values. Values for Max and Min are then assigned based on the appropriate parameter values. In lines 76 and 79, we call helper functions in our class to check for proper min and max values and to construct a good user description based on the values for min and max.

// Overrides
 
	public function Validate($_objectToValidate)
	{
		// Check the values again to make sure the rule is set up properly.
 
		$_MethodName = 'Get' . $this->m_PropertyName;
		$this->m_PropertyValue = $_objectToValidate->$_MethodName();
 
		$this->CheckValues();
 
		$_MinOnly = $this->m_Min > 0 && $this->m_Max == 0;
		$_MaxOnly = $this->m_Max > 0 && $this->m_Min == 0;
		$_MaxAndMin = $this->m_Min > 0 && $this->m_Max > 0 && $this->m_Min < $this->m_Max;
		$_Len = strlen($this->m_PropertyValue);
 
		if($_MinOnly == true)
		{
			$this->m_IsValid = $_Len >= $this->m_Min;
			return;
		}
 
		if($_MaxOnly == true)
		{
			$this->m_IsValid = $_Len <= $this->m_Max;
			return;
		}
 
		if($_MaxAndMin == true)
		{
			$this->m_IsValid = ($_Len >= $this->m_Min)
			&& ($_Len <= $this->m_Max);
 
			return;
		}
 
	}

We arrive at our only override from the Rule base class in line 84. We declared this method to be abstract in the Rule base class, so we are required to implement the method in our new class. In line 91, we set out to get the value of the correct property from the object which has been passed in. Since we are using a convention of “getters and setters”, we can construct the proper “get” call to grab the value from the object. For example, if our rule is set to validate the LastName of a Person object at runtime, the call to get that value would be GetLastName(). Another call is placed to CheckValues() to make sure that the values are still good. We do this because the object could have been edited with the interface methods since the initial call to the constructor. Lines 96 to 99 create member variables representing how the object has been configured based on the min and max values. The length of the property value is recorded for comparison to the min and max values. Lines 101 to 119 set the m_IsValid variable for the correct configuration scenario.

	// Helper Methods
 
	/**
	 * Figures out how to display the rule text to the user based on the
	 * values of Min and Max.
	 *
	 */
	private function CalculateDisplayText()
	{
		if($this->m_Min == 0 && $this->m_Max > 0)	// we have a rule where only the max has been set
		{
			$this->m_DisplayText = $this->m_PropertyName . ' may be no longer than ' . $this->m_Max . ' characters in length.';
		}
 
		if($this->m_Min > 0 && $this->m_Max == 0)	// we have a rule where only the min has been set
		{
			$this->m_DisplayText = $this->m_PropertyName . ' must be at least ' . $this->m_Min . ' characters in length.';
		}
 
		if($this->m_Min > 0 && $this->m_Max > 0 && $this->m_Min < $this->m_Max)	// we have a rule where min and max have been set
		{
			$this->m_DisplayText = $this->m_PropertyName . ' must be between ' . $this->m_Min . ' and ' . $this->m_Max . ' characters in length.';
		}
	}
 
	/**
	 * Checks values for min and max set by the programmer.
	 * Min must be less than max if max is greater than zero.
	 * Max must be greater than min if min is greater than zero.
	 * Neither may be a negative number.
	 * Both values may not be equal to zero at the same time.
	 *
	 */
	private function CheckValues()
	{
		// check for negative values
		if($this->m_Min < 0 || $this->m_Max < 0)
		{
			throw new Exception('Min or Max values may not be less than zero.');
		}
 
		// check for double zeros.
		if($this->m_Min == 0 && $this->m_Max == 0)
		{
			throw new Exception('Min or Max values may not both be set to zero.');
		}
 
		// check for min less than max when max is set
		if($this->m_Max > 0 && $this->m_Min >= $this->m_Max)
		{
			throw new Exception('If Max is set to a non zero number, Min must be less than Max.');
		}
 
		// check for max greater than min when min is set
		if($this->m_Min > 0 && $this->m_Max <= $this->m_Min && $this->m_Max != 0)
		{
			throw new Exception('If Min is set to a non zero number, Max must be greater than Min.');
		}
 
	}
 
}
?>

CalculateDisplayText() creates a message for the user based on how the min and max values are set. You can see that CheckValues() is throwing an exception if there are crazy values set up for an object of our class. These kinds of errors would be the result of improper coding while using the class. Their audience is the developer. I feel that it is important to provide this kind of feedback for others.

Conclusion

We now have a base class and a product of that class to use going forward with our framework. Hopefully, you’re thinking of a few other classes you might create to handle some common validation situations that you run in to. Feel free to send in your code. I will add them to the framework and discuss the new classes on the blog. In the next article, we are going to build another abstract base class which makes use of the validation classes we have created so far. I know it’s a long road, but we’ll have some really cool development tools as we move forward.

Also Available in This Series

• A Business Objects Framework for Wordpress
• Building Monkey Wrench – The Rule Classes

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