Source for file Load.class.php

Documentation is available at Load.class.php

  1. <?php
  2. /**
  3.  * Gumbo Library Framework
  4.  *
  5.  * LICENSE
  6.  * This library is being released under the terms of the New BSD License.  A
  7.  * copy of the license is packaged with the software (LICENSE.txt).  If no
  8.  * copy is found, a copy of the license template can be found at:
  9.  * http://www.opensource.org/licenses/bsd-license.php
  10.  * 
  11.  * @category Gumbo
  12.  * @package Load
  13.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  14.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  15.  * @author Michael Luster <mluster79@yahoo.com>
  16.  * @link http://sourceforge.net/projects/phpgumbo
  17.  * @version 0.0.1
  18.  */
  19.  
  20. /**
  21.  * Load Class
  22.  * 
  23.  * This is the foundation to all Gumbo Classes.  It is responsible for loading
  24.  * Library files into memory.  By default, any name supplied with "Gumbo_" prepended
  25.  * to it will be classified as a Gumbo Library Class file.  The class defines
  26.  * default rules for such cases.  The class is also responsible for loading other
  27.  * file types into memory.  This can be accomplished using a load method directly
  28.  * or by creating Load_Settings.  The latter is easier.
  29.  * 
  30.  * When the class is loaded, it will automatically define the Home directory.  This
  31.  * is the physical location of this class file on the hard drive.  The program
  32.  * should then define a Custom directory (if needed).  When loading a Gumbo Library
  33.  * Class file, the custom directory, if set, will be checked first.
  34.  * 
  35.  * The class implements the Singleton Interface, which means there is only one instance
  36.  * of this class.  It can be accessed directly through the Singleton method or by
  37.  * assigning a variable.
  38.  * <pre>
  39.  * Gumbo_Load::instance ()->method ();
  40.  * 
  41.  * // same as
  42.  * $load = Gumbo_Load::instance ();
  43.  * $load->method ();
  44.  * </pre>
  45.  * 
  46.  * There is an overload method defined that works specifically with Gumbo Library
  47.  * Classes.  These statements are placed above various class files to ensure that
  48.  * certain required Classes/Interfaces are loaded.
  49.  * <pre>
  50.  * $load->Gumbo_Valid_Address;
  51.  * </pre>
  52.  * 
  53.  * The class implements the Gumbo_Interface_Settings interface.  This allows it to
  54.  * save various settings.  The Gumbo_Load_Setting extends the generic Gumbo_Setting
  55.  * class.  The Gumbo_Load_Setting was specifically designed to be used by this
  56.  * class.  It is recommended to define certain settings for certain file types
  57.  * prior to the start of the application.  This will make loading specific file
  58.  * types easier by simply passing a key.
  59.  * <pre>
  60.  * // returns full path based on "templates" setting
  61.  * include ($load->load ("template_file", "templates", true));
  62.  * </pre>
  63.  *
  64.  * @category Gumbo
  65.  * @package Load
  66.  * @copyright Copyright (c) 2007, iBayou, Michael Luster
  67.  * @license http://www.opensource.org/licenses/bsd-license.php New BSD License
  68.  * @author Michael Luster <mluster79@yahoo.com>
  69.  * @link http://sourceforge.net/projects/phpgumbo
  70.  * @desc Load Class
  71.  * @version 0.0.1
  72.  */
  73.  
  74. gumbo_load ("Interface_Singleton");
  75. gumbo_load ("Interface_Load");
  76. gumbo_load ("Interface_Settings");
  77. gumbo_load ("Load_Setting");
  78.  
  79. class Gumbo_Load implements Gumbo_Interface_Load, Gumbo_Interface_Singleton, Gumbo_Interface_Settings {
  80.     
  81.     /** @var Gumbo_Interface_Load $_instance Singleton instance */
  82.     private static $_instance = null;
  83.     
  84.     /** @var string $_dir_home Gumbo directory location */
  85.     private $_dir_home;
  86.     /** @var string $_dir_customer Gumbo custom directory */
  87.     private $_dir_custom;
  88.     
  89.     /** @var Gumbo_Interface_Load_Setting[] $_settings Load settings */
  90.     private $_settings = array ();
  91.     
  92.     
  93.     
  94.     /**
  95.      * Constructor
  96.      * The Constructor will set the primary library home directory.  This is
  97.      * the current location of the Gumbo_Load file.
  98.      */
  99.     private function __construct () {
  100.         $this->_dir_home = str_replace ("\\", "/", dirname (__FILE__)) . "/";
  101.         if (defined ("GUMBO_CUSTOM")) {
  102.             $this->_dir_custom = GUMBO_CUSTOM;
  103.         }
  104.     }
  105.     
  106.     /**
  107.      * Singleton Method
  108.      * @return Gumbo_Interface_Load 
  109.      */
  110.     public static function instance () {
  111.         if (self::$_instance == null) {
  112.             self::$_instance = new Gumbo_load ();
  113.         }
  114.         return self::$_instance;
  115.     }
  116.     
  117.     
  118.     
  119.     /** ACTION METHODS **/
  120.     /**
  121.      * Quick load of a file using a setting key
  122.      * 
  123.      * The method will require the file name and a key reference.  The key
  124.      * will refer to a saved setting, which will be used to the load the
  125.      * file.  If no key is defined, or the key doesn't exist, the default
  126.      * settings will be used.  The method is a quick wrapper to the Load
  127.      * file method.
  128.      * 
  129.      * The return_path parameter, if set, will return the file name string.  This
  130.      * is useful for performing direct includes of templates inside a particular
  131.      * structure.
  132.      * 
  133.      * @param string $name file name
  134.      * @param string $key settings reference
  135.      * @param bool $return_path returns the formatted path string
  136.      * @return mix 
  137.      * @uses Gumbo_Load_Setting
  138.      * @throws Gumbo_Exception
  139.      */
  140.     public function load ($name, $key=null, $path_only=false) {
  141.         // verify precondition
  142.         try {
  143.             if (!is_null ($key) && !is_string ($key)) {
  144.                 throw new Gumbo_Exception ("Invalid Argument 'key:str|obj|null' => {$key}:" . gettype ($key));
  145.             }
  146.         } catch (Gumbo_Exception $e) {
  147.             $e->setFunction ($e);
  148.             gumbo_trigger ($e);
  149.             $key = null;
  150.         }
  151.         
  152.         try {
  153.             if (!is_bool ($path_only)) {
  154.                 throw new Gumbo_Exception ("Invalid Argument 'path_only:bool' => {$path_only}:" . gettype ($path_only));
  155.             }
  156.         } catch (Gumbo_Exception $e) {
  157.             $e->setFunction (__METHOD__);
  158.             gumbo_trigger ($e);
  159.             $path_only = false;
  160.         }
  161.         
  162.         // load the setting
  163.         $setting = $this->getSetting ($key);
  164.         
  165.         // return the path if no setting exists
  166.         if (!$setting) {
  167.             if ($path_only) {
  168.                 return $this->getFullPath ($name);
  169.             }
  170.             
  171.             if (strstr ($name, "Gumbo_")) {
  172.                 return $this->loadClass ($name);
  173.             }
  174.             return $this->loadFile ($name);
  175.         }
  176.         
  177.         // returns only the file name
  178.         if ($path_only) {
  179.             return $this->getFullPath ($name, $setting->getDirs (), $setting->getExtension (), $setting->getStretch (), $setting->getSeparator (), $setting->getPath (), $setting->getRemove ());
  180.         }
  181.         
  182.         // loads a class/file
  183.         if ($setting->getClass ()) {
  184.             return $this->loadClass ($name, $setting->getDirs (), $setting->getExtension (), $setting->getStretch (), $setting->getSeparator (), $setting->getPath (), $setting->getRemove ());
  185.         }
  186.         return $this->loadFile ($name, $setting->getDirs (), $setting->getExtension (), $setting->getOnce (), $setting->getInclude (), $setting->getStretch (), $setting->getSeparator (), $setting->getPath (), $setting->getRemove ());
  187.     }
  188.     
  189.     /**
  190.      * Loads a Class file into memory
  191.      * 
  192.      * The load class will load a class file into memory only once.  This
  193.      * is so the same class name isn't loaded twice.  The stretch setting
  194.      * will separate the class name into components.  Each component would
  195.      * represent a sub-directory of the primary path.  The separator
  196.      * indicates the character used to separate the directory class names.
  197.      * 
  198.      * For example:
  199.      * <code>
  200.      * $load->loadClass ("This_Class_Name", null, null, true, "_");
  201.      * </code>
  202.      * The search will look for the following file
  203.      * <path>/this/class/name.class.php where .class.php is the extension
  204.      * 
  205.      * Any class name prepended with Gumbo_* will automatically create the
  206.      * appropriate settings.  Simply load the class name.
  207.      * <code>
  208.      * $load->loadClass ("Gumbo_Class");
  209.      * </code>
  210.      * 
  211.      * @param string $name class name
  212.      * @param string|array$dirs starting locations
  213.      * @param string $ext class file extension (default: class.php)
  214.      * @param bool $stretch stretch the class name as directories (default: false)
  215.      * @param string $separator class name separator (default: "_")
  216.      * @param string $path which path to search through (default: "include")
  217.      * @param string $remove removes string pattern from the class name when performing a file search
  218.      * @return bool 
  219.      * @uses Gumbo_Load_Setting
  220.      * @throws Gumbo_Exception
  221.      */
  222.     public function loadClass ($name, $dirs=null, $ext=null, $stretch=false, $separator=null, $path="include", $remove=null) {
  223.         try {
  224.             if (!is_string ($name)) {
  225.                 throw new Gumbo_Exception ("Invalid Argument 'name:str' => {$name}:" . gettype ($name));
  226.             }
  227.             if (class_exists ($name, false) || interface_exists ($name, false)) {
  228.                 return true;
  229.             }
  230.             
  231.             // check for a Gumbo Class
  232.             if (substr ($name, 0, 6) == "Gumbo_") {
  233.                 return gumbo_load ($name);
  234.             } else {
  235.                 $setting = new Gumbo_Load_Setting ();
  236.                 $setting->setDirs ($dirs);
  237.                 $setting->setExtension ($ext);
  238.                 $setting->setStretch ($stretch);
  239.                 $setting->setSeparator ($separator);
  240.                 $setting->setPath ($path);
  241.                 $setting->setRemove ($remove);
  242.                 if (is_null ($ext)) { $setting->setExtension ("class.php"); }
  243.                 
  244.                 $this->loadFile ($name, $setting->getDirs (), $setting->getExtension (), true, false, $setting->getStretch (), $setting->getSeparator (), $setting->getPath (), $setting->getRemove ());
  245.             }
  246.             
  247.             if (!class_exists ($name, false) && !interface_exists ($name, false)) {
  248.                 throw new Gumbo_Exception ("Class|Interface Does Not Exist: {$name}");
  249.             }
  250.             return true;
  251.         } catch (Gumbo_Exception $e) {
  252.             $e->setFunction (__METHOD__);
  253.             gumbo_trigger ($e);
  254.         }
  255.         return false;
  256.     }
  257.     
  258.     /**
  259.      * Loads a given class file into memory
  260.      * @param string $name class name
  261.      * @param string|array$dirs locations to search through
  262.      * @param string $ext file extension (default: "php")
  263.      * @param bool $once loads the file only once (default: false)
  264.      * @param bool $use_include use include instead of require (default: false)
  265.      * @param bool $stretch stretches the directory path based on the file name (default: false)
  266.      * @param string $separator character separating the directory names inside the file name (default: "_")
  267.      * @param string $path start path to the file (default: include) [include|home|absolute]
  268.      * @param string $remove removes a string pattern from the file name when performing a file search
  269.      * @return bool 
  270.      * @throws Gumbo_Exception
  271.      */
  272.     public function loadFile ($name, $dirs=null, $ext=null, $once=false, $use_include=false, $stretch=false, $separator=null, $path="include", $remove=null) {
  273.         try {
  274.             // verify precondition
  275.             if (!is_string ($name)) {
  276.                 throw new Gumbo_Exception ("Invalid Argument 'name:str' => {$name}:" . gettype ($name));
  277.             }
  278.             
  279.             try {
  280.                 if (!is_bool ($once)) {
  281.                     throw new Gumbo_Exception ("Invalid Argument 'once:bool' => {$once}:" . gettype ($once));
  282.                 }
  283.             } catch (Gumbo_Exception $e) {
  284.                 $e->setFunction (__METHOD__);
  285.                 gumbo_trigger ($e);
  286.                 $once = false;
  287.             }
  288.             
  289.             try {
  290.                 if (!is_bool ($use_include)) {
  291.                     throw new Gumbo_Exception ("Invalid Argument 'use_include:bool' => {$use_include}:" . gettype ($use_include));
  292.                 }
  293.             } catch (Gumbo_Exception $e) {
  294.                 $e->setFunction (__METHOD__);
  295.                 gumbo_trigger ($e);
  296.                 $use_include = false;
  297.             }
  298.             
  299.             $file = $this->getFullPath ($name, $dirs, $ext, $stretch, $separator, $path, $remove);
  300.             if (!$file) {
  301.                 return false;
  302.             }
  303.             
  304.             // include the file
  305.             if ($once) {
  306.                 // verify that the file wasn't previously included
  307.                 $found = false;
  308.                 foreach (get_included_files () as $val) {
  309.                     if ($file === $val) {
  310.                         $found = true;
  311.                         break;
  312.                     }
  313.                 }
  314.                 if ($found) {
  315.                     return true;
  316.                 }
  317.                 
  318.                 if ($use_include) {
  319.                     // include the file
  320.                     return include_once ($file);
  321.                 } else {
  322.                     // require the file
  323.                     require_once ($file);
  324.                 }
  325.             } else {
  326.                 if ($use_include) {
  327.                     // include the file
  328.                     return include ($file);
  329.                 } else {
  330.                     // require the file
  331.                     require ($file);
  332.                 }
  333.             }
  334.             
  335.             return true;
  336.         } catch (Gumbo_Exception $e) {
  337.             $e->setFunction (__METHOD__);
  338.             gumbo_trigger ($e);
  339.         }
  340.         return false;
  341.     }
  342.     
  343.     
  344.     
  345.     /**
  346.      * Adds a setting, overwriting the original setting if exists
  347.      * @postcondition remove all non alpha-numeric (except underscores) characters from $key
  348.      * @param Gumbo_Interface_Setting $setting 
  349.      * @param string $key reference key
  350.      * @throws Gumbo_Exception
  351.      */
  352.     public function addSetting (Gumbo_Interface_Setting $setting, $key) {
  353.         try {
  354.             // verify precondition
  355.             if (!is_string ($key)) {
  356.                 throw new Gumbo_Exception ("Invalid Argument 'key:str' => {$key}:" . gettype ($key));
  357.             }
  358.             
  359.             $key = ereg_replace ("[^0-9A-Za-z_]", "", $key);
  360.             $this->_settings [$key] = $setting;
  361.         } catch (Gumbo_Exception $e) {
  362.             $e->setFunction (__METHOD__);
  363.             gumbo_trigger ($e);
  364.         }
  365.     }
  366.     
  367.     /**
  368.      * Removes a Setting
  369.      * @param string $key 
  370.      * @throws Gumbo_Exception
  371.      */
  372.     public function removeSetting ($key) {
  373.         try {
  374.             // verify precondition
  375.             if (!is_string ($key)) {
  376.                 throw new Gumbo_Exception ("Invalid Argument 'key:str' => {$key}:" . gettype ($key));
  377.             }
  378.             if (!$this->isSetting ($key)) {
  379.                 throw new Gumbo_Exception ("Setting Undefined: {$key}");
  380.             }
  381.             
  382.             unset ($this->_settings [$key]);
  383.         } catch (Gumbo_Exception $e) {
  384.             $e->setFunction (__METHOD__);
  385.             gumbo_trigger ($e);
  386.         }
  387.     }
  388.     
  389.     /**
  390.      * Resets all Settings
  391.      * @postcondition clears all settings
  392.      */
  393.     public function resetSettings () {
  394.         $this->_settings = array ();
  395.     }
  396.     
  397.     
  398.     
  399.     
  400.     
  401.     /** MUTATOR METHODS **/
  402.     /**
  403.      * Sets the Custom Class File location
  404.      * @precondition is_dir ($loc)
  405.      * @param string $loc 
  406.      * @throws Gumbo_Exception
  407.      */
  408.     public function setDirCustom ($loc) {
  409.         try {
  410.             // verify precondition
  411.             if (!is_string ($loc)) {
  412.                 throw new Gumbo_Exception ("Invalid Argument 'loc:str' => {$loc}:" . gettype ($loc));
  413.             }
  414.             if (!is_dir ($loc)) {
  415.                 throw new Gumbo_Exception ("Invalid Directory: {$loc}");
  416.             }
  417.             
  418.             $this->_dir_custom = str_replace ("\\", "/", $loc) . "/";
  419.         } catch (Gumbo_Exception $e) {
  420.             $e->setFunction (__METHOD__);
  421.             gumbo_trigger ($e);
  422.         }
  423.     }
  424.     
  425.     
  426.     
  427.     /** ACCESSOR METHODS **/
  428.     /**
  429.      * Loads a class file into memory
  430.      * @param string $name class name
  431.      * @return bool 
  432.      */
  433.     public function __get ($name) {
  434.         return gumbo_load ($name);
  435.     }
  436.     
  437.     /**
  438.      * Returns the home directory
  439.      * @return string 
  440.      */
  441.     public function getDirHome () {
  442.         return $this->_dir_home;
  443.     }
  444.     
  445.     /**
  446.      * Returns the Custom directory
  447.      * @return string 
  448.      */
  449.     public function getDirCustom () {
  450.         return $this->_dir_custom;
  451.     }
  452.     
  453.     /**
  454.      * Returns a formatted file path
  455.      * @param string $name file name
  456.      * @param string|array$dirs locations to search through (from path)
  457.      * @param string $ext file extension (if null, uses the string from the last dot *.ext)
  458.      * @param bool $stretch stretch the file name from the path directory
  459.      * @param string $separator stretch separator character (typically "." or "_")
  460.      * @param string $path path to start from (default: include) [include|home|absolute]
  461.      * @param string $remove removes string pattern from the file name before file search
  462.      * @return string 
  463.      * @uses Gumbo_Load_Setting
  464.      * @throws Gumbo_Exception
  465.      * @todo parse separator by lowercase/uppercase letters
  466.      */
  467.     public function getFullPath ($name, $dirs=null, $ext=null, $stretch=false, $separator=null, $path="include", $remove=null) {
  468.         try {
  469.             // verify precondition
  470.             if (!is_string ($name)) {
  471.                 throw new Gumbo_Exception ("Invalid Argument 'name:str' => {$name}:" . gettype ($name));
  472.             }
  473.             
  474.             $setting = new Gumbo_Load_Setting ();
  475.             $setting->setDirs ($dirs);
  476.             $setting->setExtension ($ext);
  477.             $setting->setStretch ($stretch);
  478.             $setting->setSeparator ($separator);
  479.             $setting->setPath ($path);
  480.             $setting->setRemove ($remove);
  481.             
  482.             // check for extension in file name
  483.             if (is_null ($ext) && strstr ($name, ".")) {
  484.                 $tmp = explode (".", $name);
  485.                 $last = count ($tmp) - 1;
  486.                 $setting->setExtension ($tmp [$last]);
  487.                 $last = null;
  488.                 $tmp = null;
  489.             }
  490.             
  491.             // remove extension from file name, if it exists
  492.             if (substr ($name, strlen ($name) - strlen ($setting->getExtension ())) == $setting->getExtension ()) {
  493.                 $name = substr ($name, 0, strlen ($name) - strlen ("." . $setting->getExtension ()));
  494.             }
  495.             
  496.             // check if the file stretches the directory
  497.             $file = str_replace ($setting->getRemove (), "", $name);
  498.             $dirs_stretch = null;
  499.             if ($setting->getStretch () && strstr ($file, $setting->getSeparator ())) {
  500.                 $tmp = explode ($setting->getSeparator (), $file);
  501.                 if (count ($tmp) > 1) {
  502.                     $num = count ($tmp) - 1;
  503.                     foreach ($tmp as $key=>$val) {
  504.                         if ($key == $num) {
  505.                             $file = $val;
  506.                             break;
  507.                         }
  508.                         $dirs_stretch .= gumbo_appendLocation ($val);
  509.                     }
  510.                 }
  511.             }
  512.             
  513.             // format the directories listed
  514.             $dirs = array ();
  515.             if (is_array ($setting->getDirs ()) && count ($setting->getDirs ()) > 0) {
  516.                 foreach ($setting->getDirs () as $val) {
  517.                     // checking if from Home path
  518.                     if ($setting->getPath () == "home") {
  519.                         if ($this->getDirCustom ()) {
  520.                             $path = gumbo_appendLocation ($this->getDirCustom (), $val, $dirs_stretch);
  521.                             if (is_dir ($path)) {
  522.                                 $dirs [] = $path;
  523.                             }
  524.                         }
  525.                         
  526.                         $path = gumbo_appendLocation ($this->getDirHome (), $val, $dirs_stretch);
  527.                         if (is_dir ($path)) {
  528.                             $dirs [] = $path;
  529.                         }
  530.                     } else {
  531.                         $path = gumbo_appendLocation ($val, $dirs_stretch);
  532.                         if (is_dir ($path)) {
  533.                             $dirs [] = $path;
  534.                         }
  535.                     }
  536.                 }
  537.             } else {
  538.                 if ($setting->getPath () == "home") {
  539.                     $path = gumbo_appendLocation ($this->getDirCustom (), $dirs_stretch);
  540.                     if (is_dir ($path)) {
  541.                         $dirs [] = $path;
  542.                     }
  543.                     
  544.                     $path = gumbo_appendLocation ($this->getDirHome (), $dirs_stretch);
  545.                     if (is_dir ($path)) {
  546.                         $dirs [] = $path;
  547.                     }
  548.                 }
  549.             }
  550.             
  551.             // set the file name
  552.             $file = gumbo_appendFile ($file, $setting->getExtension ());
  553.             
  554.             // set the location of the first found file
  555.             $loc = null;
  556.             if (is_array ($dirs)) {
  557.                 foreach ($dirs as $dir) {
  558.                     if (file_exists ($dir . $file)) {
  559.                         $loc = $dir;
  560.                         break;
  561.                     }
  562.                 }
  563.             }
  564.             
  565.             // verify file exists
  566.             if (!file_exists ($loc . $file)) {
  567.                 throw new Gumbo_Exception ("File Not Found: {$loc}{$file}");
  568.             }
  569.             return $loc . $file;
  570.         } catch (Gumbo_Exception $e) {
  571.             $e->setFunction (__METHOD__);
  572.             gumbo_trigger ($e);
  573.         }
  574.         return false;
  575.     }
  576.     
  577.     /**
  578.      * Returns the list of all Settings
  579.      * @return Gumbo_Interface_Setting[] 
  580.      */
  581.     public function getSettings () {
  582.         return $this->_settings;
  583.     }
  584.     
  585.     /**
  586.      * Returns a single Setting object based on the key
  587.      * @param string $key 
  588.      * @return Gumbo_Interface_Setting 
  589.      * @throws Gumbo_Exception
  590.      */
  591.     public function getSetting ($key) {
  592.         try {
  593.             // verify precondition
  594.             if (is_null ($key)) { return null; }
  595.             if (!is_string ($key)) {
  596.                 throw new Gumbo_Exception ("Invalid Argument 'key:str' => {$key}:" . gettype ($key));
  597.             }
  598.             if (!$this->isSetting ($key)) {
  599.                 throw new Gumbo_Exception ("Setting Undefined: {$key}");
  600.             }
  601.             
  602.             return $this->_settings [$key];
  603.         } catch (Gumbo_Exception $e) {
  604.             $e->setFunction (__METHOD__);
  605.             gumbo_trigger ($e);
  606.         }
  607.         return null;
  608.     }
  609.     
  610.     /**
  611.      * Returns if a Setting exists
  612.      * @param string $key 
  613.      * @return bool 
  614.      * @throws Gumbo_Exception
  615.      */
  616.     public function isSetting ($key) {
  617.         try {
  618.             // verify precondition
  619.             if (!is_string ($key)) {
  620.                 throw new Gumbo_Exception ("Invalid Argument 'key:str' => {$key}:" . gettype ($key));
  621.             }
  622.             
  623.             return isset ($this->_settings [$key]);
  624.         } catch (Gumbo_Exception $e) {
  625.             $e->setFunction (__METHOD__);
  626.             gumbo_trigger ($e);
  627.         }
  628.         return false;
  629.     }
  630.     
  631. }
  632.  
  633. ?>