1 <?php
2 /**
3 * @package FrameworkOnFramework
4 * @subpackage platform
5 * @copyright Copyright (C) 2010-2016 Nicholas K. Dionysopoulos / 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('FOF_INCLUDED') 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 * Checks if the current script is run inside a valid CMS execution
28 *
29 * @return bool
30 */
31 public function checkExecution();
32
33 /**
34 * Set the error Handling, if possible
35 *
36 * @param integer $level PHP error level (E_ALL)
37 * @param string $log_level What to do with the error (ignore, callback)
38 * @param array $options Options for the error handler
39 *
40 * @return void
41 */
42 public function setErrorHandling($level, $log_level, $options = array());
43
44 /**
45 * Raises an error, using the logic requested by the CMS (PHP Exception or dedicated class)
46 *
47 * @param integer $code
48 * @param string $message
49 *
50 * @return mixed
51 */
52 public function raiseError($code, $message);
53
54 /**
55 * Returns the ordering of the platform class. Files with a lower ordering
56 * number will be loaded first.
57 *
58 * @return integer
59 */
60 public function getOrdering();
61
62 /**
63 * Returns a platform integration object
64 *
65 * @param string $key The key name of the platform integration object, e.g. 'filesystem'
66 *
67 * @return object
68 *
69 * @since 2.1.2
70 */
71 public function getIntegrationObject($key);
72
73 /**
74 * Forces a platform integration object instance
75 *
76 * @param string $key The key name of the platform integration object, e.g. 'filesystem'
77 * @param object $object The object to force for this key
78 *
79 * @return object
80 *
81 * @since 2.1.2
82 */
83 public function setIntegrationObject($key, $object);
84
85 /**
86 * Is this platform enabled? This is used for automatic platform detection.
87 * If the environment we're currently running in doesn't seem to be your
88 * platform return false. If many classes return true, the one with the
89 * lowest order will be picked by FOFPlatform.
90 *
91 * @return boolean
92 */
93 public function isEnabled();
94
95 /**
96 * Returns the (internal) name of the platform implementation, e.g.
97 * "joomla", "foobar123" etc. This MUST be the last part of the platform
98 * class name. For example, if you have a plaform implementation class
99 * FOFPlatformFoobar you MUST return "foobar" (all lowercase).
100 *
101 * @return string
102 *
103 * @since 2.1.2
104 */
105 public function getPlatformName();
106
107 /**
108 * Returns the version number string of the platform, e.g. "4.5.6". If
109 * implementation integrates with a CMS or a versioned foundation (e.g.
110 * a framework) it is advisable to return that version.
111 *
112 * @return string
113 *
114 * @since 2.1.2
115 */
116 public function getPlatformVersion();
117
118 /**
119 * Returns the human readable platform name, e.g. "Joomla!", "Joomla!
120 * Framework", "Something Something Something Framework" etc.
121 *
122 * @return string
123 *
124 * @since 2.1.2
125 */
126 public function getPlatformHumanName();
127
128 /**
129 * Returns absolute path to directories used by the CMS.
130 *
131 * The return is a table with the following key:
132 * * root Path to the site root
133 * * public Path to the public area of the site
134 * * admin Path to the administrative area of the site
135 * * tmp Path to the temp directory
136 * * log Path to the log directory
137 *
138 * @return array A hash array with keys root, public, admin, tmp and log.
139 */
140 public function getPlatformBaseDirs();
141
142 /**
143 * Returns the base (root) directories for a given component. The
144 * "component" is used in the sense of what we call "component" in Joomla!,
145 * "plugin" in WordPress and "module" in Drupal, i.e. an application which
146 * is running inside our main application (CMS).
147 *
148 * The return is a table with the following keys:
149 * * main The normal location of component files. For a back-end Joomla!
150 * component this is the administrator/components/com_example
151 * directory.
152 * * alt The alternate location of component files. For a back-end
153 * Joomla! component this is the front-end directory, e.g.
154 * components/com_example
155 * * site The location of the component files serving the public part of
156 * the application.
157 * * admin The location of the component files serving the administrative
158 * part of the application.
159 *
160 * All paths MUST be absolute. All four paths MAY be the same if the
161 * platform doesn't make a distinction between public and private parts,
162 * or when the component does not provide both a public and private part.
163 * All of the directories MUST be defined and non-empty.
164 *
165 * @param string $component The name of the component. For Joomla! this
166 * is something like "com_example"
167 *
168 * @return array A hash array with keys main, alt, site and admin.
169 */
170 public function getComponentBaseDirs($component);
171
172 /**
173 * Return a list of the view template paths for this component. The paths
174 * are in the format site:/component_name/view_name/layout_name or
175 * admin:/component_name/view_name/layout_name
176 *
177 * The list of paths returned is a prioritised list. If a file is
178 * found in the first path the other paths will not be scanned.
179 *
180 * @param string $component The name of the component. For Joomla! this
181 * is something like "com_example"
182 * @param string $view The name of the view you're looking a
183 * template for
184 * @param string $layout The layout name to load, e.g. 'default'
185 * @param string $tpl The sub-template name to load (null by default)
186 * @param boolean $strict If true, only the specified layout will be
187 * searched for. Otherwise we'll fall back to
188 * the 'default' layout if the specified layout
189 * is not found.
190 *
191 * @return array
192 */
193 public function getViewTemplatePaths($component, $view, $layout = 'default', $tpl = null, $strict = false);
194
195 /**
196 * Get application-specific suffixes to use with template paths. This allows
197 * you to look for view template overrides based on the application version.
198 *
199 * @return array A plain array of suffixes to try in template names
200 */
201 public function getTemplateSuffixes();
202
203 /**
204 * Return the absolute path to the application's template overrides
205 * directory for a specific component. We will use it to look for template
206 * files instead of the regular component directorues. If the application
207 * does not have such a thing as template overrides return an empty string.
208 *
209 * @param string $component The name of the component for which to fetch the overrides
210 * @param boolean $absolute Should I return an absolute or relative path?
211 *
212 * @return string The path to the template overrides directory
213 */
214 public function getTemplateOverridePath($component, $absolute = true);
215
216 /**
217 * Load the translation files for a given component. The
218 * "component" is used in the sense of what we call "component" in Joomla!,
219 * "plugin" in WordPress and "module" in Drupal, i.e. an application which
220 * is running inside our main application (CMS).
221 *
222 * @param string $component The name of the component. For Joomla! this
223 * is something like "com_example"
224 *
225 * @return void
226 */
227 public function loadTranslations($component);
228
229 /**
230 * By default FOF will only use the Controller's onBefore* methods to
231 * perform user authorisation. In some cases, like the Joomla! back-end,
232 * you alos need to perform component-wide user authorisation in the
233 * Dispatcher. This method MUST implement this authorisation check. If you
234 * do not need this in your platform, please always return true.
235 *
236 * @param string $component The name of the component.
237 *
238 * @return boolean True to allow loading the component, false to halt loading
239 */
240 public function authorizeAdmin($component);
241
242 /**
243 * This method will try retrieving a variable from the request (input) data.
244 * If it doesn't exist it will be loaded from the user state, typically
245 * stored in the session. If it doesn't exist there either, the $default
246 * value will be used. If $setUserState is set to true, the retrieved
247 * variable will be stored in the user session.
248 *
249 * @param string $key The user state key for the variable
250 * @param string $request The request variable name for the variable
251 * @param FOFInput $input The FOFInput object with the request (input) data
252 * @param mixed $default The default value. Default: null
253 * @param string $type The filter type for the variable data. Default: none (no filtering)
254 * @param boolean $setUserState Should I set the user state with the fetched value?
255 *
256 * @return mixed The value of the variable
257 */
258 public function getUserStateFromRequest($key, $request, $input, $default = null, $type = 'none', $setUserState = true);
259
260 /**
261 * Load plugins of a specific type. Obviously this seems to only be required
262 * in the Joomla! CMS.
263 *
264 * @param string $type The type of the plugins to be loaded
265 *
266 * @return void
267 */
268 public function importPlugin($type);
269
270 /**
271 * Execute plugins (system-level triggers) and fetch back an array with
272 * their return values.
273 *
274 * @param string $event The event (trigger) name, e.g. onBeforeScratchMyEar
275 * @param array $data A hash array of data sent to the plugins as part of the trigger
276 *
277 * @return array A simple array containing the resutls of the plugins triggered
278 */
279 public function runPlugins($event, $data);
280
281 /**
282 * Perform an ACL check. Please note that FOF uses by default the Joomla!
283 * CMS convention for ACL privileges, e.g core.edit for the edit privilege.
284 * If your platform uses different conventions you'll have to override the
285 * FOF defaults using fof.xml or by specialising the controller.
286 *
287 * @param string $action The ACL privilege to check, e.g. core.edit
288 * @param string $assetname The asset name to check, typically the component's name
289 *
290 * @return boolean True if the user is allowed this action
291 */
292 public function authorise($action, $assetname);
293
294 /**
295 * Returns a user object.
296 *
297 * @param integer $id The user ID to load. Skip or use null to retrieve
298 * the object for the currently logged in user.
299 *
300 * @return JUser The JUser object for the specified user
301 */
302 public function getUser($id = null);
303
304 /**
305 * Returns the JDocument object which handles this component's response. You
306 * may also return null and FOF will a. try to figure out the output type by
307 * examining the "format" input parameter (or fall back to "html") and b.
308 * FOF will not attempt to load CSS and Javascript files (as it doesn't make
309 * sense if there's no JDocument to handle them).
310 *
311 * @return JDocument
312 */
313 public function getDocument();
314
315 /**
316 * Returns an object to handle dates
317 *
318 * @param mixed $time The initial time
319 * @param null $tzOffest The timezone offset
320 * @param bool $locale Should I try to load a specific class for current language?
321 *
322 * @return JDate object
323 */
324 public function getDate($time = 'now', $tzOffest = null, $locale = true);
325
326 public function getLanguage();
327
328 /**
329 * @return FOFDatabaseDriver
330 */
331 public function getDbo();
332
333 /**
334 * Is this the administrative section of the component?
335 *
336 * @return boolean
337 */
338 public function isBackend();
339
340 /**
341 * Is this the public section of the component?
342 *
343 * @return boolean
344 */
345 public function isFrontend();
346
347 /**
348 * Is this a component running in a CLI application?
349 *
350 * @return boolean
351 */
352 public function isCli();
353
354 /**
355 * Is AJAX re-ordering supported? This is 100% Joomla!-CMS specific. All
356 * other platforms should return false and never ask why.
357 *
358 * @return boolean
359 */
360 public function supportsAjaxOrdering();
361
362 /**
363 * Performs a check between two versions. Use this function instead of PHP version_compare
364 * so we can mock it while testing
365 *
366 * @param string $version1 First version number
367 * @param string $version2 Second version number
368 * @param string $operator Operator (see version_compare for valid operators)
369 *
370 * @deprecated Use PHP's version_compare against JVERSION in your code. This method is scheduled for removal in FOF 3.0
371 *
372 * @return boolean
373 */
374 public function checkVersion($version1, $version2, $operator);
375
376 /**
377 * Saves something to the cache. This is supposed to be used for system-wide
378 * FOF data, not application data.
379 *
380 * @param string $key The key of the data to save
381 * @param string $content The actual data to save
382 *
383 * @return boolean True on success
384 */
385 public function setCache($key, $content);
386
387 /**
388 * Retrieves data from the cache. This is supposed to be used for system-side
389 * FOF data, not application data.
390 *
391 * @param string $key The key of the data to retrieve
392 * @param string $default The default value to return if the key is not found or the cache is not populated
393 *
394 * @return string The cached value
395 */
396 public function getCache($key, $default = null);
397
398 /**
399 * Clears the cache of system-wide FOF data. You are supposed to call this in
400 * your components' installation script post-installation and post-upgrade
401 * methods or whenever you are modifying the structure of database tables
402 * accessed by FOF. Please note that FOF's cache never expires and is not
403 * purged by Joomla!. You MUST use this method to manually purge the cache.
404 *
405 * @return boolean True on success
406 */
407 public function clearCache();
408
409 /**
410 * Returns an object that holds the configuration of the current site.
411 *
412 * @return mixed
413 */
414 public function getConfig();
415
416 /**
417 * Is the global FOF cache enabled?
418 *
419 * @return boolean
420 */
421 public function isGlobalFOFCacheEnabled();
422
423 /**
424 * logs in a user
425 *
426 * @param array $authInfo authentification information
427 *
428 * @return boolean True on success
429 */
430 public function loginUser($authInfo);
431
432 /**
433 * logs out a user
434 *
435 * @return boolean True on success
436 */
437 public function logoutUser();
438
439 public function logAddLogger($file);
440
441 /**
442 * Logs a deprecated practice. In Joomla! this results in the $message being output in the
443 * deprecated log file, found in your site's log directory.
444 *
445 * @param string $message The deprecated practice log message
446 *
447 * @return void
448 */
449 public function logDeprecated($message);
450
451 public function logDebug($message);
452
453 /**
454 * Returns the root URI for the request.
455 *
456 * @param boolean $pathonly If false, prepend the scheme, host and port information. Default is false.
457 * @param string $path The path
458 *
459 * @return string The root URI string.
460 */
461 public function URIroot($pathonly = false, $path = null);
462
463 /**
464 * Returns the base URI for the request.
465 *
466 * @param boolean $pathonly If false, prepend the scheme, host and port information. Default is false.
467 * |
468 * @return string The base URI string
469 */
470 public function URIbase($pathonly = false);
471
472 /**
473 * Method to set a response header. If the replace flag is set then all headers
474 * with the given name will be replaced by the new one (only if the current platform supports header caching)
475 *
476 * @param string $name The name of the header to set.
477 * @param string $value The value of the header to set.
478 * @param boolean $replace True to replace any headers with the same name.
479 *
480 * @return void
481 */
482 public function setHeader($name, $value, $replace = false);
483
484 /**
485 * In platforms that perform header caching, send all headers.
486 *
487 * @return void
488 */
489 public function sendHeaders();
490 }
491