muckiware / facility-plugin
Muckiware Facility Plugin for Shopware 6
Package info
github.com/muckiware/MuckiFacilityPlugin
Type:shopware-platform-plugin
pkg:composer/muckiware/facility-plugin
Requires
- php: ~8.3.0 || ~8.4.0 || ~8.5.0
- ext-sodium: *
- aws/aws-sdk-php: ^3.369
- dragonmantank/cron-expression: ^3.6
- gabrielelana/byte-units: ^0.5.0
- muckiware/restic: ^1.6
- shopware/core: ~6.6.10.14 || ~6.7.6
- spatie/db-dumper: ^3.8
Requires (Dev)
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- dev-main
- v0.11.0
- v0.10.1
- v0.10.0
- v0.9.0
- v0.8.3
- v0.8.2
- v0.8.1
- v0.8.0
- v0.7.0
- v0.6.1
- v0.6.0
- v0.5.0
- dev-release
- dev-chore/release-workflow
- dev-fix/backup-command-columns-nullable
- dev-feat/folder-browser
- dev-feat/schedule-management
- dev-feat/dashboard
- dev-feat/repository-password-encryption
- dev-feat/repository-status-tab
- dev-20-added-messagebus-dispatch-integration-for-backup-run
- dev-17-change-size-value-of-snapshots-as-metric-type
- dev-11-snapshots-remove-via-admin-snapshot-list
- dev-9-hostname-for-restic-snapshots
- dev-12-remove-repository-password-of-api-content
- dev-8-webp-image-converter
- dev-dev
- dev-feature-cli-command-backup
This package is auto-updated.
Last update: 2026-11-21 08:35:24 UTC
README
Muckiware Facility Plugin for Shopware 6 Web shops for to maintenance and backup of the database.
- The plugin provides a backup functionality for the database.
- Creates a backup of folders and files by an individual configuration into repository database. The plugin use the restic backup tool for to create the backups. https://restic.readthedocs.io/
- The backups will be encrypted by a password.
- Cleanups tables like cart, if the database table grow up in too large.
Requirements
- Shopware 6.6.10.11 or greater or 6.7.6.0 or greater
- PHP 8.3.x or greater
- restic 0.15.x or greater
Installation
composer require muckiware/facility-plugin bin/console plugin:install -a MuckiFacilityPlugin
Repository password secret
Repository passwords created through the administration are stored encrypted. The key is derived
from the environment variable MUWA_FACILITY_SECRET, which you have to add to your .env:
echo "MUWA_FACILITY_SECRET=$(openssl rand -hex 32)" >> .env
Keep this value with your disaster recovery notes. Without it, no encrypted repository password can be read back — not even from a restored database. Restoring a shop onto a fresh host with a newly generated secret means the repository passwords are lost, and with them access to the backups.
If you would rather keep no secret in the database at all, see Password sources.
General Configuration
Plugin configuration under:
Settings -> Extensions -> My extensions -> MuckiFacilityPlugin -> Configure
| Option | Desc |
|---|---|
| Global settings - Active | Turn plugin on/off global |
| Global backup settings -> Active database backup | Turn backup database on/off global, for cli command bin/console muckiware:db:dump <Type of backup> |
| Global backup settings -> Compress database backup file | Turn on/off compressen for db dump, for cli command bin/console muckiware:db:dump <Type of backup> |
| Global backup settings -> Use own restic path | Turn on/off own restic |
| Global backup settings -> Own path to binary of restic | Enter the absolut path to binary file of restic. Example input: /var/www/html/bin/restic_0.17.3_linux_386 |
| Dashboard -> Show backup status on the dashboard | Shows a card with the latest repository status (date, next scheduled backup, repository size, number of snapshots, backup duration, check status) of every active backup repository on the administration dashboard. Off by default. Requires the muwa_backup_repository.viewer permission and system_config:read. |
| Dashboard -> Show S3 mirror status on the dashboard | Shows a separate card with the latest S3 mirror run of every active repository with an S3 mirror target: target (bucket/prefix, connection), status, last run, last successful run, uploaded/deleted files and data volume. The error/skip message is shown as tooltip of the status. Switched on and off independently of the backup status card, which no longer has an S3 column. Off by default. Same permissions as above. |
Respoitory Configuration
First you will need a repository configuration for the backup. The repository configuration is the base for the backup process. The repository configuration contains the backup source and the backup target. The backup source is the path to the folder or file which should be backuped. The backup target is the path to the repository where the backup data should be restored.
Settings -> Extensions -> Backup Repositories -> Add Repository
for to create a new repository configuration.
General Configuration Setup
| Option | Desc |
|---|---|
| Active | Turn repository on/off |
| Technical Name | Free choose as a technical name, is just for better to organize the backup configurations |
| Database dump type | Choose the typ of database dump backup. As separate dump files for each table, only one dump file for the complete database, or none database dump. |
| Repository Path | Absolute path to the backup repository folder. Note that this path cannot be changed after creation! |
| Hostname | Client hostname for the backup snapshots, default hostname is muwa-facility-client |
| Repository Password | The backup repository will be encryped by a password. Remembering this password is very important! If you lose it, you won’t be able to get access to the data stored in the repository outside of the shop functionality. Note that this password cannot be changed after creation! |
| Restore Path | Enter here the absolute path for the target of the restored data. |
Backup Paths
Use the Add backup path-button for to define the files and folders which should be backup. You can choose a complete folder, or a single file.

