The php_class model should be used to create all of your php classes can cannot be created using a more specific model such as select, form_handler or custom. Using the model is much easier that writing classes by hand since, at the very least, you will not have to code any standard get and set methods. Instead, you can just select which standard methods you would like to have generated. Using the model also improves the documentation associated with your classes because you can indicate the expected format of the class variables. For array fields, you can also set the array dimensions.

Class Setup Fields

The initial set of fields is used to set up the class. Often these fields will be left empty.

Class Setup Fields

Before Class

If the class is to run within a certain namespace enter this in the before class code area. This area could also be used to require any dependent classes. If you need more rows to edit this section you can change the value of the second select field above the editor area. 

Extends Class

If you are extending another class, enter the class to be extended here. Note that the class you enter will automatically be required, there is no need to explicitly add a require statement for the class being extended. Click on the search icon if you can't recall the name of the class you wish to extend. When extending classes that don't belong to the current namespace, begin the class name with a backslash character (\).

If your class will be using the default message handling protocol in order to return validation errors specify standard_base in the Extends Class field. You can then use methods such as assign_message. The standard_base class also includes the site object which will often be needed by the classes you define.

Implements

If your class implements a certain interface, use this field to enter the name of the interface that it implements.

Abstract Class

If you are developing an abstract class, check this option.

Include Descriptions

Check this option if you want to include the field comments you enter into the rightmost column of the field definitions as comments within the generated class.

Obfuscate

If you will be distributing your code to others and you want to protect your intellectual property you can mark this checkbox to obfuscate the code. When code is obfuscated you won't be able to debug the code using standard debuggers. In order to preserve the readable class code, it is saved under the private_data/unobfuscated folder in addition to saving the obfuscated code under the classes folder.

Class Properties

For each property supported by the class you must enter a row into the Class Properties grid. The data type provides a hint to the users of the class as to what type of data is expected when getting or setting class variables.  

Class Property Definitions

Visability

Most of your class variables should be defined as protected in order to prevent user of the class from changing the class properties without going through a method of the class.

Special Behavior

Static

Static variables are used to define values associated with the class itself, as opposed to an class object (an instance of the class). For example, if a class wants to keep track of how many times it has been instantiated, this could be done using a static variable,

Constant

Class variables defined as constants cannot be changed. These are normally defined in upper case.

Array Dimensions

This is mainly used for documentation purposes to indicate which fields are arrays and how many dimensions they define.

Initial Value

The initial value column does not require quotes for scalar properties with a string data type. Quotes will be added automatically. The one exception is if you want to initalize a property to an empty string. In this case enter two single quotes in the Initial Value column. Initial values for array fields are declared using normal array syntax including quotes for string values.

Generating Standard Get and Set Methods

Generally speaking, it is a poor practice to define public variable for your classes since these can be accessed directly by any code that uses the class. This makes it impossible for the class to control the values that are assigned and it makes debugging more difficult since there is no central point of access for class variables. A better approach is to define all of your class properties as private or protected and to create functions to get and set the values.

Get Functions

Get Functions can either be defined as Simple or Transform Null. With Simple functions, the generated get method returns whatever value is currently assigned to the property. If the property has never been assigned, a null value would be returned. If Transform Null is chosen, the generated method will not return a null value. Instead, if the get method is called when the property contains a null value, the return value will either be an empty string, 0, or false depending on the data type of property.

Set Functions

When defining "input" parameters to a class you will normally declare these as either private (if you want to restrict access be subclasses) or protected to allow direct access by subclasses. Additionally you will want to declare a "Set" method  to allow users of the class to assign the property. The php_class model provides several options for declaring automatic set methods.

Here we see all of the options that are available to configure the generated set functions:

Set Function Options 

Let's review the differences between these options.

Simple

Simple set methods simply assign the field to whatever value is passed to the method.

Coerce

