Page Comparison

...

Some existing classes, files and functions have no docs, use a bad style, do not have a boilerplate or contain commented out code so code sniffer will warn about it. However, new files will be expected to follow this and we should attempt to update existing code where possible.

/**
 * A short one line description of the class
 *
 * You can now add a longer description and describe properties that might
 * be found via a magic get or set.
 *
 * @author Your Name <email@example.com>
 * @copyright Copyright (c) 2024 You or your employer
 */
class MyClass
{
	/** @var int A description of what the property stores. */
	protected int $property;

	/**
	 * A property that needs a long explanation
	 *
	 * If a property is complicated you may use a multi-line
	 * doc block for it.
	 *
	 * @var array
	 */
	protected array $data = [];

	/**
	 * A one line description of the method
	 *
	 * An optional longer description of the method if needed.
	 *
	 * You only need to to define @returns if you explicitly use
	 * a return statement.
	 *
	 * @param int $value A description of the value
	 */
	public function set_property(int $value)
	{
		$this->property = $value;
	}

	/**
	 * A one line description of the method
	 *
	 * An optional longer description of the method if needed.
	 *
	 * @returns int An optional text description what is returned when it is not already described.  
	 */
	public function get_property(): int
	{
		return $this->property;
	}
}

Page Parameters

• $_GET, $_POST and $_REQUEST super globals must not be accessed directly. Instead values passed to them should be access via param::required(), param::optional() or check_var()

  • If param::required() is used the code must handle the exception that will occur if it is not set.

  • check_var() will automatically display a message and terminate the script if a required parameter is not present

  • param::optional() allows a value other than null to be returned if it is not set, so is recommended over check_var() for parameters that are not required.

...

Some existing code uses direct access so code sniffer will warn about it. However, new files will be expected to follow this and we should attempt to update existing code where possible.

Auto-loading

In order to be autoloaded classes must:

• use the file extenstion '.class.php'
• be located in any of the following locations:
  • <base dir>/classes
  • <base dir>/*/classes
  • <base dir>/plugins/*/classes
• the main name of the file must be a lowercase version of the class name, for exmple if your class is called MyClass the filename would be myclass.class.php

We expect all classes in ExamSys to autoload

Files

PHP files should only contain php code.

...

Although it is good practice not to show PHP errors on a production server, Rogō should be written so that no errors occur when error reporting is set to E_ALL.

Templates

Templates require some documentation to help people that want to make use of them

{#This file is part of ExamSys

ExamSys is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

ExamSys is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with ExamSys. If not, see <http://www.gnu.org/licenses/>.
#}

{#
A one line description of the template.

You can optionally add more details about the template to help developers
understand how, when and why they might want to use it.

author Your name <email@example.com>
copyright 2024 onwards You or your employer

Required variables:

action - the form action
data - the form data

Required localised language strings -
lang.retention
lang.update
#}

We require that any data that the template uses is described

We also describe any language strings we expect in the template.

Things to Avoid

Globals

Where possible the use of global variables should be minimised. The $GLOBAL[] syntax should never be used.

...