PHP Methods

In addition to cTemplate Methods, PHP Methods can also customize what happens when content is added, updated, removed, copied and displayed in webCOMAND or through the APIs.

PHP Methods are a bit more work to implement than cTemplate Methods, but they execute faster and have all of the capabilities of PHP and the COMAND PHP API at their disposal. PHP Methods are defined in a PHP class called a Model. A Content Type is then associated with the Model, whose methods will be accessible from the object, in addition to the object methods already provided by the COMAND PHP API.

Models

By default, objects retrieved from the repository will be an instance of the COMAND cObject Model, which provides access to the fields and methods defined in the repository, as if a PHP class was defined with the same fields and methods. While this works well in many situations, it is often useful to define a content type class to represent an object loaded from the repository, providing content type specific PHP variables and methods.

A content type class is a standard PHP class file that meets the following criteria.

Namespace - The class file namespace should always match the package and folder where the model is located in the file system. For example,
namespace com_example\models
Class Name - The class name must match the identifier of the corresponding content type. PHP class names are not case sensitive. However, it is a best practice to match the case anyway.
Extends - The class must extend \io_comand_repo\models\cObject.
Filename - The filename must match the identifier of the corresponding content type. Filenames are not case-sensitive on all operating systems. However, it is a best practice to match the case, even when the operating system does not require it.
File Path - The file should be saved to a package folder or subfolder that matches the namespace, so the COMAND API auto-loader can find it.

Uses

The most common reasons to introduce a PHP Model and methods are:

Customize webCOMND
Prepare and validate content
Custom methods

Customize webCOMAND

webCOMAND checks for certain Content Type methods by their name and calls them automatically to accomplish certain tasks. In many cases a method is called in response to content modifications. A content type method can be defined in one of the following ways (only the first match will be used).

Content Type Model Method - A content type model can override any method listed below by defining a method with the same name (case-insensitive). This completely overrides the default process, so it is up to that method to define the new process, which should typically invoke the parent::method() when it is appropriate to continue with the default process.
Content Type cTemplate - If a content type template is defined with the same (case-insensitive) name as one of the methods below, it will be used.
Content Type Model "method__" - If a public method is defined with the same (case-insensitive) name as one of the methods below, preceded by method__ ("method" followed by two underscore characters), it will be used. For example, method__Validate().

For example, if a Content Type cTemplate named "Summary" or Content Type Model Method named "method__Summary()" is defined, it will be called and its return value will be used whenever the object is referenced as a string.

If a Content Type cTemplate named Summary is defined, it will override a PHP Model Method named method__Summary(), which will no longer get called. That behavior can be useful. However, if you would like to ensure PHP code is executed, even if a Content Type cTemplate is defined, use the Content Type Model Method (e.g. Summary()). That method can override the cTemplate and also call the cTemplate with parent::New(). See the Example Template below.

Simple Example

The following example PHP class will be used for objects of a content type with the identifier "Contact".

<?php

namespace com_example\models;

/**
 * Class to be used for objects loaded from a COMAND repository with
 * the content type Contact.
 */
class Contact extends \io_comand_repo\models\cObject {
	/**
	 * Custom method to print the name of a Contact.
	 */
	function print_name(): string {
		print("$this->FirstName $this->LastName");
	}
}

Hooks

In addition to the definition of arbitrary custom variables and methods, COMAND hooks can also be defined for COMAND to utilize in difference scenarios.

Field Validation

Field validations can be defined as an associative array named $_field_validations with keys that correspond to field identifiers and the value is an array of functions to call sequentially to validate the field value upon submission. If the function names are given as the key to an associative array value, the value represents the parameter or an array of parameters. The provided function names will be processed as follows:

Class _validate_ - Check for method in this class with same name preceded by "_validate_" (ie. "email" would check for "_validate_email").
Class _prepare_ - Check for method in this class with same name preceded by "_prepare_", which can alter the field value before it is saved (returns altered value).
Extension _validate_ - Check for method in loaded extensions (last loaded checked first) with the same name preceded by "_validate_".
Extension _prepare_ - Check for method in loaded extensions (last loaded checked first) with the same name preceded by "_prepare_".
Built-in PHP Function - Check for standard PHP function and use it to alter the field value, like "_prepare_" methods (ie. trim).

Field validations are processed between after field value type validation occurs and before the Validate method is processed.

Field Validation Example

<?php

namespace com_example\models;

/**
 * Class to be used for objects loaded from a COMAND repository with
 * the content type Contact.
 */
class Contact extends \io_comand_repo\models\cObject {
	public static $_field_validations = array(
		'FirstName'=>array( 'trim', 'required', 'min_length'=>10 )
	);
}

Recognized Methods

A complete list of methods utilized by COMAND, see recognized content type methods.

Example

The following example PHP class will be used for objects of a content type with the identifier "Contact".

<?php

namespace com_example\models;

/**
 * Class to be used for objects loaded from a COMAND repository with
 * the content type Contact.
 */
class Contact extends \io_comand_repo\models\cObject {
	/**
	 * This method will be called when a new Contact object is created.
	 */
    public function New() {
		// set a default FirstName field value
		$this->FirstName = 'John';

		// do whatever the content type Contact would normally do,
		// which includes calling New() on content types it extends.
		return parent::New();
	}
}

Example Template

New content type classes can be created based on the following example skeleton.

<?php

namespace com_example\models;

/**
 * Class to be used for objects loaded from a COMAND repository with
 * the content type Contact.
 */
class Contact extends \io_comand_repo\models\cObject {
	public static $_field_validations = [
		'Name'=>['Trim', 'Required', 'MinLength' => 10]
	];

	/**
	 * This method will be called when a new Contact object is created.
	 */
	function New() {
		// set a default FirstName field value
		$this->FirstName = 'John';

		// do whatever the content type Contact would normally do,
		// which includes calling New() on content types it extends.
		return parent::New();
	}
}