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
^
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
^
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
^
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
^
allow-plugins: ~
^
^
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 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)