### Example install.sql Content

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/sql.md

This is an example of the content expected in an install.sql file for the SQL package installation plugin.

```sql
CREATE TABLE wcf1_test (
	id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
	name VARCHAR(255) NOT NULL
);
```

--------------------------------

### Example Style Instruction in package.xml

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/style.md

Use this instruction type in your package.xml to specify the relative path to the style archive that should be installed.

```xml
<instruction type="style">style.tgz</instruction>
```

--------------------------------

### Example Smiley XML Configuration

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/smiley.md

Example of how to configure a smiley in the smiley.xml file for package installation. Ensure the path is relative to the WoltLab Suite Core root and files are installed via the file PIP.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<smiley name="smile">
    <title>Smile</title>
    <path>smile.png</path>
    <path2x>smile@2x.png</path2x>
    <aliases>:) ;)</aliases>
    <showorder>1</showorder>
</smiley>
```

--------------------------------

### Example package.xml Structure

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/package-xml.md

This is a basic example of a package.xml file, illustrating its root structure and essential elements.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<package name="com.example.simple" xmlns="http://www.woltlab.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.woltlab.com/package/1.0/package.xsd">
	<packageinformation>
		<packagename language="en">Simple Package</packagename>
		<packagename language="de">Einfaches Paket</packagename>
		<packagedescription language="en">A simple example package.</packagedescription>
		<version>1.0.0</version>
		<date>2023-01-01</date>
		<packageurl>https://example.com/packages/simple</packageurl>
		<license language="en">MIT License</license>
	</packageinformation>
	<authorinformation>
		<author>Example Author</author>
		<authorurl>https://example.com</authorurl>
	</authorinformation>
	<requiredpackages>
		<requiredpackage minversion="2.7.5" file="requirements/com.example.foo.tar">com.example.foo</requiredpackage>
	</requiredpackages>
	<optionalpackages>
		<optionalpackage file="optionals/com.example.bar.tar">com.example.bar</optionalpackage>
	</optionalpackages>
	<excludedpackages>
		<excludedpackage version="7.0.0 Alpha 1">com.woltlab.wcf</excludedpackage>
	</excludedpackages>
	<instructions type="install">
		<!-- Installation instructions go here -->
	</instructions>
</package>
```

--------------------------------

### package.xml - Package Manifest Structure

Source: https://context7.com/woltlab/docs.woltlab.com/llms.txt

An example of a package.xml file, which serves as the manifest for installable packages. It declares metadata, version, dependencies, conflicts, and installation instructions.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://www.woltlab.com"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.woltlab.com http://www.woltlab.com/XSD/2019/package.xsd"
         name="com.example.myplugin">
    <packageinformation>
        <packagename>My Plugin</packagename>
        <packagename language="de">Mein Plugin</packagename>
        <packagedescription>Adds example functionality.</packagedescription>
        <version>1.0.0</version>
        <date>2024-06-01</date>
    </packageinformation>
    <authorinformation>
        <author>Jane Doe</author>
        <authorurl>https://example.com</authorurl>
    </authorinformation>
    <requiredpackages>
        <requiredpackage minversion="6.0.0">com.woltlab.wcf</requiredpackage>
    </requiredpackages>
    <excludedpackages>
        <excludedpackage version="7.0.0 Alpha 1">com.woltlab.wcf</excludedpackage>
    </excludedpackages>
    <instructions type="install">
        <instruction type="file" />
        <instruction type="template" />
        <instruction type="eventListener" />
        <instruction type="language" />
    </instructions>
    <instructions type="update" fromversion="0.9.0">
        <instruction type="file" />
    </instructions>
</package>
```

--------------------------------

### Package Installation Instructions

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/migration/wcf21/package.md

Defines installation instructions for package components, allowing for default filenames based on the Package Installation Plugin (PIP) or explicit file paths. Supports various instruction types like eventListener, sql, language, file, and script.

```xml
<instructions type="install">
    <!-- assumes `eventListener.xml` -->
    <instruction type="eventListener" />
    <!-- assumes `install.sql` -->
    <instruction type="sql" />
    <!-- assumes `language/*.xml` -->
    <instruction type="language" />

    <!-- exceptions -->

    <!-- assumes `files.tar` -->
    <instruction type="file" />
    <!-- no default value, requires relative path -->
    <instruction type="script">acp/install_com.woltlab.wcf_3.0.php</instruction>
