Flow Installation Hints
Just leave your hints and comment on existing ones. For the Flow releases we will go through them and integrate them into the installation instructions / manual where it makes sense.
- 1 Database related
- 2 "Maximum function nesting level reached" fatal error
- 3 Memory exhausted during unit tests
- 4 Usernames with "." don't work with workspace handling in BE editing
- 5 Suhosin related notes
- 6 Running on Windows OS's
The default character set resp. collation should be, for MySql, utf8_unicode_ci. This should be applied to the database itself (the schema) in order to serve as sane defaults for new tables being set up with no explicit collation directions.
If something when wrong at a stage during the lifetime, you might end up with error messages like
Error Code: 1215. Cannot add foreign key constraint
This is a sign that the columns you intend to wire together have a different type, charset or collation. A different collation is even considered if one collation is inherited from the table, and one is defined explicitly!
In order to clean that up if you stumble upon these cases, follow the following steps:
Caution: We will set the character set to UTF-8, however, if your database is currently defined as something else, like latin-1, the content will be messed up because unlike the name suggests, the content itself it not converted.
- Set/correct the database's character set and collation:
ALTER DATABASE `your_database` COLLATE 'utf8_unicode_ci';
- Fetch the tables in this database which derive from the intended collation using the following SQL:
SELECT * FROM information_schema.tables WHERE TABLE_SCHEMA = 'your_database' AND TABLE_COLLATION != 'utf8_unicode_ci'
- Examine the column TABLE_NAME in the result set, these are the tables where the collation does not match. In order to clean that up, you have to build a stack of SQL commands for each table name, you might do that in your favorite column-able editor or spreadsheet application:
ALTER TABLE `one_table` CONVERT TO CHARACTER SET utf8 COLLATE 'utf8_unicode_ci';
This will "recursively" (down to each column of that table) apply the appropriate definition.
Having done this, you should be able to create your foreign key constraints.
"Maximum function nesting level reached" fatal error
In case you get a fatal error message saying something like "Maximum function nesting level of '100' reached, aborting!", check your php.ini-file for settings regarding "xdebug" and modify/add a line xdebug.max_nesting_level = 500 (suggested value; the blog example requires at least a value of about 150).
Memory exhausted during unit tests
If unit tests do not fully complete, it may be neccessary to extend the memory limit. Modify your php.ini and set it to at least 256M memory_limit = 256M
Usernames with "." don't work with workspace handling in BE editing
There is currently an issue with usernames containing a dot in it while trying to edit a page in the "content" module of the backend. TYPO3 is adding a "@user-USERNAME.html" to the websites URI and if you have a "." in your username (like "@user-foo.bar.html") you'll get a 404 message displayed. See #27991
Caution: Suhosin provides security to your PHP environment. Only make changes to the configuration if you know and are aware of what you are doing and what influences these changes have.
General hints when using Suhosin
When using Suhosin it's likely you sometimes experience some unexpected behavior when developing with TYPO3 Flow. If so, it's always a good idea also to check /var/log/syslog because in default "configuration" (http://www.hardened-php.net/suhosin/configuration.html#suhosin.log.syslog) it's set to log Alerts. When suhosin prevents any action, it's logged there. Such an alert may look like:
ALERT - configured GET variable value length limit exceeded - dropped variable '__widgetContext'
An additional help may be setting the "filter action" (http://www.hardened-php.net/suhosin/configuration.html#suhosin.filter.action) to a value like 400 in order for you directly seeing that something went wrong.
Unit tests abort with a segfault
An additional abort may occur during unit tests in the combination of php with suhosin patch. A whitelist entry has to be added in this case. Check your suhosin.ini-file and modify/add a line suhosin.executor.include.whitelist = vfs://
Unexpected behavior with serialized objects in request arguments
Protected class's member names are prepended with an asterisk wrapped in null-bytes (www.php.net/manual/en/function.serialize.php). The suhosin-extension removes the complete variable if such a null-byte occurs. Check your suhosin.ini-file and modify/add the lines:
suhosin.get.disallow_nul = Off suhosin.post.disallow_nul = Off
Some additional information: due to documentation that Off should work; at this author's case it didn't and setting to 0 (zero) was necessary. Also check if suhosin.request.disallow_nul must also be set.
Exceeding GET variable value length
In TYPO3 Flow, sometimes serialized objects are transferred via GET (e.g. Fluid widgets). This may exceed Suhosin's "default configuration" (http://www.hardened-php.net/suhosin/configuration.html#suhosin.get.max_value_length), so you might want to set:
suhosin.get.max_value_length = 1024
Running on Windows OS's
If you haven't installed PHP to the default location (specified by the *PHP_BINDIR* constant which usually points to *C:/php*), you'll have to specify the path to your php binary explicitly:
Edit the file *…/Configuration/Settings.yaml* and set/uncomment the TYPO3.Flow.core.phpBinaryPathAndFilename directive. Please use single forward slashes, an uppercase drive letter in any case and avoid typical special characters like ~ or () (see https://forge.typo3.org/issues/35916 for more information on this). The whole setting should read e.g.:
TYPO3: Flow: core: phpBinaryPathAndFilename: 'C:/Programs/Zend/ZendServer/bin/php.exe'
If nothing works, it may be a good idea to add the executable to your PATH (if not there anyways) and just set this directive to php or php.exe.
TYPO3 Flow uses symbolic links to make public resources available to the browser without needing to copy them to an accessible directory. Unfortunately Windows usually requires a user with privileged rights for that, so you might get errors like the following when trying to create a symlink via PHP:
Warning: symlink(): Cannot create symlink, error code(1314)
To get the creation of symbolic links work (only Windows Vista and above), open the local policy editor secpol.msc and locate Security Settings > Local Policies > User Rights Management > Create symbolic links and grant this permission to the appropriate group. I myself chose "Everybody", because there is no reason why a non-admin should not be allowed to create symbolic links IF he has write permission anyway. (the German description is Sicherheitseinstellungen > Lokale Richtlinien > Zuweisen von Benutzerrechten > Erstellen symbolischer Verknüpfungen).
- Rebooting* then is a must (additionally, see https://forge.typo3.org/issues/35935 for additional information).
- Note:* Symlinks are created on the first run and if you install new packages with public resources. If you can't get the above working, you can also run the command prompt *as administrator* and execute the flow batch once:
If this is not an option for you, creation of symlinks can be replaced with copying by changing the strategy:
TYPO3: Flow: resource: publishing: fileSystem: mirrorMode: copy
Command Line Tool
To run the flow command line interface, make sure the directory of your php binary is in the *path environment variable*. You can add it to the path by executing:
An alternative solution is to edit the path in the *flow.bat* script in the root directory. Afterwards you can run the CLI:
> CD path/to/your/flow/installation > flow.bat help
- Note:* If you get an error because PHP could not create the required symlinks, follow the steps mentioned above
If you want to clone TYPO3 Flow to a Windows system, Git needs to be configured so it does not convert new line characters. This is done with the setting core.autocrlf and should be set to "input":
git config --global core.autocrlf input
If you don't do this you might run into errors like "Uncaught Exception The ... annotation for ... seems to be invalid."