AeonDumpManager/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

AeonDumpManager is a Shopware 6 plugin (shopware-platform-plugin) that manages database dumps for Shopware 6 development environments. It lists, creates, and deletes gzip-compressed mysqldump/ mariadb-dump SQL dumps, both from a Settings-page admin UI (async creation with a polling progress bar) and via aeon:dump:{list,create,remove} console commands (sync creation). Design decisions and the full build spec live under .scratch/admin-dump-manager/ and .scratch/dump-manager-implementation-spec/ (Wayfinder maps) — consult those before changing the dump-creation/retention/ACL behavior.

• Plugin bootstrap class: src/AeonDumpManager.php (extends Shopware\Core\Framework\Plugin) — this is the entry point Shopware calls for install/uninstall/activate/deactivate/update lifecycle hooks.
• Plugin class name is wired via composer.json → extra.shopware-plugin-class.
• Services are registered manually in src/Resources/config/services.yaml (Symfony DI, YAML format, autowiring is not configured — every new service/command/task must be added here explicitly with its tag, e.g. console.command or shopware.scheduled.task).
• Plugin store-config UI fields (e.g. maxDumps, retantionDays) are defined in src/Resources/config/config.xml and read at runtime via Shopware's SystemConfigService.
• src/Resources/app/administration/ holds the admin UI module (Vue-based Shopware Administration extension). The aeon-dump-manager module (src/module/aeon-dump-manager/) provides the list page (page/aeon-dump-manager-list), en-GB/de-DE snippets and ACL privilege roles (acl/: viewer, creator, deleter); src/service/dump-api.service.ts is the client for the dump API routes.

Running the plugin

There is no standalone runtime — this plugin only runs inside a Shopware 6 instance. Local dev uses docker-compose.yml, which mounts the repo into a dockware/shopware container at custom/plugins/AeonDumpManager:

docker compose up -d

Shop/Admin/Adminer are all served on port 80/443; SSH into the container on port 22 (SSH_USER=shopware / SSH_PWD=shopware); admin-watcher and storefront-watcher proxies are exposed on 8888/9998/9999 for bin/build-administration.sh --watch style workflows run inside the container.

Plugin install/activate must be done through Shopware's own tooling inside the container (e.g. bin/console plugin:refresh, bin/console plugin:install --activate AeonDumpManager) — there is no composer script for this in this repo.

The container's internal processes run as uid/gid 33 (www-data). The repo directory on the host is group-owned by that group with setgid bit set (chgrp -R 33 + chmod g+s), so both the container and host users in group 33 can write without ownership fights.

Tests

PHPUnit, bootstrapped through Shopware's own TestBootstrapper (tests/TestBootstrap.php), which activates this plugin inside a real Shopware kernel for the test run (KERNEL_CLASS is set to Shopware\Core\Kernel in phpunit.xml). This means tests require a working Shopware installation/DB to bootstrap against — they are not runnable as an isolated PHP package.

In CI (phpunit job) the latest Shopware version allowed by the plugin's require.shopware/core constraint is resolved with Composer. The prepared project (composer create-project + phpunit, then system:install into shopware_test on a MariaDB 10.11 service) plus a SQL dump of the installed database are cached under a key that contains that version, so a new Shopware release invalidates the cache. On a hit the dump is restored instead of reinstalling; the plugin is then copied into custom/plugins and the bootstrapper only activates it.

vendor/bin/phpunit                              # full suite
vendor/bin/phpunit --filter TestClassName        # single test class
vendor/bin/phpunit tests/SomeTest.php            # single file

Dependencies

• PHP ^8.2, shopware/core ~6.7.0 (from composer.json); phpunit/phpunit ^10.0 as the only dev dependency.
• PSR-4 autoload: AeonDumpManager\ → src/, AeonDumpManager\Tests\ → tests/.

CI / release pipeline

Gitea workflows in .gitea/, plugin-agnostic (name/version come from composer.json). shopware-cli runs from its official Docker image, intentionally unpinned (latest): a red build after a CLI release means fix the config.

• workflows/plugin-checks.yml (PRs into main) has three jobs: version-changelog (the composer.json version must be greater than the latest published Gitea release and have a matching ## [x.y.z] CHANGELOG heading), package (shared composite action actions/package: shopware-cli extension package, extension validate on the zip, scripts/ci/assert-built-assets.sh), and phpunit. The package job caches the tested zip keyed by the commit's tree hash.
• workflows/release.yml (push to main, serialized; every step is idempotent so a failed run can simply be re-run): reuses the cached zip when the tree hash matches (else packages again, always re-validates), creates the Gitea release + tag via API with the zip as asset, publishes a root-level repack of the zip to the Composer registry (Gitea requires composer.json at the zip root), then links the package to the repo. Uses RELEASE_TOKEN.
• Required checks on main (plugin-checks / version-changelog|package|phpunit (pull_request)) are set once with scripts/protect-main.sh (tea api). Build excludes/validation live in .config/shopware-extension.yml. Background: docs/spec/shopware-guideline-compliance.md.

Adding functionality

• New console commands go in src/Command/, new scheduled tasks in src/ScheduledTask/ — both must be registered in src/Resources/config/services.yaml with the appropriate tag or Shopware will not discover them.
• Scheduled tasks need a matching handler (tagged messenger.message_handler) to actually run; a bare ScheduledTask subclass like ExampleTask only defines the schedule, not the behavior.