[Sommaire] [Imprimer]

   1  $Id: STANDARD,v 1.13 2003/06/09 21:13:13 hpdl Exp $
   2  
   3  osCommerce Coding Standards
   4  
   5  Coding standards are defined to keep the codebase in a maintainable state.
   6  
   7  The more developers working within the codebase means the more ways php
   8  logic can be written.
   9  
  10  If every developer follows the standards then everyone is able to review
  11  the codebase and not waste time thinking about why a certain style was
  12  used in a particular area compared to another area.
  13  
  14  File Format
  15  -----------
  16  
  17  The source code should be saved in Unix format - meaning with Unix
  18  linefeeds.
  19  
  20  Most editors are able to set the preferred format method of Windows,
  21  Unix, or Macintosh.
  22  
  23  Some editors add a line to the bottom of the file. This is safe to have
  24  as long as a further character (including the space character) does not
  25  exist. Characters that exist at the end of the file may interfer when
  26  redirections occur as text has been sent to the client already.
  27  
  28  The filename of the files must be all lowercass characters and contain
  29  no more than 31 characters to be Apple/Mac compatible.
  30  
  31  Indentation
  32  -----------
  33  
  34  Indentation of logic should be 2 whitespace characters.
  35  
  36  TABs should not be used.
  37  
  38  Starting and Ending PHP Logic
  39  -----------------------------
  40  
  41  When starting PHP logic, the tag should be written as "<?php", not in the
  42  short form of "<?" or in ASP compatible tags such as "<%".
  43  
  44  The end tag to mark the end of the PHP logic should be written as "?>".
  45  
  46  A valid example:
  47  
  48  <?php
  49    echo "Hello World!";
  50  ?>
  51  
  52  Defining Constants
  53  ------------------
  54  
  55  Constants must be defined before they are being used - which also includes
  56  constants called from include()'d/require()'d files.
  57  
  58  Variable Scope*
  59  --------------
  60  
  61  All variables must be accessed and set within their scope as:
  62  
  63  $HTTP_GET_VARS['variable']
  64  $HTTP_POST_VARS['variable']
  65  $HTTP_COOKIE_VARS['variable']
  66  $variable (either local, or session)
  67  
  68  * This needs to be updated when the codebase has been made compatible with
  69  the register_global parameter. Session variables are then accessed and set
  70  within its scope as:
  71  
  72  $HTTP_SESSION_VARS['variable']
  73  
  74  When PHP3 support is dropped, the following scope will be used:
  75  
  76  $_GET['variable']
  77  $_POST['variable']
  78  $_COOKIE['variable']
  79  $_SESSION['variable']
  80  
  81  PHP 4.0.x does not support the above scope which was introduced in PHP 4.1.x.
  82  The following can be used which is not compatible with PHP 3.x:
  83  
  84  $_GET =& $HTTP_GET_VARS;
  85  $_POST =& $HTTP_POST_VARS;
  86  $_COOKIE =& $HTTP_COOKIE_VARS;
  87  $_SESSION =& $HTTP_SESSION_VARS;
  88  
  89  include() vs require()
  90  ----------------------
  91  
  92  The use of include() will include the specified file when needed, whereas
  93  the use of require() will always include the specified file regardless if it
  94  is needed or not.
  95  
  96  Example:
  97  
  98  <?php
  99    require('file.php');
 100  
 101    if (condition == true) {
 102      include('file_true.php');
 103    } else {
 104      ...
 105    }
 106  ?>
 107  
 108  Instantiating Classes
 109  ---------------------
 110  
 111  When instantiating classes into objects, the following style must be used:
 112  
 113  <?php
 114  // without class parameters*
 115    $object = new className;
 116    
 117  // with class parameters
 118    $object = new className($parameter1);
 119  ?>
 120  
 121  * PHP3 does not support the following style which includes an empty bracket
 122  set:
 123  
 124  <?php
 125    $object = new className();
 126  ?>
 127  
 128  Displaying Strings
 129  ------------------
 130  
 131  Strings or values should be displayed as:
 132  
 133  <?php
 134    echo 'Hello Mr Mister!';
 135  ?>
 136  
 137  The following styles should be avoided:
 138  
 139  <?php
 140    print $variable;
 141  ?>
 142  
 143  <?=$variable;?>
 144  
 145  Singe-Quotes vs Double-Quotes
 146  -----------------------------
 147  
 148  When displaying strings single quote characters should be used.
 149  
 150  Double quote characters should be used only when control characters are
 151  needed.
 152  
 153  For example:
 154  
 155  <?php
 156    echo 'Hello Mr Mister!' . "\n";
 157  ?>
 158  
 159  
 160  Custom Functions
 161  ----------------
 162  
 163  All custom functions should start with tep_ so that the developer knows
 164  a native PHP function is not being called.*
 165  
 166  An example custom function style:
 167  
 168  <?php
 169    function tep_my_function($parameter, $optional = '') {
 170      global $HTTP_GET_VARS, $another_variable;
 171  
 172      ....
 173  
 174      return true;
 175    }
 176  ?>
 177  
 178  * When 2.2 is finalized the custom functions should be renamed to osc_*
 179  as "tep" refers to the previous name of the project.
 180  
 181  Class Names
 182  -----------
 183  
 184  There are two types of styles to use when classes are used.
 185  
 186  The first type of class set are the static classes that can be found in
 187  the includes/classes directory.
 188  
 189  If the class name contains more than one word, the words in the filename
 190  are separated with an underscore character. The actual class name is one
 191  whole word where words from the second onwards being capitalized.
 192  
 193  For example, a class name of myOwnClass has a filename of
 194  my_own_class.php.
 195  
 196  The second type of class set are the dynamic modules that can be found
 197  in the includes/modules/* directories.
 198  
 199  The class names must match the filename as most of them are include()'d
 200  dynamicly.
 201  
 202  For example, a class filename of my_own_module.php has a class name of
 203  my_own_module.
 204  
 205  Class Structure
 206  ---------------
 207  
 208  The class should be written in the following structure:
 209  
 210  <?php
 211    class myclass {
 212      var $variable;
 213  
 214  // class constuctor
 215      function myclass() {
 216  
 217        ....
 218  
 219        return true;
 220      }
 221  
 222  // class methods
 223      function do_something() {
 224  
 225        $this->variable = 'set';
 226  
 227        return true;
 228      }
 229    }
 230  
 231    $class = new myclass;
 232    $class->do_something();
 233  ?>
 234  
 235  Database Queries
 236  ----------------
 237  
 238  Database queries are wrapped around custom functions and should be
 239  structured as:
 240  
 241  <?php
 242  // multi-result set
 243    $action_query = tep_db_query("select column1, ...");
 244    while ($action = tep_db_fetch_array($action_query)) {
 245      echo $action['column1'];
 246    }
 247  
 248  // single result set
 249    $action_query = tep_db_query("select column1, ...");
 250    $action = tep_db_fetch_array($action_query);
 251  
 252    echo $action['column1'];
 253  
 254  // return number of rows
 255    $action_query = tep_db_query("select count(*) as total from ...");
 256    $action = tep_db_fetch_array($action_query);
 257  
 258    echo $action['total'];
 259  
 260  // query with parameters
 261    $action_query = tep_db_query("select column1 from table where field = '" . tep_db_input($some_id) . "'");
 262    while ($action = tep_db_fetch_array($action_query)) {
 263      ....
 264    }
 265  ?>
 266  
 267  Unlike displaying strings, double quote characters are wrapped around the sql query.
 268  
 269  The following is currently for the Administration Tool but will also be implemented
 270  in the Catalog module.
 271  
 272  Before data can be entered in the database, it must be protected against possible
 273  attacks residing in the user input. The data is first prepared and then protected
 274  when inserting it into the table. The following structure is used:
 275  
 276  <?php
 277    $value1 = tep_db_prepare_input($HTTP_POST_VARS['value1']);
 278  
 279    tep_db_query("update table set column = '" . tep_db_input($value1) . "' where id = '" . (int)$id . "'");
 280  ?>
 281  
 282  Variable type casting should be performed directly for integer based values, such
 283  as column IDs: (int)$variable
 284  
 285  Multiple values can be parsed, protected and inserted into the table in an easier
 286  fashion:
 287  
 288  <?php
 289    $value1 = tep_db_prepare_input($HTTP_POST_VARS['value1']);
 290    $value2 = tep_db_prepare_input($HTTP_POST_VARS['value2']);
 291    $value3 = tep_db_prepare_input($HTTP_POST_VARS['value3']);
 292  
 293    $sql_data_array = array('column1' => $value1,
 294                            'column2' => $value2,
 295                            'column3' => $value3);
 296  
 297    tep_db_perform('table', $sql_data_array);
 298  ?>
 299  
 300  A similar structure can be used for updating values in a table:
 301  
 302  <?php
 303    $value1 = tep_db_prepare_input($HTTP_POST_VARS['value1']);
 304    $value2 = tep_db_prepare_input($HTTP_POST_VARS['value2']);
 305    $value3 = tep_db_prepare_input($HTTP_POST_VARS['value3']);
 306  
 307    $sql_data_array = array('column1' => $value1,
 308                            'column2' => $value2,
 309                            'column3' => $value3);
 310  
 311    tep_db_perform('table', $sql_data_array, 'update', "id = '" . (int)$id . "'");
 312  ?>
 313  
 314  Table names should not directly be entered in the query, but the constant
 315  parameter assigned to that table. A list of defined constant table names
 316  can currently be found in includes/database_tables.php.
 317  
 318  Function Output
 319  ---------------
 320  
 321  All custom functions should return strings; not directly via echo().
 322  
 323  For example:
 324  
 325  <?php
 326    function tep_my_function($string) {
 327      return $string;
 328    }
 329  ?>
 330  
 331  and not:
 332  
 333  <?php
 334    function tep_my_function($string) {
 335      echo $string;
 336    }
 337  ?>
 338  
 339  Condition Statements
 340  --------------------
 341  
 342  If statements should be written as:
 343  
 344  <?php
 345    if (condition == true) {
 346      ....
 347    } else {
 348      ....
 349    }
 350  ?>
 351  
 352  If the condition is to check for a boolean value, this should be added
 353  to the condition (as above) for clarity.
 354  
 355  The following should not be used:
 356  
 357  <?php
 358    if (!$condition) {
 359      ....
 360    }
 361  ?>
 362  
 363  instead use the following:
 364  
 365  <?php
 366    if ($condition == false) {
 367      ....
 368    }
 369  ?>
 370  
 371  Multiple conditions should reside in their own parenthesis, as:
 372  
 373  <?php
 374    if ( (condition == true) && (condition == true) ) {
 375      ....
 376    }
 377  ?>
 378  
 379  Simple boolean expressions can be written as:
 380  
 381  <?php
 382    $value = (($condition == true) ? 'true' : 'false');
 383  ?>
 384  
 385  Simple statements can be written as:
 386  
 387  <?php
 388    if ($condition == true) ....
 389  ?>
 390  
 391  Functions do not need to be checked with a true/false
 392  statement. For the following valid example:
 393  
 394  <?php
 395    if (empty($string)) {
 396      ...
 397    }
 398  
 399    if ( (isset($variable)) && (tep_not_null($string)) ) {
 400      ...
 401    }
 402  ?>
 403  
 404  Switch-Case statements should be written as:
 405  
 406  <?php
 407    switch ($value) {
 408      case '1':
 409        ....
 410        break;
 411      case '2':
 412        ....
 413        break;
 414      default:
 415        ....
 416        break;
 417    }
 418  ?>
 419  
 420  Condition Checking
 421  ------------------
 422  
 423  To see if a variable exists, use the following structure:
 424  
 425  <?php
 426    if (isset($variable)) {
 427      ...
 428    }
 429  ?>
 430  
 431  and not:
 432  
 433  <?php
 434    if ($variable) {
 435      ...
 436    }
 437  ?>
 438  
 439  Repetitive Statements
 440  ---------------------
 441  
 442  while loops should be written as:
 443  
 444  <?php
 445    while (condition == true) {
 446      ....
 447    }
 448  ?>
 449  
 450  Walking through an array should be written as:
 451  
 452  <?php
 453  // for php3 compatibility
 454    reset($array);
 455    while (list($key, $value) = each($array)) {
 456      ....
 457    }
 458  
 459  // the php4 way
 460    foreach ($array as $key => $value) {
 461      ....
 462    }
 463  ?>
 464  
 465  for loops should be written as:
 466  
 467  <?php
 468    for ($i=0, $n=sizeof($array); $i<$n; $i++) {
 469      ....
 470    }
 471  ?>
 472  
 473  Mixing HTML and PHP
 474  -------------------
 475  
 476  Common HTML tags started in HTML must end in HTML, and
 477  tags started in PHP must end in PHP.
 478  
 479  Wrong:
 480  
 481  <td><?php echo "Hello</td>"; ?>
 482  
 483  Correct:
 484  
 485  <td><?php echo "Hello"; ?></td>
 486  
 487  Correct:
 488  
 489  <?php
 490    echo '<td>Hello</td>';
 491  ?>
 492  
 493  Exceptions to this standard include the tep_draw_form()
 494  function:
 495  
 496  <?php
 497    echo tep_draw_form();
 498  ?>
 499  [form input fields are placed here]
 500  </form>
 501  ?>