[CLEANUP] Improve the @param/@return/@var PHPDoc
[Packages/TYPO3.CMS.git] / typo3 / sysext / backend / Classes / Module / AbstractFunctionModule.php
1 <?php
2 namespace TYPO3\CMS\Backend\Module;
3
4 /*
5 * This file is part of the TYPO3 CMS project.
6 *
7 * It is free software; you can redistribute it and/or modify it under
8 * the terms of the GNU General Public License, either version 2
9 * of the License, or any later version.
10 *
11 * For the full copyright and license information, please read the
12 * LICENSE.txt file that was distributed with this source code.
13 *
14 * The TYPO3 project - inspiring people to share!
15 */
16
17 use TYPO3\CMS\Backend\Template\DocumentTemplate;
18 use TYPO3\CMS\Backend\Utility\BackendUtility;
19 use TYPO3\CMS\Core\Authentication\BackendUserAuthentication;
20 use TYPO3\CMS\Core\Database\DatabaseConnection;
21 use TYPO3\CMS\Core\Utility\ArrayUtility;
22 use TYPO3\CMS\Core\Utility\GeneralUtility;
23 use TYPO3\CMS\Lang\LanguageService;
24
25 /**
26 * Parent class for 'Extension Objects' in backend modules.
27 *
28 * Used for 'submodules' to other modules. Also called 'Function menu modules'
29 * in \TYPO3\CMS\Core\Utility\ExtensionManagementUtility. And now its even called
30 * 'Extension Objects'. Or 'Module functions'. Wish we had just one name. Or a
31 * name at all...(?) Thank God its not so advanced when it works...
32 *
33 * In other words this class is used for backend modules which is not true
34 * backend modules appearing in the menu but rather adds themselves as a new
35 * entry in the function menu which typically exists for a backend
36 * module (like Web>Functions, Web>Info or Tools etc...)
37 * The magic that binds this together is stored in the global variable
38 * $TBE_MODULES_EXT where extensions wanting to connect a module based on
39 * this class to an existing backend module store configuration which consists
40 * of the classname, script-path and a label (title/name).
41 *
42 * For more information about this, please see the large example comment for the
43 * class \TYPO3\CMS\Backend\Module\BaseScriptClass. This will show the principle of a
44 * 'level-1' connection. The more advanced example - having two layers as it is done
45 * by the 'func_wizards' extension with the 'web_info' module - can be seen in the
46 * comment above.
47 *
48 * EXAMPLE: One level.
49 * This can be seen in the extension 'cms' where the info module have a
50 * function added. In 'ext_tables.php' this is done by this function call:
51 *
52 * \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::insertModuleFunction(
53 * 'web_info',
54 * \TYPO3\CMS\Frontend\Controller\PageInformationController::class,
55 * NULL,
56 * 'LLL:EXT:cms/locallang_tca.xlf:mod_tx_cms_webinfo_page'
57 * );
58 *
59 * EXAMPLE: Two levels.
60 * This is the advanced example. You can see it with the extension 'func_wizards'
61 * which is the first layer but then providing another layer for extensions to connect by.
62 * The key used in TBE_MODULES_EXT is normally 'function' (for the 'function menu')
63 * but the 'func_wizards' extension uses an alternative key for its configuration: 'wiz'.
64 * In the 'ext_tables.php' file of an extension ('wizard_crpages') which uses the
65 * framework provided by 'func_wizards' this looks like this:
66 *
67 * \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::insertModuleFunction(
68 * 'web_func',
69 * \TYPO3\CMS\WizardCrpages\Controller\CreatePagesWizardModuleFunctionController::class
70 * NULL,
71 * 'LLL:EXT:wizard_crpages/locallang.xlf:wiz_crMany',
72 * 'wiz'
73 * );
74 *
75 * But for this two-level thing to work it also requires that the parent
76 * module (the real backend module) supports it.
77 * This is the case for the modules web_func and web_info since they have two
78 * times inclusion sections in their index.php scripts. For example (from web_func):
79 *
80 * Make instance:
81 * $SOBE = GeneralUtility::makeInstance(\TYPO3\CMS\Func\Controller\PageFunctionsController::class);
82 * $SOBE->init();
83 *
84 * Anyways, the final interesting thing is to see what the framework
85 * "func_wizard" actually does:
86 *
87 * class WebFunctionWizardsBaseController extends \TYPO3\CMS\Backend\Module\AbstractFunctionModule {
88 * var $localLangFile = "locallang.xlf";
89 * var $function_key = "wiz";
90 * function init(&$pObj, $conf) {
91 * OK, handles ordinary init. This includes setting up the
92 * menu array with ->modMenu
93 * parent::init($pObj,$conf);
94 * $this->handleExternalFunctionValue();
95 * }
96 * }
97 *
98 * Notice that the handleExternalFunctionValue of this class
99 * is called and that the ->function_key internal var is set!
100 *
101 * The two level-2 sub-module "wizard_crpages" and "wizard_sortpages"
102 * are totally normal "submodules".
103 *
104 * @author Kasper Skårhøj <kasperYYYY@typo3.com>
105 * @see \TYPO3\CMS\Backend\Module\BaseScriptClass
106 * @see \TYPO3\CMS\FuncWizards\Controller\WebFunctionWizardsBaseController
107 * @see \TYPO3\CMS\WizardSortpages\View\SortPagesWizardModuleFunction
108 */
109 abstract class AbstractFunctionModule {
110
111 /**
112 * Contains a reference to the parent (calling) object (which is probably an instance of
113 * an extension class to \TYPO3\CMS\Backend\Module\BaseScriptClass
114 *
115 * @var BaseScriptClass
116 * @see init()
117 */
118 public $pObj;
119
120 /**
121 * @var BaseScriptClass
122 */
123 public $extObj = NULL;
124
125 /**
126 * Set to the directory name of this class file.
127 *
128 * @see init()
129 * @var string
130 */
131 public $thisPath = '';
132
133 /**
134 * Can be hardcoded to the name of a locallang.xlf file (from the same directory as the class file) to use/load
135 *
136 * @see incLocalLang()
137 * @var string
138 */
139 public $localLangFile = 'locallang.xlf';
140
141 /**
142 * Contains module configuration parts from TBE_MODULES_EXT if found
143 *
144 * @see handleExternalFunctionValue()
145 * @var array
146 */
147 public $extClassConf;
148
149 /**
150 * If this value is set it points to a key in the TBE_MODULES_EXT array (not on the top level..) where another classname/filepath/title can be defined for sub-subfunctions.
151 * This is a little hard to explain, so see it in action; it used in the extension 'func_wizards' in order to provide yet a layer of interfacing with the backend module.
152 * The extension 'func_wizards' has this description: 'Adds the 'Wizards' item to the function menu in Web>Func. This is just a framework for wizard extensions.' - so as you can see it is designed to allow further connectivity - 'level 2'
153 *
154 * @see handleExternalFunctionValue(), \TYPO3\CMS\FuncWizards\Controller\WebFunctionWizardsBaseController
155 * @var string
156 */
157 public $function_key = '';
158
159 /**
160 * Initialize the object
161 *
162 * @param BaseScriptClass $pObj A reference to the parent (calling) object
163 * @param array $conf The configuration set for this module - from global array TBE_MODULES_EXT
164 * @throws \RuntimeException
165 * @see \TYPO3\CMS\Backend\Module\BaseScriptClass::checkExtObj()
166 */
167 public function init(&$pObj, $conf) {
168 $this->pObj = $pObj;
169 // Path of this script:
170 $reflector = new \ReflectionObject($this);
171 $this->thisPath = dirname($reflector->getFilename());
172 if (!@is_dir($this->thisPath)) {
173 throw new \RuntimeException('TYPO3 Fatal Error: Could not find path for class ' . get_class($this), 1381164687);
174 }
175 // Local lang:
176 $this->incLocalLang();
177 // Setting MOD_MENU items as we need them for logging:
178 $this->pObj->MOD_MENU = array_merge($this->pObj->MOD_MENU, $this->modMenu());
179 }
180
181 /**
182 * If $this->function_key is set (which means there are two levels of object connectivity) then
183 * $this->extClassConf is loaded with the TBE_MODULES_EXT configuration for that sub-sub-module
184 *
185 * @return void
186 * @see $function_key, \TYPO3\CMS\FuncWizards\Controller\WebFunctionWizardsBaseController::init()
187 */
188 public function handleExternalFunctionValue() {
189 // Must clean first to make sure the correct key is set...
190 $this->pObj->MOD_SETTINGS = BackendUtility::getModuleData($this->pObj->MOD_MENU, GeneralUtility::_GP('SET'), $this->pObj->MCONF['name']);
191 if ($this->function_key) {
192 $this->extClassConf = $this->pObj->getExternalItemConfig($this->pObj->MCONF['name'], $this->function_key, $this->pObj->MOD_SETTINGS[$this->function_key]);
193 }
194 }
195
196 /**
197 * Including any locallang file configured and merging its content over
198 * the current global LOCAL_LANG array (which is EXPECTED to exist!!!)
199 *
200 * @return void
201 */
202 public function incLocalLang() {
203 if (
204 $this->localLangFile
205 && (
206 @is_file(($this->thisPath . '/' . $this->localLangFile))
207 || @is_file(($this->thisPath . '/' . substr($this->localLangFile, 0, -4) . '.xml'))
208 || @is_file(($this->thisPath . '/' . substr($this->localLangFile, 0, -4) . '.php'))
209 )
210 ) {
211 $LOCAL_LANG = $this->getLanguageService()->includeLLFile($this->thisPath . '/' . $this->localLangFile, FALSE);
212 if (is_array($LOCAL_LANG)) {
213 $GLOBALS['LOCAL_LANG'] = (array)$GLOBALS['LOCAL_LANG'];
214 ArrayUtility::mergeRecursiveWithOverrule($GLOBALS['LOCAL_LANG'], $LOCAL_LANG);
215 }
216 }
217 }
218
219 /**
220 * Same as \TYPO3\CMS\Backend\Module\BaseScriptClass::checkExtObj()
221 *
222 * @return void
223 * @see \TYPO3\CMS\Backend\Module\BaseScriptClass::checkExtObj()
224 */
225 public function checkExtObj() {
226 if (is_array($this->extClassConf) && $this->extClassConf['name']) {
227 $this->extObj = GeneralUtility::makeInstance($this->extClassConf['name']);
228 $this->extObj->init($this->pObj, $this->extClassConf);
229 // Re-write:
230 $this->pObj->MOD_SETTINGS = BackendUtility::getModuleData($this->pObj->MOD_MENU, GeneralUtility::_GP('SET'), $this->pObj->MCONF['name']);
231 }
232 }
233
234 /**
235 * Calls the main function inside ANOTHER sub-submodule which might exist.
236 *
237 * @return void
238 */
239 public function extObjContent() {
240 if (is_object($this->extObj)) {
241 return $this->extObj->main();
242 }
243 }
244
245 /**
246 * Dummy function - but is used to set up additional menu items for this submodule.
247 *
248 * @return array A MOD_MENU array which will be merged together with the one from the parent object
249 * @see init(), \TYPO3\CMS\Frontend\Controller\PageInformationController::modMenu()
250 */
251 public function modMenu() {
252 return array();
253 }
254
255 /**
256 * @return LanguageService
257 */
258 protected function getLanguageService() {
259 return $GLOBALS['LANG'];
260 }
261
262 /**
263 * @return BackendUserAuthentication
264 */
265 protected function getBackendUserAuthentication() {
266 return $GLOBALS['BE_USER'];
267 }
268
269 /**
270 * @return DocumentTemplate
271 */
272 protected function getDocumentTemplate() {
273 return $GLOBALS['TBE_TEMPLATE'];
274 }
275
276 /**
277 * @return string
278 */
279 protected function getBackPath() {
280 return $GLOBALS['BACK_PATH'];
281 }
282
283 /**
284 * @return DatabaseConnection
285 */
286 protected function getDatabaseConnection() {
287 return $GLOBALS['TYPO3_DB'];
288 }
289
290 }