</instructions>
```

--------------------------------

### Example Box XML Configuration

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/box.md

This is an example of a box.xml file, demonstrating the structure for defining a box with various properties.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<package name="com.woltlab.wcf.boxes">
	<version>1.0.0</version>

	<box name="com.woltlab.wcf.RecentActivity" defaultOrder="10">
		<name language="en">Recent Activity</name>
		<name language="de">Aktuelle Aktivitäten</name>

		<boxType>system</boxType>
		<objectType>com.woltlab.wcf.boxController</objectType>
		<position>sidebarRight</position>
		<showHeader>1</showHeader>
		<visibleEverywhere>1</visibleEverywhere>
	</box>

	<box name="com.woltlab.wcf.WelcomeMessage" defaultOrder="20">
		<name language="en">Welcome Message</name>
		<name language="de">Willkommensnachricht</name>

		<boxType>html</boxType>
		<position>contentTop</position>
		<showHeader>0</showHeader>
		<visibleEverywhere>0</visibleEverywhere>
		<visibilityExceptions>
			<page name="com.woltlab.wcf.page.Index" />
		</visibilityExceptions>
		<cssClassName>welcome-box</cssClassName>
		<content language="en">
			<title>Welcome!</title>
			<html>
				<p>This is a custom welcome message.</p>
			</html>
		</content>
		<content language="de">
			<title>Willkommen!</title>
			<html>
				<p>Dies ist eine benutzerdefinierte Willkommensnachricht.</p>
			</html>
		</content>
	</box>
</package>
```

--------------------------------

### Specify Installation Instruction with File

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/package-xml.md

Use `<instruction>` to define a specific installation task. The `type` attribute determines the Package Installation Plugin (PIP) to use, and the element value is the relative file path.

```xml
<instruction type="objectTypeDefinition">objectTypeDefinition.xml</instruction>
```

--------------------------------

### Example fileDelete.xml

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/file-delete.md

This XML snippet demonstrates the structure for defining a file deletion within a package installation. It specifies the file to be deleted and its associated application context.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<files name="fileDelete">
	<file application="wcf">
		path/to/your/file.js
	</file>
</files>
```

--------------------------------

### Example page.xml Configuration

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/page.md

An example XML configuration file for defining a page controller. This file specifies the page identifier, type, controller class, and other attributes.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<package name="com.example.mypackage">
    <page name="MyPage" identifier="com.example.mypackage.MyPage">
        <pageType>system</pageType>
        <controller>com.example.mypackage.page.MyPageController</controller>
        <handler>com.example.mypackage.page.MyPageHandler</handler>
        <parent>com.woltlab.wcf.index</parent>
        <hasFixedParent>0</hasFixedParent>
        <permissions>user.canViewMyPage,admin.canViewMyPage</permissions>
        <options>myPackage.myOption</options>
        <excludeFromLandingPage>0</excludeFromLandingPage>
        <requireObjectID>1</requireObjectID>
        <availableDuringOfflineMode>0</availableDuringOfflineMode>
        <allowSpidersToIndex>0</allowSpidersToIndex>
        <cssClassName>my-custom-class</cssClassName>
        <content>
            <title language="en">My Page Title</title>
            <content language="en">&lt;p&gt;This is the content of my page.&lt;/p&gt;</content>
        </content>
    </page>
</package>
```

--------------------------------

### UserRuntimeCache Implementation Example

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/php/api/caches_runtime-caches.md

An example implementation of a `UserRuntimeCache` class, extending `AbstractRuntimeCache` and specifying the `listClassName` property.

```php
<?php

namespace wcf\system\cache\runtime;

use wcf\data\user\UserList;

/**
 * User runtime cache.
 * @package wcf\system\cache\runtime
 */
class UserRuntimeCache extends AbstractRuntimeCache
{
    /**
     * @inheritDoc
     */
    public static string $listClassName = UserList::class;
}

```

--------------------------------

### Minimal Page Structure Example

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/migration/wcf21/templates.md

This example shows the minimum required template includes for displaying a page, including the header and footer. The content title is automatically handled.

```smarty
{include file='header'}

<div class="section">
    Hello World!
</div>

{include file='footer'}
```

--------------------------------

### Define Package Installation Plugin

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/pip.md

Defines a package installation plugin using the `<pip>` element. The `name` attribute specifies the plugin's name, and the text content is the PHP classname. Ensure the class file is installed in the `wcf` application and adheres to the `\wcf\*` namespace for correct uninstallation.

```xml
<pip name="examplePlugin">\wcf\example\ExamplePlugin</pip>
```

--------------------------------

### Application-Specific File Installation

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/file.md

This instruction allows installing files specific to an application. The 'application' attribute determines which application the files are associated with.

```xml
<!-- if an application "com.woltlab.example" is being installed, the following lines are equivalent -->
<instruction type="file" />
<instruction type="file" application="example" />
```

```xml
<!-- if the same application wants to install additional files, in WoltLab Suite Core's directory: -->
<instruction type="file" application="wcf">files_wcf.tar</instruction>
```

--------------------------------

### Example Cache Builder Implementation

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/php/api/caches_persistent-caches.md

This is an example of a cache builder class that extends AbstractCacheBuilder. It demonstrates how to implement custom cache logic.

```php
<?php
use wcf\system\cache\builder\ExampleCacheBuilder;

$data = ExampleCacheBuilder::getInstance()->getData($parameters);

```

--------------------------------

### aclOption.xml Example

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/acl-option.md

This XML file demonstrates the structure for defining ACL options and categories. It includes examples of category names and object types.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<data name="aclOption">
    <category name="user.general">
        <option name="canDoSomething" />
    </category>
    <category name="mod.general">
        <option name="canDoSomethingElse" />
    </category>
