docs/migration/wsc53/php.md

   1 # Migrating from WSC 5.3 - PHP
   2
   3 ## Minimum requirements
   4
   5 The minimum requirements have been increased to the following:
   6
   7 - **PHP:** 7.2.24
   8 - **MySQL:** 5.7.31 or 8.0.19
   9 - **MariaDB:** 10.1.44
  10
  11 Most notably PHP 7.2 contains usable support for scalar types by the addition of nullable types in PHP 7.1 and parameter type widening in PHP 7.2.
  12
  13 It is recommended to make use of scalar types and other newly introduced features whereever possible.
  14 Please refer to the PHP documentation for details.
  15
  16 ## Flood Control
  17
  18 To prevent users from creating massive amounts of contents in short periods of time, i.e., spam, existing systems already use flood control mechanisms to limit the amount of contents created within a certain period of time.
  19 With WoltLab Suite 5.4, we have added a general API that manages such rate limiting.
  20 Leveraging this API is easily done.
  21
  22 1. Register an object type for the definition `com.woltlab.wcf.floodControl`: `com.example.foo.myContent`.
  23 2. Whenever the active user creates content of this type, call
  24     ```php
  25     FloodControl::getInstance()->registerContent('com.example.foo.myContent');
  26     ```
  27     You should only call this method if the user creates the content themselves.
  28     If the content is automatically created by the system, for example when copying / duplicating existing content, no activity should be registered.
  29 3. To check the last time when the active user created content of the relevant type, use
  30     ```php
  31     FloodControl::getInstance()->getLastTime('com.example.foo.myContent');
  32     ```
  33     If you want to limit the number of content items created within a certain period of time, for example within one day, use
  34     ```php
  35     $data = FloodControl::getInstance()->countContent('com.example.foo.myContent', new \DateInterval('P1D'));
  36     // number of content items created within the last day
  37     $count = $data['count'];
  38     // timestamp when the earliest content item was created within the last day
  39     $earliestTime = $data['earliestTime'];
  40     ```
  41     The method also returns `earliestTime` so that you can tell the user in the error message when they are able again to create new content of the relevant type.
  42
  43     !!! info "Flood control entries are only stored for 31 days and older entries are cleaned up daily."
  44
  45 The previously mentioned methods of `FloodControl` use the active user and the current timestamp as reference point.
  46 `FloodControl` also provides methods to register content or check flood control for other registered users or for guests via their IP address.
  47 For further details on these methods, please refer to the [documentation in the FloodControl class](https://github.com/WoltLab/WCF/blob/master/wcfsetup/install/files/lib/system/flood/FloodControl.class.php).
  48
  49 !!! warning "Do not interact directly with the flood control database table but only via the `FloodControl` class!"
  50
  51 ## DatabasePackageInstallationPlugin
  52
  53 `DatabasePackageInstallationPlugin` is a new idempotent package installation plugin (thus it is available in the sync function in the devtools) to update the database schema using the PHP-based database API.
  54 `DatabasePackageInstallationPlugin` is similar to `ScriptPackageInstallationPlugin` by requiring a PHP script that is included during the execution of the script.
  55 The script is expected to return an array of `DatabaseTable` objects representing the schema changes so that in contrast to using `ScriptPackageInstallationPlugin`, no `DatabaseTableChangeProcessor` object has to be created.
  56 The PHP file must be located in the `acp/database/` directory for the devtools sync function to recognize the file.
  57
  58 ## PHP Database API
  59
  60 The PHP API to add and change database tables during package installations and updates in the `wcf\system\database\table` namespace now also supports renaming existing table columns with the new `IDatabaseTableColumn::renameTo()` method:
  61
  62 ```php
  63 PartialDatabaseTable::create('wcf1_test')
  64         ->columns([
  65                 NotNullInt10DatabaseTableColumn::create('oldName')
  66                         ->renameTo('newName')
  67         ]);
  68 ```
  69
  70 !!! info "Like with every change to existing database tables, packages can only rename columns that they installed."
  71
  72 ## Captcha
  73
  74 The reCAPTCHA v1 implementation was completely removed.
  75 This includes the `\wcf\system\recaptcha\RecaptchaHandler` class (not to be confused with the one in the `captcha` namespace).
  76
  77 The reCAPTCHA v1 endpoints have already been turned off by Google and always return a HTTP 404.
  78 Thus the implementation was completely non-functional even before this change.
  79
  80 See [WoltLab/WCF#3781](https://github.com/WoltLab/WCF/pull/3781) for details.
  81
  82 ## Search
  83
  84 The generic implementation in the `AbstractSearchEngine::parseSearchQuery()` method was dangerous, because it did not have knowledge about the search engine’s specifics.
  85 The implementation was completely removed: `AbstractSearchEngine::parseSearchQuery()` now always throws a `\BadMethodCallException`.
  86
  87 If you implemented a custom search engine and relied on this method, you can inline the previous implementation to preserve existing behavior.
  88 You should take the time to verify the rewritten queries against the manual of the search engine to make sure it cannot generate malformed queries or security issues.
  89
  90 See [WoltLab/WCF#3815](https://github.com/WoltLab/WCF/issues/3815) for details.
  91
  92 ## Styles
  93
  94 The `StyleCompiler` class is marked `final` now.
  95 The internal SCSS compiler object being stored in the `$compiler` property was a design issue that leaked compiler state across multiple compiled styles, possibly causing misgenerated stylesheets.
  96 As the removal of the `$compiler` property effectively broke compatibility within the `StyleCompiler` and as the `StyleCompiler` never was meant to be extended, it was marked final.
  97
  98 See [WoltLab/WCF#3929](https://github.com/WoltLab/WCF/pull/3929) for details.
  99
 100 ## Tags
 101
 102 Use of the `wcf1_tag_to_object.languageID` column is deprecated.
 103 The `languageID` column is redundant, because its value can be derived from the `tagID`.
 104 With WoltLab Suite 5.4, it will no longer be part of any indices, allowing more efficient index usage in the general case.
 105
 106 If you need to filter the contents of `wcf1_tag_to_object` by language, you should perform an `INNER JOIN wcf1_tag tag ON tag.tagID = tag_to_object.tagID` and filter on `wcf1_tag.languageID`.
 107
 108 See [WoltLab/WCF#3904](https://github.com/WoltLab/WCF/pull/3904) for details.
 109
 110 ## Avatars
 111
 112 The `ISafeFormatAvatar` interface was added to properly support fallback image types for use in emails.
 113 If your custom `IUserAvatar` implementation supports image types without broad support (i.e. anything other than PNG, JPEG, and GIF), then you should implement the `ISafeFormatAvatar` interface to return a fallback PNG, JPEG, or GIF image.
 114
 115 See [WoltLab/WCF#4001](https://github.com/WoltLab/WCF/pull/4001) for details.