The .horde.yml File Format

This document describes the .horde.yml file format used by Horde Framework 6 components. The .horde.yml file serves as the canonical source of component metadata and is used by the horde-components tool to generate composer.json files and manage releases. For older versions of this format, see Doc/Dev/HordeYmlFormat


 Overview

The .horde.yml format has evolved from Horde Framework 5.2 through the git split and into Horde 6. 
It provides a unified way to declare component metadata, dependencies, autoloading rules and other configuration that can be transformed into various package management formats.

Key characteristics:


    YAML 1.2 format
    Single source of truth for component metadata
    Generates composer.json automatically via horde-components tool
    Supports both composer-native and legacy PEAR dependencies
    Provides autoloading configuration for PSR-0, PSR-4 and classmap strategies


 Meta Data Section

These fields appear at the top level of the .horde.yml file and define the component's identity and basic properties.


 Required Fields

id (string, mandatory)


    Component identifier
    For libraries: uppercase without Horde_ prefix (e.g., Autoloader, Exception, Browser)
    For applications: lowercase (e.g., horde, turba, ansel)

name (string, mandatory)


    Display name with proper capitalization (e.g., Horde, Turba, Autoloader, Exception)

full (string, mandatory)


    One-line description of the component
    Should be concise and descriptive

description (string, mandatory)


    Multi-line description of the component
    Can use YAML multi-line string syntax (>- for folded strings)
    Provides detailed information about component functionality

list (string, mandatory)


    Mailing list appropriate for the component
    Common values: dev, horde, or application-specific list names
    May be empty string if no specific list applies

type (string, mandatory)


    Component type indicator
    Classic values: application, library - these work for regular composer packages.
    Modern Horde 6 values: horde-application, horde-library, horde-theme, component - these trigger special handling by the horde/horde-composer-plugin installer for components which need it.
    Used to determine composer package type

authors (list, mandatory)


    List of contributor information
    Each entry has the following attributes:

 name (string): Full name of the contributor
 user (string): Horde username or identifier
 email (string): Email address
 active (boolean): true if currently active, false if inactive
** role (string): Contributor role (lead, developer, contributor)

version (object, mandatory)


    Contains two sub-keys:

 release (string): Current release version in semantic versioning format (e.g., 3.0.0-alpha10)
 api (string): Current API version (e.g., 3.0.0alpha1)


    Version numbers follow semantic versioning with optional stability suffixes
    Pre-release versions use formats like: 1.0.0-alpha1, 2.0.0-beta3

state (object, mandatory)


    Contains two sub-keys:

 release (string): Release stability (stable, beta, alpha)
 api (string): API stability (stable, beta, alpha)


    API stability can differ from release stability