If Coerce is used, the value passed into the set method will be cast to the Data Type associated with the field. For example, if an integer is passed into a field that is defined as a string, the integer will be converted to a string before assigning it to the class property.

Coerce, Allow Null

This option is similar to Coerce except that if a null value is passed to the set method, the class property will be set to null.

Coerce, Make Empty Null

This option is similar to Coerce except that "empty" values passed to the set method will be converted to null values.

Force Arg Type

When this option is chosen, the php Data Type of the property will be specified in the set method's parameter declaration. In such a case, php will raise an error if the caller attempts to pass a value that is not the same data type.

Adding Functions to Your Class

You can code as many functions as required by setting the Section Type to function and the Location to After Last Sibling as shown:

Function Definition

Section Types

Functions are just one of the section types that can be added. Let's review the other types shown here:

php_class Section Types

property

In most cases your properties will be coded automatically by entering the properties, PHP Data Type, Visibility, etc, in the upper grid of the specification. The property section type is only used to enter complex property definitions that can't be expressed using the columns provided in the upper grid. In this case, you would define the property by hand using whatever features you require. When adding custom properties, the location column should always be set to "Replace Section".  Properties introduced in the custom code grid do not have to appear in the variable grid above, however, if they are specified in the upper grid the property name must be entered in the Section Id column.

function

Most of your Section Types will be defined as functions. Within the code you can declare functions as private, static, etc. according to your requirements.

get

Get is used to supplement code that is automatically generated when you choose one of the options under the Generate Get Function column in the upper grid.  When you use get as the section type you must enter the class property for the get function you which to supplement under the Section Id column.

set

Set is used to supplement code that is automatically generated when you choose one of the options under the Generate Set Function column in the upper grid.  When you use set as the section type you must enter the class property for the set function you which to supplement under the Section Id column.

example

The example option can be used to retain some sample code that you don't need at the moment. This code will not be included in the generated class but it will be saved as part of the specification so that you can refer to it later.

Supplementing the Generated Methods

Using the custom code editor you can add your own code to replace or supplement the default get and set methods. In this example, we add a parameter to the get_audio_file method to indicate the type of audio file to get. Since we are changing the interface to this get method we need to set the location to Replace Section and we supply the entire function. In the set example below we specify the location as Replace Body since we are replacing the contents of the function but not the declaration.

Supplementing generated get and set methods

Unlike other functions, when supplementing get or set methods you must specify the property name in the Section Id column.

The Location selector allows you to choose the following ways to supplement the generated method:

Supplementing the default get and set methods

Use Replace Section if you want to write the method in its entirety. Another way to do this would be to not generate the method at all and, instead, code the method as a normal function.

Use the Replace Body option if you want to supply all of the code for the method (except for the method declaration).

Top of Body is placed at the top of the function. In the case of a set method, this is before the property value is assigned.

Bottom of Body will be placed at the bottom of the function. In the case of a set method this is after the property value is assigned.

After Last Sibling is used to code a normal function.

Inheriting standard_base

A common problem when building complex systems involves error handling. Consider the following scenario in which your class calls a method of another class and that class calls a method of a third class and the third class sets a message.  

Class messaging example

If each of these classes inherits from standard_base they will all have the "plumbing" necessary to exchange messages. In the general case any class can set a message by calling its assign_message method. Class2 could "collect" the messages assigned by Class3 by using the code:

class3->transfer_your_messages_to_me($this);

Class1 would do the same after calling a method of class2. 

To learn more about assigning messages please refer to the messages model. Message examples are also provided in the custom model help.

Help With Classes

GenHelm is entirely built in itself and most of the source code is included in your installation. To learn more about using the php_class model or other standard models you can search for components generated using the model you are interested in and review the inputs and supplied code.

Supported Examples

The example command can be used to load the following examples:

example cart_item

Build example functions for cart item classes.

example invoice_api

Build a sample class used to manage invoices within an e-commerce site.

Sample php_class definition
🡇
Sample php_class definition