</data>
```

--------------------------------

### Example userProfileMenu.xml Configuration

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/user-profile-menu.md

This XML configuration defines a user profile menu item. Ensure the class specified implements the `wcf\system\menu\user\profile\content\IUserProfileMenuContent` interface.

```xml
<userprofilemenuitem name="exampleTab">
    <classname>wcf\user\profile\tab\ExampleProfileTab</classname>
    <showorder>10</showorder>
    <options>option1,option2</options>
    <permissions>user.general.canSeeExampleTab</permissions>
</userprofilemenuitem>
```

--------------------------------

### Package System - package.xml

Source: https://context7.com/woltlab/docs.woltlab.com/llms.txt

This section describes the structure and usage of the `package.xml` file, which serves as the manifest for installable packages in WoltLab Suite. It details how to declare metadata, dependencies, and installation instructions.

```APIDOC
## Package System

### package.xml – Package manifest

Every installable package requires a `package.xml` at its root. It declares metadata, version, dependencies, conflicts, and an ordered list of PIP instructions.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://www.woltlab.com"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://www.woltlab.com http://www.woltlab.com/XSD/2019/package.xsd"
         name="com.example.myplugin">
    <packageinformation>
        <packagename>My Plugin</packagename>
        <packagename language="de">Mein Plugin</packagename>
        <packagedescription>Adds example functionality.</packagedescription>
        <version>1.0.0</version>
        <date>2024-06-01</date>
    </packageinformation>
    <authorinformation>
        <author>Jane Doe</author>
        <authorurl>https://example.com</authorurl>
    </authorinformation>
    <requiredpackages>
        <requiredpackage minversion="6.0.0">com.woltlab.wcf</requiredpackage>
    </requiredpackages>
    <excludedpackages>
        <excludedpackage version="7.0.0 Alpha 1">com.woltlab.wcf</excludedpackage>
    </excludedpackages>
    <instructions type="install">
        <instruction type="file" />
        <instruction type="template" />
        <instruction type="eventListener" />
        <instruction type="language" />
    </instructions>
    <instructions type="update" fromversion="0.9.0">
        <instruction type="file" />
    </instructions>
</package>
```
```

--------------------------------

### Basic ACP Template Installation

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/acp-template.md

Use this instruction to install ACP templates from an archive. The archive name is optional and defaults to 'acptemplates.tar' if not specified.

```xml
<instruction type="acpTemplate" />
```

```xml
<instruction type="acpTemplate">acptemplates.tar</instruction>
```

--------------------------------

### Optional Package with File

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/package-xml.md

Defines an optional package that can be selected during installation, including the path to its archive file.

```xml
<optionalpackage file="optionals/com.example.bar.tar">com.example.bar</optionalpackage>
```

--------------------------------

### Specify Installation Instruction with Default File

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/package-xml.md

If a PIP provides a default file name, you can omit the element value for the `<instruction>` tag.

```xml
<instruction type="objectTypeDefinition" />
```

--------------------------------

### ACP Template Installation for Specific Application

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/acp-template.md

Specify the `application` attribute to install ACP templates into a particular application's directory. If the installing package is an application, it defaults to that application. Otherwise, it defaults to WoltLab Suite Core.

```xml
<instruction type="acpTemplate" />
<instruction type="acpTemplate" application="example" />
```

--------------------------------

### Install Template Listeners

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/tutorial/series/part_2.md

This XML file configures the installation of template listeners, including those for the birthday sort field and birthday display. It uses the `include` syntax to load external templates.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<templateListeners>
    <templateListener
        packageId="com.woltlab.wcf.people"
        template="__personListBirthdaySortField.tpl"
        order="10"
    />
    <templateListener
        packageId="com.woltlab.wcf.people"
        template="__personListBirthday.tpl"
        order="10"
    />
</templateListeners>

```

--------------------------------

### objectType.xml Example

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/object-type.md

This XML file demonstrates the structure for registering an object type. It includes the package identifier and definition name.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<data name="objectType">
    <type>
        <name>com.woltlab.wcf.example</name>
        <classname>ExampleObjectTypeProvider</classname>
        <!-- Optional fields may be defined here -->
    </type>
</data>
```

--------------------------------

### Define Package Structure with package.xml

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/getting-started.md

This XML file defines the metadata, dependencies, and installation instructions for a WoltLab Suite package. Ensure correct encoding and structure for proper installation.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://www.woltlab.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.woltlab.com http://www.woltlab.com/XSD/2019/package.xsd" name="com.example.test">
	<packageinformation>
		<!-- com.example.test -->
		<packagename>Simple Package</packagename>
		<packagedescription>A simple package to demonstrate the package system of WoltLab Suite Core</packagedescription>
		<version>1.0.0</version>
		<date>2023-09-15</date>
	</packageinformation>
	<authorinformation>
		<author>Your Name</author>
		<authorurl>http://www.example.com</authorurl>
	</authorinformation>
	<requiredpackages>
		<requiredpackage minversion="6.0.0">com.woltlab.wcf</requiredpackage>
	</requiredpackages>
	<excludedpackages>
		<excludedpackage version="7.0.0 Alpha 1">com.woltlab.wcf</excludedpackage>
	</excludedpackages>
	<instructions type="install">
		<instruction type="file" />
		<instruction type="template" />
		<instruction type="page" />
	</instructions>
