[TASK] The Number of The Workspace
[Packages/TYPO3.CMS.git] / typo3 / sysext / lowlevel / README.rst
1 INTRODUCTION
2 ============
3
4 For various reasons your TYPO3 installation may over time accumulate data with integrity problems or data you wish
5 to delete completely. For instance, why keep old versions of published content? Keep that in your backup - don't load
6 your running website with that overhead!
7
8 Or what about deleted records? Why not flush them - they also fill up your database and filesystem and most likely you
9 can rely on your backups in case of an emergency recovery?
10
11 Also, relations between records and files inside TYPO3 may be lost over time for various reasons.
12
13 If your website runs as it should such "integrity problems" are mostly easy to automatically repair by simply removing
14 the references pointing to a missing record or file.
15
16 However, it might also be "soft references" from eg. typolinks (``<link 123>...</link>``) or a file references in a
17 TypoScript template (``something.file = fileadmin/template/miss_me.jpg``) which are missing. Those cannot be automatically
18 repaired but the cleanup script incorporates warnings that will tell you about these problems if they exist and you
19 can manually fix them.
20
21 This script provides solutions to these problems by offering an array of tools that can analyze your TYPO3 installation
22 for various problems and in some cases offer fixes for them. Also third party extensions can plug additional
23 functionality into the script.
24
25
26
27 PREPARATIONS
28 ============
29
30 THERE IS ABSOLUTELY NO WARRANTY associated with this script! It is completely on your OWN RISK that you run it.
31 It may cause accidental data loss due to software bugs or circumstances that it does not know about yet - or data
32 loss might happen due to misuse!
33
34 ALWAYS make a complete backup of your website! That means:
35
36 * Dump the complete database to an SQL file. This can usually be done from the command line like this::
37
38         mysqldump [database name] -u [database user] -p --add-drop-table > ./mywebsite.sql
39
40 * Save all files in the webroot of your site. I usually do this from the command line like this::
41
42         tar czf ./mywebsite.tgz [webroot directory of your site]
43
44 Before running with the ``--AUTOFIX`` option ALWAYS make sure to add the parameter ``--dryrun`` to see what would be fixed.
45
46 Also, NEVER BYPASS the REFERENCE INDEX CHECK if ``--AUTOFIX`` is used for those tools which require a clean reference index.
47
48 It could be a good idea to run a myisamchk on your database just to make sure MySQL has everything pulled together right.
49
50 Something like this will do::
51
52         myisamchk [path_to_mysql_databases]/[database_name]/*.MYI -s -r
53
54
55
56 RUNNING the SCRIPT
57 ==================
58
59 The "[base command]" is::
60
61         [typo3_site_directory]/typo3/cli_dispatch.phpsh lowlevel_cleaner
62
63 Try this first. If it all works out you should see a help-screen. Otherwise there will be instructions about what to do.
64 For instance, you will have to create a backend user, "_cli_lowlevel", with any random password since you never need
65 to log in with the user. Never mind permissions, they are not important since this script will force the user to run
66 as "admin" in "Live" workspace.
67
68 You can use the script entirely by following the help screens. However, through this document you get some idea about
69 the best order of events since they may affect each other.
70
71 For each of the tools in the test you can see a help screen by running::
72
73         [base command] [toolkey]
74
75 Example with the tool "orphan_records"::
76
77         [typo3_site_directory]/typo3/cli_dispatch.phpsh lowlevel_cleaner orphan_records
78
79
80
81 SUGGESTED ORDER OF CLEAN UP
82 ---------------------------
83
84 The suggested order below assumes that you are interested in running all these tests. Maybe you are not! So you should
85 check the description of each one and if there is any of the tests you wish not to run, just leave it out.
86
87 It kind of gets simpler that way since the complexity mostly is when you wish to run all tests successively in which
88 case there is an optimal order that ensures you don't have to run the tests all over again.
89
90 - ``[base command] orphan_records -r --AUTOFIX```
91
92   - As a beginning, get all orphaned records out of the system since you probably want to. Since orphan records may
93     keep some missing relations from being detected it's a good idea to get them out immediately.
94
95 - ``[base command] versions -r --AUTOFIX``
96
97   - Flush all published versions now if you like. Published versions may also keep references to records which could
98     affect other tests, hence do it now if you want to.
99
100 - ``[base command] tx_templavoila_unusedce -r --AUTOFIX``
101
102   - (Assumes usage of "TemplaVoila" extension!)
103   - This should be done AFTER flushing published versions (since versions could reference elements that might be
104     safe to remove)
105   - This should be done BEFORE flushing deleted versions (since this tool will create new deleted records), given
106     that you want to completely flush them of course.
107   - You should run it over again until there remains no more unused elements. You need to do this because deleting
108     elements might generate new unused elements if the now-deleted elements had references.
109
110 - ``[base command] double_files -r --AUTOFIX```
111
112   - Fix any files referenced twice or more before you delete records (which could potentially delete a file that is
113     referenced by another file).
114
115 - ``[base command] deleted -r --AUTOFIX``
116
117   - Flush deleted records. As a rule of thumb, tools that create deleted records should be run before this one so
118     the deleted records they create are also flushed (if you like to of course)
119
120 - ``[base command] missing_relations -r --AUTOFIX``
121
122   - Remove missing relations at this point.
123   - If you get an error like this; "\TYPO3\CMS\Core\Database\ReferenceIndex::setReferenceValue(): ERROR: No reference
124     record with hash="132ddb399c0b15593f0d95a58159439f" was found!" just run the test again until no errors occur.
125     The reason is that another fixed reference in the same record and field changed the reference index hash. Running
126     the test again will find the new hash string which will then work for you.
127
128 - ``[base command] cleanflexform -r --AUTOFIX``
129
130   - After the "deleted" tool since we cannot clean-up deleted records and to make sure nothing unimportant
131     is cleaned up.
132
133 - ``[base command] rte_images -r --AUTOFIX``
134
135   - Will be affected by flushed deleted records, versions and orphans so must be run after any of those tests.
136
137
138
139 EXECUTED ANYTIME
140 ----------------
141
142 These can be executed anytime, however you should wait till all deleted records and versions are flushed so you don't
143 waste system resources on fixing deleted records.
144
145 ::
146
147         [base command] missing_files -r --AUTOFIX
148         [base command] lost_files -r --AUTOFIX
149
150
151
152 NIGHTLY REPORTS OF PROBLEMS IN THE SYSTEM
153 -----------------------------------------
154
155 If you wish to scan your TYPO3 installations for problems with a cronjob or so, a shell script that outputs a
156 report could look like this::
157
158         #!/bin/sh
159         /[WEBROOT_ABS_PATH]/typo3/cli_dispatch.phpsh lowlevel_cleaner orphan_records -r -v 2 -s
160         /[WEBROOT_ABS_PATH]/typo3/cli_dispatch.phpsh lowlevel_cleaner versions -r -v 2 -s
161         /[WEBROOT_ABS_PATH]/typo3/cli_dispatch.phpsh lowlevel_cleaner tx_templavoila_unusedce -r --refindex update -v 2 -s
162         /[WEBROOT_ABS_PATH]/typo3/cli_dispatch.phpsh lowlevel_cleaner double_files -r --refindex update -v 2 -s
163         /[WEBROOT_ABS_PATH]/typo3/cli_dispatch.phpsh lowlevel_cleaner deleted -r -v 1 -s
164         /[WEBROOT_ABS_PATH]/typo3/cli_dispatch.phpsh lowlevel_cleaner missing_relations -r --refindex update -v 2 -s
165         /[WEBROOT_ABS_PATH]/typo3/cli_dispatch.phpsh lowlevel_cleaner cleanflexform -r -v 2 -s
166         /[WEBROOT_ABS_PATH]/typo3/cli_dispatch.phpsh lowlevel_cleaner rte_images -r --refindex update -v 2 -s
167         /[WEBROOT_ABS_PATH]/typo3/cli_dispatch.phpsh lowlevel_cleaner missing_files -r --refindex update -v 2 -s
168         /[WEBROOT_ABS_PATH]/typo3/cli_dispatch.phpsh lowlevel_cleaner lost_files -r --refindex update -v 2 -s
169
170
171 You may wish to set the verbosity level (``-v``) to "3" instead of "2" as in the case above, depending on how important
172 you consider the warnings.
173
174 You might also wish to disable tests like "deleted" which would report deleted records - something that might not
175 warrant a warning, frankly speaking...
176
177 If you append ``--AUTOFIX --YES`` to each test it will actually perform clean up operations after checking, however it is
178 NOT RECOMMENDED to do that as a nightly cron-job! In addition you should study what repair operations each test does
179 to your system before using it!
180
181
182 EXAMPLE SCRIPT FOR CHECKING YOUR INSTALLATION
183 ---------------------------------------------
184
185 ::
186
187     #!/bin/sh
188     ./cli_dispatch.phpsh lowlevel_cleaner missing_files -r -v 2 -s --refindex check
189     ./cli_dispatch.phpsh lowlevel_cleaner double_files -r -v 2 -s --refindex ignore
190     ./cli_dispatch.phpsh lowlevel_cleaner lost_files -r -v 2 -s --refindex ignore
191     ./cli_dispatch.phpsh lowlevel_cleaner orphan_records -r -v 2 -s
192     ./cli_dispatch.phpsh lowlevel_cleaner versions -r -v 2 -s
193     ./cli_dispatch.phpsh lowlevel_cleaner deleted -r -v 1 -s
194     ./cli_dispatch.phpsh lowlevel_cleaner missing_relations -r -v 2 -s --refindex ignore
195     ./cli_dispatch.phpsh lowlevel_cleaner cleanflexform -r -v 2 -s
196     ./cli_dispatch.phpsh lowlevel_cleaner rte_images -r -v 2 -s --refindex ignore
197
198
199 EXAMPLE SCRIPT FOR CLEANING YOUR INSTALLATION
200 ---------------------------------------------
201
202 ::
203
204     #!/bin/sh
205     ./cli_dispatch.phpsh lowlevel_cleaner missing_files -r -v 2 -s --AUTOFIX --YES --refindex update
206     ./cli_dispatch.phpsh lowlevel_cleaner double_files -r -v 2 -s --AUTOFIX --YES --refindex update
207     ./cli_dispatch.phpsh lowlevel_cleaner lost_files -r -v 2 -s --AUTOFIX --YES --refindex update
208     ./cli_dispatch.phpsh lowlevel_cleaner orphan_records -r -v 2 -s --AUTOFIX --YES
209     ./cli_dispatch.phpsh lowlevel_cleaner versions -r -v 2 -s --AUTOFIX --YES
210     ./cli_dispatch.phpsh lowlevel_cleaner deleted -r -v 1 -s --AUTOFIX --YES
211     ./cli_dispatch.phpsh lowlevel_cleaner missing_relations -r -v 2 -s --AUTOFIX --YES --refindex update
212     ./cli_dispatch.phpsh lowlevel_cleaner cleanflexform -r -v 2 -s --AUTOFIX --YES
213     ./cli_dispatch.phpsh lowlevel_cleaner rte_images -r -v 2 -s --refindex ignore
214
215
216 ADDING YOUR OWN TOOLS TO THE TEST
217 =================================
218
219 You can plug additional analysis tools into the cleaner script. All you need to do is create a class with a few specific
220 functions and configure the cleaner to use it. You should encapsulate your class in an extension (as always).
221
222 In the steps below, substitute these strings with corresponding values:
223
224 - YOUREXTKEYNOUS = Your extension key, no underscores!
225 - YOUREXTKEY = Your full extension key
226 - CLEANERTOOL = Name prefix for your cleaner module
227
228 STEP1: Set up your class as a tool for the cleaner
229 --------------------------------------------------
230
231 - In the :file:`ext_localconf.php` file of your extension, add this::
232
233         $TYPO3_CONF_VARS['EXTCONF']['lowlevel']['cleanerModules']['tx_YOUREXTKEYNOUS_CLEANERTOOL'] =
234                 array('EXT:YOUREXTKEY/class.YOUREXTKEYNOUS_CLEANERTOOL.php:tx_YOUREXTKEYNOUS_CLEANERTOOL');
235
236 - In your extension, create a PHP file ``YOUREXTKEY/class.YOUREXTKEYNOUS_CLEANERTOOL.php``
237
238 - Finally, make sure to "Clear cache in typo3conf/" after having done this!
239
240 STEP2: Build your cleaner class
241 -------------------------------
242
243 - In the new PHP file, create a class with these basic functions::
244
245         class YOUREXTKEYNOUS_CLEANERTOOL extends \TYPO3\CMS\Lowlevel\CleanerCommand {
246
247                 /**
248                  * Constructor
249                  */
250                 public function __construct() {
251                         parent::__construct()();
252
253                         // Setting up help:
254                         $this->cli_options[] = array('--option1 value', 'Description...');
255                         $this->cli_options[] = array('--option2 value', 'Description...');
256
257                         $this->cli_help['name'] = 'YOUREXTKEYNOUS_CLEANERTOOL -- DESCRIPTION HERE!';
258                         $this->cli_help['description'] = trim('LONG DESCRIPTION HERE');
259
260                         $this->cli_help['examples'] = 'EXAMPLES HERE';
261                 }
262
263                 /**
264                  * Analyze and return result
265                  */
266                 public function main() {
267
268                         // Initialize result array:
269                         $resultArray = array(
270                                 'message' => $this->cli_help['name'].
271                                                         LF.LF.
272                                                         $this->cli_help['description'],
273                                 'headers' => array(
274                                         'SOME_ANALYSIS_1' => array('HEADER','DESCRIPTION',VERBOSITY_LEVEL 0-3),
275                                         'SOME_ANALYSIS_2' => array('HEADER','DESCRIPTION',VERBOSITY_LEVEL 0-3),
276                                         'SOME_ANALYSIS_...' => array('HEADER','DESCRIPTION',VERBOSITY_LEVEL 0-3),
277                                 ),
278                                 'SOME_ANALYSIS_1' => array(),
279                                 'SOME_ANALYSIS_2' => array(),
280                                 'SOME_ANALYSIS_...' => array(),
281                         );
282
283                         // HERE you run your analysis and put result into
284                         // $resultArray['SOME_ANALYSIS_1']
285                         // $resultArray['SOME_ANALYSIS_2']
286                         // $resultArray['SOME_ANALYSIS_...']
287
288                         return $resultArray;
289                 }
290
291                 /**
292                  * Mandatory autofix function
293                  */
294                 public function main_autoFix($resultArray) {
295                         // HERE you traverse the result array and AUTOFIX what can be fixed
296                         // Make sure to use $this->cli_noExecutionCheck() - see examples from bundled tools
297                 }
298         }
299
300 STEP3: Develop your tool to do something
301 ----------------------------------------
302
303 - You should now be able to see your tool appear in the list of tools and you should see output from it when you
304   choose it.
305 - Make sure to study the bundled tools from EXT:lowlevel/. Try to deliver the same high quality of documentation and
306   coding style from there. In particular how the constructor is used to set help-message information.
307 - Also, take a look at ``\TYPO3\CMS\Backend\Clipboard\Clipboard`` which is the very base class - you can use the functions
308   in there in your script.