FANDOM


The only way to implement a library or framework is to have an orderly method of producing code. Code conventions are necesary for both the user and the library maintainer. This document outlines what they are. The specification is not comprehensive, but it provides a starting point and a baseline minimum.


Style Edit

Generally speaking, you can get a good idea od the coding style simply by viewing the source-code. for instance:

  • There is a space on either side of assignment and comparison operators
  • No line of code ever spans across the 80 character column margin.
  • Curly braces begin on the same line as the signature/flow-control keyword declaration and they end on their own line (which lines up with the beginning of the declaration)

Indentation Edit

I'm not going to enter the debate about tabs vs spaces. The rule is, we use 4 spaces to indent. Get used to it.

Naming Conventions Edit

For both variables and method names (identifiers), we use CamelCase as opposed to under_scores. As you shouold know, identifiers are case-sensitive in PHP so you have to bear that in mind when utilising them.

Types and Prefixes Edit

We include datatype hints in our identifier names. These hints are in the form a short (usually 3-letter or less) lower-case prefix. For instance the variable $strName is obviously a string. Obviouisly, all variables have a type associated with them, so all variables will have this short lowercase prefix. Methods on the other-hand do not always return something, such method names begin with a capital letter indicating that void is returned. Class and interface names always begin with a Capital. Private member variables and methods need to begin with an underscore. So, for example, $this->_arrMyStuff refers to a private member variable which happens to be an array. Sometimes types go beyond what the PHP language provides - higher level types. For instnace, we may refer to a string which happens to a be well-formed XML document as $xmlMyVar or a DOM node as $ndMyNode. Below is a list of commonly used types. You can invent your own high-level types as long as it is obvious what they are. The primary objective is to make the code easy to read even if it takes a little more effort to produce. The benefits are obvious.

prefix Type
str String
int Integer
dbl Double or Float
bln Boolean
xml Well formed XML as a string
nd DOM node
json JavaScript Object Notation as a string
res A PHP resource
arr A PHP array
obj A PHP object instance
dbl Double

Constructors Edit

This framework is for PHP5 and above only. As such, the __construct identifier MUST be used for all class constructors.

Doc Comments Edit

ALL code MUST be documented with Doc Comments - no exceptions. For details on how to use Doc Comments, see the [PhpDocumentor manual]

Inline Comments Edit

We never really comment inline, but we use comments inside code bocks where there are no Doc Comments. In this case, we use double slash, for instance // todo: need to fix this. they key thing is that inline comments are always on their own line (so they are more in-block than they are in-line). And they begin at column 41 - so they essentially take up the right-hand side half of the 80 column limit. Refer to the example.

