Cms Composer Installers Laravel Package

Getting Started

Start by installing the package in a TYPO3 project using Composer:

composer require typo3/cms-composer-installers

This package is a Composer plugin and should be added automatically when you require typo3/cms-core (for TYPO3 12+), or explicitly in projects using typo3/cms v11.5 with legacy layout. Once installed, it modifies how Composer installs TYPO3 core and extensions to match TYPO3’s runtime expectations.

Your first day-to-day interaction will be ensuring your composer.json includes the correct web-dir in the extra section:

"extra": {
  "typo3/cms": {
    "web-dir": "public"
  }
}

This tells TYPO3 where the web-accessible document root is (default: public/). Then, require extensions using typo3-cms-extension type, and make sure each extension defines its extension-key.

Implementation Patterns

• Extension packaging: When developing or consuming TYPO3 extensions, ensure the extension’s composer.json includes:

  "extra": {
    "typo3/cms": {
      "extension-key": "my_extension"
    }
  }
  

  This is required for v4+ of the plugin — missing it breaks the extension silently at runtime.

• Resource management: With all extensions installed under vendor/ (v4+ behavior), public assets (e.g., CSS, JS, icons) must live in Resources/Public/. The plugin auto-symlinks these into public/typo3conf/ext/[key]/ at compile time. Use TYPO3’s core utility to generate public paths:

  $path = PathUtility::getAbsoluteWebPath(
    GeneralUtility::getFileAbsFileName('EXT:my_extension/Resources/Public/Icons/Icon.svg')
  );
  

• Build workflows: The plugin integrates into composer install/update, so CI/CD pipelines should run composer dump-autoload --optimize and composer install --no-dev --optimize-autoloader to avoid runtime path issues. Avoid manual file copying or symlinking — let the plugin handle path mapping.

• Upgrading from legacy: If pinned to v3.x due to hard-coded paths in old extensions (typo3conf/ext/...), explicitly require:

  composer require typo3/cms-composer-installers:^3.1
  

  but migrate extensions to the new Resources/Public pattern as soon as possible.

Gotchas and Tips

• Breaking change: web-dir must be a subdirectory of the project root — v4+ disallows setting . or app-dir/root-dir. Verify your CI configurations don’t rely on legacy layout assumptions.

• Extension key typos: Composer emits a warning if extension-key is missing, but extensions may still be installed incorrectly. Always run composer validate and check logs on composer install.

• Path utilities are non-negotiable: Never hardcode paths like typo3conf/ext/my_ext/Resources/Public/.... Always use PathUtility::getAbsoluteWebPath() to avoid broken URLs in production (where vendor/ is not web-accessible).

• PHP 8.1+ only: The latest versions require PHP ≥8.1. Avoid updating if stuck on older PHP unless you lock to v3.x.

• Use composer run-scripts for post-install hooks: The plugin exposes Composer events — leverage scripts like @auto-update to regenerate routes or flush caches if needed post-deploy.

• Debugging path issues: Enable COMPOSER_DEV_REFERENCE=true and run composer diagnose — it will check web-dir validity and whether paths resolve. Also inspect vendor/typo3/cms-composer-installers/ cache files: .typo3-extension-paths.php and .typo3-web-path.php show the computed mappings.

• Tip for monorepos: If using monorepos or custom build folders, override only web-dir in the root composer.json. The plugin is intentionally minimal — avoid complex extra config beyond what’s documented.