README

Synchronizes Composer packages of type dravencms-package: configuration installation and public asset publishing are independent. Requires PHP 8.2+ and a filesystem/web server supporting directory symlinks. There is no copying fallback for public assets.

Package metadata

{
  "type": "dravencms-package",
  "require": {"dravencms/packager": "^3.0"},
  "extra": {
    "dravencms": {
      "configuration": "dravencms.config.neon",
      "assets": {"public": "%wwwDir%/assets/example"}
    }
  }
}

Only publish a directory containing runtime assets. Do not link a whole package or its development assets/ directory. Asset mappings name directories, without globs; destinations must be below %wwwDir%/assets/. The old files asset mappings are rejected. Generic non-public files installation is unchanged.

Project setup and migration

Run packager:sync in the project's Composer post-install-cmd and post-update-cmd:

php vendor/dravencms/packager/bin/packager packager:sync --no-interaction

Each invocation reconciles assets for all packages, even already installed packages and packages whose locally changed configuration is kept. Noninteractive config synchronization keeps project configuration. Assets can be synchronized separately:

php vendor/dravencms/packager/bin/packager packager:assets

For an existing installation with copied asset directories, upgrade all asset-owning packages with Packager 3. Skip Composer scripts on this first upgrade, then migrate:

composer install --no-scripts
php vendor/dravencms/packager/bin/packager packager:assets --migrate-copies
composer run-script post-install-cmd --no-interaction

Migration moves existing directories, including custom files, to var/packager/asset-backups/<timestamp>/assets/ outside the web root before replacing them with links. Inspect any custom changes there and move project-owned assets to a separate namespace. Normal synchronization refuses destination collisions. Unmanaged files and symlinks are never replaced. The full plan is checked before changes, and link/directory changes roll back if synchronization fails.

Links are relative, for example www/assets/example -> ../../vendor/example/plugin/public, so complete release directories can move. The web server must follow symlinks and have access to their targets. Runtime assets must remain available in deployed vendor packages. Deploy the complete vendor tree before switching a release live.

Ownership is recorded in var/packager/assets.json; persist it with the project and ignore var/packager/ in Git. Removing a Composer package unlinks only its recorded mount, leaving package files and project assets alone. A matching preexisting relative link can be adopted. Do not put this state in a cache directory or the web root.

Commands

php vendor/dravencms/packager/bin/packager packager:sync
php vendor/dravencms/packager/bin/packager packager:assets [--migrate-copies]
php vendor/dravencms/packager/bin/packager packager:install dravencms/example
php vendor/dravencms/packager/bin/packager packager:uninstall dravencms/example [--purge]

Uninstall removes the configuration include and managed links; --purge also removes the generated configuration file. If the Composer package is still installed, the next synchronization restores its links.

Building package public directories

Commit an explicit array of runtime paths in assets/public-assets.json, and run vendor/bin/build-public-assets from the package root. Add the Composer script "build:assets": "build-public-assets" for maintainers. CSS imports and local url() dependencies are collected recursively, preserving relative paths. Missing/escaping sources and non-runtime files fail the build. The builder verifies previously generated files before replacing the public directory and removes obsolete generated files.

Commit the resulting public/ and public-assets.manifest.json in releases. Builds are a maintainer step; Composer installation uses the committed output and needs no Node dependencies or frontend build tools.

Tests

After composer install, run composer test. Filesystem and command tests use only temporary fixtures and do not bootstrap an application or database.

License

LGPL-3.0.