</package>
```

--------------------------------

### Example clipboardAction.xml Configuration

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/clipboard-action.md

This XML configuration defines a clipboard action, specifying the class name for processing and the pages where it should be available. The 'showorder' attribute is optional.

```xml
<clipboardAction name="myAction">
    <actionclassname>wcf\system\clipboard\action\MyAction</actionclassname>
    <pages>
        <page>wcf\page\MyPage</page>
    </pages>
    <showorder>10</showorder>
</clipboardAction>
```

--------------------------------

### package.xml for WoltLab Suite Core 3

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/tutorial/series/part_1.md

Defines the structure, dependencies, and installation instructions for a WoltLab Suite Core 3 package. Ensure required packages are installed before dependent ones.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<package name="com.woltlab.wcf.tutorial.part1" version="1.0.0" vendor="WoltLab GmbH" type="wcf">
	<name>
		<label lang="en">Tutorial Package Part 1</label>
	</name>
	<description>
		<label lang="en">A simple package for the tutorial series.</label>
	</description>

	<author name="WoltLab GmbH"/>

	<dependencies>
		<dependency package="com.woltlab.wcf" version="5.4.0 Alpha 1"/>
	</dependencies>

	<disallow version="6.0.0 Alpha 1"/>

	<files>
		<file from="acp/template/" to="acp/template/"/>
		<file from="acp/style/" to="acp/style/"/>
		<file from="acp/script/" to="acp/script/"/>
	</files>

	<templates>
		<template from="acp/template/" to="acp/template/"/>
	</templates>

	<instructions type="install">
		<instruction type="sql">sql/install.sql</instruction>
		<instruction type="language"/>
		<instruction type="menuitem"/>
		<instruction type="acp_style"/>
	</instructions>

	<instructions type="update">
		<instruction type="sql">sql/update.sql</instruction>
		<instruction type="language"/>
		<instruction type="menuitem"/>
		<instruction type="acp_style"/>
	</instructions>

	<instructions type="uninstall">
		<instruction type="sql">sql/uninstall.sql</instruction>
		<instruction type="language"/>
		<instruction type="menuitem"/>
	</instructions>
</package>
```

--------------------------------

### Example LastActivityCronjob Implementation

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/php/api/cronjobs.md

This example demonstrates the basic structure of a cronjob class that extends `AbstractCronjob` and implements the `execute` method. Ensure the `AbstractCronjob::execute()` method is called to fire events.

```php
<?php

namespace wcf\system\cronjob;

use wcf\system\cronjob\Cronjob;

class LastActivityCronjob extends AbstractCronjob
{
    /**
     * @inheritDoc
     */
    public function execute(Cronjob $cronjob): void
    {
        parent::execute($cronjob);

        // Your cronjob logic here
        echo "Last activity cronjob executed.";
    }
}

```

--------------------------------

### Idempotent Package Installation Plugin (PHP)

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/migration/wsc30/php.md

Implement 'IIdempotentPackageInstallationPlugin' and the 'getSyncDependencies' method for package installation plugins (PIPs) intended for the developer tools sync feature. This ensures PIPs can be invoked multiple times without side effects and manages dependencies.

```php
<?php
class ExamplePackageInstallationPlugin extends AbstractXMLPackageInstallationPlugin implements IIdempotentPackageInstallationPlugin {
  public static function getSyncDependencies() {
    // provide a list of dependent PIPs in arbitrary order
    return [];
  }
}
```

--------------------------------

### Menu XML Configuration

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/menu.md

Example of a menu.xml file used for configuring menus. This file defines the structure and properties of menus that can be placed anywhere on the site.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<data name="menu">
    <title language="en">Example Menu</title>
    <menuitem identifier="com.woltlab.wcf.ExampleMenu.FirstItem">
        <title language="en">First Item</title>
        <link>https://example.com</link>
    </menuitem>
    <menuitem identifier="com.woltlab.wcf.ExampleMenu.SecondItem">
        <title language="en">Second Item</title>
        <link>https://example.com/page2</link>
    </menuitem>
</data>
```

--------------------------------

### Basic Pagination Component Usage

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/javascript/components_pagination.md

This is a basic example of how to use the pagination component with static URLs. Ensure the `url` parameter is set for link behavior.

```html
<woltlab-core-pagination page="1" count="10" url="https://www.woltlab.com"></woltlab-core-pagination>
```

--------------------------------

### Create PSR-15 Dialog Form

Source: https://context7.com/woltlab/docs.woltlab.com/llms.txt

Implement interactive forms using Psr15DialogForm for PSR-15 controllers. This example shows basic field setup and request handling for GET and POST methods.

```php
// --- Dialog form (PSR-15 controller) ---
use wcf\system\form\builder\Psr15DialogForm;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Server\RequestHandlerInterface;