license (object, mandatory)


    Contains two sub-keys:

 identifier (string): SPDX license identifier (e.g., LGPL-2.1-only, BSD-2-Clause, GPL-2.0-only)
 uri (string): Link to full license text (e.g., http://www.horde.org/licenses/lgpl21)


 Optional Fields

homepage (string)


    URL to component's homepage or documentation
    Typically https://www.horde.org/libraries/Horde_ComponentName or https://www.horde.org/apps/appname

vendor (string)


    Composer vendor name
    Defaults to "horde" if not specified
    Used to generate composer package name (vendor/id)

!++ Example Meta Data

^
---
id: Browser
name: Browser
full: Browser detection library
description: >-
  A library for getting information about the current user's browser and its
  capabilities.
list: dev
type: library
homepage: https://www.horde.org/libraries/Horde_Browser
authors:
  -
    name: Chuck Hagenbuch
    user: chuck
    email: chuck@horde.org
    active: false
    role: lead
  -
    name: Michael Slusarz
    user: slusarz
    email: slusarz@horde.org
    active: false
    role: developer
version:
  release: 3.0.0-alpha10
  api: 3.0.0alpha1
state:
  release: alpha
  api: alpha
license:
  identifier: LGPL-2.1-only
  uri: http://www.horde.org/licenses/lgpl21
vendor: horde
^


 Dependencies Section

The dependencies section declares required, optional and development dependencies. It supports PHP version constraints, PHP extensions, composer packages and legacy PEAR packages.

Don't use PEAR packages anymore. It's strictly for Backwards Compatibility.

!++ Structure

^
dependencies:
  uses: readonly-parameters           # Optional: special feature flags
  required:
    php: version-constraint           # PHP version requirement
    ext:                              # PHP binary extensions
      extension-name: version-constraint
    composer:                         # Composer packages
      vendor/package: version-constraint
    pear:                             # Legacy PEAR packages
      channel/package: version-constraint
  optional:
    composer:                         # Optional composer packages
      vendor/package: version-constraint
    ext:                              # Optional PHP extensions
      extension-name: version-constraint
    pear:                             # Optional PEAR packages
      channel/package: version-constraint
  dev:
    composer:                         # Development-only composer packages
      vendor/package: version-constraint
^

!++ Required Dependencies

dependencies: required: php (string)


    PHP version constraint using composer syntax
    Examples: ^7.4 || ^8, ^8, ^8.2
    Determines minimum PHP version

dependencies: required: ext (object)


    Map of PHP extension names to version constraints
    Version constraint can be '*' for any version or a specific version
    Common extensions: hash, pdo, gettext, gd, imagick

dependencies: required: composer (object)


    Map of composer package names to version constraints
    Package names in vendor/package format
    For Horde packages: horde/package-name (lowercase)
    Version constraints use composer syntax: ^3, ^3.0, ~2.0.0, >=1.0

dependencies: required: pear (object)


    Map of PEAR package names to version constraints
    Package names in channel/package format (e.g., pear.horde.org/Horde_Date)
    Primarily for legacy compatibility
    Horde 6 components prefer composer dependencies

!++ Optional Dependencies

dependencies: optional (object)


    Same structure as required section
    Declares suggested packages that enhance functionality
    Can contain composer, ext and pear sub-keys
    Used for feature-specific dependencies

!++ Development Dependencies

dependencies: dev: composer (object)


    Development-only composer dependencies
    Typically includes testing tools and code quality tools
    Examples: horde/test, phpunit/phpunit, phpstan/phpstan
    Generates composer.json require-dev section

!++ Special Features

dependencies: uses (string)


    Declares special language or framework features in use
    Currently known value: readonly-parameters
    Used for compatibility checking and code analysis

!++ Example Dependencies

^
dependencies:
  uses: readonly-parameters
  required:
    php: ^8.2
    ext:
      hash: '*'
      gettext: '*'
    composer:
      horde/exception: ^3
      horde/translation: ^3
      horde/util: ^3
  optional:
    ext:
      gd: '*'
      imagick: '*'
    composer:
      horde/cache: ^3
      horde/log: ^3
  dev:
    composer:
      horde/test: ^3
      phpunit/phpunit: ^12 || ^11
      phpstan/phpstan: ^2
^


 Autoload Section

The autoload section defines how PHP classes should be found within the component. It supports PSR-0, PSR-4 and classmap strategies.

!++ Structure

^
autoload:
  psr-0:                              # PSR-0 autoloading
    Class_Prefix: lib/
  psr-4:                              # PSR-4 autoloading
    Vendor\Namespace\: src/
  classmap:                           # Classmap autoloading
    - lib/
    - other-dir/
^

The horde-components tool auto-senses some common autoloading patterns and sets up defaults if no autoload section is present.

!++ Autoload Strategies

autoload: psr-0 (object)


    Map of class name prefixes to directories
    Legacy autoloading standard using underscores as directory separators
    Example: Horde_Http in lib/ directory
    Directory is relative to component root
    Using PSR-0 autoloader with "" namespace should be avoided. Use the classmap instead.

autoload: psr-4 (object)


    Map of namespaces to directories
    Modern autoloading standard using namespace separators
    Namespace must end with backslash
    Example: Horde\Browser\ maps to src/
    Directory is relative to component root

autoload: classmap (array)


    List of directories to recursively scan for PHP files
    Each PHP file is scanned for class definitions
    Useful for legacy code without consistent naming
    Example: ['lib/'] scans all PHP files in lib/ directory

!++ Autoload-Dev Section

autoload-dev (object)


    Same structure as autoload section
    Applied only in development context
    Typically used for test namespaces
    If test directory exists, PSR-4 rule is auto-generated for Vendor\Package\Test\ namespace

!++ Default Behavior

If no autoload section is present, horde-components will auto-detect:


    If lib/ directory exists: generates PSR-0 rule from package name
    If src/ directory exists: generates PSR-4 rule from package name
    If test/ directory exists: generates PSR-4 autoload-dev rule for Test namespace

!++ Example Autoload

^
autoload:
  psr-0:
    Horde_Browser: lib/
  psr-4:
    Horde\Browser\: src/
  classmap:
    - lib/legacy/
^

^
autoload:
  classmap:
    - lib/
  psr-4:
    Horde\Ansel\: src/
^


 Composer Integration

Several additional sections support composer-specific features.

!++ Commands Section

commands (array, optional)


    List of paths relative to package root offered as vendor binaries
    If provided, no automatic search in bin/ directory occurs
    Each path should point to an executable file
    These become composer bin entries

nocommands (array, optional)


    List of paths relative to package root excluded from vendor binaries
    Takes precedence over commands list or implicitly found bin/ executables
    Used to exclude non-binary files from bin/ directory

Example:
^nocommands:
  - bin/horde-bootstrap
  - bin/horde-components-prototype-transpile
^

!++ Conflicts Section

conflicts (object, optional)


    Declares package conflicts in composer format
    Directly transformed into composer.json conflict section
    No composer or pear sub-keys (flat structure)
    Used to prevent incompatible versions from coexisting

Example:
^conflicts:
  horde/base: <= 5.9.9
  horde/horde: <= 5.9.9
^

Use conflicts when already-released packages have overly liberal constraints that allow problematic combinations.

!++ Provides Section

provides (object, optional)


    Declares virtual packages or capabilities provided
    Directly transformed into composer.json provide section
    No composer or pear sub-keys (flat structure)
    Used for interface compliance or successor relationships

Example:
^provides:
  horde/base: 6.1.1
  horde/user-management-api-implementation: 1.0
^

Use provides when:


    Multiple packages can satisfy the same capability
    Package is successor to another package (e.g., ingo succeeds forwards and vacation modules)
    Package provides an interface that others can depend on

!++ Allow-Plugins Section

allow-plugins (mixed, optional)


    Controls which composer plugins are allowed to run
    Can be tilde (~) to allow all plugins
    Can be object mapping plugin names to boolean values
    Prevents composer from prompting about plugin permissions

Example:
^allow-plugins: ~
^

Example:
^allow-plugins:
  horde/horde-installer-plugin: true
  composer/installers: true
^


 Quality Section

The quality section configures code quality tools.

!++ Structure

^
quality:
  phpstan:
    level: 9
  php-cs-fixer:
    enabled: true
^

!++ PHPStan Configuration

quality: phpstan: level (integer)


    Sets PHPStan analysis level (0-9)
    Higher levels are more strict
    Level 9 is the maximum strictness

This setting instructs the horde-components qc and ci to FAIL if a previous water mark was no longer achieved.


 Complete Examples

!++ Modern Horde 6 Library

^
---
id: Browser
name: Browser
full: Browser detection library
description: >-
  A library for getting information about the current user's browser and its
  capabilities.
list: dev


    use horde-library if you need integration with the horde/horde-installer-plugin, i.e. javascript files which need to be exposed to web/ directory or horde database migrations in the migration/ directory. Otherwise use "library"

type: library
homepage: https://www.horde.org/libraries/Horde_Browser
authors:
  -
    name: Chuck Hagenbuch
    user: chuck
    email: chuck@horde.org
    active: false
    role: lead
version:
  release: 3.0.0-alpha10
  api: 3.0.0alpha1
state:
  release: alpha
  api: alpha
license:
  identifier: LGPL-2.1-only
  uri: http://www.horde.org/licenses/lgpl21
dependencies:
  required:
    php: ^7.4 || ^8
    composer:
      horde/exception: ^3
      horde/translation: ^3
      horde/util: ^3
vendor: horde
^

!++ Application with Mixed Dependencies

^
---
id: ansel
name: Ansel
full: Photo gallery application
description: Ansel is a full featured photo gallery application.
list: ansel
type: application
homepage: https://www.horde.org/apps/ansel
authors:
  -
    name: Michael J Rubinsky
    user: mrubinsk
    email: mrubinsk@horde.org
    active: true
    role: lead
version:
  release: 4.0.0-alpha6
  api: 4.0.0alpha1
state:
  release: alpha
  api: beta
license:
  identifier: GPL-2.0-only
  uri: http://www.horde.org/licenses/gpl
dependencies:
  required:
    php: ^7.4 || ^8
    composer:
      horde/horde: ^6
      horde/core: ^3
      horde/form: ^3
      horde/image: ^3
    ext:
      gettext: '*'
      hash: '*'
  optional:
    composer:
      horde/service_twitter: ^3
      horde/service_facebook: ^3
    ext:
      gd: '*'
      imagick: '*'
autoload:
  classmap:
    - lib/
  psr-4:
    Horde\Ansel\: src/
vendor: horde
^

!++ Component with Quality Tools

^
---
id: components
name: Components
full: Developer tool for managing Horde components
description: >-
  The package provides utility methods required when preparing a new component
  release for Horde. It also includes quality control checks.
list: horde
type: component
authors:
  -
    name: Jan Schneider
    user: jan
    email: jan@horde.org
    active: true
    role: lead
version:
  release: 1.0.0-alpha39
  api: 1.0.0alpha1
state:
  release: alpha
  api: alpha
license:
  identifier: LGPL-2.1-only
  uri: http://www.horde.org/licenses/lgpl21
dependencies:
  required:
    php: ^8.2
    composer:
      horde/cli: ^3
      horde/argv: '*'
      horde/util: '*'
  optional:
    composer:
      horde/test: ^3
      phpunit/phpunit: ^9
  dev:
    composer:
      horde/test: ^3
      phpunit/phpunit: ^12 || ^11 || ^10 || ^9
nocommands:
  - bin/horde-bootstrap
  - bin/horde-components-prototype-transpile
allow-plugins: ~
quality:
  phpstan:
    level: 9
vendor: horde
^


 Related Tools

The .horde.yml file is primarily managed by the horde-components tool:


    Validates .horde.yml syntax and completeness
    Generates composer.json from .horde.yml
    Updates version numbers during releases
    Transforms PEAR dependencies to composer equivalents
    Manages release workflow

For more information on release management, see Doc/Dev/ReleaseProcess.


 Migration from Horde 5

When migrating from Horde 5 to Horde 6:


    Update type from "library" or "application" to "horde-library" or "horde-application" if applicable - if default composer behaviour is sufficient, keep the default types.
    Convert pear dependencies under dependencies:required:pear (dependencies:required:pear) to composer dependencies
    Add vendor: horde if not present (automatic update by some horde-components operations)
    Update PHP version constraints. Horde 6.0 targets php 8.1-8.5 but if you really support older versions, say so. 
    Review and update license identifiers to use most recent edition of SPDX format
    Only add autoload section if auto-sensing doesn't get it right.
    Consider adding quality section for static analysis (can be done by horde-components qc --fix command)


 See Also


    Doc/Dev/ReleaseProcess - Component release workflow
    Doc/Dev/ComposerIntegration - Composer integration details
    horde-components - Component management tool