root

Changeset 315

Show
Ignore:
Timestamp:
10/19/08 00:32:49 (2 years ago)
Author:
wbond
Message:

More API documentation updates

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • fActiveRecord.php

    r314 r315 Hide Line Numbers
    11<?php 
    22/** 
    3  * An {@link http://en.wikipedia.org/wiki/Active_record_pattern active record pattern} base class 
     3 * An [http://en.wikipedia.org/wiki/Active_record_pattern active record pattern] base class 
    44 *  
    5  * This class uses {@link fORMSchema} to inspect your database and provides an 
     5 * This class uses fORMSchema to inspect your database and provides an 
    66 * OO interface to a single database table. The class dynamically handles 
    77 * method calls for getting, setting and other operations on columns. It also 
    …… 
    2828     
    2929    /** 
    30      * Sets a value to the $values array, preserving the old value in $old_values 
     30     * Sets a value to the `$values` array, preserving the old value in `$old_values` 
    3131     * 
    3232     * @internal 
    …… 
    122122     * value has changed. The value associated with each key is an array of 
    123123     * old values with the first entry being the oldest value. The static  
    124      * methods {@link assign()}, {@link changed()}, {@link has()} and 
    125      * {@link retrieve()} are the best way to interact with this array. 
     124     * methods ::assign(), ::changed(), ::has() and ::retrieve() are the best  
     125     * way to interact with this array. 
    126126     *  
    127127     * @var array 
    …… 
    133133     *  
    134134     * This array is used to cache related records so that a database query 
    135      * is not required each time related records are accessed. The 
    136      * {@link fORMRelated} class handles most of the interaction with this 
    137      * array. 
     135     * is not required each time related records are accessed. The fORMRelated 
     136     * class handles most of the interaction with this array. 
    138137     *  
    139138     * @var array 
    …… 
    155154     * Handles all method calls for columns, related records and hook callbacks 
    156155     *  
    157      * Dynamically handles get, set, prepare, encode and inspect methods for 
    158      * each column in this record. Method names are in the form verbColumName(). 
    159      *  
    160      * This method also handles associate, build, count and link verbs for 
    161      * records in many-to-many relationships; build, count and populate verbs 
    162      * for all related records in one-to-many relationships and the create verb 
    163      * for all related records in *-to-one relationships. 
    164      *  
    165      * replace:: hook callbacks registered through 
    166      * {@link fORM::registerHookCallback()} will be delegated via this method. 
     156     * Dynamically handles `get`, `set`, `prepare`, `encode` and `inspect` 
     157     * methods for each column in this record. Method names are in the form 
     158     * `verbColumName()`. 
     159     *  
     160     * This method also handles `associate`, `build`, `count` and `link` verbs 
     161     * for records in many-to-many relationships; `build`, `count` and 
     162     * `populate` verbs for all related records in one-to-many relationships 
     163     * and the `create` verb for all related records in *-to-one relationships. 
     164     *  
     165     * `replace::` hook callbacks registered through 
     166     * fORM::registerHookCallback() will be delegated via this method. 
    167167     *  
    168168     * @throws fValidationException 
    …… 
    316316     * @throws fNotFoundException 
    317317     *  
    318      * @param  mixed $primary_key  The primary key value(s). If multi-field, use an associative array of (string) {field name} => (mixed) {value}. 
     318     * @param  mixed $primary_key  The primary key value(s). If multi-field, use an associative array of `(string) {field name} => (mixed) {value}`. 
    319319     * @return fActiveRecord 
    320320     */ 
    …… 
    677677     *  - **float**: takes 1 parameter to specify the number of decimal places 
    678678     *  - **date, time, timestamp**: `format()` will be called on the fDate/fTime/fTimestamp object with the 1 parameter specified 
    679      *  - **objects**: the object will be converted to a string by `__toString()` or a string cast and then will be run through fHTML::encode() 
     679     *  - **objects**: the object will be converted to a string by `__toString()` or a `(string)` cast and then will be run through fHTML::encode() 
    680680     *  - **all other data types**: the value will be run through fHTML::encode() 
    681681     *  
    …… 
    10451045     *  
    10461046     * Below are the transformations performed: 
    1047      *   - varchar, char, text columns: will run through {@link fHTML::prepare()} 
    1048      *   - boolean: will return 'Yes' or 'No' 
    1049      *   - integer: will add thousands/millions/etc. separators 
    1050      *   - float: will add thousands/millions/etc. separators and takes 1 parameter to specify the number of decimal places 
    1051      *   - date, time, timestamp: format() will be called on the {@link fDate}/{@link fTime}/{@link fTimestamp} object with the 1 parameter specified 
    1052      *   - objects: objects: the object will be converted to a string by __toString() or a string cast and then will be run through {@link fHTML::prepare()} 
     1047     *  
     1048     *  - **varchar, char, text**: will run through fHTML::prepare() 
     1049     *  - **boolean**: will return `'Yes'` or `'No'` 
     1050     *  - **integer**: will add thousands/millions/etc. separators 
     1051     *  - **float**: will add thousands/millions/etc. separators and takes 1 parameter to specify the number of decimal places 
     1052     *  - **date, time, timestamp**: `format()` will be called on the fDate/fTime/fTimestamp object with the 1 parameter specified 
     1053     *  - **objects**: the object will be converted to a string by `__toString()` or a `(string)` cast and then will be run through fHTML::prepare() 
    10531054     *  
    10541055     * @param  string $column      The name of the column to retrieve 

  • fAuthorization.php

    r311 r315 Hide Line Numbers
    6363     * Adds a named IP address or range, or array of addresses and/or ranges 
    6464     *  
    65      * This method allows {@link checkIP()} to be called with a name instead 
    66      * of the actual IPs. 
    67      *  
    68      * @param  string $name       The name to give the IP address(es)/range(s) 
    69      * @param  mixed  $ip_ranges  This can be string (or array of strings) of the IP(s) or IP range(s) to restrict to. Please see the {@link checkIP()} method description for details on the allowable formats. 
     65     * This method allows ::checkIP() to be called with a name instead of the 
     66     * actual IPs. 
     67     *  
     68     * @param  string $name       The name to give the IP addresses/ranges 
     69     * @param  mixed  $ip_ranges  This can be string (or array of strings) of the IPs or IP ranges to restrict to - please see ::checkIP() for format details 
    7070     * @return void 
    7171     */ 
    …… 
    139139     * Checks to see if the user is from the IPs or IP ranges specified 
    140140     *  
    141      * The $ip_ranges parameter can be either a single string, or an array of 
     141     * The `$ip_ranges` parameter can be either a single string, or an array of 
    142142     * strings, each of which should be in one of the following formats: 
    143      *   - A single IP address: 
    144      *     - 192.168.1.1 
    145      *     - 208.77.188.166 
    146      *   - A CIDR range 
    147      *     - 192.168.1.0/24 
    148      *     - 208.77.188.160/28 
    149      *   - An IP/subnet mask combination 
    150      *     - 192.168.1.0/255.255.255.0 
    151      *     - 208.77.188.160/255.255.255.240 
    152      *  
    153      * @param  mixed $ip_ranges  This can be string (or array of strings) of the IPs or IP ranges to restrict to. See method description for details. 
     143     *   
     144     *  - A single IP address: 
     145     *   - 192.168.1.1 
     146     *   - 208.77.188.166 
     147     *  - A CIDR range 
     148     *   - 192.168.1.0/24 
     149     *   - 208.77.188.160/28 
     150     *  - An IP/subnet mask combination 
     151     *   - 192.168.1.0/255.255.255.0 
     152     *   - 208.77.188.160/255.255.255.240 
     153     *  
     154     * @param  mixed $ip_ranges  A string (or array of strings) of the IPs or IP ranges to restrict to - see method description for details 
    154155     * @return boolean  If the user is coming from (one of) the IPs or ranges specified 
    155156     */ 
    …… 
    274275     
    275276    /** 
    276      * Gets the value that was set as the user token, NULL if no token has been set 
    277      *  
    278      * @return mixed  The user token that had been set, NULL if none 
     277     * Gets the value that was set as the user token, `NULL` if no token has been set 
     278     *  
     279     * @return mixed  The user token that had been set, `NULL` if none 
    279280     */ 
    280281    static public function getUserToken() 
    …… 
    368369     * Sets the authorization levels to use for level checking 
    369370     *  
    370      * @param  array $levels  An associative array of (string) {level} => (integer), for each level 
     371     * @param  array $levels  An associative array of `(string) {level} => (integer) {value}`, for each level 
    371372     * @return void 
    372373     */ 
    …… 
    406407     * Array should be formatted like: 
    407408     *  
    408      * <pre> 
     409     * {{{ 
    409410     * array ( 
    410      *     (string) {resource name} => array((mixed) {permission}, ... ), ... 
     411     *     (string) {resource name} => array( 
     412     *         (mixed) {permission}, ... 
     413     *     ), ... 
    411414     * ) 
    412      * </pre> 
    413      *  
    414      * The resource name or the permission may be the single character '*' 
     415     * }}} 
     416     *  
     417     * The resource name or the permission may be the single character `'*'` 
    415418     * which acts as a wildcard. 
    416419     *  
    417      * @param  array $acls  The logged in user's ACLs (see method description for format) 
     420     * @param  array $acls  The logged in user's ACLs - see method description for format 
    418421     * @return void 
    419422     */ 

  • fBuffer.php

    r311 r315 Hide Line Numbers
    11<?php 
    22/** 
    3  * Provides a single, simplified interface for {@link http://php.net/outcontrol output buffering} to prevent nested buffering issues and provide a more logical API 
     3 * Provides a single, simplified interface for [http://php.net/outcontrol output buffering] to prevent nested buffering issues and provide a more logical API 
    44 *  
    55 * @copyright  Copyright (c) 2008 William Bond 
    …… 
    187187     
    188188    /** 
    189      * Starts capturing output, should be used with {@link stopCapture()} to grab output from code that does not offer an option of returning a value instead of outputting it 
     189     * Starts capturing output, should be used with ::stopCapture() to grab output from code that does not offer an option of returning a value instead of outputting it 
    190190     *  
    191191     * @return void 

  • fCookie.php

    r311 r315 Hide Line Numbers
    6363     
    6464    /** 
    65      * Gets a cookie value from $_COOKIE, while allowing a default value to be provided 
     65     * Gets a cookie value from `$_COOKIE`, while allowing a default value to be provided 
    6666     *  
    6767     * @param  string $name           The name of the cookie to retrieve 
    …… 
    103103     *  
    104104     * The following methods allow for setting default parameters for this method: 
    105      *   - {@link setDefaultExpires()}:  Sets the default for the $expires parameter 
    106      *   - {@link setDefaultPath()}:     Sets the default for the $path parameter 
    107      *   - {@link setDefaultDomain()}:   Sets the default for the $domain parameter 
    108      *   - {@link setDefaultSecure()}:   Sets the default for the $secure parameter 
    109      *   - {@link setDefaultHTTPOnly()}: Sets the default for the $httponly parameter 
     105     *    
     106     *  - ::setDefaultExpires():  Sets the default for the `$expires` parameter 
     107     *  - ::setDefaultPath():     Sets the default for the `$path` parameter 
     108     *  - ::setDefaultDomain():   Sets the default for the `$domain` parameter 
     109     *  - ::setDefaultSecure():   Sets the default for the `$secure` parameter 
     110     *  - ::setDefaultHTTPOnly(): Sets the default for the `$httponly` parameter 
    110111     *  
    111112     * @param  string         $name      The name of the cookie to set 
    112113     * @param  mixed          $value     The value of the cookie to set 
    113      * @param  string|integer $expires   A relative string to be interpreted by {@link http://php.net/strtotime strtotime()} or an integer unix timestamp 
     114     * @param  string|integer $expires   A relative string to be interpreted by [http://php.net/strtotime strtotime()] or an integer unix timestamp 
    114115     * @param  string         $path      The path this cookie applies to 
    115116     * @param  string         $domain    The domain this cookie applies to 
    …… 
    176177     * Sets the default domain to use for cookies 
    177178     *  
    178      * This value will be used when the $domain parameter of the {@link set()} 
    179      * method is not specified or is set to NULL. 
     179     * This value will be used when the `$domain` parameter of the ::set() 
     180     * method is not specified or is set to `NULL`. 
    180181     *  
    181182     * @param  string $domain  The default domain to use for cookies 
    …… 
    191192     * Sets the default expiration date to use for cookies 
    192193     *  
    193      * This value will be used when the $expires parameter of the {@link set()} 
    194      * method is not specified or is set to NULL. 
     194     * This value will be used when the `$expires` parameter of the ::set() 
     195     * method is not specified or is set to `NULL`. 
    195196     *  
    196197     * @param  string|integer $expires  The default expiration date to use for cookies 
    …… 
    206207     * Sets the default httponly flag to use for cookies 
    207208     *  
    208      * This value will be used when the $httponly parameter of the {@link set()} 
    209      * method is not specified or is set to NULL. 
     209     * This value will be used when the `$httponly` parameter of the ::set() 
     210     * method is not specified or is set to `NULL`. 
    210211     *  
    211212     * @param  boolean $httponly  The default httponly flag to use for cookies 
    …… 
    221222     * Sets the default path to use for cookies 
    222223     *  
    223      * This value will be used when the $path parameter of the {@link set()} 
    224      * method is not specified or is set to NULL. 
     224     * This value will be used when the `$path` parameter of the ::set() 
     225     * method is not specified or is set to `NULL`. 
    225226     *  
    226227     * @param  string $path  The default path to use for cookies 
    …… 
    234235     
    235236    /** 
    236      * Sets the default httponly flag to use for cookies 
    237      *  
    238      * @param  boolean $httponly  The default secure flag to use for cookies 
     237     * Sets the default secure flag to use for cookies 
     238     *  
     239     * This value will be used when the `$secure` parameter of the ::set() 
     240     * method is not specified or is set to `NULL`. 
     241     *  
     242     * @param  boolean $secure  The default secure flag to use for cookies 
    239243     * @return void 
    240244     */ 

  • fCore.php

    r311 r315 Hide Line Numbers
    192192     * multiple parameters. 
    193193     *  
    194      * <pre> 
     194     * {{{ 
     195     * #!php 
    195196     * // Passing multiple parameters in a normal fashion 
    196197     * fCore::call('Class::method', TRUE, 0, 'test'); 
    …… 
    198199     * // Passing multiple parameters in a parameters array 
    199200     * fCore::call('Class::method', array(TRUE, 0, 'test')); 
    200      * </pre> 
     201     * }}} 
    201202     *  
    202203     * To pass parameters by reference they must be assigned to an 
    …… 
    205206     * will be passed by value. 
    206207     *  
    207      * <pre> 
     208     * {{{ 
     209     * #!php 
    208210     * // Passing parameters by reference 
    209211     * fCore::call('Class::method', array(&$var1, &$var2)); 
    210      * </pre> 
     212     * }}} 
    211213     *  
    212214     * @param  callback $callback    The function or method to call 
    …… 
    258260     * Checks an error/exception destination to make sure it is valid 
    259261     *  
    260      * @param  string $destination  The destination for the exception. An email, file or the string 'html'. 
    261      * @return string|boolean  'email', 'file', 'html' or FALSE 
     262     * @param  string $destination  The destination for the exception. An email, file or the string `'html'`. 
     263     * @return string|boolean  `'email'`, `'file'`, `'html'` or `FALSE` 
    262264     */ 
    263265    static private function checkDestination($destination) 
    …… 
    301303     
    302304    /** 
    303      * Creates a string representation of any variable using predefined strings for booleans, null and empty strings 
     305     * Creates a string representation of any variable using predefined strings for booleans, `NULL` and empty strings 
    304306     *  
    305307     * The string output format of this method is very similar to the output of 
    306      * {@link http://php.net/print_r print_r()} except that the following values 
     308     * [http://php.net/print_r print_r()] except that the following values 
    307309     * are represented as special strings: 
    308      *   - TRUE: {true} 
    309      *   - FALSE: {false} 
    310      *   - NULL: {null} 
    311      *   - '': {empty_string} 
     310     *    
     311     *  - `TRUE`: `'{true}'` 
     312     *  - `FALSE`: `'{false}'` 
     313     *  - `NULL`: `'{null}'` 
     314     *  - `''`: `'{empty_string}'` 
    312315     *  
    313316     * @param  mixed $data  The value to dump 
    …… 
    374377     
    375378    /** 
    376      * Enables debug messages globally, i.e. they will be shown for any call to {@link debug()} 
     379     * Enables debug messages globally, i.e. they will be shown for any call to ::debug() 
    377380     *  
    378381     * @param  boolean $flag  If debugging messages should be shown 
    …… 
    388391     * Turns on a feature where undefined constants are automatically created with the string value equivalent to the name 
    389392     *  
    390      * This functionality only works if {@link enableErrorHandling()} has been 
     393     * This functionality only works if ::enableErrorHandling() has been 
    391394     * called first. This functionality may have a very slight performance 
    392      * impact since a E_STRICT error message must be captured and then a 
    393      * call to {@link http://php.net/define define()} is made. 
     395     * impact since a `E_STRICT` error message must be captured and then a 
     396     * call to [http://php.net/define define()] is made. 
    394397     *  
    395398     * @return void 
    …… 
    413416     * Turns on developer-friendly error handling that includes context information including a backtrace and superglobal dumps 
    414417     *  
    415      * All errors that match the current error_reporting() level will be 
     418     * All errors that match the current 
     419     * [http://php.net/error_reporting error_reporting()] level will be 
    416420     * redirected to the destination and will include a full backtrace. In 
    417421     * addition, dumps of the following superglobals will be made to aid in 
    418422     * debugging: 
    419      *   - $_SERVER 
    420      *   - $_POST 
    421      *   - $_GET 
    422      *   - $_SESSION 
    423      *   - $_FILES 
    424      *   - $_COOKIE 
     423     *  
     424     *  - `$_SERVER` 
     425     *  - `$_POST` 
     426     *  - `$_GET` 
     427     *  - `$_SESSION` 
     428     *  - `$_FILES` 
     429     *  - `$_COOKIE` 
    425430     *  
    426431     * The superglobal dumps are only done once per page, however a backtrace 
    …… 
    429434     * If an email address is specified for the destination, only one email 
    430435     * will be sent per script execution. If both error and 
    431      * {@link enableExceptionHandling() exception handling} are set to the same 
     436     * [enableExceptionHandling() exception handling] are set to the same 
    432437     * email address, the email will contain both errors and exceptions. 
    433438     *  
    434      * @param  string $destination  The destination for the errors and context information - an email address, a file path or the string 'html' 
     439     * @param  string $destination  The destination for the errors and context information - an email address, a file path or the string `'html'` 
    435440     * @return void 
    436441     */ 
    …… 
    450455     *  
    451456     * Any uncaught exception will be redirected to the destination specified, 
    452      * and the page will execute the $closing_code callback before exiting. The 
    453      * destination will receive a message with the exception messaage, a full 
    454      * backtrace and dumps of the following superglobals to aid in debugging: 
    455      *   - $_SERVER 
    456      *   - $_POST 
    457      *   - $_GET 
    458      *   - $_SESSION 
    459      *   - $_FILES 
    460      *   - $_COOKIE 
     457     * and the page will execute the `$closing_code` callback before exiting. 
     458     * The destination will receive a message with the exception messaage, a 
     459     * full backtrace and dumps of the following superglobals to aid in 
     460     * debugging: 
     461     *  
     462     *  - `$_SERVER` 
     463     *  - `$_POST` 
     464     *  - `$_GET` 
     465     *  - `$_SESSION` 
     466     *  - `$_FILES` 
     467     *  - `$_COOKIE` 
    461468     *  
    462469     * The superglobal dumps are only done once per page, however a backtrace 
    …… 
    468475     * If an email address is specified for the destination, only one email 
    469476     * will be sent per script execution. If both exception and 
    470      * {@link enableErrorHandling() error handling} are set to the same 
     477     * [enableErrorHandling() error handling] are set to the same 
    471478     * email address, the email will contain both exceptions and errors. 
    472479     *  
    473      * @param  string   $destination   The destination for the exception and context information - an email address, a file path or the string 'html' 
     480     * @param  string   $destination   The destination for the exception and context information - an email address, a file path or the string `'html'` 
    474481     * @param  callback $closing_code  This callback will happen after the exception is handled and before page execution stops. Good for printing a footer. 
    475      * @param  array    $parameters    The parameters to send to $closing_code 
     482     * @param  array    $parameters    The parameters to send to `$closing_code` 
    476483     * @return void 
    477484     */ 
    …… 
    490497     
    491498    /** 
    492      * Prints the {@link dump()} of a value in a pre tag with the class "exposed" 
     499     * Prints the ::dump() of a value in a pre tag with the class `exposed` 
    493500     *  
    494501     * @param  mixed $data  The value to show 
    …… 
    504511     * Generates some information about the context of an error or exception 
    505512     *  
    506      * @return string  A string containing $_SERVER, $_GET, $_POST, $_FILES, $_SESSSION 
     513     * @return string  A string containing `$_SERVER`, `$_GET`, `$_POST`, `$_FILES`, `$_SESSION` and `$_COOKIE` 
    507514     */ 
    508515    static private function generateContext() 
    …… 
    521528     * Returns the (generalized) operating system the code is currently running on 
    522529     *  
    523      * @return string  Either 'windows', 'solaris' or 'linux/unix' (linux, *BSD) 
     530     * @return string  Either `'windows'`, `'solaris'` or `'linux/unix'` (linux, *BSD) 
    524531     */ 
    525532    static public function getOS() 
    …… 
    652659     
    653660    /** 
    654      * Adds a callback for when certain types of exceptions are {@link toss() tossed}  
     661     * Adds a callback for when certain types of exceptions are [toss() tossed]  
    655662     *  
    656663     * The callback will be called when any exception of the class, or any 
    …… 
    786793     
    787794    /** 
    788      * Returns TRUE for non-empty strings, numbers, objects, empty numbers and string-like numbers (such as 0, 0.0, '0') 
     795     * Returns `TRUE` for non-empty strings, numbers, objects, empty numbers and string-like numbers (such as `0`, `0.0`, `'0'`) 
    789796     *  
    790797     * @param  mixed $value  The value to check 
    …… 
    838845     * The default error handler in PHP will show the line number of this 
    839846     * method as the triggering code. To get a full backtrace, use 
    840      * {@link enableErrorHandling()}. 
    841      *  
    842      * @param  string $error_type  The type of error to trigger: 'error', 'warning', 'notice' 
     847     * ::enableErrorHandling(). 
     848     *  
     849     * @param  string $error_type  The type of error to trigger: `'error'`, `'warning'`, `'notice'` 
    843850     * @param  string $message     The error message 
    844851     * @return void 

  • fCryptography.php

    r273 r315 Hide Line Numbers
    11<?php 
    22/** 
    3  * Provides cryptography functionality, including hashing, symmetric key encryption and public key encryption 
     3 * Provides cryptography functionality, including hashing, symmetric-key encryption and public-key encryption 
    44 *  
    55 * @copyright  Copyright (c) 2007-2008 William Bond 
    …… 
    2929     
    3030    /** 
    31      * Checks a password against a hash 
     31     * Checks a password against a hash created with ::hashPassword() 
    3232     *  
    3333     * @param  string $password  The password to check 
    …… 
    171171     
    172172    /** 
    173      * Decrypts ciphertext encrypted using public-key encryption via {@link publicKeyEncrypt()} 
     173     * Decrypts ciphertext encrypted using public-key encryption via ::publicKeyEncrypt() 
    174174     *  
    175175     * A public key (X.509 certificate) is required for encryption and a 
    …… 
    243243     * @param  string $plaintext        The content to be encrypted 
    244244     * @param  string $public_key_file  The path to an X.509 public key certificate 
    245      * @return string  A base-64 encoded result containing a Flourish fingerprint and suitable for decryption using {@link publicKeyDecrypt()} 
     245     * @return string  A base-64 encoded result containing a Flourish fingerprint and suitable for decryption using ::publicKeyDecrypt() 
    246246     */ 
    247247    static public function publicKeyEncrypt($plaintext, $public_key_file) 
    …… 
    282282     * @param  string $private_key_file  The path to a PEM-encoded private key 
    283283     * @param  string $password          The password for the private key 
    284      * @return string  The base64-encoded signature 
     284     * @return string  The base64-encoded signature suitable for verification using ::publicKeyVerify() 
    285285     */ 
    286286    static public function publicKeySign($plaintext, $private_key_file, $password) 
    …… 
    307307     
    308308    /** 
    309      * Checks a signature for plaintext to verify the creator 
     309     * Checks a signature for plaintext to verify the creator - works with ::publicKeySign() 
    310310     *  
    311311     * A private key (PEM) is required for signing and a public key 
    …… 
    340340     
    341341    /** 
    342      * Generates a random number using mt_rand() - make sure {@link seedRandom()} has been called 
     342     * Generates a random number using [http://php.net/mt_rand mt_rand()] after ensuring a good PRNG seed 
    343343     *  
    344344     * @param  integer $min  The minimum number to return 
    …… 
    360360     *  
    361361     * @param  integer $length  The length of string to return 
    362      * @param  string  $type    The type of string to return, can be 'alphanumeric', 'alpha', 'numeric', or 'hexadecimal' 
     362     * @param  string  $type    The type of string to return: `'alphanumeric'`, `'alpha'`, `'numeric'`, or `'hexadecimal'` 
    363363     * @return string  A random string of the type and length specified 
    364364     */ 
    …… 
    454454     
    455455    /** 
    456      * Decrypts ciphertext encrypted using symmetric-key encryption via {@link symmetricKeyEncrypt()} 
     456     * Decrypts ciphertext encrypted using symmetric-key encryption via ::symmetricKeyEncrypt() 
    457457     *  
    458458     * Since this is symmetric-key cryptography, the same key is used for 
    …… 
    526526     * @param  string $plaintext   The content to be encrypted 
    527527     * @param  string $secret_key  The secret key to use for encryption 
    528      * @return string  An encrypted and base-64 encoded result containing a Flourish fingerprint and suitable for decryption using {@link symmetricKeyDecrypt()} 
     528     * @return string  An encrypted and base-64 encoded result containing a Flourish fingerprint and suitable for decryption using ::symmetricKeyDecrypt() 
    529529     */ 
    530530    static public function symmetricKeyEncrypt($plaintext, $secret_key) 

  • fDatabase.php

    r311 r315 Hide Line Numbers
    44 *  
    55 * This class is implemented to use the UTF-8 character encoding. Please see 
    6  * {@link http://flourishlib.com/docs/UTF-8} for more information. 
     6 * http://flourishlib.com/docs/UTF-8 for more information. 
    77 *  
    88 * The following databases are supported: 
    9  *   - {@link http://microsoft.com/sql/ MSSQL} 
    10  *   - {@link http://mysql.com MySQL} 
    11  *   - {@link http://postgresql.org PostgreSQL} 
    12  *   - {@link http://sqlite.org SQLite} 
     9 *  
     10 *  - [http://microsoft.com/sql/ MSSQL] 
     11 *  - [http://mysql.com MySQL] 
     12 *  - [http://postgresql.org PostgreSQL] 
     13 *  - [http://sqlite.org SQLite] 
    1314 *  
    1415 * The class will automatically use the first of the following extensions it finds: 
    15  *   - MSSQL (via ODBC) 
    16  *     - {@link http://php.net/pdo_odbc pdo_odbc} 
    17  *     - {@link http://php.net/odbc odbc} 
    18  *   - MSSQL 
    19  *     - {@link http://msdn.microsoft.com/en-us/library/cc296221.aspx sqlsrv} 
    20  *     - {@link http://php.net/pdo_dblib pdo_dblib} 
    21  *     - {@link http://php.net/mssql mssql} (or {@link http://php.net/sybase sybase}) 
    22  *   - MySQL 
    23  *     - {@link http://php.net/mysql mysql} 
    24  *     - {@link http://php.net/mysqli mysqli} 
    25  *     - {@link http://php.net/pdo_mysql pdo_mysql} 
    26  *   - PostgreSQL 
    27  *     - {@link http://php.net/pgsql pgsql} 
    28  *     - {@link http://php.net/pdo_pgsql pdo_pgsql} 
    29  *   - SQLite 
    30  *     - {@link http://php.net/pdo_sqlite pdo_sqlite} (for v3.x) 
    31  *     - {@link http://php.net/sqlite sqlite} (for v2.x) 
     16 *  
     17 *  - MSSQL (via ODBC) 
     18 *   - [http://php.net/pdo_odbc pdo_odbc] 
     19 *   - [http://php.net/odbc odbc] 
     20 *  - MSSQL 
     21 *   - [http://msdn.microsoft.com/en-us/library/cc296221.aspx sqlsrv] 
     22 *   - [http://php.net/pdo_dblib pdo_dblib] 
     23 *   - [http://php.net/mssql mssql] (or [http://php.net/sybase sybase]) 
     24 *  - MySQL 
     25 *   - [http://php.net/mysql mysql] 
     26 *   - [http://php.net/mysqli mysqli] 
     27 *   - [http://php.net/pdo_mysql pdo_mysql] 
     28 *  - PostgreSQL 
     29 *   - [http://php.net/pgsql pgsql] 
     30 *   - [http://php.net/pdo_pgsql pdo_pgsql] 
     31 *  - SQLite 
     32 *   - [http://php.net/pdo_sqlite pdo_sqlite] (for v3.x) 
     33 *   - [http://php.net/sqlite sqlite] (for v2.x) 
    3234 *  
    3335 * @copyright  Copyright (c) 2007-2008 William Bond 
    …… 
    7577     *  
    7678     * Options include: 
    77      *   - mssql, mysql, mysqli, odbc, pgsql, sqlite, sqlsrv, pdo 
     79     *  
     80     *  - `'mssql'` 
     81     *  - `'mysql'` 
     82     *  - `'mysqli'` 
     83     *  - `'odbc'` 
     84     *  - `'pgsql'` 
     85     *  - `'sqlite'` 
     86     *  - `'sqlsrv'` 
     87     *  - `'pdo'` 
    7888     *  
    7989     * @var string 
    …… 
    131141     
    132142    /** 
    133      * The database type (postgresql, mysql, sqlite) 
     143     * The database type: `'mssql'`, `'mysql'`, `'postgresql'`, or `'sqlite'` 
    134144     *  
    135145     * @var string 
    …… 
    153163     
    154164    /** 
    155      * Establishes a connection to the database. 
    156      *  
    157      * @param  string  $type      The type of the database: 'mssql', 'mysql', 'postgresql', 'sqlite' 
    158      * @param  string  $database  Name of the database. If an ODBC connection 'dsn:' concatenated with the DSN, if SQLite the path to the database file. 
     165     * Configures the connection to a database - connection is not made until the first query is executed 
     166     *  
     167     * @param  string  $type      The type of the database: `'mssql'`, `'mysql'`, `'postgresql'`, `'sqlite'` 
     168     * @param  string  $database  Name of the database. If an ODBC connection `'dsn:'` concatenated with the DSN, if SQLite the path to the database file. 
    159169     * @param  string  $username  Database username, required for all databases except SQLite 
    160170     * @param  string  $password  The password for the username specified 
    …… 
    607617     *  
    608618     * It is recommended to use the error handling features of 
    609      * {@link fCore::enableErrorHandling()} to log or email these warnings. 
    610      *  
    611      * @param  integer $threshold  The limit of how long an SQL query can take before a warning is triggered 
     619     * fCore::enableErrorHandling() to log or email these warnings. 
     620     *  
     621     * @param  integer $threshold  The limit (in milliseconds) of how long an SQL query can take before a warning is triggered 
    612622     * @return void 
    613623     */ 
    …… 
    622632     *  
    623633     * The valid data types are: 
    624      *   - blob 
    625      *   - boolean 
    626      *   - date 
    627      *   - float 
    628      *   - integer 
    629      *   - string (also varchar, char or text) 
    630      *   - time 
    631      *   - timestamp 
     634     *  
     635     *  - `'blob'` 
     636     *  - `'boolean'` 
     637     *  - `'date'` 
     638     *  - `'float'` 
     639     *  - `'integer'` 
     640     *  - `'string'` (also varchar, char or text) 
     641     *  - `'varchar'` 
     642     *  - `'char'` 
     643     *  - `'text'` 
     644     *  - `'time'` 
     645     *  - `'timestamp'` 
    632646     *  
    633647     * In addition to being able to specify the data type, you can also pass 
    634648     * in an SQL statement with data type placeholders in the following form: 
    635      *   - %l for a blob 
    636      *   - %b for a boolean 
    637      *   - %d for a date 
    638      *   - %f for a float 
    639      *   - %i for an integer 
    640      *   - %s for a string 
    641      *   - %t for a time 
    642      *   - %p for a timestamp 
     649     *    
     650     *  - `%l` for a blob 
     651     *  - `%b` for a boolean 
     652     *  - `%d` for a date 
     653     *  - `%f` for a float 
     654     *  - `%i` for an integer 
     655     *  - `%s` for a string 
     656     *  - `%t` for a time 
     657     *  - `%p` for a timestamp 
    643658     *  
    644659     * @param  string $sql_or_type  This can either be the data type to escape or an SQL string with a data type placeholder - see method description 
    645      * @param  mixed  $value,...    The value to escape - you should pass a single value if a data type is specified or a value for each placeholder 
     660     * @param  mixed  $value        The value to escape - you should pass a single value if a data type is specified or a value for each placeholder 
     661     * @param  mixed  ... 
    646662     * @return string  The escaped value/SQL 
    647663     */ 
    …… 
    798814     * Escapes a blob for use in SQL, includes surround quotes when appropriate 
    799815     *  
    800      * A NULL value will be returned as 'NULL' 
     816     * A `NULL` value will be returned as `'NULL'` 
    801817     *  
    802818     * @param  string $value  The blob to escape 
    …… 
    830846     * Escapes a boolean for use in SQL, includes surround quotes when appropriate 
    831847     *  
    832      * A NULL value will be returned as 'NULL' 
     848     * A `NULL` value will be returned as `'NULL'` 
    833849     *  
    834850     * @param  boolean $value  The boolean to escape 
    …… 
    852868     * Escapes a date for use in SQL, includes surrounding quotes 
    853869     *  
    854      * A NULL or invalid value will be returned as 'NULL' 
     870     * A `NULL` or invalid value will be returned as `'NULL'` 
    855871     *  
    856872     * @param  string $value  The date to escape 
    …… 
    872888     * Escapes a float for use in SQL 
    873889     *  
    874      * A NULL value will be returned as 'NULL' 
     890     * A `NULL` value will be returned as `'NULL'` 
    875891     *  
    876892     * @param  float $value  The float to escape 
    …… 
    895911     * Escapes an integer for use in SQL 
    896912     *  
    897      * A NULL or invalid value will be returned as 'NULL' 
     913     * A `NULL` or invalid value will be returned as `'NULL'` 
    898914     *  
    899915     * @param  integer $value  The integer to escape 
    …… 
    918934     * Escapes a string for use in SQL, includes surrounding quotes 
    919935     *  
    920      * A NULL value will be returned as 'NULL' 
     936     * A `NULL` value will be returned as `'NULL'` 
    921937     *  
    922938     * @param  string $value  The string to escape 
    …… 
    9951011     * Escapes a time for use in SQL, includes surrounding quotes 
    9961012     *  
    997      * A NULL or invalid value will be returned as 'NULL' 
     1013     * A `NULL` or invalid value will be returned as `'NULL'` 
    9981014     *  
    9991015     * @param  string $value  The time to escape 
    …… 
    10151031     * Escapes a timestamp for use in SQL, includes surrounding quotes 
    10161032     *  
    1017      * A NULL or invalid value will be returned as 'NULL' 
     1033     * A `NULL` or invalid value will be returned as `'NULL'` 
    10181034     *  
    10191035     * @param  string $value  The timestamp to escape 
    …… 
    12011217     
    12021218    /** 
    1203      * Gets the php extension being used (mssql, mysql, mysqli, pgsql, sqlite, or pdo) 
     1219     * Gets the php extension being used 
    12041220     *  
    12051221     * @internal 
    …… 
    12161232     * Gets the database type 
    12171233     *  
    1218      * @return string  The database type (mssql, mysql, pgsql or sqlite) 
     1234     * @return string  The database type: `'mssql'`, `'mysql'`, `'postgresql'` or `'sqlite'` 
    12191235     */ 
    12201236    public function getType() 
    …… 
    13591375     * @param  string $sql           The SQL to check for a transaction query 
    13601376     * @param  string $result_class  The type of result object to create 
    1361      * @return mixed  If the connection is not via PDO will return FALSE, otherwise an object of the type $result_class 
     1377     * @return mixed  If the connection is not via PDO will return `FALSE`, otherwise an object of the type $result_class 
    13621378     */ 
    13631379    private function handleTransactionQueries($sql, $result_class) 
    …… 
    14241440     
    14251441    /** 
    1426      * Executes one or more sql queries 
    1427      *  
    1428      * @param  string $sql        One or more SQL statements 
    1429      * @param  mixed  $value,...  The optional value(s) to place into any placeholders in the SQL - see {@link escape()} for details 
     1442     * Executes one or more SQL queries 
     1443     *  
     1444     * @param  string $sql    One or more SQL statements 
     1445     * @param  mixed  $value  The optional value(s) to place into any placeholders in the SQL - see ::escape() for details 
     1446     * @param  mixed  ... 
    14301447     * @return fResult|array  The fResult object(s) for the query 
    14311448     */ 
    …… 
    15031520     *  
    15041521     * @param  fResult $result    The result object for the query 
    1505      * @param  mixed   $resource  Only applicable for pdo, odbc and sqlsrv extentions, this is either the PDOStatement object or odbc or sqlsrv resource 
     1522     * @param  mixed   $resource  Only applicable for `pdo`, `odbc` and `sqlsrv` extentions, this is either the `PDOStatement` object or `odbc` or `sqlsrv` resource 
    15061523     * @return void 
    15071524     */ 
    …… 
    16041621     * Translates the SQL statement using fSQLTranslation and executes it 
    16051622     *  
    1606      * @param  string $sql        One or more SQL statements 
    1607      * @param  mixed  $value,...  The optional value(s) to place into any placeholders in the SQL - see {@link escape()} for details 
     1623     * @param  string $sql    One or more SQL statements 
     1624     * @param  mixed  $value  The optional value(s) to place into any placeholders in the SQL - see ::escape() for details 
     1625     * @param  mixed  ... 
    16081626     * @return fResult|array  The fResult object(s) for the query 
    16091627     */ 
    …… 
    16341652     * be deleted. 
    16351653     *  
    1636      * @param  string $sql        A single SQL statement 
    1637      * @param  mixed  $value,...  The optional value(s) to place into any placeholders in the SQL - see {@link escape()} for details 
     1654     * @param  string $sql    A single SQL statement 
     1655     * @param  mixed  $value  The optional value(s) to place into any placeholders in the SQL - see ::escape() for details 
     1656     * @param  mixed  ... 
    16381657     * @return fUnbufferedResult  The result object for the unbuffered query 
    16391658     */ 
    …… 
    17061725     * is executed, the old result will be deleted. 
    17071726     *  
    1708      * @param  string $sql        A single SQL statement 
    1709      * @param  mixed  $value,...  The optional value(s) to place into any placeholders in the SQL - see {@link escape()} for details 
     1727     * @param  string $sql    A single SQL statement 
     1728     * @param  mixed  $value  The optional value(s) to place into any placeholders in the SQL - see ::escape() for details 
     1729     * @param  mixed  ... 
    17101730     * @return fUnbufferedResult  The result object for the unbuffered query 
    17111731     */ 
    …… 
    17321752     *  
    17331753     * The valid data types are: 
    1734      *   - blob (or %l) 
    1735      *   - boolean (or %b) 
    1736      *   - date (or %d) 
    1737      *   - float (or %f) 
    1738      *   - integer (or %i) 
    1739      *   - string (also %s, varchar, char or text) 
    1740      *   - time (or %t) 
    1741      *   - timestamp (or %p) 
     1754     *  
     1755     *  - `'blob'` (or `'%l'`) 
     1756     *  - `'boolean'` (or `'%b'`) 
     1757     *  - `'date'` (or `'%d'`) 
     1758     *  - `'float'` (or `'%f'`) 
     1759     *  - `'integer'` (or `'%i'`) 
     1760     *  - `'string'` (also `'%s, `'varchar'`, `'char'` or `'text'`) 
     1761     *  - `'time'` (or `'%t'`) 
     1762     *  - `'timestamp'` (or `'%p'`) 
    17421763     *  
    17431764     * @param  string $data_type  The data type being unescaped - see method description for valid values 
    …… 
    18721893     *  
    18731894     * @param  string $value  The value to unescape 
    1874      * @return string  The time in HH:MM:SS format 
     1895     * @return string  The time in `HH:MM:SS` format 
    18751896     */ 
    18761897    private function unescapeTime($value) 
    …… 
    18841905     *  
    18851906     * @param  string $value  The value to unescape 
    1886      * @return string  The timestamp in YYYY-MM-DD HH:MM:SS format 
     1907     * @return string  The timestamp in `YYYY-MM-DD HH:MM:SS` format 
    18871908     */ 
    18881909    private function unescapeTimestamp($value) 

  • fDate.php

    r267 r315 Hide Line Numbers
    11<?php 
    22/** 
    3  * Represents a date 
     3 * Represents a date as a value object 
    44 *  
    55 * @copyright  Copyright (c) 2007-2008 William Bond 
    …… 
    2828     * @throws fValidationException 
    2929     *  
    30      * @param  fDate|object|string|integer $date  The date to represent, NULL is interpreted as today 
     30     * @param  fDate|object|string|integer $date  The date to represent, `NULL` is interpreted as today 
    3131     * @return fDate 
    3232     */ 
    …… 
    7373     
    7474    /** 
    75      * Returns this date in 'Y-m-d' format 
    76      *  
    77      * @return string  The 'Y-m-d' format of this date 
     75     * Returns this date in `Y-m-d` format 
     76     *  
     77     * @return string  The `Y-m-d` format of this date 
    7878     */ 
    7979    public function __toString() 
    …… 
    8484     
    8585    /** 
    86      * Changes the date by the adjustment specified, only asjustments of a day or more will be made 
     86     * Changes the date by the adjustment specified, only adjustments of a day or more will be made 
    8787     *  
    8888     * @throws fValidationException 
    …… 
    124124     * @throws fValidationException 
    125125     *  
    126      * @param  string $format  The {@link http://php.net/date date()} function compatible formatting string, or a format name from {@link fTimestamp::defineFormat()} 
     126     * @param  string $format  The [http://php.net/date date()] function compatible formatting string, or a format name from fTimestamp::defineFormat() 
    127127     * @return string  The formatted date 
    128128     */ 
    …… 
    151151     *  
    152152     * The output will read like: 
    153      *  - "This date is {return value} the provided one" when a date it passed 
    154      *  - "This date is {return value}" when no date is passed and comparing with today 
     153     *  
     154     *  - "This date is `{return value}` the provided one" when a date it passed 
     155     *  - "This date is `{return value}`" when no date is passed and comparing with today 
    155156     *  
    156157     * Examples of output for a date passed might be: 
    157      *  - 2 days after 
    158      *  - 1 year before 
    159      *  - same day 
     158     *  
     159     *  - `'2 days after'` 
     160     *  - `'1 year before'` 
     161     *  - `'same day'` 
    160162     *  
    161163     * Examples of output for no date passed might be: 
    162      *  - 2 days from now 
    163      *  - 1 year ago 
    164      *  - today 
     164     *  
     165     *  - `'2 days from now'` 
     166     *  - `'1 year ago'` 
     167     *  - `'today'` 
    165168     *  
    166169     * You would never get the following output since it includes more than one unit of time measurement: 
    167      *  - 3 weeks and 1 day 
    168      *  - 1 year and 2 months 
     170     *  
     171     *  - `'3 weeks and 1 day'` 
     172     *  - `'1 year and 2 months'` 
    169173     *  
    170174     * Values that are close to the next largest unit of measure will be rounded up: 
    171      *  - 6 days would be represented as 1 week, however 5 days would not 
    172      *  - 29 days would be represented as 1 month, but 21 days would be shown as 3 weeks 
    173      *  
    174      * @param  fDate|object|string|integer $other_date  The date to create the difference with, NULL is interpreted as today 
     175     *  
     176     *  - `6 days` would be represented as `1 week`, however `5 days` would not 
     177     *  - `29 days` would be represented as `1 month`, but `21 days` would be shown as `3 weeks` 
     178     *  
     179     * @param  fDate|object|string|integer $other_date  The date to create the difference with, `NULL` is interpreted as today 
    175180     * @return string  The fuzzy difference in time between the this date and the one provided 
    176181     */ 
    …… 
    241246     * Returns the difference between the two dates in seconds 
    242247     *  
    243      * @param  fDate|object|string|integer $other_date  The date to calculate the difference with, NULL is interpreted as today 
    244      * @return integer  The difference between the two dates in seconds, positive if $other_date is before this date or negative if after 
     248     * @param  fDate|object|string|integer $other_date  The date to calculate the difference with, `NULL` is interpreted as today 
     249     * @return integer  The difference between the two dates in seconds, positive if `$other_date` is before this date or negative if after 
    245250     */ 
    246251    public function getSecondsDifference($other_date=NULL) 
    …… 
    258263     * modify the current date: 
    259264     *  
    260      * To change the date to the first of the month: 
    261      *  
    262      * <pre> 
    263      * Y-m-01 
    264      * </pre> 
    265      *  
    266      * To change the date to the last of the month: 
    267      *  
    268      * <pre> 
    269      * Y-m-t 
    270      * </pre> 
    271      *  
    272      * To change the date to the 5th week of the year: 
    273      *  
    274      * <pre> 
    275      * Y-\W5-N 
    276      * </pre> 
     265     *  - `'Y-m-01'` to change the date to the first of the month 
     266     *  - `'Y-m-t'` to change the date to the last of the month 
     267     *  - `'Y-\W5-N'` to change the date to the 5th week of the year 
    277268     *  
    278269     * @param  string $format  The current date will be formatted with this string, and the output used to create a new object 

  • fDirectory.php

    r274 r315 Hide Line Numbers
    7979     
    8080    /** 
    81      * Makes sure a directory has a / or \ at the end 
     81     * Makes sure a directory has a `/` or `\` at the end 
    8282     *  
    8383     * @param  string $directory  The directory to check 
    …… 
    111111     * Creates an object to represent a directory on the filesystem 
    112112     *  
     113     * If multiple fDirectory objects are created for a single directory, 
     114     * they will reflect changes in each other including rename and delete 
     115     * actions. 
     116     *  
    113117     * @throws fValidationException 
    114118     *  
    …… 
    173177     
    174178    /** 
    175      * When used in a string context, represents the file as the filename 
    176      *  
    177      * @return string  The filename of the file 
     179     * Returns the full filesystem path for the directory 
     180     *  
     181     * @return string  The full filesystem path 
    178182     */ 
    179183    public function __toString() 
    …… 
    184188     
    185189    /** 
    186      * Will delete a directory and all files and folders inside of it 
     190     * Will delete a directory and all files and directories inside of it 
    187191     *  
    188192     * This operation will not be performed until the filesystem transaction 
    …… 
    222226     * Gets the disk usage of the directory and all files and folders contained within 
    223227     *  
    224      * May be incorrect if files over 2GB exist. 
     228     * This method may return incorrect results if files over 2GB exist and the 
     229     * server uses a 32 bit operating system 
    225230     *  
    226231     * @param  boolean $format          If the filesize should be formatted for human readability 
    227232     * @param  integer $decimal_places  The number of decimal places to format to (if enabled) 
    228      * @return integer|string  If formatted a string with filesize in b/kb/mb/gb/tb, otherwise an integer 
     233     * @return integer|string  If formatted, a string with filesize in b/kb/mb/gb/tb, otherwise an integer 
    229234     */ 
    230235    public function getFilesize($format=FALSE, $decimal_places=1) 
    …… 
    250255     * Gets the parent directory 
    251256     *  
    252      * @return fDirectory  The object representing the parent dir 
     257     * @return fDirectory  The object representing the parent directory 
    253258     */ 
    254259    public function getParent() 
    …… 
    275280     *  
    276281     * If the web path is requested, uses translations set with 
    277      * {@link fFilesystem::addWebPathTranslation()} 
     282     * fFilesystem::addWebPathTranslation() 
    278283     *  
    279284     * @param  boolean $translate_to_web_path  If the path should be the web path 
    …… 
    384389     
    385390    /** 
    386      * Performs a scandir on a directory, removing the . and .. folder references 
    387      *  
    388      * @return array  The fFile and fDirectory objects for the files/folders in this directory 
     391     * Performs a [http://php.net/scandir scandir()] on a directory, removing the `.` and `..` entries 
     392     *  
     393     * @return array  The fFile (or fImage) and fDirectory objects for the files/directories in this directory 
    389394     */ 
    390395    public function scan() 
    …… 
    411416     
    412417    /** 
    413      * Performs a recursive scandir on a directory, removing the . and .. folder references 
    414      *  
    415      * @return array  The fFile and fDirectory objects for the files/folders (listed recursively) in this directory 
     418     * Performs a **recursive** [http://php.net/scandir scandir()] on a directory, removing the `.` and `..` entries 
     419     *  
     420     * @return array  The fFile and fDirectory objects for the files/directory (listed recursively) in this directory 
    416421     */ 
    417422    public function scanRecursive() 

  • fEmail.php

    r309 r315 Hide Line Numbers
    33 * Allows creating and sending a single email containing plaintext, HTML, attachments and S/MIME encryption 
    44 *  
    5  * Please note that this class uses the {@link http://php.net/function.mail mail()} 
     5 * Please note that this class uses the [http://php.net/function.mail mail()] 
    66 * function, and thus would have poor performance if used for mass mailing. 
    77 *  
    88 * This class is implemented to use the UTF-8 character encoding. Please see 
    9  * {@link http://flourishlib.com/docs/UTF-8} for more information. 
     9 * http://flourishlib.com/docs/UTF-8 for more information. 
    1010 *  
    1111 * @copyright  Copyright (c) 2008 William Bond 
    …… 
    2929     *  
    3030     * The matches will be: 
    31      *   - [0]: The whole email address 
    32      *   - [1]: The name before the @ 
    33      *   - [2]: The domain/ip after the @ 
     31     *   
     32     *  - `[0]`: The whole email address 
     33     *  - `[1]`: The name before the `@` 
     34     *  - `[2]`: The domain/ip after the `@` 
    3435     *  
    3536     * @var string 
    …… 
    4445     
    4546    /** 
    46      * A regular expression to match a 'name <email>' string, exluding those with comments and folding whitespace 
     47     * A regular expression to match a `name <email>` string, exluding those with comments and folding whitespace 
    4748     *  
    4849     * The matches will be: 
    49      *   - [0]: The whole name and email address 
    50      *   - [1]: The name 
    51      *   - [2]: The whole email address 
    52      *   - [3]: The email username before the @ 
    53      *   - [4]: The email domain/ip after the @ 
     50     *  
     51     *  - `[0]`: The whole name and email address 
     52     *  - `[1]`: The name 
     53     *  - `[2]`: The whole email address 
     54     *  - `[3]`: The email username before the `@` 
     55     *  - `[4]`: The email domain/ip after the `@` 
    5456     *  
    5557     * @var string 
    …… 
    6870     
    6971    /** 
    70      * Flags if the class should use popen to send mail via sendmail 
     72     * Flags if the class should use [http://php.net/popen popen()] to send mail via sendmail 
    7173     *  
    7274     * @var boolean 
    …… 
    7577     
    7678    /** 
    77      * Flags if the class should convert \r\n to \n for qmail. This makes invalid email headers that may work. 
     79     * Flags if the class should convert `\r\n` to `\n` for qmail. This makes invalid email headers that may work. 
    7880     *  
    7981     * @var boolean 
    …… 
    8385     
    8486    /** 
    85      * Sets the class to try and fix broken qmail implementations that add \r to \r\n 
     87     * Sets the class to try and fix broken qmail implementations that add `\r` to `\r\n` 
    8688     *  
    8789     * @return void 
    …… 
    293295     * Adds an attachment to the email 
    294296     *  
    295      * Duplicate filenames will be changed to be unique. 
     297     * If a duplicate filename is detected, it will be changed to be unique. 
    296298     *  
    297299     * @param  string $filename   The name of the file to attach 
    …… 
    383385     * Takes a multi-address email header and builds it out using an array of emails 
    384386     *  
    385      * @param  string $header  The header name without ': ', the header is non-blank, ': ' will be added 
     387     * @param  string $header  The header name without `': '`, the header is non-blank, `': '` will be added 
    386388     * @param  array  $emails  The email addresses for the header 
    387      * @return string  The email header with a trailing "\r\n" 
     389     * @return string  The email header with a trailing `\r\n` 
    388390     */ 
    389391    private function buildMultiAddressHeader($header, $emails) 
    …… 
    430432     
    431433    /** 
    432      * Turns a name and email into a '"name" <email>' string, or just 'email' if no name is provided 
     434     * Turns a name and email into a `"name" <email>` string, or just `email` if no name is provided 
    433435     *  
    434436     * This method will remove newline characters from the name and email, and 
    435      * will remove any backslash (\) and double quote (") characters from 
     437     * will remove any backslash (`\`) and double quote (`"`) characters from 
    436438     * the name. 
    437439     *  
    …… 
    526528     *  
    527529     * @param  string $boundary  The boundary to use for the top level mime block 
    528      * @return string  The headers to be sent to the mail() function 
     530     * @return string  The headers to be sent to the [http://php.net/function.mail mail()] function 
    529531     */ 
    530532    private function createHeaders($boundary) 
    …… 
    578580     * @param  string $headers  The headers for the message 
    579581     * @param  string $body     The message body 
    580      * @return array  0 => The message headers, 1 => The message body 
     582     * @return array  `0` => The message headers, `1` => The message body 
    581583     */ 
    582584    private function createSMIMEBody($to, $subject, $headers, $body) 
    …… 
    964966     * Adds the email address the email will be bounced to 
    965967     *  
    966      * This email address will be set to the Return-Path and Errors-To headers. 
     968     * This email address will be set to the `Return-Path` header. 
    967969     *  
    968970     * @param  string $email  The email address to bounce to 
    …… 
    980982     
    981983    /** 
    982      * Adds the From: email address to the email 
     984     * Adds the `From:` email address to the email 
    983985     *  
    984986     * @param  string $email  The email address being sent from 
    …… 
    10001002     *  
    10011003     * This method accepts either ASCII or UTF-8 encoded text. Please see 
    1002      * {@link http://flourishlib.com/docs/UTF-8} for more information. 
     1004     * http://flourishlib.com/docs/UTF-8 for more information. 
    10031005     *  
    10041006     * @param  string $html  The HTML version of the email body 
    …… 
    10151017     *  
    10161018     * This method accepts either ASCII or UTF-8 encoded text. Please see 
    1017      * {@link http://flourishlib.com/docs/UTF-8} for more information. 
     1019     * http://flourishlib.com/docs/UTF-8 for more information. 
    10181020     *  
    10191021     * @param  string $plaintext  The plaintext version of the email body 
    …… 
    10271029     
    10281030    /** 
    1029      * Adds the Reply-To: email address to the email 
     1031     * Adds the `Reply-To:` email address to the email 
    10301032     *  
    10311033     * @param  string $email  The email address to reply to 
    …… 
    10441046     
    10451047    /** 
    1046      * Adds the Sender: email address to the email 
    1047      *  
    1048      * The Sender: header is used to indicate someone other than the From: 
     1048     * Adds the `Sender:` email address to the email 
     1049     *  
     1050     * The `Sender:` header is used to indicate someone other than the `From:` 
    10491051     * address is actually submitting the message to the network. 
    10501052     *  
    …… 
    10671069     *  
    10681070     * This method accepts either ASCII or UTF-8 encoded text. Please see 
    1069      * {@link http://flourishlib.com/docs/UTF-8} for more information. 
     1071     * http://flourishlib.com/docs/UTF-8 for more information. 
    10701072     *  
    10711073     * @param  string $subject  The subject of the email 

  • fEmptySetException.php

    r214 r315 Hide Line Numbers
    11<?php 
    22/** 
    3  * An exception when an {@link fRecordSet} does not contain any elements 
     3 * An exception when an fRecordSet does not contain any elements 
    44 *  
    55 * @copyright  Copyright (c) 2007-2008 William Bond 

  • fEnvironmentException.php

    r214 r315 Hide Line Numbers
    11<?php 
    22/** 
    3  * An exception caused by an environment error 
     3 * An exception caused by an environment error such a file permissions 
    44 *  
    55 * @copyright  Copyright (c) 2007-2008 William Bond 

  • fFile.php

    r273 r315 Hide Line Numbers
    8888     * Creates an object to represent a file on the filesystem 
    8989     *  
     90     * If multiple fFile objects are created for a single file, they will 
     91     * reflect changes in each other including rename and delete actions. 
     92     *  
    9093     * @throws fValidationException 
    9194     *  
    …… 
    143146     
    144147    /** 
    145      * When used in a string context, represents the file as the filename 
    146      *  
    147      * @return string  The filename of the file 
     148     * Returns the filename of the file 
     149     *  
     150     * @return string  The filename 
    148151     */ 
    149152    public function __toString() 
    …… 
    312315     * Gets the size of the file 
    313316     *  
    314      * May be incorrect for files over 2GB on certain operating systems. 
     317     * The return value may be incorrect for files over 2GB on 32-bit OSes. 
    315318     *  
    316319     * @param  boolean $format          If the filesize should be formatted for human readability 
    …… 
    337340     *  
    338341     * If the web path is requested, uses translations set with 
    339      * {@link fFilesystem::addWebPathTranslation()} 
     342     * fFilesystem::addWebPathTranslation() 
    340343     *  
    341344     * @param  boolean $translate_to_web_path  If the path should be the web path 
    …… 
    395398     *  
    396399     * @param  string  $new_filename  The new full path to the file 
    397      * @param  boolean $overwrite     If the new filename already exists, TRUE will cause the file to be overwritten, FALSE will cause the new filename to change 
     400     * @param  boolean $overwrite     If the new filename already exists, `TRUE` will cause the file to be overwritten, `FALSE` will cause the new filename to change 
    398401     * @return void 
    399402     */ 

  • fFilesystem.php

    r286 r315 Hide Line Numbers
    11<?php 
    22/** 
    3  * Handles filesystem-level tasks 
     3 * Handles filesystem-level tasks including filesystem transactions and the reference map to keep all fFile and fDirectory objects in sync 
    44 *  
    55 * @copyright  Copyright (c) 2008 William Bond 
    …… 
    8282     * for output into HTML. 
    8383     *  
    84      * By default the DOCUMENT_ROOT will be converted to a blank string, in 
    85      * essence stripping it from filesystem paths. 
     84     * By default the `$_SERVER['DOCUMENT_ROOT']` will be converted to a blank 
     85     * string, in essence stripping it from filesystem paths. 
    8686     *  
    8787     * @param  string $search_path   The path to look for 
    …… 
    103103     * Flourish filesystem transactions are NOT full ACID-compliant 
    104104     * transactions, but rather more of an filesystem undo buffer which can 
    105      * return the filesystem to the state when begin() was called. If your PHP 
     105     * return the filesystem to the state when ::begin() was called. If your PHP 
    106106     * script dies in the middle of an operation this functionality will do 
    107107     * nothing for you and all operations will be retained, except for deletes 
    …… 
    160160     
    161161    /** 
    162      * Takes a file size and converts it to bytes 
     162     * Takes a file size including a unit of measure (i.e. kb, GB, M) and converts it to bytes 
    163163     *  
    164164     * @param  string $size  The size to convert to bytes 
    …… 
    213213     *  
    214214     * @param  string $file_path  The file to rename 
    215      * @param  string $element    The piece of information to return ('dirname', 'basename', 'extension', or 'filename') 
     215     * @param  string $element    The piece of information to return: `'dirname'`, `'basename'`, `'extension'`, or `'filename'` 
    216216     * @return array  The file's dirname, basename, extension and filename 
    217217     */ 
    …… 
    258258     *  
    259259     * @param  string $file  The name of the file or directory 
    260      * @return mixed  Will return NULL if no match, or the exception object if a match occurs 
     260     * @return mixed  Will return `NULL` if no match, or the exception object if a match occurs 
    261261     */ 
    262262    static public function &hookExceptionMap($file) 
    …… 
    278278     *  
    279279     * @param  string $file  The name of the file or directory 
    280      * @return mixed  Will return NULL if no match, or the exception object if a match occurs 
     280     * @return mixed  Will return `NULL` if no match, or the exception object if a match occurs 
    281281     */ 
    282282    static public function &hookFilenameMap($file) 
    …… 
    304304     *  
    305305     * @param  string $file           The filename to check 
    306      * @param  string $new_extension  The new extension for the filename, do not include . 
     306     * @param  string $new_extension  The new extension for the filename, should not include `.` 
    307307     * @return string  The unique file name 
    308308     */ 
    …… 
    343343     * @internal 
    344344     *  
    345      * @param  string    $file       A file or directory name, directories should end in / or \ 
     345     * @param  string    $file       A file or directory name, directories should end in `/` or `\` 
    346346     * @param  Exception $exception  The exception for this file/directory 
    347347     * @return void 
    …… 
    381381     * Updates the filename map recursively, causing all objects representing a directory to be updated 
    382382     *  
    383      * Also updated all files and directories in the specified directory to the new paths. 
     383     * Also updates all files and directories in the specified directory to the new paths. 
    384384     *  
    385385     * @internal 

  • fRecordSet.php

    r308 r315 Hide Line Numbers
    2424     
    2525    /** 
    26      * Callbacks registered for the __call() handler 
     26     * Callbacks registered for the ::__call() handler 
    2727     *  
    2828     * @var array 
    …… 
    3232     
    3333    /** 
    34      * Creates an {@link fRecordSet} by specifying the class to create plus the where conditions and order by rules 
     34     * Creates an fRecordSet by specifying the class to create plus the where conditions and order by rules 
    3535     *  
    3636     * The where conditions array can contain key => value entries in any of the following formats (where VALUE/VALUE2 can be of any data type): 
    37      * <pre> 
    38      *  - '%column%='                       => VALUE,                        // column = VALUE 
    39      *  - '%column%!'                       => VALUE,                        // column <> VALUE 
    40      *  - '%column%~'                       => VALUE,                        // column LIKE '%VALUE%' 
    41      *  - '%column%<'                       => VALUE,                        // column < VALUE 
    42      *  - '%column%<='                      => VALUE,                        // column <= VALUE 
    43      *  - '%column%>'                       => VALUE,                        // column > VALUE 
    44      *  - '%column%>='                      => VALUE,                        // column >= VALUE 
    45      *  - '%column%='                       => array(VALUE, VALUE2,...),     // column IN (VALUE, VALUE2, ...) 
    46      *  - '%column%!'                       => array(VALUE, VALUE2,...),     // column NOT IN (VALUE, VALUE2, ...) 
    47      *  - '%column%~'                       => array(VALUE, VALUE2,...),     // (column LIKE '%VALUE%' OR column LIKE '%VALUE2%' OR column ...) 
    48      *  - '%column%!|%column2%<|%column3%=' => array(VALUE, VALUE2, VALUE3), // (column <> '%VALUE%' OR column2 < '%VALUE2%' OR column3 = '%VALUE3%') 
    49      *  - '%column%|%column2%|%column3%~'   => VALUE,                        // (column LIKE '%VALUE%' OR column2 LIKE '%VALUE2%' OR column3 LIKE '%VALUE%') 
    50      *  - '%column%|%column2%|%column3%~'   => array(VALUE, VALUE2,...)      // ((column LIKE '%VALUE%' OR column2 LIKE '%VALUE%' OR column3 LIKE '%VALUE%') AND (column LIKE '%VALUE2%' OR column2 LIKE '%VALUE2%' OR column3 LIKE '%VALUE2%') AND ...) 
    51      * </pre> 
     37     *  
     38     * {{{ 
     39     * '%column%='                       => VALUE,                        // column = VALUE 
     40     * '%column%!'                       => VALUE,                        // column <> VALUE 
     41     * '%column%~'                       => VALUE,                        // column LIKE '%VALUE%' 
     42     * '%column%<'                       => VALUE,                        // column < VALUE 
     43     * '%column%<='                      => VALUE,                        // column <= VALUE 
     44     * '%column%>'                       => VALUE,                        // column > VALUE 
     45     * '%column%>='                      => VALUE,                        // column >= VALUE 
     46     * '%column%='                       => array(VALUE, VALUE2,...),     // column IN (VALUE, VALUE2, ...) 
     47     * '%column%!'                       => array(VALUE, VALUE2,...),     // column NOT IN (VALUE, VALUE2, ...) 
     48     * '%column%~'                       => array(VALUE, VALUE2,...),     // (column LIKE '%VALUE%' OR column LIKE '%VALUE2%' OR column ...) 
     49     * '%column%!|%column2%<|%column3%=' => array(VALUE, VALUE2, VALUE3), // (column <> '%VALUE%' OR column2 < '%VALUE2%' OR column3 = '%VALUE3%') 
     50     * '%column%|%column2%|%column3%~'   => VALUE,                        // (column LIKE '%VALUE%' OR column2 LIKE '%VALUE2%' OR column3 LIKE '%VALUE%') 
     51     * '%column%|%column2%|%column3%~'   => array(VALUE, VALUE2,...)      // ((column LIKE '%VALUE%' OR column2 LIKE '%VALUE%' OR column3 LIKE '%VALUE%') AND (column LIKE '%VALUE2%' OR column2 LIKE '%VALUE2%' OR column3 LIKE '%VALUE2%') AND ...) 
     52     * }}} 
    5253     *  
    5354     * The order bys array can contain key => value entries in any of the following formats: 
    54      * <pre> 
    55      *  - '%column%'     => 'asc'      // 'first_name' => 'asc' 
    56      *  - '%column%'     => 'desc'     // 'last_name'  => 'desc' 
    57      *  - '%expression%' => 'asc'      // "CASE first_name WHEN 'smith' THEN 1 ELSE 2 END" => 'asc' 
    58      *  - '%expression%' => 'desc'     // "CASE first_name WHEN 'smith' THEN 1 ELSE 2 END" => 'desc' 
    59      * </pre> 
     55     *  
     56     * {{{ 
     57     * '%column%'     => 'asc'      // 'first_name' => 'asc' 
     58     * '%column%'     => 'desc'     // 'last_name'  => 'desc' 
     59     * '%expression%' => 'asc'      // "CASE first_name WHEN 'smith' THEN 1 ELSE 2 END" => 'asc' 
     60     * '%expression%' => 'desc'     // "CASE first_name WHEN 'smith' THEN 1 ELSE 2 END" => 'desc' 
     61     * }}} 
    6062     *  
    6163     * The %column% in both the where conditions and order bys can be in any of the formats: 
    62      * <pre> 
    63      *  - '%column%'                                                                 // e.g. 'first_name' 
    64      *  - '%current_table%.%column%'                                                 // e.g. 'users.first_name' 
    65      *  - '%related_table%.%column%'                                                 // e.g. 'user_groups.name' 
    66      *  - '%related_table%{%route%}.%column%'                                        // e.g. 'user_groups{user_group_id}.name' 
    67      *  - '%related_table%=>%once_removed_related_table%.%column%'                   // e.g. 'user_groups=>permissions.level' 
    68      *  - '%related_table%{%route%}=>%once_removed_related_table%.%column%'          // e.g. 'user_groups{user_group_id}=>permissions.level' 
    69      *  - '%related_table%=>%once_removed_related_table%{%route%}.%column%'          // e.g. 'user_groups=>permissions{read}.level' 
    70      *  - '%related_table%{%route%}=>%once_removed_related_table%{%route%}.%column%' // e.g. 'user_groups{user_group_id}=>permissions{read}.level' 
    71      * </pre> 
    72      *  
    73      * @param  string  $class             The class to create the {@link fRecordSet} of 
     64     *  
     65     * {{{ 
     66     * '%column%'                                                                 // e.g. 'first_name' 
     67     * '%current_table%.%column%'                                                 // e.g. 'users.first_name' 
     68     * '%related_table%.%column%'                                                 // e.g. 'user_groups.name' 
     69     * '%related_table%{%route%}.%column%'                                        // e.g. 'user_groups{user_group_id}.name' 
     70     * '%related_table%=>%once_removed_related_table%.%column%'                   // e.g. 'user_groups=>permissions.level' 
     71     * '%related_table%{%route%}=>%once_removed_related_table%.%column%'          // e.g. 'user_groups{user_group_id}=>permissions.level' 
     72     * '%related_table%=>%once_removed_related_table%{%route%}.%column%'          // e.g. 'user_groups=>permissions{read}.level' 
     73     * '%related_table%{%route%}=>%once_removed_related_table%{%route%}.%column%' // e.g. 'user_groups{user_group_id}=>permissions{read}.level' 
     74     * }}} 
     75     *  
     76     * @param  string  $class             The class to create the fRecordSet of 
    7477     * @param  array   $where_conditions  The column => value comparisons for the where clause 
    7578     * @param  array   $order_bys         The column => direction values to use for sorting 
    7679     * @param  integer $limit             The number of records to fetch 
    7780     * @param  integer $page              The page offset to use when limiting records 
    78      * @return fRecordSet  A set of {@link fActiveRecord} objects 
     81     * @return fRecordSet  A set of fActiveRecord objects 
    7982     */ 
    8083    static public function build($class, $where_conditions=array(), $order_bys=array(), $limit=NULL, $page=NULL) 
    …… 
    142145     
    143146    /** 
    144      * Creates an {@link fRecordSet} from an array of records 
     147     * Creates an fRecordSet from an array of records 
    145148     *  
    146149     * @throws fValidationException 
    …… 
    160163     
    161164    /** 
    162      * Creates an {@link fRecordSet} from an SQL statement 
     165     * Creates an fRecordSet from an SQL statement 
    163166     *  
    164167     * @param  string $class                  The type of object to create 
    …… 
    178181     
    179182    /** 
    180      * Registers a callback to be called when a specific method is handled by __call() 
     183     * Registers a callback to be called when a specific method is handled by ::__call() 
    181184     *   
    182185     * The callback should accept the following parameters: 
    183      *   - $record_set:  The actual record set 
    184      *   - $class:       The class of each record 
    185      *   - &$records:    The ordered array of fActiveRecords 
    186      *   - &$pointer:    The current array pointer for the records array 
    187      *   - &$associate:  If the record should be associated with an fActiveRecord holding it 
     186     *  
     187     *  - **`$record_set`**:  The actual record set 
     188     *  - **`$class`**:       The class of each record 
     189     *  - **`&$records`**:    The ordered array of fActiveRecords 
     190     *  - **`&$pointer`**:    The current array pointer for the records array 
     191     *  - **`&$associate`**:  If the record should be associated with an fActiveRecord holding it 
    188192     *  
    189193     * @param  string   $method    The method to hook for 
    …… 
    211215     
    212216    /** 
    213      * A flag to indicate this should record set should be associated to the parent {@link fActiveRecord} object 
     217     * A flag to indicate this should record set should be associated to the parent fActiveRecord object 
    214218     *  
    215219     * @var boolean 
    …… 
    225229     
    226230    /** 
    227      * The number of rows that would have been returned if a LIMIT clause had not been used 
     231     * The number of rows that would have been returned if a `LIMIT` clause had not been used 
    228232     *  
    229233     * @var integer 
    …… 
    232236     
    233237    /** 
    234      * The SQL to get the total number of rows that would have been returned if a LIMIT clause had not been used 
     238     * The SQL to get the total number of rows that would have been returned if a `LIMIT` clause had not been used 
    235239     *  
    236240     * @var string 
    …… 
    254258     
    255259    /** 
    256      * Allows for preloading of related records by dynamically creating preload{related plural class}() methods 
     260     * Allows for preloading of related records for all records in record set 
     261     *  
     262     *  
    257263     *   
    258264     * @throws fValidationException 
    …… 
    301307     *  
    302308     * @param  string  $class                  The type of records to create 
    303      * @param  fResult $result_object          The {@link fResult} object of the records to create 
    304      * @param  string  $non_limited_count_sql  An SQL statement to get the total number of rows that would have been returned if a LIMIT clause had not been used. Should only be passed if a LIMIT clause is used. 
     309     * @param  fResult $result_object          The fResult object of the records to create 
     310     * @param  string  $non_limited_count_sql  An SQL statement to get the total number of rows that would have been returned if a `LIMIT` clause had not been used. Should only be passed if a `LIMIT` clause is used. 
    305311     * @return fRecordSet 
    306312     */ 
    …… 
    453459     * Returns the number of records in the set 
    454460     *  
    455      * @param  boolean $ignore_limit  If set to TRUE, this method will return the number of records that would be in the set if there was no LIMIT clause 
     461     * @param  boolean $ignore_limit  If set to `TRUE`, this method will return the number of records that would be in the set if there was no `LIMIT` clause 
    456462     * @return integer  The number of records in the set 
    457463     */ 
    …… 
    497503     * Filters the record set via a callback 
    498504     *  
    499      * @param  callback $callback  The callback can be either a callback that accepts a single parameter and returns a boolean, or a string like '{record}::methodName' to filter based on the output of $record->methodName() 
     505     * @param  callback $callback  The callback can be either a callback that accepts a single parameter and returns a boolean, or a string like `'{record}::methodName'` to filter based on the output of `$record->methodName()` 
    500506     * @return fRecordSet  A new fRecordSet with the filtered records 
    501507     */ 
    …… 
    529535     
    530536    /** 
    531      * Flags this record set for association with the {@link fActiveRecord} object that references it 
     537     * Flags this record set for association with the fActiveRecord object that references it 
    532538     *  
    533539     * @internal 
    …… 
    546552     * @throws fValidationException 
    547553     *  
    548      * @return object|false  The current record or FALSE if no remaining records 
     554     * @return object|false  The current record or `FALSE` if no remaining records 
    549555     */ 
    550556    public function fetchRecord() 
    …… 
    618624     
    619625    /** 
    620      * Returns if this record set is flagged for association with the {@link fActiveRecord} object that references it 
     626     * Returns if this record set is flagged for association with the fActiveRecord object that references it 
    621627     *  
    622628     * @internal 
    …… 
    647653     *  
    648654     * The record will be passed to the callback as the first parameter unless 
    649      * it's position is specified by the placeholder string '{record}'. More 
     655     * it's position is specified by the placeholder string `'{record}'`. More 
    650656     * details further down. 
    651657     *  
    652658     * Additional parameters can be passed to the callback in one of two 
    653659     * different ways: 
     660     *  
    654661     *  - Passing a non-array value will cause it to be passed to the callback 
    655662     *  - Passing an array value will cause the array values to be passed to the callback with their corresponding record 
    …… 
    660667     *  
    661668     * To allow passing the record as a specific parameter to the callback, a 
    662      * placeholder string '{record}' will be replaced with a the record. You 
    663      * can also specify '{record}::methodName' to cause the output of a method 
     669     * placeholder string `'{record}'` will be replaced with a the record. You 
     670     * can also specify `'{record}::methodName'` to cause the output of a method 
    664671     * from the record to be passed instead of the whole record. 
    665672     *  
    666      * @param  callback $callback       The callback to pass the values to 
    667      * @param  mixed    $parameter,...  The parameter to pass to the callback - see method description for details 
     673     * @param  callback $callback   The callback to pass the values to 
     674     * @param  mixed    $parameter  The parameter to pass to the callback - see method description for details 
     675     * @param  mixed    ... 
    668676     * @return array  An array of the results from the callback 
    669677     */ 
    670     public function map($callback) 
     678    public function map($callback, $parameter) 
    671679    { 
    672680        $parameters = array_slice(func_get_args(), 1); 
    …… 
    955963     *  
    956964     * The callback should take two parameters: 
    957      *  - The first two records on the first call if no $inital_value is specified 
    958      *  - The initial value and the first record for the first call if an $initial_value is specified 
     965     *  
     966     *  - The first two records on the first call if no `$inital_value` is specified 
     967     *  - The initial value and the first record for the first call if an `$initial_value` is specified 
    959968     *  - The result of the last call plus the next record for the second and subsequent calls 
    960969     *  
    …… 
    10011010     * Sorts the set by the return value of a method from the class created and rewind the interator 
    10021011     *  
    1003      * This methods uses {@link fUTF8::inatcmp()} to perform comparisons. 
     1012     * This methods uses fUTF8::inatcmp() to perform comparisons. 
    10041013     *  
    10051014     * @throws fValidationException 
    10061015     *  
    10071016     * @param  string $method     The method to call on each object to get the value to sort by 
    1008      * @param  string $direction  Either 'asc' or 'desc' 
     1017     * @param  string $direction  Either `'asc'` or `'desc'` 
    10091018     * @return void 
    10101019     */ 
    …… 
    10351044     
    10361045    /** 
    1037      * Sorts the set by passing the callback to {@link http://php.net/usort usort()} and rewinds the interator 
     1046     * Sorts the set by passing the callback to [http://php.net/usort `usort()`] and rewinds the interator 
    10381047     *  
    10391048     * @throws fValidationException 
    10401049     *  
    1041      * @param  mixed $callback  The function/method to pass to usort() 
     1050     * @param  mixed $callback  The function/method to pass to `usort()` 
    10421051     * @return void 
    10431052     */ 
    …… 
    10501059     
    10511060    /** 
    1052      * Throws a {@link fEmptySetException} if the {@link fRecordSet} is empty 
     1061     * Throws an fEmptySetException if the record set is empty 
    10531062     *  
    10541063     * @throws fEmptySetException