You can define for each path item a compress option. If the compress option is active, the backup data will be compressed by gzip. For folders which containing mainly compressed image files, additional compression during backup would make less sense.
Commands before and after a backup
A repository can run an optional command before and after a backup. Select Batch / shell script
to execute a .sh file with /bin/bash. The script can either be selected from the server or
uploaded in the administration. Uploaded scripts are stored in
files/private/mucki-facility/batch/; uploading the same filename again overwrites the existing
file. After an upload, the absolute script path is written to the Shell script field
automatically.
Arguments belong in the separate Arguments field, not behind the script path. For example:
| Field | Example |
|---|---|
| Shell script | /var/www/html/files/private/mucki-facility/batch/cron_before.sh |
| Arguments | /var/www/html --mode "full backup" |
The script receives these values as normal positional arguments ($1, $2, $3, ...). Argument
parsing follows these rules:
- Spaces, tabs and line breaks separate arguments.
- Wrap a value containing whitespace in single or double quotes, for example
"value with spaces"or'value with spaces'. - Outside single quotes, a backslash escapes the following character, for example
value\ with\ spaces. - Unclosed quotes and a trailing backslash are rejected.
- A null byte (
\0) cannot be passed as a process argument. - Characters such as
/ : . _ - = @ # % , ; & | $ ( )are allowed.
Arguments are passed directly to the process without invoking a shell. Shell syntax is therefore
not evaluated: values such as ;, &&, $HOME, $(command), * and ~ are passed literally.
This prevents an argument from starting an additional shell command. If expansion is required, the
shell script must implement it explicitly.
The administration field has no explicit character limit and the value is stored as LONGTEXT.
The operating system still limits the combined size of process arguments and environment variables
(ARG_MAX), so the field should be used for command parameters rather than large payloads.
Delete of snapshots
You can remove old snapshots of a repository with the command.
bin/console muckiware:backup:snapshots <backupRepositoryId> --remove <snapshotIds>
The snapshot ids are passed as comma separated list to the --remove option, for example
--remove 8888ec40,79766175.
This setup defines the daily, weekly, month or yearly values for this remove process. More details about the keep-parameters you can find in the restic documentation https://restic.readthedocs.io/en/latest/060_forget.html#removing-snapshots-according-to-a-policy
Initial Backup
Finally, click on the Create new Repository-button, for to create a new backup repository. This action creates then a configuration item in the shop database. And it creates the backup repository folder which is defined in the Repository Path field.
Take over an existing repository
An existing local restic repository (for example one that was filled by a shell script and a cronjob) can be added to the management instead of creating a new empty one.
Settings -> Extensions -> Backup Repositories -> Add Repository opens a dialog with two options:
New repository leads to the unchanged create page, Take over existing repository asks for
the path of the restic repository, its password and the restore path (required). The restore path
follows the same rules as the restore directory (Settings::getRestorePathRejection(): no overlap
with the repository or dump path, no project or system folder); otherwise the takeover is rejected
with MUWA_TAKEOVER_INVALID_RESTORE_PATH (meta.reason).
What happens:
- The repository stays where it is. It is only read (
restic snapshots); the takeover never callsinit,unlock,pruneorforgetand does not start a backup. - The snapshots are imported into the snapshot list. The name of the new configuration is the folder name of the repository, the hostname is taken from the most recent snapshot (without snapshots the plugin default is used). The password is stored encrypted like for every other repository and is never part of a log entry or an API response.
- Afterwards the detail page opens on the tab Configuration, where you complete the rest of the configuration. In this tab the backup paths of the existing snapshots are offered as suggestions (Adopt copies them into the backup paths; save to keep them).
Requirements and notes:
- Only local paths are supported (no
sftp:,s3:or other restic backends). - The web server user (the user running the shop and the worker) needs write permission on the
repository folder. Otherwise the takeover is rejected with a message in the dialog and no record is
created. A repository that is already managed is rejected as well. The duplicate check matches the
normalized path and its variant with a trailing slash; a record created via the normal create page
is stored as typed, so a differently written path (e.g. with a double slash) may not be detected.
The path must not be longer than 255 characters after normalization. If restic cannot read the
repository (wrong password, unreadable files, e.g. owned by root), the dialog shows restic's error
text. Other storage errors are reported as
MUWA_TAKEOVER_SAVE_FAILED. - Switch off the old cronjob or script. Otherwise two places back up to and clean up the same repository.
- The forget rules of the configuration also apply to the old snapshots of the repository. Check the retention values before the first backup run.
- The status tab (check result and repository statistics) is filled after the worker has run the
follow-up check, that is started by the takeover (
bin/console messenger:consume async). You can also fill it manually withbin/console muckiware:backup:check <backupRepositoryId>andbin/console muckiware:repository:stats <backupRepositoryId>. When the check is finished an administration notification appears.
Create Backup
cli
You can create a backup by the command line interface with the following command:
bin/console muckiware:backup:create <backupRepositoryId>
Administration panel
You can also create a backup in the administration panel.
- Go into the list of backup configurations under Settings -> Extensions -> Backup Repositories
- Select the backup repository
- Click on the Start backup-button

