mirror/php-e107
1
0
Fork 0
mirror of https://github.com/e107inc/e107.git synced 2025-08-06 22:57:14 +02:00
Code Issues Releases Wiki Activity

Clarification around class and method naming added.

Cameron
2020-05-25 11:46:32 -07:00
parent e33600ee1a
commit 097745d4ee
1 changed files with 65 additions and 50 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
e107-Coding-Standard.md

@@ -1,15 +1,15 @@
IMPORTANT: This is a work in progress!
IMPORTANT: If you're unsure of something, ask in gitter.
# Section 1 - Pear Standard
(Where no comment here, the Pear standard applies unmodified) The Pear coding standards (http://pear.php.net/manual/en/standards.php) form the basis of our own standard. This standard makes some comments on those standards, and in some cases defines a different way of doing things.
### Indenting
## Indenting
Use tabs to indent - not spaces - then you can adjust your editor to suit.
### Control Structures
## Control Structures
Use BSD/Allman/Pascal style - opening '{' on a new line. The only exception is for short single statements within {...} such as ' return ; '- then it may be on a single line. This is optional.
@@ -44,19 +44,59 @@ Use BSD/Allman/Pascal style - opening '{' on a new line. The only exception is f
# Section 2 - PHP/e107
### Variables
Use camelCase for variables.
[PSR-1](https://www.php-fig.org/psr/psr-1/) is used with the exception of class/method naming (see below).
## Variables
Use **camelCase** for variables.
$camelCase = "value";
### Constants
## Constants
Use UPPER_CASE_WITH_UNDERSCORES for constants.
define("CONSTANT_NAME", "some value");
Where numeric values represent a particular status, define a constant for that value to make the meaning more obvious.
### Paths
## Classes, Methods and Functions.
Class names must must use **lowercase** and use an **underscore** (_) if necessary. The corresponding file should use the same name and casing. Example: **login_shortcodes.php**
```
class login_shortcodes extends e_shortcode
{
}
```
Method/Function names should use **camelCase** unless they are shortcodes (eg. _sc_news_image()_) or methods within **e_admin_form_ui** in which case they should use **lowercase** to match the database field name.
Routines are to be documented at both file and function level using phpDoc syntax. Where appropriate create supplementary pages of general documentation, and document individual variables.
When passing more than three or so parameters to a function, consider passing some of them in an array (especially convenient if many are optional) or if within a class, consider using vars.
**Better:**
function myFunction($array)
{
}
**Avoid:**
function myFunction($var1,$var2,$var3,$var4,$var5,$var6);
{
}
Avoid replicating or bypassing e107 classes/handlers which are used for specific purposes.
One example: use the e107 file-class instead of PHP file functions to read directories.
$fl = e107::getFile();
$filesArray = $fl->get_files($path, $fmask);
## Paths
Use the e_XXX path constants to refer to directories:
Absolute constants (e_XXX_ABS) for paths within HTML pages
Relative paths (e_XXX) to access files from within the code
@@ -70,7 +110,7 @@ Relative paths (e_XXX) to access files from within the code
$img = e_PLUGIN_ABS."myplugin/images/myimage.png";
### Forms
## Forms
Always use e107's form handler for form elements in the front-end.
$frm = e107::getForm();
@@ -80,7 +120,7 @@ Always use e107's form handler for form elements in the front-end.
$frm->admin_button($name, $value, $action, $label); // $label needed only when different to $value
$frm->admin_button('field_name', LAN_UPDATE, 'update');
### Globals
## Globals
Avoid the use of global variables, especially as an alternative to parameter passing. (We'll always need some globals - but the less there are, the smaller the chance of a clash). In v2.0 use the e107::getxxx syntax to get pointers to 'global' functions and objects like $sql, $tp
$pref = e107::getPref(); // grab preferences array
@@ -91,33 +131,8 @@ Avoid the use of global variables, especially as an alternative to parameter pas
$fl = e107::getFile(); // file handling class.
$mes = e107::getMessage(); // message handling
### Functions and Classes
Routines are to be documented at both file and function level using phpDoc syntax. Where appropriate create supplementary pages of general documentation, and document individual variables.
When passing more than three or so parameters to a function, consider passing some of them in an array (especially convenient if many are optional) or if within a class, consider using vars.
**Better:**
function myfunc($array)
{
}
**Avoid:**
function myfunc($var1,$var2,$var3,$var4,$var5,$var6);
{
}
Avoid replicating or bypassing e107 classes/handlers which are used for specific purposes.
One example: use the e107 file-class instead of PHP file functions to read directories.
$fl = e107::getFile();
$filesArray = $fl->get_files($path, $fmask);
### If/Else and Switch
## If/Else and Switch
Consider switch statements rather than multiple if...then...elseif.... (generally for three or more, or better yet, use an array to change the result where possible.
Simple 'If/Else' example:
@@ -165,8 +180,8 @@ Preferred version of above:
);
$val = $array[$option];
### Extract
Avoid using extract() on arrays (usually DB rows) - it causes confusion, and sometimes unneeded variables. And especially don't use it on $_POST and $_GET variables! Use the new _retrieve_ function to select and fetch data as an array.
## Extract
Avoid using `extract()` on arrays (usually DB rows) - it causes confusion, and sometimes unneeded variables. And especially don't use it on $_POST and $_GET variables! Use the new _retrieve_ function to select and fetch data as an array.
**Good:**
@@ -185,7 +200,7 @@ Avoid using extract() on arrays (usually DB rows) - it causes confusion, and som
$text .= $field_name;
}
### Explode() and List
## Explode() and List
Consider using list() instead of explode() when the values will be given their own strings and the size of the array is known.
**Okay:**
@@ -202,16 +217,16 @@ Consider using list() instead of explode() when the values will be given their o
As $_POST variables are checked/sanitized, create new variables to hold the checked values - makes it obvious what's safe and what's dodgy. (Note validator_class.php, especially where the same DB data can be input from several different places). Make sure $_POST variables are only processed if the user has the relevant permissions, and if the relevant options are enabled (its not enough to hide the button or field which initiates the post - security levels MUST be checked at the point of execution).
### Debugging/Errors
## Debugging/Errors
Code must not produce any PHP warnings or notices during normal use. This primarily implies that all variables must be defined before being used. It also implies that a corrupted installation may produce errors, although as far as practicable the code should accommodate this. Many PHP notices can be avoided by using the functions vartrue() and varset() - see class2.php.
We recommend this collection of [Firefox Addons](https://addons.mozilla.org/en-US/firefox/collections/camer0n/e107developer/). Most important being the _e107 Debugger_.
### Upgrades
## Upgrades
For simple changes, the code should silently handle the situation
For more complex changes, an upgrade routine is required. See [plugin]_setup.php
### Javascript, CSS and Meta
## Javascript, CSS and Meta
Use the following functions to include js or css files
e107::js();
@@ -236,7 +251,7 @@ Don't enclose integer values in quotes in WHERE clauses - slows up the query. (B
Where only one record is expected, use "LIMIT 1" in the query for better performance.
### insert() and update()
## insert() and update()
Associate field names and values (rather than using an ordered list of just values) - avoids problems with DB changes. Make sure values are specified for any field without a default - else fails in STRICT mode.
Insert Example:
@@ -282,7 +297,7 @@ To avoid problems when 'STRICT' mode is set for MySQL, make sure any field which
If reading XML files (typically plugin.xml) use the filter capability to limit the amount of data retained in memory to that which is actually needed.
### Plugins
## Plugins
Many of the plugins in the v2 branch have not yet been upgraded to the v2 way of doing things.
If you are developing a new plugin for v2+ of e107, be sure to use the following plugins as your reference of how things SHOULD be done.
@@ -291,9 +306,9 @@ If you are developing a new plugin for v2+ of e107, be sure to use the following
To check whether a particular plugin is installed, use function e107::isInstalled($plugname) - returns TRUE if plugin installed.
## Language Files and LANS
### Language Files and LANS
### Plugin Language-File Naming
#### Plugin Language-File Naming
Use the following path: _e107_plugins/YOUR_PLUGIN/languages/LANGUAGE/_
@@ -302,7 +317,7 @@ Use the following path: _e107_plugins/YOUR_PLUGIN/languages/LANGUAGE/_
* English_global.php - used site-wide.
* English_log.php - used for logging.
### Loading Language-Files
#### Loading Language-Files
To load a language file from the current theme's directory:
e107::lan('theme'); // loads e107_themes/CURRENT_THEME/languages/English.php (when English is selected)
@@ -322,7 +337,7 @@ Will include the following paths:
e107_plugins/faqs/languages/English/English_admin.php
### Defining Language Terms aka 'LANS'
#### Defining Language Terms aka 'LANS'
Avoid duplicating terms, particularly in the admin area. If coding for admin, always search lan_admin.php and the lan_xxxx.php of the specific page you are working on for existing LANs which may match what you need translated. Avoid using HTML or URLs inside LAN definitions.
Also, use double quotes within the defines and use str_replace where needed. See the examples below:
@@ -351,7 +366,7 @@ Avoid short language strings for words such as 'and', 'to' and so on. There aren
## Template Files
### Template Files
Use the **gallery** plugin as your reference.
Avoid code, especially functions, inside template files. You may load a template file in the following way:
@@ -360,12 +375,12 @@ Avoid code, especially functions, inside template files. You may load a template
## HTML
### HTML
e107 v2+ uses the HTML5 standard. Be sure to validate the HTML output of your code.
Many of us use the Firefox addon: http://users.skynet.be/mgueury/mozilla/
## Shortcodes
### Shortcodes
Note and use the class-based structure introduced in v2.0 - with this it should be possible to totally avoid globals. See the **gallery** or **faqs** plugins for an example.