Source for file interface.php

Documentation is available at interface.php

  1. <?php
  2. /**
  3.  * @package     FrameworkOnFramework
  4.  * @subpackage  platform
  5.  * @copyright   Copyright (C) 2010 - 2012 Akeeba Ltd. All rights reserved.
  6.  * @license     GNU General Public License version 2 or later; see LICENSE.txt
  7.  */
  8. // Protect from unauthorized access
  9. defined('_JEXEC') or die;
  10.  
  11. /**
  12.  * Part of the FOF Platform Abstraction Layer. It implements everything that
  13.  * depends on the platform FOF is running under, e.g. the Joomla! CMS front-end,
  14.  * the Joomla! CMS back-end, a CLI Joomla! Platform app, a bespoke Joomla!
  15.  * Platform / Framework web application and so on.
  16.  *
  17.  * This is the abstract class implementing some basic housekeeping functionality
  18.  * and provides the static interface to get the appropriate Platform object for
  19.  * use in the rest of the framework.
  20.  *
  21.  * @package  FrameworkOnFramework
  22.  * @since    2.1
  23.  */
  24. interface FOFPlatformInterface
  25. {
  26.     /**
  27.      * Set the error Handling, if possible
  28.      *
  29.      * @param   integer  $level      PHP error level (E_ALL)
  30.      * @param   string   $log_level  What to do with the error (ignore, callback)
  31.      * @param   array    $options    Options for the error handler
  32.      *
  33.      * @return  void 
  34.      */
  35.     public function setErrorHandling($level, $log_level, $options = array());
  36.     /**
  37.      * Returns the ordering of the platform class. Files with a lower ordering
  38.      * number will be loaded first.
  39.      *
  40.      * @return  integer 
  41.      */
  42.     public function getOrdering();
  43.  
  44.     /**
  45.      * Is this platform enabled? This is used for automatic platform detection.
  46.      * If the environment we're currently running in doesn't seem to be your
  47.      * platform return false. If many classes return true, the one with the
  48.      * lowest order will be picked by FOFPlatform.
  49.      *
  50.      * @return  boolean 
  51.      */
  52.     public function isEnabled();
  53.  
  54.     /**
  55.      * Returns the base (root) directories for a given component. The
  56.      * "component" is used in the sense of what we call "component" in Joomla!,
  57.      * "plugin" in WordPress and "module" in Drupal, i.e. an application which
  58.      * is running inside our main application (CMS).
  59.      *
  60.      * The return is a table with the following keys:
  61.      * * main    The normal location of component files. For a back-end Joomla!
  62.      *          component this is the administrator/components/com_example
  63.      *          directory.
  64.      * * alt    The alternate location of component files. For a back-end
  65.      *          Joomla! component this is the front-end directory, e.g.
  66.      *          components/com_example
  67.      * * site    The location of the component files serving the public part of
  68.      *          the application.
  69.      * * admin    The location of the component files serving the administrative
  70.      *          part of the application.
  71.      *
  72.      * All paths MUST be absolute. All four paths MAY be the same if the
  73.      * platform doesn't make a distinction between public and private parts,
  74.      * or when the component does not provide both a public and private part.
  75.      * All of the directories MUST be defined and non-empty.
  76.      *
  77.      * @param   string  $component  The name of the component. For Joomla! this
  78.      *                               is something like "com_example"
  79.      *
  80.      * @return  array  A hash array with keys main, alt, site and admin.
  81.      */
  82.     public function getComponentBaseDirs($component);
  83.  
  84.     /**
  85.      * Return a list of the view template paths for this component. The paths
  86.      * are in the format site:/component_name/view_name/layout_name or
  87.      * admin:/component_name/view_name/layout_name
  88.      *
  89.      * The list of paths returned is a prioritised list. If a file is
  90.      * found in the first path the other paths will not be scanned.
  91.      *
  92.      * @param   string   $component  The name of the component. For Joomla! this
  93.      *                                is something like "com_example"
  94.      * @param   string   $view       The name of the view you're looking a
  95.      *                                template for
  96.      * @param   string   $layout     The layout name to load, e.g. 'default'
  97.      * @param   string   $tpl        The sub-template name to load (null by default)
  98.      * @param   boolean  $strict     If true, only the specified layout will be
  99.      *                                searched for. Otherwise we'll fall back to
  100.      *                                the 'default' layout if the specified layout
  101.      *                                is not found.
  102.      *
  103.      * @return  array 
  104.      */
  105.     public function getViewTemplatePaths($component, $view, $layout = 'default', $tpl = null, $strict = false);
  106.  
  107.     /**
  108.      * Get application-specific suffixes to use with template paths. This allows
  109.      * you to look for view template overrides based on the application version.
  110.      *
  111.      * @return  array  A plain array of suffixes to try in template names
  112.      */
  113.     public function getTemplateSuffixes();
  114.  
  115.     /**
  116.      * Return the absolute path to the application's template overrides
  117.      * directory for a specific component. We will use it to look for template
  118.      * files instead of the regular component directorues. If the application
  119.      * does not have such a thing as template overrides return an empty string.
  120.      *
  121.      * @param   string   $component  The name of the component for which to fetch the overrides
  122.      * @param   boolean  $absolute   Should I return an absolute or relative path?
  123.      *
  124.      * @return  string  The path to the template overrides directory
  125.      */
  126.     public function getTemplateOverridePath($component, $absolute = true);
  127.  
  128.     /**
  129.      * Load the translation files for a given component. The
  130.      * "component" is used in the sense of what we call "component" in Joomla!,
  131.      * "plugin" in WordPress and "module" in Drupal, i.e. an application which
  132.      * is running inside our main application (CMS).
  133.      *
  134.      * @param   string  $component  The name of the component. For Joomla! this
  135.      *                               is something like "com_example"
  136.      *
  137.      * @return  void 
  138.      */
  139.     public function loadTranslations($component);
  140.  
  141.     /**
  142.      * By default FOF will only use the Controller's onBefore* methods to
  143.      * perform user authorisation. In some cases, like the Joomla! back-end,
  144.      * you alos need to perform component-wide user authorisation in the
  145.      * Dispatcher. This method MUST implement this authorisation check. If you
  146.      * do not need this in your platform, please always return true.
  147.      *
  148.      * @param   string  $component  The name of the component.
  149.      *
  150.      * @return  boolean  True to allow loading the component, false to halt loading
  151.      */
  152.     public function authorizeAdmin($component);
  153.  
  154.     /**
  155.      * This method will try retrieving a variable from the request (input) data.
  156.      * If it doesn't exist it will be loaded from the user state, typically
  157.      * stored in the session. If it doesn't exist there either, the $default
  158.      * value will be used. If $setUserState is set to true, the retrieved
  159.      * variable will be stored in the user session.
  160.      *
  161.      * @param   string    $key           The user state key for the variable
  162.      * @param   string    $request       The request variable name for the variable
  163.      * @param   FOFInput  $input         The FOFInput object with the request (input) data
  164.      * @param   mixed     $default       The default value. Default: null
  165.      * @param   string    $type          The filter type for the variable data. Default: none (no filtering)
  166.      * @param   boolean   $setUserState  Should I set the user state with the fetched value?
  167.      *
  168.      * @return  mixed  The value of the variable
  169.      */
  170.     public function getUserStateFromRequest($key, $request, $input, $default = null, $type = 'none', $setUserState = true);
  171.  
  172.     /**
  173.      * Load plugins of a specific type. Obviously this seems to only be required
  174.      * in the Joomla! CMS.
  175.      *
  176.      * @param   string  $type  The type of the plugins to be loaded
  177.      *
  178.      * @return void 
  179.      */
  180.     public function importPlugin($type);
  181.  
  182.     /**
  183.      * Execute plugins (system-level triggers) and fetch back an array with
  184.      * their return values.
  185.      *
  186.      * @param   string  $event  The event (trigger) name, e.g. onBeforeScratchMyEar
  187.      * @param   array   $data   A hash array of data sent to the plugins as part of the trigger
  188.      *
  189.      * @return  array  A simple array containing the resutls of the plugins triggered
  190.      */
  191.     public function runPlugins($event, $data);
  192.  
  193.     /**
  194.      * Perform an ACL check. Please note that FOF uses by default the Joomla!
  195.      * CMS convention for ACL privileges, e.g core.edit for the edit privilege.
  196.      * If your platform uses different conventions you'll have to override the
  197.      * FOF defaults using fof.xml or by specialising the controller.
  198.      *
  199.      * @param   string  $action     The ACL privilege to check, e.g. core.edit
  200.      * @param   string  $assetname  The asset name to check, typically the component's name
  201.      *
  202.      * @return  boolean  True if the user is allowed this action
  203.      */
  204.     public function authorise($action, $assetname);
  205.  
  206.     /**
  207.      * Returns a user object.
  208.      *
  209.      * @param   integer  $id  The user ID to load. Skip or use null to retrieve
  210.      *                         the object for the currently logged in user.
  211.      *
  212.      * @return  JUser  The JUser object for the specified user
  213.      */
  214.     public function getUser($id = null);
  215.  
  216.     /**
  217.      * Returns the JDocument object which handles this component's response. You
  218.      * may also return null and FOF will a. try to figure out the output type by
  219.      * examining the "format" input parameter (or fall back to "html") and b.
  220.      * FOF will not attempt to load CSS and Javascript files (as it doesn't make
  221.      * sense if there's no JDocument to handle them).
  222.      *
  223.      * @return  JDocument 
  224.      */
  225.     public function getDocument();
  226.  
  227.     /**
  228.      * Is this the administrative section of the component?
  229.      *
  230.      * @return  boolean 
  231.      */
  232.     public function isBackend();
  233.  
  234.     /**
  235.      * Is this the public section of the component?
  236.      *
  237.      * @return  boolean 
  238.      */
  239.     public function isFrontend();
  240.  
  241.     /**
  242.      * Is this a component running in a CLI application?
  243.      *
  244.      * @return  boolean 
  245.      */
  246.     public function isCli();
  247.  
  248.     /**
  249.      * Is AJAX re-ordering supported? This is 100% Joomla!-CMS specific. All
  250.      * other platforms should return false and never ask why.
  251.      *
  252.      * @return  boolean 
  253.      */
  254.     public function supportsAjaxOrdering();
  255.  
  256.     /**
  257.      * Performs a check between two versions. Use this function instead of PHP version_compare
  258.      * so we can mock it while testing
  259.      *
  260.      * @param   string  $version1  First version number
  261.      * @param   string  $version2  Second version number
  262.      * @param   string  $operator  Operator (see version_compare for valid operators)
  263.      *
  264.      * @return  boolean 
  265.      */
  266.     public function checkVersion($version1, $version2, $operator);
  267.  
  268.     /**
  269.      * Saves something to the cache. This is supposed to be used for system-wide
  270.      * FOF data, not application data.
  271.      *
  272.      * @param   string  $key      The key of the data to save
  273.      * @param   string  $content  The actual data to save
  274.      *
  275.      * @return  boolean  True on success
  276.      */
  277.     public function setCache($key, $content);
  278.  
  279.     /**
  280.      * Retrieves data from the cache. This is supposed to be used for system-side
  281.      * FOF data, not application data.
  282.      *
  283.      * @param   string  $key      The key of the data to retrieve
  284.      * @param   string  $default  The default value to return if the key is not found or the cache is not populated
  285.      *
  286.      * @return  string  The cached value
  287.      */
  288.     public function getCache($key, $default = null);
  289.  
  290.     /**
  291.      * Clears the cache of system-wide FOF data. You are supposed to call this in
  292.      * your components' installation script post-installation and post-upgrade
  293.      * methods or whenever you are modifying the structure of database tables
  294.      * accessed by FOF. Please note that FOF's cache never expires and is not
  295.      * purged by Joomla!. You MUST use this method to manually purge the cache.
  296.      *
  297.      * @return  boolean  True on success
  298.      */
  299.     public function clearCache();
  300.  
  301.     /**
  302.      * Is the global FOF cache enabled?
  303.      *
  304.      * @return  boolean 
  305.      */
  306.     public function isGlobalFOFCacheEnabled();
  307.  
  308.     /**
  309.      * logs in a user
  310.      *
  311.      * @param   array  $authInfo  authentification information
  312.      *
  313.      * @return  boolean  True on success
  314.      */
  315.     public function loginUser($authInfo);
  316.  
  317.     /**
  318.      * logs out a user
  319.      *
  320.      * @return  boolean  True on success
  321.      */
  322.     public function logoutUser();
  323.  
  324. }

Documentation generated on Tue, 19 Nov 2013 15:05:49 +0100 by phpDocumentor 1.4.3