An Example Edit

   <?php
   /**
    * _XsltDriver.php
    * 
    * This script defined the base class for all XSLT drivers. All must inherit it.
    */
   
   /**
    * _BaseDriver.php is an base class. All driver classes should inherit this one
    * and override the methods where appropriate.
    * 
    * @import	_BaseDriver.php
    */
   include_once dirname(__FILE__)."/../_BaseDriver.php";
   
   
   /**
    * This class is the base class of all native XSLT driver classes.
    */
   class _XsltDriver extends _BaseDriver {
   
       /**
        * Cache parameters for the XSLT tranformation result
        * 
        * In the standard XAO framework, caching can be done at two stages. The
        * first is at the content generation stage which uses $arrDocCacheParams,
        * the second is at the transformation results stage which uses this array.
        * The array has the same requirements and is used in exactly the same way
        * as the $arrDocCacheParams array. Also see doc comments at XaoRoot::
        * arrCacheParams for more info. NOT IMPLEMENTED YET
        * 
        * @var      array
        */
       protected $arrXsltCacheParams = array();
   
       /**
        * DOM object instance of the source document
        * 
        * This has to be specified in the constructor.
        *
        * @var      object
        */
       protected $objSrc;
       
       /**
        * Whether or not to convert transform output from UTF8 to ISO-5589-1
        * 
        * @access  public
        * @var     bool
        */
       protected $blnUtf8ToWestern = false;
       
       /**
        * DOM instance of XSLT document
        * 
        * @var		object
        */
       protected $objStyle;
       
       /**
        * The stylesheet URI
        * 
        * @var		string
        */
       protected $uriStyleSheet;
   
       /**
        * List of XSL parameters to be passed to the XSLT processor
        * 
        * Usually these will be set by the application class which inherits DomDoc.
        * The transform methods of this class should use this associative array to
        * add these parameters to the processor. WARNING: RELYING ON THIS METHOD OF
        * SETTING XSL PARAMS WILL MAKE YOUR STYLSHEET INCOMPATIBLE WITH CLIENT-SIDE
        * TRANSFORMATION. IMPORTANT NOTE: YOUR PARAMS WILL NOT BE AVAILABLE IN YOUR
        * STYLSHEET IF YOU DO NOT DECLARE THEM (WITH EMPTY VALUES). THE PROCESSOR
        * WILL ONLY FEED PARAM VALUES TO THE STYLESHEET BY OVERRIDING THE VALUES OF
        * EXISTING ONES.
        *
        * @access   public
        * @var      array
        */
       public $arrXslParams = array();
   
       /**
        * XSLT processing result container
        * 
        * Regardless of which XSLT processor is used, the result is always stored
        * in this variable AS A STRING.
        *
        * @var      string
        */
       protected $strXsltResult;
       
       /**
        * Whether or not a transformation has completed successfully
        * 
        * @var		bool
        */
       public $blnCompleted = false;
       
       /**
        * The sonstructor function sets up all the required data
        * 
        * @param	object	An instance of the DOM document source XML
        * @param	string	The location of the stylesheet file to use
        * @return	void
        */
       public function __construct($objDoc,$uriStylSheet) {
                                           // sanity checks
           if(!is_object($objDoc) || !is_a($objDoc,"DOMDocument")) {
               if(is_object($objDoc)) $strType = get_class($objDoc);
               else $strType = gettype($objDoc);
               $this->XaoThrow(
                   "The XSLT class needs a DOMDocument object instance. "
                   .$strType." was passed.",
                   debug_backtrace(),null,true
               );
               return;
           }
           if(!file_exists($uriStylSheet)) {
               $this->XaoThrow(
                   "XSLT transformer class cannot find stylesheet ".$uriStylSheet,
                   debug_backtrace()
               );
               return;
           }
           $this->objSrc = $objDoc;
       }
   
       /**
        * Add or update an XSL parameter for use when the Transformer is called
        * A local array of the parameters is populated for subsequent transferal to
        * the Transformer class when $this->Transform() is called.
        *
        * @param   string  Name of the XSL parameter or an ossicuative array
        * @param   string  String value of the parameter
        * @return  void
        */
       public function SetXslParam($mxdName,$strValue = null) {
                                           // check to see if we process in 
                                           // associative array mode
           if(!$strValue && is_array($mxdName)) {
               foreach($mxdName AS $name => $value) {
                   if($this->blnTestSafeName($name)) {
                       $this->arrXslParams[$name] = $value;
                   }
               }
           }
                                           // otherwise it's just a single param
           elseif(is_string($mxdName) && $mxdName && $strValue !== null) {
               if($this->blnTestSafeName($mxdName)) {
                   $this->arrXslParams[$mxdName] = $strValue;
               }
           }
                                           // whoops!
           else {
               $this->XaoThrow(
                   "_XsltDriver::SetXslParam() Invalid arguments.",
                   debug_backtrace()
               );
           }
       }
       
       /**
        * Gets the text output of the transform if one has successfully completed.
        * 
        * @return 	string	the results of the transform.
        */
       public function strGetXsltResult() {
                                           // We only return a result if processing
                                           // has completed
           if($this->blnCompleted) {
               return $this->strXsltResult;
           }
           else {
               $this->XaoThrow(
                   "_XsltDriver::strGetXsltResult() A result cannot be returned"
                   ." until a transformation has been completed",
                   debug_backtrace()
               );
           }
       } 
       
       /**
        * To be overridden
        */
       public function Transform() {
           $this->__not_implemented();
       }
   }
   
   ?>

Ad blocker interference detected!


Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.