final class FooDialogAction implements RequestHandlerInterface {
    public function handle(ServerRequestInterface $request): ResponseInterface {
        $form = new Psr15DialogForm(static::class, WCF::getLanguage()->get('wcf.foo.dialog'));
        $form->appendChildren([
            TextFormField::create('name')->label('wcf.foo.name')->required(),
        ]);
        $form->build();

        if ($request->getMethod() === 'GET') {
            return $form->toResponse();
        }
        $response = $form->validateRequest($request);
        if ($response !== null) return $response;

        $data = $form->getData()['data'];
        // process $data …
    }
}
```

--------------------------------

### Open a Dialog with `_dialogSetup`

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/javascript/new-api_dialogs.md

Demonstrates how to open a dialog by calling `UiDialog.open()` with `this` context, which triggers the `_dialogSetup` method for configuration. The `_dialogSetup` method returns an object containing the dialog's ID, source HTML, and options like `onClose`.

```javascript
define(["Ui/Dialog"], function(UiDialog) {
  "use strict";

  function Foo() {};
  Foo.prototype = {
    bar: function() {
      // this will open the dialog constructed by _dialogSetup
      UiDialog.open(this);
    },

    _dialogSetup: function() {
      return {
        id: "myDialog",
        source: "<p>Hello World!</p>",
        options: {
          onClose: function() {
            // the fancy dialog was closed!
          }
        }
      }
    }
  };

  return Foo;
});
```

--------------------------------

### Smarty Template Example

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/getting-started.md

This is a basic Smarty template that includes header and footer files and displays a dynamic greeting. It demonstrates how to mix HTML with template scripting.

```smarty
{include file='header'}

<div class="section">
	Hello {$greet}!
</div>

{include file='footer'}
```

--------------------------------

### PHP Example Usage

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/php/api/events.md

This PHP code demonstrates how to instantiate and use the ExampleComponent. It checks the return value of getVar() and prints a message. The output will change based on whether an event listener has modified the internal state.

```php
<?php

$example = new wcf\system\example\ExampleComponent();
if ($example->getVar() == 1) {
	echo "var is 1!";
}
else if ($example->getVar() == 2) {
	echo "var is 2!";
}
else {
	echo "No, var is neither 1 nor 2.";
}

// output: var is 1!
```

--------------------------------

### Renaming Database Table Columns

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/migration/wsc53/php.md

Example of renaming an existing database table column using the PHP Database API. This change can only be made by packages that installed the original column.

```php
PartialDatabaseTable::create('wcf1_test')
        ->columns([
                NotNullInt10DatabaseTableColumn::create('oldName')
                        ->renameTo('newName')
        ]);
```

--------------------------------

### Handling AJAX Form Submissions with Psr15DialogForm

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/php/api/form_builder/overview.md

Use Psr15DialogForm for forms processed via AJAX. Implement `validateRequest` and `toResponse` for AJAX handling. This example shows a basic action class that processes GET and POST requests for a dialog form.

```php
<?php

namespace wcf\action;

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\RequestHandlerInterface;
use wcf\system\form\builder\field\validation\FormFieldValidationError;
use wcf\system\form\builder\field\validation\FormFieldValidator;
use wcf\system\form\builder\Psr15DialogForm;
use wcf\system\WCF;

final class FooAction implements RequestHandlerInterface
{
    /**
     * @inheritDoc
     */
    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        $form = $this->getForm();

        if ($request->getMethod() === 'GET') {
            return $form->toResponse();
        } elseif ($request->getMethod() === 'POST') {
            $response = $form->validateRequest($request);
            if ($response !== null) {
                return $response;
            }

            $data = $form->getData()['data'];

            // process data
        } else {
            throw new \LogicException('Unreachable');
        }
    }

    private function getForm(): Psr15DialogForm
    {
        $form = new Psr15DialogForm(
            static::class,
            WCF::getLanguage()->get('wcf.foo.dialog.name')
        );
        $form->appendChildren([
            TextFormField::create('name')
                ->label('wcf.foo.name')
                ->description('wcf.foo.name.description')
                ->required()
                ->maximumLength(255)
                ->addValidator(new FormFieldValidator('notFoo', function (TextFormField $formField) {
                    if ($formField->getValue() === 'foo') {
                        $formField->addValidationError(
                            new FormFieldValidationError(
                                'isFoo',
                                'wcf.foo.name.error.isFoo'
                            )
                        );
                    }
                })),
            BooleanFormField::create('isCool')
                ->label('wcf.foo.isCool')
                ->value(true)
        ]);
        $form->build();

        return $form;
    }
}

