docs/migration/wcf21/php.md

   1 # WCF 2.1.x - PHP
   2
   3 ## Message Processing
   4
   5 WoltLab Suite 3.0 finally made the transition from raw bbcode to bbcode-flavored HTML, with many new features related to message processing being added. This change impacts both message validation and storing, requiring slightly different APIs to get the job done.
   6
   7 ### Input Processing for Storage
   8
   9 The returned HTML is an intermediate representation with a maximum of meta data embedded into it, designed to be stored in the database. Some bbcodes are replaced during this process, for example `[b]…[/b]` becomes `<strong>…</strong>`, while others are converted into a metacode tag for later processing.
  10
  11 ```php
  12 <?php
  13 $processor = new \wcf\system\html\input\HtmlInputProcessor();
  14 $processor->process($message, $messageObjectType, $messageObjectID);
  15 $html = $processor->getHtml();
  16 ```
  17
  18 The `$messageObjectID` can be zero if the element did not exist before, but it should be non-zero when saving an edited message.
  19
  20 ### Embedded Objects
  21
  22 Embedded objects need to be registered after saving the message, but once again you can use the processor instance to do the job.
  23
  24 ```php
  25 <?php
  26 $processor = new \wcf\system\html\input\HtmlInputProcessor();
  27 $processor->process($message, $messageObjectType, $messageObjectID);
  28 $html = $processor->getHtml();
  29
  30 // at this point the message is saved to database and the created object
  31 // `$example` is a `DatabaseObject` with the id column `$exampleID`
  32
  33 $processor->setObjectID($example->exampleID);
  34 if (\wcf\system\message\embedded\object\MessageEmbeddedObjectManager::getInstance()->registerObjects($processor)) {
  35     // there is at least one embedded object, this is also the point at which you
  36     // would set `hasEmbeddedObjects` to true (if implemented by your type)
  37     (new \wcf\data\example\ExampleEditor($example))->update(['hasEmbeddedObjects' => 1]);
  38 }
  39 ```
  40
  41 ### Rendering the Message
  42
  43 The output processor will parse the intermediate HTML and finalize the output for display. This step is highly dynamic and allows for bbcode evaluation and contextual output based on the viewer's permissions.
  44
  45 ```php
  46 <?php
  47 $processor = new \wcf\system\html\output\HtmlOutputProcessor();
  48 $processor->process($html, $messageObjectType, $messageObjectID);
  49 $renderedHtml = $processor->getHtml();
  50 ```
  51
  52 #### Simplified Output
  53
  54 At some point there can be the need of a simplified output HTML that includes only basic HTML formatting and reduces more sophisticated bbcodes into a simpler representation.
  55
  56 ```php
  57 <?php
  58 $processor = new \wcf\system\html\output\HtmlOutputProcessor();
  59 $processor->setOutputType('text/simplified-html');
  60 $processor->process(…);
  61 ```
  62
  63 #### Plaintext Output
  64
  65 The `text/plain` output type will strip down the simplified HTML into pure text, suitable for text-only output such as the plaintext representation of an email.
  66
  67 ```php
  68 <?php
  69 $processor = new \wcf\system\html\output\HtmlOutputProcessor();
  70 $processor->setOutputType('text/plain');
  71 $processor->process(…);
  72 ```
  73
  74 ### Rebuilding Data
  75
  76 #### Converting from BBCode
  77
  78 !!! warning "Enabling message conversion for HTML messages is undefined and yields unexpected results."
  79
  80 Legacy message that still use raw bbcodes must be converted to be properly parsed by the html processors. This process is enabled by setting the fourth parameter of `process()` to `true`.
  81
  82 ```php
  83 <?php
  84 $processor = new \wcf\system\html\input\HtmlInputProcessor();
  85 $processor->process($html, $messageObjectType, $messageObjectID, true);
  86 $renderedHtml = $processor->getHtml();
  87 ```
  88
  89 #### Extracting Embedded Objects
  90
  91 The `process()` method of the input processor is quite expensive, as it runs through the full message validation including the invocation of HTMLPurifier. This is perfectly fine when dealing with single messages, but when you're handling messages in bulk to extract their embedded objects, you're better of with `processEmbeddedContent()`. This method deconstructs the message, but skips all validation and expects the input to be perfectly valid, that is the output of a previous run of `process()` saved to storage.
  92
  93 ```php
  94 <?php
  95 $processor = new \wcf\system\html\input\HtmlInputProcessor();
  96 $processor->processEmbeddedContent($html, $messageObjectType, $messageObjectID);
  97
  98 // invoke `MessageEmbeddedObjectManager::registerObjects` here
  99 ```
 100
 101 ## Breadcrumbs / Page Location
 102
 103 !!! warning "Breadcrumbs used to be added left to right, but parent locations are added from the bottom to the top, starting with the first ancestor and going upwards. In most cases you simply need to reverse the order."
 104
 105 Breadcrumbs used to be a lose collection of arbitrary links, but are now represented by actual page objects and the control has shifted over to the `PageLocationManager`.
 106
 107 ```php
 108 <?php
 109 // before
 110 \wcf\system\WCF::getBreadcrumbs()->add(new \wcf\system\breadcrumb\Breadcrumb('title', 'link'));
 111
 112 // after
 113 \wcf\system\page\PageLocationManager::getInstance()->addParentLocation($pageIdentifier, $pageObjectID, $object);
 114 ```
 115
 116 ## Pages and Forms
 117
 118 The property `$activeMenuItem` has been deprecated for the front end and is no longer evaluated at runtime. Recognition of the active item is entirely based around the invoked controller class name and its definition in the page table. You need to properly [register your pages](../../package/pip/page.md) for this feature to work.
 119
 120 ## Search
 121
 122 ### ISearchableObjectType
 123
 124 Added the `setLocation()` method that is used to set the current page location based on the search result.
 125
 126 ### SearchIndexManager
 127
 128 The methods `SearchIndexManager::add()` and `SearchIndexManager::update()` have been deprecated and forward their call to the new method `SearchIndexManager::set()`.