Joomla! Platform 12.1

Download

Demo

Source code for file /libraries/joomla/application/component/model.php

Documentation is available at model.php

  1. <?php
  2. /**
  3.  * @package     Joomla.Platform
  4.  * @subpackage  Application
  5.  *
  6.  * @copyright   Copyright (C) 2005 - 2012 Open Source Matters, Inc. All rights reserved.
  7.  * @license     GNU General Public License version 2 or later; see LICENSE
  8.  */
  9.  
  10. defined('JPATH_PLATFORM') or die;
  11.  
  12. /**
  13.  * Base class for a Joomla Model
  14.  *
  15.  * Acts as a Factory class for application specific objects and
  16.  * provides many supporting API functions.
  17.  *
  18.  * @package     Joomla.Platform
  19.  * @subpackage  Application
  20.  * @since       11.1
  21.  */
  22. abstract class JModel extends JObject
  23. {
  24.     /**
  25.      * Indicates if the internal state has been set
  26.      *
  27.      * @var    boolean 
  28.      * @since  11.1
  29.      */
  30.     protected $stateSet = null;
  31.  
  32.     /**
  33.      * Indicates if the internal state has been set
  34.      *
  35.      * @var    boolean 
  36.      * @since  11.1
  37.      * @deprecated use $stateSet declare as private
  38.      */
  39.     protected $__state_set = null;
  40.  
  41.     /**
  42.      * Database Connector
  43.      *
  44.      * @var    object 
  45.      * @since  11.1
  46.      */
  47.     protected $db;
  48.  
  49.     /**
  50.      * Database Connector
  51.      *
  52.      * @var    object 
  53.      * @since  11.1
  54.      * @deprecated use $db declare as private
  55.      */
  56.     protected $_db;
  57.  
  58.     /**
  59.      * The model (base) name
  60.      *
  61.      * @var    string 
  62.      * @note   Replaces _name variable in 11.1
  63.      * @since  11.1
  64.      */
  65.     protected $name;
  66.  
  67.     /**
  68.      * The URL option for the component.
  69.      *
  70.      * @var    string 
  71.      * @since  11.1
  72.      */
  73.     protected $option = null;
  74.  
  75.     /**
  76.      * A state object
  77.      *
  78.      * @var    string 
  79.      * @note   Replaces _state variable in 11.1
  80.      * @since  11.1
  81.      */
  82.     protected $state;
  83.  
  84.     /**
  85.      * The event to trigger when cleaning cache.
  86.      *
  87.      * @var      string 
  88.      * @since    11.1
  89.      */
  90.     protected $event_clean_cache = null;
  91.  
  92.     /**
  93.      * Add a directory where JModel should search for models. You may
  94.      * either pass a string or an array of directories.
  95.      *
  96.      * @param   mixed   $path    A path or array[sting] of paths to search.
  97.      * @param   string  $prefix  A prefix for models.
  98.      *
  99.      * @return  array  An array with directory elements. If prefix is equal to '', all directories are returned.
  100.      *
  101.      * @since   11.1
  102.      */
  103.     public static function addIncludePath($path = '', $prefix = '')
  104.     {
  105.         static $paths;
  106.  
  107.         if (!isset($paths))
  108.         {
  109.             $paths = array();
  110.         }
  111.  
  112.         if (!isset($paths[$prefix]))
  113.         {
  114.             $paths[$prefix] = array();
  115.         }
  116.  
  117.         if (!isset($paths['']))
  118.         {
  119.             $paths[''] = array();
  120.         }
  121.  
  122.         if (!empty($path))
  123.         {
  124.             jimport('joomla.filesystem.path');
  125.  
  126.             if (!in_array($path, $paths[$prefix]))
  127.             {
  128.                 array_unshift($paths[$prefix], JPath::clean($path));
  129.             }
  130.  
  131.             if (!in_array($path, $paths['']))
  132.             {
  133.                 array_unshift($paths[''], JPath::clean($path));
  134.             }
  135.         }
  136.  
  137.         return $paths[$prefix];
  138.     }
  139.  
  140.     /**
  141.      * Adds to the stack of model table paths in LIFO order.
  142.      *
  143.      * @param   mixed  $path  The directory as a string or directories as an array to add.
  144.      *
  145.      * @return  void 
  146.      *
  147.      * @since   11.1
  148.      */
  149.     public static function addTablePath($path)
  150.     {
  151.         jimport('joomla.database.table');
  152.         JTable::addIncludePath($path);
  153.     }
  154.  
  155.     /**
  156.      * Create the filename for a resource
  157.      *
  158.      * @param   string  $type   The resource type to create the filename for.
  159.      * @param   array   $parts  An associative array of filename information.
  160.      *
  161.      * @return  string  The filename
  162.      *
  163.      * @since   11.1
  164.      */
  165.     protected static function _createFileName($type, $parts = array())
  166.     {
  167.         $filename = '';
  168.  
  169.         switch ($type)
  170.         {
  171.             case 'model':
  172.                 $filename = strtolower($parts['name']) . '.php';
  173.                 break;
  174.  
  175.         }
  176.         return $filename;
  177.     }
  178.  
  179.     /**
  180.      * Returns a Model object, always creating it
  181.      *
  182.      * @param   string  $type    The model type to instantiate
  183.      * @param   string  $prefix  Prefix for the model class name. Optional.
  184.      * @param   array   $config  Configuration array for model. Optional.
  185.      *
  186.      * @return  mixed   A model object or false on failure
  187.      *
  188.      * @since   11.1
  189.      */
  190.     public static function getInstance($type, $prefix = '', $config = array())
  191.     {
  192.         $type = preg_replace('/[^A-Z0-9_\.-]/i', '', $type);
  193.         $modelClass = $prefix . ucfirst($type);
  194.  
  195.         if (!class_exists($modelClass))
  196.         {
  197.             jimport('joomla.filesystem.path');
  198.             $path = JPath::find(JModel::addIncludePath(null, $prefix), JModel::_createFileName('model', array('name' => $type)));
  199.             if (!$path)
  200.             {
  201.                 $path = JPath::find(JModel::addIncludePath(null, ''), JModel::_createFileName('model', array('name' => $type)));
  202.             }
  203.             if ($path)
  204.             {
  205.                 require_once $path;
  206.  
  207.                 if (!class_exists($modelClass))
  208.                 {
  209.                     JError::raiseWarning(0, JText::sprintf('JLIB_APPLICATION_ERROR_MODELCLASS_NOT_FOUND', $modelClass));
  210.                     return false;
  211.                 }
  212.             }
  213.             else
  214.             {
  215.                 return false;
  216.             }
  217.         }
  218.  
  219.         return new $modelClass($config);
  220.     }
  221.  
  222.     /**
  223.      * Constructor
  224.      *
  225.      * @param   array  $config  An array of configuration options (name, state, dbo, table_path, ignore_request).
  226.      *
  227.      * @since   11.1
  228.      */
  229.     public function __construct($config = array())
  230.     {
  231.         // Guess the option from the class name (Option)Model(View).
  232.         if (empty($this->option))
  233.         {
  234.             $r = null;
  235.  
  236.             if (!preg_match('/(.*)Model/i', get_class($this), $r))
  237.             {
  238.                 JError::raiseError(500, JText::_('JLIB_APPLICATION_ERROR_MODEL_GET_NAME'));
  239.             }
  240.  
  241.             $this->option = 'com_' . strtolower($r[1]);
  242.         }
  243.  
  244.         // Set the view name
  245.         if (empty($this->name))
  246.         {
  247.             if (array_key_exists('name', $config))
  248.             {
  249.                 $this->name = $config['name'];
  250.             }
  251.             else
  252.             {
  253.                 $this->name = $this->getName();
  254.             }
  255.         }
  256.  
  257.         // Set the model state
  258.         if (array_key_exists('state', $config))
  259.         {
  260.             $this->state = $config['state'];
  261.         }
  262.         else
  263.         {
  264.             $this->state = new JObject;
  265.         }
  266.  
  267.         // Set the model dbo
  268.         if (array_key_exists('dbo', $config))
  269.         {
  270.             $this->_db = $config['dbo'];
  271.         }
  272.         else
  273.         {
  274.             $this->_db = JFactory::getDbo();
  275.         }
  276.  
  277.         // Set the default view search path
  278.         if (array_key_exists('table_path', $config))
  279.         {
  280.             $this->addTablePath($config['table_path']);
  281.         }
  282.         elseif (defined('JPATH_COMPONENT_ADMINISTRATOR'))
  283.         {
  284.             $this->addTablePath(JPATH_COMPONENT_ADMINISTRATOR . '/tables');
  285.         }
  286.  
  287.         // Set the internal state marker - used to ignore setting state from the request
  288.         if (!empty($config['ignore_request']))
  289.         {
  290.             $this->__state_set = true;
  291.         }
  292.  
  293.         // Set the clean cache event
  294.         if (isset($config['event_clean_cache']))
  295.         {
  296.             $this->event_clean_cache = $config['event_clean_cache'];
  297.         }
  298.         elseif (empty($this->event_clean_cache))
  299.         {
  300.             $this->event_clean_cache = 'onContentCleanCache';
  301.         }
  302.  
  303.     }
  304.  
  305.     /**
  306.      * Gets an array of objects from the results of database query.
  307.      *
  308.      * @param   string   $query       The query.
  309.      * @param   integer  $limitstart  Offset.
  310.      * @param   integer  $limit       The number of records.
  311.      *
  312.      * @return  array  An array of results.
  313.      *
  314.      * @since   11.1
  315.      */
  316.     protected function _getList($query, $limitstart = 0, $limit = 0)
  317.     {
  318.         $this->_db->setQuery($query, $limitstart, $limit);
  319.         $result = $this->_db->loadObjectList();
  320.  
  321.         return $result;
  322.     }
  323.  
  324.     /**
  325.      * Returns a record count for the query
  326.      *
  327.      * @param   string  $query  The query.
  328.      *
  329.      * @return  integer  Number of rows for query
  330.      *
  331.      * @since   11.1
  332.      */
  333.     protected function _getListCount($query)
  334.     {
  335.         $this->_db->setQuery($query);
  336.         $this->_db->query();
  337.  
  338.         return $this->_db->getNumRows();
  339.     }
  340.  
  341.     /**
  342.      * Method to load and return a model object.
  343.      *
  344.      * @param   string  $name    The name of the view
  345.      * @param   string  $prefix  The class prefix. Optional.
  346.      * @param   array   $config  Configuration settings to pass to JTable::getInstance
  347.      *
  348.      * @return  mixed  Model object or boolean false if failed
  349.      *
  350.      * @since   11.1
  351.      * @see     JTable::getInstance
  352.      */
  353.     protected function _createTable($name, $prefix = 'Table', $config = array())
  354.     {
  355.         // Clean the model name
  356.         $name = preg_replace('/[^A-Z0-9_]/i', '', $name);
  357.         $prefix = preg_replace('/[^A-Z0-9_]/i', '', $prefix);
  358.  
  359.         // Make sure we are returning a DBO object
  360.         if (!array_key_exists('dbo', $config))
  361.         {
  362.             $config['dbo'] = $this->getDbo();
  363.         }
  364.  
  365.         return JTable::getInstance($name, $prefix, $config);
  366.     }
  367.  
  368.     /**
  369.      * Method to get the database connector object
  370.      *
  371.      * @return  JDatabase  JDatabase connector object
  372.      */
  373.     public function getDbo()
  374.     {
  375.         return $this->_db;
  376.     }
  377.  
  378.     /**
  379.      * Method to get the model name
  380.      *
  381.      * The model name. By default parsed using the classname or it can be set
  382.      * by passing a $config['name'] in the class constructor
  383.      *
  384.      * @return  string  The name of the model
  385.      *
  386.      * @since   11.1
  387.      */
  388.     public function getName()
  389.     {
  390.         if (empty($this->name))
  391.         {
  392.             $r = null;
  393.             if (!preg_match('/Model(.*)/i', get_class($this), $r))
  394.             {
  395.                 JError::raiseError(500, JText::_('JLIB_APPLICATION_ERROR_MODEL_GET_NAME'));
  396.             }
  397.             $this->name = strtolower($r[1]);
  398.         }
  399.  
  400.         return $this->name;
  401.     }
  402.  
  403.     /**
  404.      * Method to get model state variables
  405.      *
  406.      * @param   string  $property  Optional parameter name
  407.      * @param   mixed   $default   Optional default value
  408.      *
  409.      * @return  object  The property where specified, the state object where omitted
  410.      *
  411.      * @since   11.1
  412.      */
  413.     public function getState($property = null, $default = null)
  414.     {
  415.         if (!$this->__state_set)
  416.         {
  417.             // Protected method to auto-populate the model state.
  418.             $this->populateState();
  419.  
  420.             // Set the model state set flag to true.
  421.             $this->__state_set = true;
  422.         }
  423.  
  424.         return $property === null ? $this->state : $this->state->get($property, $default);
  425.     }
  426.  
  427.     /**
  428.      * Method to get a table object, load it if necessary.
  429.      *
  430.      * @param   string  $name     The table name. Optional.
  431.      * @param   string  $prefix   The class prefix. Optional.
  432.      * @param   array   $options  Configuration array for model. Optional.
  433.      *
  434.      * @return  JTable  A JTable object
  435.      *
  436.      * @since   11.1
  437.      */
  438.     public function getTable($name = '', $prefix = 'Table', $options = array())
  439.     {
  440.         if (empty($name))
  441.         {
  442.             $name = $this->getName();
  443.         }
  444.  
  445.         if ($table = $this->_createTable($name, $prefix, $options))
  446.         {
  447.             return $table;
  448.         }
  449.  
  450.         JError::raiseError(0, JText::sprintf('JLIB_APPLICATION_ERROR_TABLE_NAME_NOT_SUPPORTED', $name));
  451.  
  452.         return null;
  453.     }
  454.  
  455.     /**
  456.      * Method to auto-populate the model state.
  457.      *
  458.      * This method should only be called once per instantiation and is designed
  459.      * to be called on the first call to the getState() method unless the model
  460.      * configuration flag to ignore the request is set.
  461.      *
  462.      * @return  void 
  463.      *
  464.      * @note    Calling getState in this method will result in recursion.
  465.      * @since   11.1
  466.      */
  467.     protected function populateState()
  468.     {
  469.     }
  470.  
  471.     /**
  472.      * Method to set the database connector object
  473.      *
  474.      * @param   object  &$db  A JDatabase based object
  475.      *
  476.      * @return  void 
  477.      *
  478.      * @since   11.1
  479.      */
  480.     public function setDbo(&$db)
  481.     {
  482.         $this->_db = &$db;
  483.     }
  484.  
  485.     /**
  486.      * Method to set model state variables
  487.      *
  488.      * @param   string  $property  The name of the property.
  489.      * @param   mixed   $value     The value of the property to set or null.
  490.      *
  491.      * @return  mixed  The previous value of the property or null if not set.
  492.      *
  493.      * @since   11.1
  494.      */
  495.     public function setState($property, $value = null)
  496.     {
  497.         return $this->state->set($property, $value);
  498.     }
  499.  
  500.     /**
  501.      * Clean the cache
  502.      *
  503.      * @param   string   $group      The cache group
  504.      * @param   integer  $client_id  The ID of the client
  505.      *
  506.      * @return  void 
  507.      *
  508.      * @since   11.1
  509.      */
  510.     protected function cleanCache($group = null, $client_id = 0)
  511.     {
  512.         // Initialise variables;
  513.         $conf = JFactory::getConfig();
  514.         $dispatcher = JDispatcher::getInstance();
  515.  
  516.         $options = array(
  517.             'defaultgroup' => ($group) ? $group : (isset($this->option) ? $this->option : JRequest::getCmd('option')),
  518.             'cachebase' => ($client_id) ? JPATH_ADMINISTRATOR . '/cache' : $conf->get('cache_path', JPATH_SITE . '/cache'));
  519.  
  520.         $cache = JCache::getInstance('callback', $options);
  521.         $cache->clean();
  522.  
  523.         // Trigger the onContentCleanCache event.
  524.         $dispatcher->trigger($this->event_clean_cache, $options);
  525.     }
  526. }
Support Joomla!
/html>