```

--------------------------------

### Install Admin Permission

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/tutorial/series/part_1.md

This XML file installs the 'admin.content.canManagePeople' permission using the userGroupOption package installation plugin. It configures the permission for administrators only and ensures it's not visible for guest user groups.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <userGroupOption>
        <category name="admin.content">
            <option name="canManagePeople">
                <defaultvalue>0</defaultvalue>
                <isnull>0</isnull>
                <usersonly>1</usersonly>
                <admindefaultvalue>1</admindefaultvalue>
            </option>
        </category>
    </userGroupOption>
</data>

```

--------------------------------

### _dialogSetup()

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/javascript/new-api_dialogs.md

Initializes and configures a dialog. It returns an object with properties like `id`, `source`, and `options` to define the dialog's behavior and content.

```APIDOC
## _dialogSetup()

### Description
Performs lazy initialization for dialogs, retrieving basic configuration and event callbacks.

### Method Signature
`_dialogSetup(): { id: string, source: any, options: Object }`

### Parameters
None

### Returns
An object containing dialog configuration:
- `id` (string): Identifier for the dialog, used for runtime identification and initial setup.
- `source` (any): Defines how the initial dialog content is constructed. Can be `undefined`, `null`, a function, an object, a string (HTML), or a `DocumentFragment`.
- `options` (Object): Configuration options and callbacks for the dialog.

#### `options.backdropCloseOnClick` (boolean)
_Defaults to `true`._
Enables closing the dialog by clicking on the backdrop.

#### `options.closable` (boolean)
_Defaults to `true`._
Enables the close button in the dialog title.

#### `options.closeButtonLabel` (string)
_Defaults to `Language.get("wcf.global.button.close")`._
Tooltip text for the close button.

#### `options.closeConfirmMessage` (string)
_Defaults to `""`._
Message for a confirmation dialog shown before closing.

#### `options.title` (string)
_Defaults to `""`._
Text displayed in the dialog title.

#### `options.onBeforeClose` (function)
_Defaults to `null`._
Callback executed before the dialog is closed. Responsible for closing the dialog itself.

#### `options.onClose` (function)
_Defaults to `null`._
Callback executed when the dialog is about to be closed, but still visible.

#### `options.onShow` (function)
_Defaults to `null`._
Callback executed after the dialog is visible but before it's finalized, receiving the dialog content element.
```

--------------------------------

### Implement Custom IFileProcessor in PHP

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/migration/wsc60/php.md

This example demonstrates how to create a custom file processor by extending `AbstractFileProcessor`. It covers handling uploads based on context, checking permissions, validating file size and extensions, and managing file adoption and deletion. Use this when you need custom logic for file processing.

```PHP
final class FooImageFileProcessor extends AbstractFileProcessor
{
    #[\]Override]
    public function acceptUpload(string $filename, int $fileSize, array $context): FileProcessorPreflightResult
    {
        if (isset($context['objectID'])) {
            $foo = $this->getFoo($context);
            if ($foo === null) {
                return FileProcessorPreflightResult::InvalidContext;
            }

            if (!$foo->canEdit()) {
                return FileProcessorPreflightResult::InsufficientPermissions;
            }
        } elseif (!WCF::getSession()->getPermission('foo.bar.canAdd')) {
            return FileProcessorPreflightResult::InsufficientPermissions;
        }

        if ($fileSize > $this->getMaximumSize($context)) {
            return FileProcessorPreflightResult::FileSizeTooLarge;
        }

        if (!FileUtil::endsWithAllowedExtension($filename, $this->getAllowedFileExtensions($context))) {
            return FileProcessorPreflightResult::FileExtensionNotPermitted;
        }

        return FileProcessorPreflightResult::Passed;
    }

    #[\]Override]
    public function getMaximumSize(array $context): ?int
    {
        return WCF::getSession()->getPermission('foo.bar.image.maxSize');
    }

    #[\]Override]
    public function getAllowedFileExtensions(array $context): array
    {
        return \explode("\n", WCF::getSession()->getPermission('foo.bar.image.allowedFileExtensions'));
    }

    #[\]Override]
    public function canAdopt(File $file, array $context): bool
    {
        $fooFromContext = $this->getFoo($context);
        $fooFromCoreFile = $this->getFooByFile($file);

        if ($fooFromCoreFile === null) {
            return true;
        }

        if ($fooFromCoreFile->fooID === $fooFromContext?->fooID) {
            return true;
        }

        return false;
    }

    #[\]Override]
    public function adopt(File $file, array $context): void
    {
        $foo = $this->getFoo($context);
        if ($foo === null) {
            return;
        }

        (new FooEditor($foo))->update([
            'imageID' => $file->fileID,
        ]);
    }

    #[\]Override]
    public function canDelete(File $file): bool
    {
        $foo = $this->getFooByFile($file);
        if ($foo === null) {
            return WCF::getSession()->getPermission('foo.bar.canAdd');
        }

        return false;
    }

    #[\]Override]
    public function canDownload(File $file): bool
    {
        $foo = $this->getFooByFile($file);
        if ($foo === null) {
            return WCF::getSession()->getPermission('foo.bar.canAdd');
        }

        return $foo->canRead();
    }

    #[\]Override]
    public function delete(array $fileIDs, array $thumbnailIDs): void
    {
        $fooList = new FooList();
        $fooList->getConditionBuilder()->add('imageID IN (?)', [$fileIDs]);
        $fooList->readObjects();

        if ($fooList->count() === 0) {
            return;
        }

        (new FooAction($fooList->getObjects(), 'delete'))->executeAction();
    }

    #[\]Override]
    public function getObjectTypeName(): string
    {
        return 'foo.bar.image';
    }
    
    #[\]Override]
    public function countExistingFiles(array $context): ?int
    {
        $foo = $this->getFoo($context);
        if ($foo === null) {
            return null;
        }

        return $foo->imageID === null ? 0 : 1;
    }
    
    private function getFoo(array $context): ?Foo
    {
        // extract foo from context
    }
    
    private function getFooByFile(File $file): ?Foo
    {
        // search foo in database by given file
    }
}
```

