mirror of
https://github.com/e107inc/e107.git
synced 2025-08-10 16:46:50 +02:00
More refinement
CaMer0n
@@ -34,69 +34,88 @@ Use BSD/Allman/Pascal style - opening '{' on a new line. The only exception is f
|
||||
|
||||
if($t ==2){ echo "<div>My long line of code and ".LAN_XXX." etc</div>"; }
|
||||
|
||||
## Comments and Documentation
|
||||
|
||||
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.
|
||||
Headers
|
||||
|
||||
Every file must have one or two standard headers, as defined in Standard headers page
|
||||
Basically as the standard:
|
||||
camelCase for variables
|
||||
UPPER_CASE_WITH_UNDERSCORES for constants
|
||||
|
||||
$camelCase = "value";
|
||||
define("UPPERCASE_CONSTANT","value");
|
||||
|
||||
|
||||
|
||||
# Section 2 - PHP/e107
|
||||
## Language Files and LANS
|
||||
### Headers
|
||||
Every file must have one or two standard headers, as defined in Standard headers page
|
||||
|
||||
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.
|
||||
|
||||
**Good:**
|
||||
|
||||
define("LAN_XXX","Thank you [b]Firstname[/b]");
|
||||
define("LAN_XXX","Thank you [x]"); // Good - replace [ and ] with <a href='...'> and </a> using str_replace()
|
||||
|
||||
|
||||
**Bad:**
|
||||
|
||||
define("LAN_XXX","Thank you <b>Firstname</b>"); //Bad contains HTML
|
||||
define("LAN_XXX","Thank you <a href='www.somewhere.com'>Firstname</a>"); //Bad contains HTML
|
||||
define("LAN_XXX","Thank you [link=www.somewhere.com]Firstname[/link]"); //Bad - allows translator to modify link.
|
||||
|
||||
Avoid short language strings for words such as 'and', 'to' and so on. There aren't always equivalents in other languages. If embedding values into a phrase, use substitution. Avoid using substitution terms which are real words or known bbcodes.
|
||||
|
||||
define('LAN_EXAMPLE_01','Update results: [x] records changed, [y] errors, [z] not changed');
|
||||
$srch = array('[x]','[y]','[z]');
|
||||
$repl = array($changed,$errors,$unchanged);
|
||||
$text = str_replace($srch,$repl,LAN_EXAMPLE_01);
|
||||
|
||||
|
||||
## Programming detail
|
||||
Important: Some of these points related to form elements are deprecated in v2. Instead you should use the new form handler. `$frm->text()`, `$frm->selectbox()` etc. eg. input tags, select boxes etc.
|
||||
### Variables
|
||||
Use camelCase for variables.
|
||||
|
||||
$camelCase = "value";
|
||||
|
||||
### 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.
|
||||
|
||||
define("CONSTANT","some value");
|
||||
|
||||
### 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
|
||||
|
||||
e_BASE; // the root directory of e107's installation
|
||||
e_PLUGIN; // equivalent to: e107_plugins/
|
||||
THEME; // equivalent to current theme directory
|
||||
|
||||
eg.
|
||||
require_once(e_PLUGIN."myplugin/myfile.php");
|
||||
$img = e_PLUGIN_ABS."myplugin/images/myimage.png";
|
||||
|
||||
|
||||
### Forms
|
||||
Always use e107's form handler for form elements.
|
||||
|
||||
$frm = e107::getForm();
|
||||
$frm->select($name,$value);
|
||||
$frm->checkbox($name,$value,$checked);
|
||||
|
||||
$frm->checkbox($name,$value,$checked);
|
||||
$frm->selectbox($name,$array,$currentValue); // full SELECT tag with OPTIONs.
|
||||
|
||||
### 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();
|
||||
$sql = e107::getDb();
|
||||
$pref = e107::getPref(); // grab preferences array
|
||||
$sql = e107::getDb(); // sql class
|
||||
$frm = e107::getForm(); // form class
|
||||
$tp = e107::getParser(); // text/template parsing class
|
||||
$ns = e107::getRender(); // rendering class.
|
||||
$fl = e107::getFile(); // file handling class.
|
||||
|
||||
### Arrays
|
||||
### 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.
|
||||
eg. One example - use the file-class instead of PHP file functions to read directories.
|
||||
|
||||
$fl = e107::getFile();
|
||||
$filesArray = $fl->get_files($path, $fmask);
|
||||
|
||||
Group functions which may be used in multiple areas of e107 into a class, and place the resulting file into the e_HANDLER directory. Where there are 'admin' and 'user' functions, create an 'admin' class which is a descendant of the 'user' class to minimize memory usage in user mode. If the class contains admin functions only, either define the class within the admin file, or create a separate file within the admin directory. **Before adding ANY new class/handler files to e107_handlers/ or a core plugin, be sure to discuss with the head developer of e107.**
|
||||
|
||||
### 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:
|
||||
@@ -145,21 +164,19 @@ Preferred version of above:
|
||||
);
|
||||
$val = $array[$option];
|
||||
|
||||
|
||||
7. Group functions related to a particular area of e107 into a class, and place the resultant file into the e_HANDLER directory. Where there are 'admin' and 'user' functions, create an 'admin' class which is a descendant of the 'user' class to minimize memory usage in user mode. If the class contains admin functions only, either define the class within the admin file, or create a separate file within the admin directory. Before committing ANY new class/handler files to svn, be sure to check with the head developer of e107.
|
||||
|
||||
8. Don't use extract() on arrays (usually DB rows) - 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
|
||||
Don't use 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:**
|
||||
|
||||
$sql = e107::getDb();
|
||||
$array = $sql->retrieve('user', 'user_email, user_name', 'user_id=1');
|
||||
$array = $sql->retrieve('user', 'user_email, user_name', 'user_id=1'); // returns row from table e107_user
|
||||
|
||||
OR
|
||||
|
||||
$array = e107::getDb()->retrieve('user', 'user_email, user_name', 'user_id=1');
|
||||
|
||||
**Bad:**
|
||||
**Avoid:**
|
||||
|
||||
while($row = $sql->db_Fetch(MYSQL_ASSOC)
|
||||
{
|
||||
@@ -169,35 +186,21 @@ Preferred version of above:
|
||||
|
||||
9. 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).
|
||||
|
||||
10. Validate generated HTML on each page you work on.
|
||||
10. Validate generated HTML on each page you work on to Html5.
|
||||
|
||||
11. 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.
|
||||
|
||||
12. Where a feature is upgraded or changed:
|
||||
|
||||
For simple changes, the code should silently handle the situation
|
||||
For more complex changes, an upgrade routine is required
|
||||
For more complex changes, an upgrade routine is required. See [plugin]_setup.php
|
||||
|
||||
13. 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
|
||||
|
||||
Note SITEURLBASE to prepend to absolute links to get a full URL. Note SERVERBASE (2.0 only) to prepend to absolute links to get a full server filesystem reference
|
||||
|
||||
14. To check whether a particular plugin is installed, use function e107::isInstalled($plugname) - returns TRUE if plugin installed. Alternatively, look at $pref['plug_installed'][plug_path'] ('plug_path' is the subdirectory name - e.g. calendar_menu). The array element exists only if the plugin is installed (assuming proper install/uninstall process followed), and contains the version number of the plugin.
|
||||
|
||||
15. Use the following method when dealing with pre-selection of OPTIONs within SELECT tags.
|
||||
|
||||
$frm->selectbox($name,$array);
|
||||
|
||||
16. Where an appropriate handler exists, use it in preference to replicating or bypassing its functionality. eg. One example - use the file-class instead of PHP file functions to read directories.
|
||||
|
||||
|
||||
$fl = e107::getFile();
|
||||
$files = $fl->get_files($path, $fmask);
|
||||
|
||||
|
||||
## SQL Details
|
||||
|
||||
1. Don't enclose integer values in quotes in WHERE clauses - slows up the query. (But make sure there's no way the value can be something other than an integer).
|
||||
@@ -271,6 +274,32 @@ Note the _FIELD_DEFS and _NOTNULL arrays for assisting with producing valid data
|
||||
|
||||
list($id,$email) = explode("|",$array);
|
||||
|
||||
## Language Files and 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.
|
||||
|
||||
**Good:**
|
||||
|
||||
define("LAN_XXX","Thank you [b]Firstname[/b]");
|
||||
define("LAN_XXX","Thank you [x]"); // Good - replace [ and ] with <a href='...'> and </a> using str_replace()
|
||||
|
||||
|
||||
**Bad:**
|
||||
|
||||
define("LAN_XXX","Thank you <b>Firstname</b>"); //Bad contains HTML
|
||||
define("LAN_XXX","Thank you <a href='www.somewhere.com'>Firstname</a>"); //Bad contains HTML
|
||||
define("LAN_XXX","Thank you [link=www.somewhere.com]Firstname[/link]"); //Bad - allows translator to modify link.
|
||||
|
||||
Avoid short language strings for words such as 'and', 'to' and so on. There aren't always equivalents in other languages. If embedding values into a phrase, use substitution. Avoid using substitution terms which are real words or known bbcodes.
|
||||
|
||||
define('LAN_EXAMPLE_01','Update results: [x] records changed, [y] errors, [z] not changed');
|
||||
$srch = array('[x]','[y]','[z]');
|
||||
$repl = array($changed,$errors,$unchanged);
|
||||
$text = str_replace($srch,$repl,LAN_EXAMPLE_01);
|
||||
|
||||
|
||||
|
||||
|
||||
## Template Files
|
||||
|
||||
(TODO v2.0 template standards)
|
||||
|
||||
Reference in New Issue
Block a user