QA Code Protocol

From FMYiRCWiki

Jump to: navigation, search

Freemed-YiRC Quality Assurance - Code Protocol


Contents


Summary

This document is intended to give a developer an understanding of how Freemed-YiRC code files should be tested in order to maintain a level of high Quality Assurance (QA).


Tests

HTML

  • All HTML tags code shall be using lower case for the tag name and parameters. 
    • <b><i><u><font color="ff0000">This is red, underlined, italicized, and bolded text</font></u></i></b>
  • All parameter arguments shall be enclosed within double-quotes ("). 
    • <td align="center" bgcolor="ff0000">
  • Parameter values may or may not be in lower case, depending upon the situation. 
    • <font color="ff0000"><input name="fy_input_var" value="Default Stuff Here">

Script Structure

Header

  • All PHP scripts/files shall begin and end with the PHP tags 
    • <?php
    • ?>
  • All scripts shall have the following copyright notice immediately after the starting PHP tag:
    • This notice should be preceded by an INDENT(tab).
    • The actual copyright years will of course vary.
    • Joe Thielen is the only authorized copyright holder for any Freemed-YiRC code in the master Freemed-YiRC code base.
      • This excludes scripts which are wholly created by other persons and included in the Freemed-YiRC code base for ease-of-use reasons. 
    • # Freemed-YiRC (C)2000-2011 Joe Thielen - Licensed under the GNU GPL V2
  • All scripts shall have a line that identifies which Freemed-YiRC module they belong to.
    • This line should immediately follow the copyright notice line.
    • The module name and module abbr should exactly match those listed in the fy_modules table for that module record. 
    • # *_-=MODULE=-_*: MedBill (MB)
  • All scripts shall have include lines for the freemed_yirc-vars.inc and freemed_yirc-funcs.inc files.
    • These include lines shall follow the module name/abbr and copyright notice lines (separated from those by a blank line) 
    • include "freemed_yirc-vars.inc";
    • include "freemed_yirc-funcs.inc";

Non-Command-Line Executable Scripts

All scripts which are not intended to be executed from the command-line, i.e. those whose output is to be viewed by a user with a web browser, shall have the following items.

Cookie/Session Checking

ALL scripts which are not intended to be used from the command-line shall include the following lines, immediately after (separated by a blank line) the include lines. 

fy_cookiecheck($cookie_user);
fy_resetcookie($cookie_user, $cookie_id, $fy_cookietime);
Variable Declaration/Import

As PHP6 will not include the register_global option, all variables passed to a given script must be declared/imported. The majority of these variables are to be imported immediately after the cookie/session functions. Possible exceptions are listed following the required/standard variables.

Required/standard variables: 

$cookie_user = $_COOKIE['cookie_user'];
$cookie_id = $_COOKIE['cookie_id'];
$fydb_host = $_COOKIE['fydb_host'];

If there are additional variables (which there are likely to be), the next line shall be a comment in the form of the following, immediately following the import of the fydb_host variable. All other variables should be imported immediately following this line/comment. 

# Imported Vars

Possible exceptions include:

  • Variables to be imported from a FORM using the POST method. A single script may act as both a data-input form and as a post-processor for that data. Therefore, the POSTed variables may only need to be imported during the post-processor section of the script.
  • Variable Variables. i.e. variables which start with the double-dollar sign notation.. ($$). This is typically used when using complex and/or dynamically created HTML form fields.

Variable Declaration/Import Sources:

  • All variables passed to the script via the URL shall be declared/imported from the $_REQUEST variable/array.
  • All variables passed to the script via form POST or GET operations shall be declared/imported from the $_POST and/or $_GET variable/array respectively.
  • All variables obtained by the script via the use of cookies shall be declared/imported from the $_COOKIE variable/array.
  • All server/environmental variables obtained by the script shall be declared/imported from the $_SERVER or $_ENV variable/array, or by using the getenv() function.
Database Connection and Security Database Permissions Checking

Immediately following the variable declaration/import section (separated by a blank line) should be the database connection and security database permissions checking lines. ALL scripts which are not intended to be used from the command-line shall include at least one security DB permission lookup which is appropriate for the given module.

The code shall look very similar to the following: 

# ---SECURITY CHECK---
$conn=fy_makeconn($fydb_type, $fydb_host, $fydb_user, $fydb_name);
if (fy_secdbcheck($conn, $fydb_type, $fydb_name, $cookie_id, "email")==1) {fy_autologout($cookie_user);exit;};
# --------------------

In the above code, email is to be replaced with the appropriate Security Database permission. If additional required permissions are necessary, that line may be duplicated and used to check additional permissions.

If there are optional permissions to be checked for use in various parts of the script, they shall be similar to the following format, immediately following the required permissions checking line(s): 

if (fy_secdbcheck($conn, $fydb_type, $fydb_name, $cookie_id, "macsis_bill")==0) {$perm_bill="X";} else {$perm_bill="";}

In the above code, macsis_bill is to be replaced with the appropriate Security Database permission. In addition, the $perm_bill variable should be replaced with an appropriate variable name, with the initial variable name of $perm_ and followed by a very brief, but still descriptive, suggestion of it's use. The format of if (has perm) {$perm_X="X";} else {$perm_X="";} shall be maintained to properly initialize the $perm_X variable... i.e., if the user has this permission, this variable value should be set to X, and if it does not, it should be BLANKED.

Group Checking

For Group-oriented modules, there is one additional security check which shall be performed with the following code, to ensure the current user is a member of a given group: 

if (fy2_authgroup($fy_id)<1) {fy_autologout($cookie_user);exit;}

Body

Every PHP script/file is different. Each has a different purpose, so the contents of the body can vary wildly. Most, however, have several items in common:

  • Starting/ending HTML output
  • Starting/ending the Freemed-YiRC window
  • SQL/DB functions

NOTE: When using the Freemed-YiRC Quick Page function (fy2_html_quickpage() in freemed_yirc-funcs2.inc), these steps are already done for you.

Starting/Ending HTML Output

Nearly every Freemed-YiRC PHP script/file will produce HTML output even if it does not make use of a Freemed-YiRC window.

Unless the PHP script/file is producing very custom HTML output (i.e., for a very customized report designed to be sent/viewed on the screen), the PHP script/file shall use the Freemed-YiRC functions for starting/ending HTML output.

Starting HTML output shall be done with one of the following functions in the freemed_yirc-funcs.inc function file:

  • fy_starthtml()
  • fy_starthtml2()

Ending HTML output shall be done with the following code: 

fy_endhtml();


Starting/Ending the Freemed-YiRC Window

The majority of Freemed-YiRC PHP scripts/files will be producing content within the Freemed-YiRC window.

Starting the Window

The following code shall be used in order to create a Freemed-YiRC window: 

$fy_window_back="SCRIPT_TO_GO_BACK_TO";
fy_startwindow($SCRIPT_NAME, $fy_window_back)

The contents of the $fy_window_back variable, in this example: SCRIPT_TO_GO_BACK_TO shall be replaced with the script name/arguments of a script which will be used if the user hits the Freemed-YiRC back icon in the upper-right hand corner of the Freemed-YiRC window (for Freemed-YiRC versions after V1.20). This variable shall also be used in the fy_wincancel() or fy_winback() functions at the bottom of a given Freemed-YiRC window.

The script/file (and it's arguments/parameters) that the $fy_window_back variable points to should (in the vast majority of cases) provide the user with a SAFE / NON-DESTRUCTIVE option. For example, if the current Freemed-YiRC window is asking a user if they wish to modify or delete data, this variable should point to a script/file which will NOT proceed with the modification/deletion of data.

The above code is typically immediately preceded by the fy_starthtml() or fy_starthtml2() function.

Providing a BACK or CANCEL Option

Every Freemed-YiRC window shall contain, as it's last/bottom item in the window (aside from output produced by the fy_endwindow() function) a BACK or CANCEL link. This link shall be provided by the same $fy_window_back variable which was also provided to the fy_startwindow() function.

The code for providing this BACK/CANCEL link shall be: 

fy_winback("", $fy_window_back);

Or: 

fy_wincancel("", $fy_window_back);

Note that the empty value in double quotes in the function's first argument may be replaced with a number indicating the column span of the Freemed-YiRC window content table in order for the link to be centered within that table.

Ending the Window

The following code shall be used in order to end a Freemed-YiRC window: 

fy_endwindow("User: $cookie_user");

The above code is typically immediately followed by the fy_endhtml() function.

Footer

There is technically nothing required at the end of any Freemed-YiRC script, as the actual content/purpose of every script is extremely variable, with the exception of the end PHP tag at the very end of the file, on the last line.

Every PHP script/file shall end the file with the end PHP tag: 

?>


Deprecated Functions

Any functions marked as DEPRECATED should not be used in new code, and should be replaced by newer functions in older code where applicable. A list of deprecated functions can be found in the Deprecated Functions article.

Variable Naming Conventions

Please see the Variable Naming Conventions article for more information.


Indentation/Curly Bracket Usage

  • In Freemed-YiRC code, the tab shall be used to indent code. For each level of indentation, an additional tab shall be used.
  • Unless code is meant to fit on one line, then curly brackets ("{" and "}") shall be on one line (with the appropriate code between them on the same line) or the curly brackets will be on a line by themselves, unless used with else or elseif, in which case the first closing curly bracket, the else or elseif, AND the opening curly bracket are on the same line.
  • The following examples are PERMITTED uses of curly brackets and indentation. 
 if ($fy_x==1) {echo "1<br />\n";} else {echo "2<br />\n";}
if ($fy_x==1)
{echo "1<br />\n";}
else {echo "1<br />\n";}

if ($fy_x==1)
{
     echo "1<br />\n";
     echo "1a<br />\n";
     echo "1b<br />\n";
} else {echo "2<br />\n";}

if ($fy_x==1)
{
     echo "1<br />\n";
} else {
     echo "2<br />\n";
}
  • The following examples are NOT PERMITTED: 
# In this example, the opening curly brace is on the same line as the if, but with no code following it on the same line.
# Also, a TAB has not been used to indent the code.
if ($fy_x==1) {
  echo "1<br />\n";
}

# In this example, the opening curly brace is on the same line as the if, but with no code following it on the same line.
# In addition, the ELSE is on a separate line than the first closing curly bracket.
if ($fy_x==1) {
     echo "1<br />\n";
}
else {
     echo "2<br />\n";
}
Retrieved from "http://freemed-yirc.familyandyouth.org/freemed-yirc/wiki/index.php/QA_Code_Protocol"
Personal tools