--------------------------------

### Example User Menu XML Configuration

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/user-menu.md

This XML file defines a user menu item. It specifies the item's name, parent, controller, link, icon, options, permissions, and class name.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<data>
    <usermenuitem name="myMenuItem">
        <parent>userMenu</parent>
        <showorder>10</showorder>
        <controller>	wolfcms\user\menu\MyMenuItemController</controller>
        <link>	/index.php?page=my-menu-item</link>
        <iconclassname>fas fa-star</iconclassname>
        <options>user</options>
        <permissions>user.canSeeMyMenuItem</permissions>
        <classname>	wolfcms\user\menu\MyMenuItemProvider</classname>
    </usermenuitem>
</data>
```

--------------------------------

### Package File Structure

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/tutorial/series/part_5.md

This outlines the directory structure for the package, highlighting new files and directories introduced in this part of the tutorial series.

```text
├── files
│   ├── acp
│   │   └── database
│   │       └── install_com.woltlab.wcf.people.php
│   ├── js
│   │   └── WoltLabSuite
│   │       └── Core
│   │           └── Controller
│   │               └── Person.js
│   └── lib
│       ├── data
│       │   └── person
│       │       ├── Person.class.php
│       │       └── information
│       │           ├── PersonInformation.class.php
│       │           ├── PersonInformationAction.class.php
│       │           ├── PersonInformationEditor.class.php
│       │           └── PersonInformationList.class.php
│       └── system
│           └── worker
│               └── PersonRebuildDataWorker.class.php
├── language
│   ├── de.xml
│   └── en.xml
├── objectType.xml
├── templates
│   ├── person.tpl
│   └── personList.tpl
├── ts
│   └── WoltLabSuite
│       └── Core
│           └── Controller
│               └── Person.ts
└── userGroupOption.xml
```

--------------------------------

### Basic File Instruction

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/file.md

Use this instruction to include any type of file, except templates, in your package. The archive must be a .tar or .tar.gz file.

```xml
<instruction type="file" />
```

```xml
<!-- is the same as -->
<instruction type="file">files.tar</instruction>
```

--------------------------------

### Example Database Object Action

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/php/database-objects.md

This snippet demonstrates how to use `ExampleAction` to create, update, and delete rows. The `executeAction()` method can be called to perform the action, and return values can be accessed via the method's return or `getReturnValues()`.

```php
<?php
use wcf\data\example\ExampleAction;

// create a row
$exampleAction = new ExampleAction([], 'create', [
    'data' => ['bar' => 'Hello World']
]);
$example = $exampleAction->executeAction()["returnValues"];

// update a row using the id
$exampleAction = new ExampleAction([1], 'update', [
    'data' => ['bar' => 'baz']
]);
$exampleAction->executeAction();

// delete a row using a model
$exampleAction = new ExampleAction([$example], 'delete');
$exampleAction->executeAction();
```

--------------------------------

### Load a JavaScript Module

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/javascript/new-api_writing-a-module.md

Loads the `WoltLabSuite/Core/Ui/Foo` module and instantiates it. This script should be placed within `<script>` tags and can use `data-relocate="true"`.

```html
<script data-relocate="true">
  require(["WoltLabSuite/Core/Ui/Foo"], function(UiFoo) {
    new UiFoo();
  });
</script>
```

--------------------------------

### acpSearchProvider.xml Example

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/acp-search-provider.md

Example XML configuration for an ACP search provider. This file defines the search provider's name and the class responsible for providing search results.

```xml
<acpsearchprovider name="example">
    <classname>Example\SearchProvider</classname>
    <showorder>10</showorder>
