Property System

Introduction

Each object has a number of member variables for non-internal use, or "properties", such as a title or its monetary value.

The DutchPIPE property system allows for automatic members, set methods and get methods ("setters" and "getters") with a minimum of code.

This means objects can have a lot of properties without lots of setters and getters obfuscating your code, and that you can add properties with a minimum of fuss.

Classic PHP members/setters/getters

Consider this simple class Employee with the member employeeNr:

1. class Employee()
2. {
3.     public $employeeNr;
4. }

To set and retrieve values, you'd use this:

1. $employee = new Employee;
2. $employee->employeeNr = '12345';
3. echo $employee->employeeNr; // Shows '12345'

Now consider this more secure class, with a basic check to see if the given number is of a certain format (it must be 5 characters long, just as an example):

1. class Employee()
2. {
3.     private $employeeNr;
4.  
5.     function setEmployeeNr($employee_nr)
6.     {
7.         if (strlen($employee_nr . '') == 5) {
8.             $this->employeeNr = $employee_nr;
9.         }}
10.  
11.     function getEmployeeNr()
12.     {
13.         return $this->employeeNr;
14.     }
15. }

To set and retrieve values, you use the setters and getters:

1. $employee = new Employee;
2. $employee->setEmployeeNr('12345');
3. echo $employee->getEmployeeNr();  // Shows '12345'

DutchPIPE properties - Magic members/setters/getters

Now the DutchPIPE property system, without a check on the format of the employee number yet:

1. class Employee()
2. {
3.     function __construct()
4.     {
5.         $this->employeeNr = new_dp_property();
6.     }
7. }

The employee number is now accessible both with a "magic" direct member, and with "magic" setters and getters:

1. $employee = new Employee;
2. $employee->employeeNr = '12345';
3. $employee->setEmployeeNr('12345');  // Same result
4. echo $employee->employeeNr;         // Shows '12345'
5. echo $employee->getEmployeeNr();    // Same result

Defining methods for setters/getters

If you define a method called setPropertyname with the first letter of the property name in upper case, that method is "magically" used both for member assignments and method calls.

At the same time, this can be used to handle setters with multiple arguments.

1. class Employee()
2. {
3.     function __construct()
4.     {
5.         $this->employeeNr = new_dp_property();
6.     }
7.  
8.     function setEmployeeNr($employee_nr, $format = 'default')
9.     {
10.         if (strlen($employee_nr . '') == 5) {
11.             $this->setDpProperty('employee_nr', $employee_nr);
12.         }}
13. }

Properties can be directly accessed in setters/getters with the setDpProperty and getDpProperty methods. You should use these methods to avoid an infinite loop (you'd create a loop for example by using $this->employee_nr = $employee_nr in the setEmployeeNr method above). setDpProperty should only be called from setters, getDpProperty should only be called from getters. Calls to these protected methods outside of these contexts should be avoided.

The second line below uses setEmployeeNr with a single argument given. The third line can be used to give a second argument:

1. $employee = new Employee;
2. $employee->employeeNr = '12345';               // Calls setEmployeeNr('12345')
3. $employee->setEmployeeNr('A940F', 'special');  // Calls setEmployeeNr('A940F', 'special')
4. echo $employee->employeeNr;                    // Shows 'A940F'
5. echo $employee->getEmployeeNr();               // Same result

With this, "simple" values can be set with magic members, and advanced stuff can set the property using the method call. This also gives place to backward compatability for properties that start simple, but then get more complex over time. The old code uses the simple call which uses defaults, and new code can use more arguments using the setter method.

Custom setters/getters

You can also define a setter method with a custom name, with the same effect. Notice the setter is "hidden" (although it could be called directly), and the magic method setEmployeeNr is used instead to access it:

1. class Employee()
2. {
3.     function __construct()
4.     {
5.         $this->employeeNr = new_dp_property(NULL, '_setEmployeeNr');
6.     }
7.  
8.     function _setEmployeeNr($employee_nr, $format = 'default')
9.     {
10.         if (strlen($employee_nr . '') == 5) {
11.             $this->setDpProperty('employee_nr', $employee_nr);
12.         }}
13. }
14.  
15. $employee = new Employee;
16. $employee->employeeNr = '12345';               // Calls _setEmployeeNr('12345')
17. $employee->setEmployeeNr('A940F', 'special');  // Calls _setEmployeeNr('A940F', 'special')
18. echo $employee->employeeNr;                    // Shows '#A940F'
19. echo $employee->getEmployeeNr();               // Same result

new_dp_property in detail

new_dp_property takes three optional arguments: the initial value, a custom setter method and a custom getter method:

1. function new_dp_property($val = NULL, $setter = NULL, $getter = NULL)

Getters work the same way as the setters covered above, for example:

1. class Employee()
2. {
3.     function __construct()
4.     {
5.         $this->employeeNr = new_dp_property(NULL, NULL, '_getEmployeeNr');
6.     }
7.  
8.     private function _getEmployeeNr()
9.     {
10.         return '#' . $this->getDpProperty('employee_nr');
11.     }
12. }
13.  
14. $employee = new Employee;
15. $employee->employeeNr = '12345';
16. echo $employee->employeeNr;      // Calls _getEmployeeNr(), shows '#12345'
17. echo $employee->getEmployeeNr(); // Same result

Read-only properties

If the setter of a new property is set to FALSE, it becomes read-only.

Also notice in the examples below the initial value of '12345' and the custom getter, which is automatically picked up because its name is in the right format:

1. class Employee()
2. {
3.     function __construct()
4.     {
5.         $this->employeeNr = new_dp_property('12345', FALSE);
6.     }
7.  
8.     function getEmployeeNr($prefix = '#')
9.     {
10.         return $prefix . $this->mEmployeeNr;
11.     }
12. }
13.  
14. $employee = new Employee;
15. $employee->employeeNr = '67890';    // No effect
16. $employee->setEmployeeNr('67890');  // No effect
17. echo $employee->employeeNr;         // Shows '#12345'
18. echo $employee->getEmployeeNr('$'); // Shows '$12345'