package.xml

package.xml describes package metadata that QUIQQER can show in package management, marketplaces, backend views, and package integrations.

Use it for package title, description, images, support links, copyright information, supported languages, capability declarations, and provider declarations.

Basic Structure

Create package.xml in the package root.

<quiqqer>
    <package>
        <title>
            <locale group="vendor/package" var="package.title"/>
        </title>

        <description>
            <locale group="vendor/package" var="package.description"/>
        </description>
    </package>
</quiqqer>

Use locale references for title and description instead of hard-coded text. Keep the actual translations in locale.xml.

Images And Previews

Use <image> for the main package image and <preview> for additional preview images.

<image src="URL_OPT_DIR/vendor/package/bin/images/logo.jpg"/>

<preview>
    <image src="URL_OPT_DIR/vendor/package/bin/images/preview/preview-1.png"/>
    <image src="URL_OPT_DIR/vendor/package/bin/images/preview/preview-2.png"/>
</preview>

Use package asset paths for images that belong to the package. Current packages commonly use URL_OPT_DIR/vendor/package/... for public package assets.

Support Links

The <support> block documents where developers and administrators can find help and package sources.

<support>
    <email><![CDATA[support@example.com]]></email>
    <forum><![CDATA[https://community.example.com]]></forum>
    <source><![CDATA[https://dev.example.com/vendor/package]]></source>
    <issues><![CDATA[https://dev.example.com/vendor/package/issues]]></issues>
    <wiki><![CDATA[https://dev.example.com/vendor/package/wikis/home]]></wiki>
</support>

Use stable URLs that match the repository and support process for the package.

Copyright And Licenses

Use <copyright> for package owner and license information.

<copyright>
    <name><![CDATA[Vendor Name]]></name>
    <license><![CDATA[GPL-3.0+]]></license>
</copyright>

If the package has multiple licenses, declare each license explicitly.

Capability Declarations

Use the optional <capabilities> block to describe what a package enables from a functional perspective. Capabilities provide stable, semantic identifiers that tools can use to discover suitable packages without depending on package names.

<quiqqer>
    <package>
        <title>
            <locale group="quiqqer/frontend-users" var="package.title"/>
        </title>

        <capabilities schemaVersion="1">
            <capability id="identity.registration">
                <title>Frontend user registration</title>
                <description>
                    Provides public registration for frontend users.
                </description>

                <useCases>
                    <useCase>customer-portal</useCase>
                    <useCase>membership-platform</useCase>
                </useCases>
            </capability>
        </capabilities>
    </package>
</quiqqer>

The first schema version supports:

Element or attribute	Required	Purpose
capabilities@schemaVersion	Yes	Selects the capability declaration schema.
capability@id	Yes	Stable semantic identifier such as identity.registration.
title	Yes	Short human-readable capability name.
description	Yes	Concise description of the function the package provides.
useCases/useCase	No	Application contexts in which the capability is useful.

A package can declare multiple capabilities:

<capabilities schemaVersion="1">
    <capability id="billing.invoices">
        <title>Invoice management</title>
        <description>Creates and manages customer invoices.</description>
    </capability>

    <capability id="billing.invoice-pdf">
        <title>Invoice PDF generation</title>
        <description>Generates PDF documents for invoices.</description>
    </capability>
</capabilities>

Capability IDs describe functions across the QUIQQER ecosystem. More than one package can provide the same capability. Consumers can therefore resolve a capability to one or more provider packages and select the provider that fits the installation.

Keep capability declarations focused:

• Declare a capability only when the package actually provides the described function.
• Use stable domain-oriented IDs rather than IDs derived from a package name.
• Keep package dependencies, conflicts, and version requirements in composer.json.
• Do not describe MCP operations, operation inputs, validation steps, or agent skills in the capability block.
• Use useCases only as discovery hints. They do not install dependencies or define execution workflows.
• Pure helper libraries do not need capabilities unless they expose a meaningful function to the platform.

Capability declarations describe what a package provides. Composer describes the package dependency graph, while providers and other APIs describe how the function is integrated or executed.

Provider Declarations

Packages can declare provider classes in <provider>. Providers connect the package to platform or domain extension points.

<provider>
    <cookie src="\Vendor\Package\CookieProvider"/>
</provider>

The child node name is the provider type. The src attribute is the PHP class that implements the provider. Provider classes should be fully qualified and autoloadable through Composer.

<provider>
    <auth src="\Vendor\Package\Auth\Provider"/>
    <desktopSearch src="\Vendor\Package\BackendSearch\Provider"/>
    <installationWizard src="\Vendor\Package\Installation\Wizard"/>
</provider>

Each provider type defines its own expected contract. For example, desktopSearch providers implement QUI\BackendSearch\ProviderInterface, while installationWizard providers implement QUI\InstallationWizard\InstallationWizardInterface.

QUIQQER core provides platform provider types such as auth, desktopSearch, installationWizard, rest, and mcp. Other packages can add additional provider APIs by reading provider declarations from installed packages. For example, quiqqer/ai-mcp 1.5.0 and later reads mcpSkill providers for MCP skill registration.

<provider>
    <mcp src="\Vendor\Package\MCP\Provider"/>
    <mcpSkill src="\Vendor\Package\MySkillProvider"/>
</provider>

Only declare providers that the package actually implements.

Real Package Shape

A module can combine localized metadata, previews, support links, and Composer metadata. quiqqer/bricks is a good module reference for package metadata, image previews, support links, and Composer alignment.

<quiqqer>
    <package>
        <title>
            <locale group="quiqqer/bricks" var="package.title"/>
        </title>

        <description>
            <locale group="quiqqer/bricks" var="package.description"/>
        </description>

        <image src="URL_OPT_DIR/quiqqer/bricks/bin/images/Logo.jpg"/>

        <preview>
            <image src="URL_OPT_DIR/quiqqer/bricks/bin/images/preview/Bricks_1.jpg"/>
            <image src="URL_OPT_DIR/quiqqer/bricks/bin/images/preview/Bricks_2.jpg"/>
        </preview>
    </package>
</quiqqer>

A package can declare providers when it implements a platform extension point:

<quiqqer>
    <package>
        <title>
            <locale group="quiqqer/cache" var="package.title"/>
        </title>

        <description>
            <locale group="quiqqer/cache" var="package.description"/>
        </description>

        <provider>
            <cookie src="\QUI\Cache\CookieProvider"/>
        </provider>
    </package>
</quiqqer>

A template package can use the same metadata structure without domain providers:

<quiqqer>
    <package>
        <title>
            <locale group="quiqqer/template-presentation" var="package.title"/>
        </title>

        <description>
            <locale group="quiqqer/template-presentation" var="package.description"/>
        </description>

        <image src="URL_OPT_DIR/quiqqer/template-presentation/bin/img/Logo.png"/>
    </package>
</quiqqer>

Practical Checklist

Before publishing package.xml:

• Use localized title and description entries.
• Store package images under package assets and reference them with URL constants.
• Add support links that match the repository and issue tracker.
• Declare copyright and license information.
• Declare stable capabilities that the package actually provides.
• Declare only implemented providers.
• Keep provider classes autoloadable through Composer.
• Keep package metadata consistent with composer.json.