</acpsearchprovider>
```

--------------------------------

### AbstractFormBuilderForm Lifecycle (GET)

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/php/pages.md

Details the execution flow when AbstractFormBuilderForm is loaded via a GET request, emphasizing the role of the Form Builder API in `checkPermissions()` and automatic form handling.

```text
__run()
 │
 ├─ readParameters()
 │   └─ Event: readParameters
 │
 └─ show()
     ├─ checkModules()
     │   └─ Event: checkModules
     │
     ├─ checkPermissions()
     │   ├─ Event: checkPermissions
     │   │
     │   └─ buildForm()
     │       ├─ createForm()
     │       ├─ Event: createForm
     │       ├─ form->build()
     │       ├─ finalizeForm()
     │       └─ Event: buildForm
     │
     ├─ readData()
     │   ├─ setFormObjectData()               ← only if $formObject is set (edit mode)
     │   │   └─ form->updatedObject()
     │   │  (no POST/FILES data, submission is skipped)
     │   ├─ Event: readData
     │   └─ setFormAction()
     │
     ├─ assignVariables()
     │   └─ Event: assignVariables
     │
     ├─ Event: show
     │
     └─ [Template rendering]

```

--------------------------------

### UiDialog.open()

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/javascript/new-api_dialogs.md

Opens a dialog using the provided object, which should have a `_dialogSetup` method.

```APIDOC
## UiDialog.open(caller: Object, html?: string)

### Description
Opens a dialog. The `caller` object is expected to have a `_dialogSetup` method that provides the dialog configuration.

### Method
`UiDialog.open(caller, html)`

### Parameters
- **caller** (Object): An object that has a `_dialogSetup` method.
- **html** (string, optional): HTML content to be used for the dialog if `source` is `null` in `_dialogSetup`.
```

--------------------------------

### SQL Instruction in package.xml

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/pip/sql.md

Specify the relative path to the .sql file within the package.xml configuration.

```xml
<instruction type="sql">install.sql</instruction>
```

--------------------------------

### Handling GET and POST Requests with Psr15DialogForm

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/migration/wsc55/php.md

This PHP code demonstrates how to handle GET requests by returning a response and POST requests by validating the server request. It returns a JsonResponse with the result on successful validation and processing.

```php
if ($request->getMethod() === 'GET') {
    return $dialogForm->toResponse();
} elseif ($request->getMethod() === 'POST') {
    $response = $dialogForm->validateRequest($request);
    if ($response !== null) {
        return $response;
    }

    $data = $dialogForm->getData();

    // Use $data.

    return new JsonResponse([
        'result' => [
            'some' => 'value',
        ],
    ]);
} else {
    // The used method is validated by a middleware. Methods that are not
    // GET or POST need to be explicitly allowed using the 'AllowHttpMethod'
    // attribute.
    throw new \LogicException('Unreachable');
}
```

--------------------------------

### Basic Dialog Creation and Usage

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/javascript/components_dialog.md

Demonstrates how to create a dialog from an HTML template and open it. The dialog is configured as a prompt, and an event listener is added to handle the primary action, logging the input value.

```html
<button id="showMyDialog">Show the dialog</button>

<template id="myDialog">
  <dl>
    <dt>
      <label for="myInput">Title</label>
    </dt>
    <dd>
      <input type="text" name="myInput" id="myInput" value="" required />
    </dd>
  </dl>
</template>
```

```typescript
import { dialogFactory } from "WoltLabSuite/Core/Component/Dialog";

document.getElementById("showMyDialog")!.addEventListener("click", () => {
  const dialog = dialogFactory().fromId("myDialog").asPrompt();

  dialog.addEventListener("primary", () => {
    const myInput = document.getElementById("myInput");

    console.log("Provided title:", myInput.value.trim());
  });
});
```

--------------------------------

### CustomFormNode Usage

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/php/api/form_builder/structure.md

Example of creating and setting content for a CustomFormNode.

```APIDOC
## CustomFormNode

### Description
A form node whose content can be set directly. Note: `TemplateFormNode` is generally preferred.

### Example
```php
CustomFormNode::create('example')
  ->content('html code')
```
```

--------------------------------

### Basic Bootstrap Script Structure in PHP

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/migration/wsc55/php.md

Demonstrates the two-phase execution of a bootstrap script. Phase 1 includes the script and returns a Closure, which is then executed in Phase 2.

```php
<?php

// Phase (1).

return static function (): void {
    // Phase (2).
};

```

--------------------------------

### Package Name with Language Support

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/package/package-xml.md

Demonstrates how to specify package names in multiple languages using the 'language' attribute. English is assumed if not specified.

```xml
<packageinformation>
	<packagename>Simple Package</packagename>
	<packagename language="de">Einfaches Paket</packagename>
</packageinformation>
```

--------------------------------

### IFormElement Methods

Source: https://github.com/woltlab/docs.woltlab.com/blob/6.2/docs/php/api/form_builder/structure.md

Methods for setting and getting labels and descriptions for form elements.

```APIDOC
## IFormElement

### Description
Represents form elements that can have a label and a description. Extends `IFormNode`.

### Methods
- `label($languageItem = null, array $variables = [])`: Sets the label for the form element.
- `getLabel()`: Gets the label of the form element.
- `requiresLabel()`: Checks if the form element requires a label.
- `description($languageItem = null, array $variables = [])`: Sets the description for the form element.
- `getDescription()`: Gets the description of the form element.
```