The php_class model should be used to create all of your PHP classes that cannot be created using a more specific model such as select, form_handler or custom. Using this model is much easier than 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.

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.

Spec Type

In addition to normal classes, the php_class model can also be used to generate abstract classes. Choose this option if you are not generating a normal class.

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.

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 can either be an explicit type like the ones shown here or they can be a union of valid types allowed by the property. If you do not want to set an explicit type, or if the generated class needs to be compatible with PHP versions prior to 7.4, you can choose a single character type. These will provide a hint to the users of the class as to what type of data is expected without actually setting a type. For example, when setting the datatype to "s", the property will not be typed as in:

protected $some_string;

For all type values that are more than one character in length, the supplied type will be used exactly as entered. For example, 

protected ?int|bool $some_property;

Typing properties is generally recommended since doing so will ensure that PHP will only allow valid values to be assigned to the typed properties. It should be noted that the value of typed properties cannot be retrieved without generating a runtime error until and unless the property has been assigned a value (including the null value).  If you want users of your class to be able to get a property value, without setting it first, it is necessary to assign an initial value to the property.

Visibility

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:

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.

Force Arg Type of Null

When this option is chosen, the PHP Data Type of the property will be specified in the set method's parameter declaration and the null value will also be allowed.

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:

Section Types

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

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.

use

This section is used to define the use or traits as part of the current class. You can find an example of this below.

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.

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:

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.  

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.

Using Traits

Including the trait Definition

Traits defined using the php_trait model are generated into the trait subfolder of the main classes folder. Therefore, to incorporate traits defined within system you first have to require the trait using:

require_once CLASS_PATH.'trait/tname.php';

If the trait is defined within the current site, it should be included using:

require_once SITE_CLASS_PATH.'trait/tname.php';

In each case, tname is the name of the trait to be used.

The reference should be defined within the Before Class definition as shown.

Adding the use Statement

Within the Custom Code section, set the Section Type to be use and set the Location to be After Last Sibling. Enter the full use statement within the Custom Code column as shown:

Sorting Properties and Functions

You can sort both properties and functions (methods) by using the sort command. To only sort properties you can enter the command sort properties. To only sort functions, enter the command sort functions.

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.