This action does not start the backup process immediately, it will be started as a background process. After a short while, you can see under the checks-tab the status of the backup checks, as well as the snapshots of each database and path item in the Snapshots-tab
At the end of every backup run, the repository statistics (total size, total file count, snapshots count, file system size) are collected and stored. You can see the latest values, plus a history of the last 10 collections, in the Repository Status-tab.
Scheduled backups
Each backup repository can have its own automatic backup schedule. Open the repository in the administration and select the Schedule-tab. The following options and runtime information are available:
| Option / value | Description |
|---|---|
| Active | Enables or disables automatic backups for this repository. |
| Cron expression | Defines when the backup is executed, for example 0 2 * * * for every day at 02:00. |
| Timezone (IANA) | Timezone used to evaluate the cron expression, for example Europe/Berlin or UTC. Daylight-saving time is taken into account. |
| Upcoming runs | Live preview of the next 5 runs of the entered cron expression, shown in the selected timezone and updated while typing. An invalid cron expression or timezone is flagged directly. |
| Status | Current state of the schedule: inactive, scheduled, queued, running, success, failed or skipped. |
| Last execution | Time of the latest completed execution. |
| Next execution | Time at which the next backup is due, shown in the selected timezone. The same value is shown in the column Next backup of the repository list and of the dashboard card "Backup status", there in the same format and timezone as Last backup run (or "No active schedule" if the schedule is switched off). |
| Last error | Error message from the latest failed or skipped execution. |
Cron expressions and timezones are validated when the schedule is saved. Runtime timestamps are
stored in UTC. If a backup is already running, another backup is not started; the scheduled run is
marked as skipped instead.
The preview is calculated by the same component as the scheduler itself, via the API route
POST /api/_action/muwa/backup/schedule/preview (ACL muwa_backup_repository:read). It does not
save anything:
// request { "cronExpression": "30 */3 * * *", "timezone": "Europe/Berlin" } // response 200 (times in UTC, ISO 8601) { "nextRuns": ["2026-11-19T14:30:00+00:00", "2026-11-19T17:30:00+00:00", "..."] }
An invalid cron expression or timezone returns HTTP 400. If timezone is omitted, UTC is used.
The scheduler uses Shopware's Scheduled Task and Message Queue systems. Both runners must therefore be active, for example as continuously running services:
bin/console scheduled-task:run bin/console messenger:consume async low_priority --time-limit=60
The task mucki_facility.dispatch_backup_schedules checks every 60 seconds for due schedules. Due
backups are queued and executed asynchronously, so the configured time can differ from the actual
start time by the polling and queue processing delay.
Command Line Interface
| Command | Desc |
|---|---|
bin/console muckiware:backup:check <backupRepositoryId> |
Checks a backup repository |
bin/console muckiware:backup:create <backupRepositoryId> |
Creates a new backup by backup repository configuration |
bin/console muckiware:backup:forget <backupRepositoryId> |
Removes snapshots of a backup repository by forget parameters |
bin/console muckiware:backup:snapshots <backupRepositoryId> |
Gets a list of snapshots in a backup repository id |
bin/console muckiware:repository:stats <backupRepositoryId> |
Collects and persists the repository status (total size, file count, snapshots count, file system size) |
bin/console muckiware:backup:restore <backupRepositoryId> <snapshotId> |
Restore data by backup repository id and snapshot id |
bin/console muckiware:db:dump <Type of backup> |
Creates just a database dump by global plugin setups |
bin/console muckiware:repository:upload <backupRepositoryId> [--force] |
Mirrors a repository to its configured S3 target (see S3 mirror) |
bin/console muckiware:backup:encrypt-passwords [--dry-run] |
Encrypts repository passwords that are still stored as plain text |
bin/console muckiware:backup:password-source <backupRepositoryId> <source> <value> |
Sets the password source of a repository (encrypted, env or file) |
Password sources
Every repository records where its password comes from. The column repository_password is read
according to that source:
| Source | Content of the column | Secret in the database |
|---|---|---|
encrypted |
ciphertext, prefix v1: |
yes, encrypted |
env |
name of an environment variable | no |
file |
path of a file | no |
plain |
the password itself (legacy) | yes, readable |
Repositories created in the administration use encrypted. To keep no secret in the database at
all, point a repository at an environment variable or a file:
bin/console muckiware:backup:password-source <backupRepositoryId> env MY_REPO_PASSWORD bin/console muckiware:backup:password-source <backupRepositoryId> file /run/secrets/repo-password
Both are verified when set, so an unreadable file or an empty variable fails right away instead of
at the next backup. A password file should not be readable by anyone but the shop user
(chmod 600), and it must live outside the document root.
plain only exists for repositories created before passwords were encrypted. Move them over with:
bin/console muckiware:backup:encrypt-passwords --dry-run bin/console muckiware:backup:encrypt-passwords
External cronjob alternative
The built-in scheduler described above is the recommended way to configure automatic backups per repository. Alternatively, you can invoke the CLI commands with an operating-system cronjob. The cronjob must run as the user that runs the Shopware instance. Example:
* 3 * * * php /var/www/html/bin/console muckiware:backup:create <backupRepositoryId> 30 5 * * * php /var/www/html/bin/console muckiware:backup:forget <backupRepositoryId> 0 6 * * * php /var/www/html/bin/console muckiware:repository:stats <backupRepositoryId>
The first row creates a backup every day at 3:00 am. The second row removes old snapshots every day at 5:30 am. Removing snapshots does not refresh the persisted repository status by itself, so the third row collects a fresh status right after, at 6:00 am.
Database dumps
Backups via command line interface are possible with the following commands:
bin/console muckiware:db:dump <backupType>
| Option backup type | Desc |
|---|---|
| completeDatabaseSingleFile (default) | Backup the complete database as single file. The backup is stored in the directory var/db/backup/ with the filename YYYY-MM-DD_HH-MM-SS_<dbname>.backup.sql.tar.gz |
| completeDatabaseSeparateFiles | Backup the complete database as single file for each database table. The backup is stored in the directory var/db/backup/YYYY-MM-DD with the filename YYYY-MM-DD_HH-MM-SS_<tablename>.backup.sql.tar.gz |
This command execute a backup of the database. Without a configured database dump path the backup is stored in the directory var/db/backup/.
With the plugin setting compressDbBackup the dump is packed into a tar.gz archive (*.backup.sql.tar.gz), otherwise it stays a plain *.backup.sql file.
The archive contains the plain *.backup.sql file and can be unpacked with:
tar -xzvf 2026-11-03_07-44-36_db.backup.sql.tar.gz
Database connections
By default a backup dumps the system database (DATABASE_URL). With a database connection a backup
configuration dumps another database instead, on the same server or on another host.
Create a connection
- Open the backup module in the administration and switch to the tab Database connections.
- Create a connection: name, type (
MySQL / MariaDB), host, port (empty = 3306), database name, user, password source and password. - Check it with Check connection. The check uses the form values, an empty password field uses the stored password.
- Choose the connection in the dropdown of the backup configuration. The first entry, Default connection (system), is the previous behaviour and the only entry as long as no connection exists. Existing configurations stay on the default connection.
The database user needs a password. The password is never sent back to the administration; when editing, leave the field empty to keep it.
Password sources
| Source | Content | Restriction |
|---|---|---|
encrypted |
the password, stored as ciphertext | needs MUWA_FACILITY_SECRET (see above) |
env |
name of an environment variable | the name must start with MUWA_DB_ |
file |
path of a file containing the password | the file must live under <projectDir>/var/secrets/; a relative path (var/secrets/db.pw) is resolved against the project directory |
plain is not available for database connections. The restrictions keep an administration user
from sending APP_SECRET or any server file as "password" to a database host of their choice; they
are checked when saving and again when the password is resolved.
Passwords with line breaks are rejected, and so are line breaks and NUL bytes in name, host, user
and database name (checked when saving and again before the dump). Passwords containing a single
quote (') are not supported: spatie/db-dumper writes the password in single quotes and without
escaping into the mysqldump credentials file, so such a password fails to log in.
If host, port, type or user of a stored connection change, or the password source changes, the
password has to be entered again. All connection fields can only be written through the
administration's save route (POST /api/_action/muwa/database-connection/save); the generic
entity API cannot change them. So a stored password is only ever sent to the host, port, type and
user it was entered for.
Deleting and errors
- A connection that is still used by a backup configuration cannot be deleted; the administration lists the configurations that use it.
- Default connection: behaviour unchanged, a failing dump is logged.
- Own connection: any error (connection not found, password not resolvable, no handler for the type, failing dump) aborts the whole backup run with a message naming the connection. There is no fallback to the system database and no incomplete dump is pushed to the repository.
- Table cleanup and
bin/console muckiware:db:dumpalways use the system database.
Support further database types
Connection data and dumper are resolved through the event mucki_facility.database_connection.resolve
(ResolveDatabaseConnectionEvent), dispatched before every dump and every connection check. The event
carries the type (getType()), the stored connection (getDatabaseConnection(), null = default
connection) and the backup settings (getBackupSettings(), null for a connection check). A listener
sets a ResolvedDatabaseConnection and a DatabaseDumperInterface (listTables(), dump(),
testConnection()). The built-in MysqlDatabaseConnectionSubscriber (priority 0) handles mysql and
only fills what is still missing, so a listener with a higher priority can replace the connection (for
example a password from a vault) and/or the dumper. Dumper errors must be thrown as
DatabaseBackupFailedException and must not contain the password.
// (imports and constructor omitted) class PostgresConnectionSubscriber implements EventSubscriberInterface { public static function getSubscribedEvents(): array { return [ResolveDatabaseConnectionEvent::NAME => ['onResolve', 10]]; } public function onResolve(ResolveDatabaseConnectionEvent $event): void { $connection = $event->getDatabaseConnection(); if ($event->getType() !== 'postgres' || $connection === null) { return; } $event->setResolvedConnection(new ResolvedDatabaseConnection( 'postgres', $connection->getHost(), $connection->getPort() ?? 5432, $connection->getDatabaseName(), $connection->getUsername(), $this->vault->read($connection) )); $event->setDumper($this->postgresDumper); // implements DatabaseDumperInterface } }
A plugin that also replaces the default connection must handle getDatabaseConnection() === null
(the example above leaves the default connection to the built-in subscriber).
Register the subscriber with the tag kernel.event_subscriber. The type is a free string on the
connection. The administration form offers mysql only; a connection of another type, created for
example by a plugin, keeps its type when edited.
Restore
As long as the shopware instance is running, you can restore the backup data via cli like this:
bin/console muckiware:backup:restore 019403b49bed7109a1e238139fb759c5 8888ec40
Or you can choose the snapshot id from the list of snapshots in the administration panel.
- Settings -> Extensions -> Backup Repositories
- Select the backup repository
- Click on the Snapshots-tab
- And select in die list of snapshots the snapshot id for to restore the data.
This action will start the restore process of the backup data as a background process.
Download restored database dumps
After a restore, the Snapshots-tab shows the panel Restored database files with a read-only tree of the
restore path. Database dumps (*.backup.sql, *.backup.sql.gz, *.backup.sql.tar.gz) have a download
button; other files are only listed.
- You need the
muwa_backup_repository:restoreprivilege. - The restore path of the repository must be an allowed path (it must not overlap with the database dump path or point to a system directory); otherwise the panel only shows a generic "restore path not allowed" message.
- The files must have been restored first, otherwise the panel is empty.
- Symbolic links are not listed. A download link is valid for 60 seconds and can be used once.
But if the shop instance is not running anymore, you can use the native restic commands for to restore the backup data.
restic -r /srv/restic-repo restore 79766175 --target /tmp/restore-workdir
Checkout the description of the restic command for more information. https://restic.readthedocs.io/en/stable/050_restore.html#
S3 mirror
A repository can be mirrored to an S3 compatible bucket (AWS S3, MinIO, Ceph, other) as an off-site copy.
The mirror copies the restic repository files as they are; the copy can be used with restic
directly (s3:<endpoint>/<bucket>/<prefix>).
Setup
- Open the backup module and switch to the tab S3 connections. Create a connection: name, provider, endpoint (not for AWS), region, access key id, secret source and secret access key. Check it with Check connection.
- Open the backup configuration, tab Configuration, section S3 mirror: choose the connection, the bucket and an optional prefix, then Save mirror target. Targets of different repositories must not overlap. Without a connection nothing is mirrored.
- Run a backup. After a green backup check the mirror is queued as a separate message, so a
running message worker is required:
bin/console messenger:consume async.
The first mirror of a large repository may take several runs and hours. The history (status, files,
data volume, message) is shown in the repository detail page, the latest state in the dashboard card
"S3 transfer status" (switched on with showS3MirrorDashboardWidget).
Secret sources
| Source | Content | Restriction |
|---|---|---|
encrypted |
the secret access key, stored as ciphertext | needs MUWA_FACILITY_SECRET (see above) |
env |
name of an environment variable | the name must start with MUWA_S3_ |
file |
path of a file containing the secret | the file must live under <projectDir>/var/secrets/ |
The secret is never sent back to the administration.
Safeguards
The mirror removes remote objects that restic deleted locally (forget, prune). It only touches keys
of the restic layout (data/, index/, keys/, snapshots/), never deletes config, and aborts
without remote changes when the local repository is locked by a running restic operation, when
the remote config belongs to a different repository, or when local data is missing.
- Use a dedicated bucket or prefix for this repository only. The mirror treats every key of the restic layout below the prefix as its own and deletes what no longer exists locally.
- The first run into a target never deletes. Deletes only happen when the remote
configexisted (and matched the local one) at the start of the run; otherwise the run only uploads and notes in its message that deletes were deferred. - Check gate. A mirror queued by a backup only uses the check of that backup run. If
restic checkitself fails (non-zero exit), a red check entry (check failed: ...) is stored and the mirror is skipped; it never falls back to an older green check. Only the CLI without check id uses the newest stored check. http://endpoints (MinIO/other) transfer request signatures and repository data unencrypted; use them only on local/internal networks. Two connections with the same host, port and path count as the same target regardless ofhttp/https.- The dashboard card "S3 transfer status" shows status, date and counters of the newest mirror run and the date of the last successful run. A succeeded run older than the newest check is shown as warning.
- Reading the upload history needs
muwa_backup_repository_uploads:read, which is part of the rolemuwa_backup_repository.viewer.
CLI
bin/console muckiware:repository:upload <backupRepositoryId> [--force]
Runs the mirror synchronously (e.g. for a cronjob without worker); it refuses to run while a backup
is running. --force mirrors even if the last repository check is not healthy.
Flow Builder events
The events mucki_facility.repository_upload.succeeded (RepositoryUploadSucceededEvent) and
mucki_facility.repository_upload.failed (RepositoryUploadFailedEvent) are available as Flow
Builder triggers, e.g. to send a mail. Data: backupRepositoryId, backupRepositoryName, status,
bucket, prefix, s3ConnectionName, startedAt, finishedAt, filesUploaded, filesDeleted,
bytesUploaded, message.
Database cleanup
This command offers a more effective option to clean up database tables as the origin Shopware function and free up more memory.
Cart Cleanup
bin/console muckiware:table:cleanup cart
Example
- Database table overview of cart before cleanup

- Execute the cleanup command

- After the cleanup, the table cart has become correspondingly much smaller size as before.
The maximum number of days that should remain in the cart table can be set in the plugin configuration.
## Log_Entry Cleanup ```shell bin/console muckiware:table:cleanup log_entry ```
Events
The plugin dispatches events over the Symfony event dispatcher at fixed points of the backup lifecycle and the repository management. Other plugins can subscribe to them, for example to ship backup results to an external monitoring system, to start follow-up jobs after a successful backup, or to log repository maintenance.
Backup lifecycle events
All event classes live in the namespace MuckiFacilityPlugin\Events. Listen for the event name
shown in the first column.
| Event name | Event class | Fired when | Payload |
|---|---|---|---|
mucki_facility.backup.before_create |
BeforeBackupCreatedEvent |
A backup run starts, after the optional pre-backup command and before the database and file backups. | getBackupSettings(): BackupRepositorySettings |
mucki_facility.database_dump.before_create |
BeforeDatabaseDumpCreatedEvent |
Immediately before the database dump is created. Only for the backup types completeDatabaseSingleFile and completeDatabaseSeparateFiles, also for a standalone dump via bin/console muckiware:db:dump <backupType>. |
getBackupSettings(): BackupRepositorySettings |
mucki_facility.database_dump.after_create |
AfterDatabaseDumpCreatedEvent |
A database dump was created successfully, with the results of this dump. | getBackupSettings(): BackupRepositorySettingsgetResults(): array<ResultEntity> |
mucki_facility.backup.after_create |
AfterBackupCreatedEvent |
The backup core, check, snapshot import and statistics collection completed successfully. | getBackupSettings(): BackupRepositorySettingsgetResults(): array<ResultEntity> (all results of the run) |
mucki_facility.backup.finished |
BackupFinishedEvent |
Exactly once after every started backup run, after after_create on success and also after a before/core/after failure. Fires before the duration is persisted. |
getBackupSettings(): BackupRepositorySettingsgetResults(): array<ResultEntity>getPrimaryError(): ?ThrowableisCoreSucceeded(): bool |
mucki_facility.backup.after_check |
AfterBackupCheckedEvent |
The backup check at the end of a backup run produced a check result, which is also persisted as check item. | getBackupRepository(): BackupRepositoryEntitygetCheckResult(): string |
AfterBackupCheckedEvent fires only as part of a complete backup run (administration, scheduler or
bin/console muckiware:backup:create <backupRepositoryId>), not for the standalone check via
bin/console muckiware:backup:check <backupRepositoryId>.
For BackupFinishedEvent, isCoreSucceeded() is true only when the before, core and after stages all
completed. A failing finished listener can fail an otherwise successful run, but never replaces an
existing primary error. Error priority is primary backup error, finished-listener error, then duration
persistence error.
Repository management events
| Event name | Event class | Fired when | Payload |
|---|---|---|---|
mucki_facility.repository.after_cleanup |
AfterRepositoryCleanedUpEvent |
After a prune run on a repository (administration). | getBackupRepository(): BackupRepositoryEntitygetOutput(): string |
mucki_facility.snapshot.after_delete |
AfterSnapshotDeletedEvent |
After a single snapshot was removed from the repository. | getBackupRepositoryId(): stringgetSnapshotId(): stringgetOutput(): string |
mucki_facility.snapshots.after_delete |
AfterSnapshotsDeletedEvent |
After a batch of snapshots was removed, for example via bin/console muckiware:backup:snapshots <backupRepositoryId> --remove <snapshotIds> (snapshot ids as comma separated list). A batch removal also fires mucki_facility.snapshot.after_delete for every single snapshot. |
getBackupRepository(): BackupRepositoryEntitygetSnapshotIds(): array<int, string>getOutput(): string |
mucki_facility.snapshots.after_forget |
AfterSnapshotsForgottenEvent |
After snapshots were removed by the keep-policy, for example via bin/console muckiware:backup:forget <backupRepositoryId>. |
getBackupRepository(): BackupRepositoryEntitygetOutput(): string |
Repository upload events (S3 mirror)
Besides the DAL-free Symfony events these two are Flow Builder triggers (see S3 mirror).
| Event name | Event class | Fired when |
|---|---|---|
mucki_facility.repository_upload.succeeded |
RepositoryUploadSucceededEvent |
An S3 mirror run finished successfully |
mucki_facility.repository_upload.failed |
RepositoryUploadFailedEvent |
An S3 mirror run failed or was aborted |
Payload classes
| Class | Description |
|---|---|
MuckiFacilityPlugin\Entity\BackupRepositorySettings |
Settings of the current run, for example getBackupRepositoryId(), getName(), getBackupType(), getRepositoryPath(), getBackupPaths(), getDbDumpPath(). |
MuckiFacilityPlugin\Core\Content\BackupRepository\BackupRepositoryEntity |
The persisted repository configuration. |
MuckiRestic\Entity\Result\ResultEntity |
One result of a restic execution, for example getOutput(), getCommandLine(), getStatus(), getDuration(). |
Snapshot entity events (DAL)
Shopware fires the standard DAL events for the snapshot entity muwa_backup_repository_snapshots.
The event names are available as constants in MuckiFacilityPlugin\Events\BackupRepositorySnapshotsEvents:
| Event name | Event class | Fired when |
|---|---|---|
muwa_backup_repository_snapshots.written |
EntityWrittenEvent |
Snapshot records are written, for example when a finished backup run imports the snapshots of the repository. |
muwa_backup_repository_snapshots.deleted |
EntityDeletedEvent |
Snapshot records are deleted in the shop database. |
muwa_backup_repository_snapshots.loaded |
EntityLoadedEvent |
Snapshot records are read over the DAL. |
Listener example
Subscriber class in your own plugin:
<?php declare(strict_types=1); namespace MyOwnPlugin\Subscriber; use MuckiFacilityPlugin\Events\AfterBackupCreatedEvent; use Symfony\Component\EventDispatcher\EventSubscriberInterface; class BackupEventSubscriber implements EventSubscriberInterface { public static function getSubscribedEvents(): array { return [ AfterBackupCreatedEvent::NAME => 'onAfterBackupCreated', ]; } public function onAfterBackupCreated(AfterBackupCreatedEvent $event): void { $repositoryName = $event->getBackupSettings()->getName(); foreach ($event->getResults() as $result) { $output = $result->getOutput(); // send the result to an external system, write a log entry, ... } } }
Registration in the services.xml of your plugin:
<service id="MyOwnPlugin\Subscriber\BackupEventSubscriber"> <tag name="kernel.event_subscriber"/> </service>
Alternatively, a single listener method on any service:
<service id="MyOwnPlugin\Notifier\BackupFinishedNotifier"> <tag name="kernel.event_listener" event="mucki_facility.backup.after_create" method="onAfterBackupCreated"/> </service>
Notes for listeners
- Backups started in the administration or by the scheduler run as message queue tasks. In that
case the events fire inside the
messenger:consumeworker process, not in the process that triggered the run. A backup by console command fires the events in the CLI process. - All events are dispatched synchronously, a slow listener delays the backup run.
- The events are notifications only: they cannot cancel or modify a run.
- Treat the payload objects as read-only; they are the instances of the current run.
Testing
phpstan
Install
Install phpstan, if required
cd custom/plugin/MuckiFacilityPlugin
composer install
Execute
cd custom/plugins/MuckiFacilityPlugin
composer run-script phpstan
Unit test
Execute first time
./vendor/bin/phpunit --configuration="custom/plugins/MuckiFacilityPlugin" --testsuite "migration"
Execute regular run
./vendor/bin/phpunit --configuration="custom/plugins/MuckiFacilityPlugin"
