haylan/AeonDumpManager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Releases Wiki Activity

docs: add dump manager research notes

Browse Source
This commit is contained in:
haylan
2026-09-14 22:00:26 +02:00
parent 0dc19897a4
commit b4e84d0570
2 changed files with 315 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/research/admin-dump-manager-ui.md
+137
View File
@@ -0,0 +1,137 @@
# Research: Administration UI for AeonDumpManager (list/create/delete SQL dumps)
Target: Shopware 6.6 administration plugin development. Differences for 6.7 noted per section.
## Summary / Recommendations
- **Menu**: Register a module with `Shopware.Module.register()` and a `navigation` entry whose `parent` is an existing settings-area id (e.g. `sw-settings` or a dedicated top-level *is not allowed* for plugins — see §1). For a dev-tooling plugin like AeonDumpManager, nest under Settings rather than trying to create a first-level item; Shopware Store review explicitly rejects plugins that add first-level menu entries.
- **Module structure**: One `module/aeon-dump-manager` folder with `index.js` (routes/navigation/snippets), a single list page component, no detail/create page needed as a separate route — a create action can be a button + modal on the list page since dumps aren't Shopware entities. Bind `sw-data-grid` directly to a plain JS array (`this.dumps`) returned from your own API, not an `EntityCollection`/`repository.search()` flow.
- **Backend communication**: Write one custom PHP controller extending `AbstractController`, scoped with `#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [ApiRouteScope::ID]])]` (or `AdministrationRouteScope::ID`) under `/api/_action/aeon-dump-manager/...`, tagged as a service (`shopware.controller` context via `routes.xml`/`routes.php` auto-discovery). Pair it with a small JS `ApiService` subclass (`Shopware.Classes.ApiService`) registered via `Application.addServiceProvider`, injected into the component via `inject: ['aeonDumpManagerApiService']`. Do **not** rely on client-side ACL checks alone (`acl.can()` only hides UI) — do the real permission check server-side, e.g. via `AclRoleDefinition` privilege validation, since ACL in the admin can be bypassed by direct API calls.
- **TypeScript**: There is no first-class "TypeScript for admin plugins" guide; official support is limited to extending the webpack build (`build/webpack.config.js`, pre-6.7) or Vite config (`vite.config.mts`, 6.7+) to add `ts-loader`/`@babel/preset-typescript`, and core is now written largely in TS internally. Unless the project already needs TS, skip it — plain JS with the existing Vue 2-options-API-via-compat conventions is the supported default and avoids one more moving build part for a small plugin.
- **File size formatting**: Do not reimplement byte formatting — the admin core already ships `fileSize(bytes, locale)` under `Shopware.Utils.format.fileSize`. Reuse it directly in the grid column renderer.
- **6.7**: Biggest relevant changes are the Vue 2 compat-layer removal (must be genuinely Vue 3 compatible components — no `$set`/`$delete`, watch `this.$…` internal API usage), Vuex→Pinia (`Shopware.State` → `Shopware.Store`, only relevant if you add a custom store), and Webpack→Vite (only relevant if you extend the build). None of this blocks writing the module against 6.6 now, provided the components avoid deprecated Vue 2-only patterns.
---
## 1. Admin menu registration
A plugin adds an admin module (and its menu entry) via `Shopware.Module.register(moduleId, config)` called from `src/Resources/app/administration/src/module/<name>/index.js`, imported by `main.js`. The `navigation` property of the config is an array of navigation-entry objects; the documented fields are `id`, `label`, `path` (a dot-notation route id matching a `routes` entry), `icon`, `color`, `parent`, and `position` (numeric ordering). [Add Menu Entry — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/routing-navigation/add-menu-entry.html)
**Important restriction**: plugin modules cannot add entries at the first level of the main menu — a `parent` pointing at an existing menu node (Shopware supports infinite nesting) is required. The Shopware Store plugin review process explicitly rejects plugins that create their own first-level menu entry. [Add Menu Entry — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/routing-navigation/add-menu-entry.html)
**ACL-gated visibility**: a `navigation` entry (and individual `routes` entries via `meta.privilege`) can carry a `privilege` key so the menu item / route is hidden unless the logged-in admin user has that privilege — privileges are declared separately via `Shopware.Service('privileges').addPrivilegeMappingEntry(...)` in a module's `acl/index.js`. [Adding Permissions — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.html)
**Where to hook in for a dev-tooling plugin**: Shopware's own settings modules (e.g. `sw-settings`) are the conventional parent for administrative/operational tooling that isn't a merchandising concept (products, orders, etc.). Since AeonDumpManager already exposes a store-config panel via `config.xml` (per `CLAUDE.md`), placing the module's navigation entry as a child of the existing settings area is the natural, non-first-level location and matches the plugin's job (dev/ops tooling, not a customer-facing catalog feature).
**6.7 differences**: The `Module.register` / navigation API itself is not called out as changed in the 6.7 upgrade materials found. The changes that *do* land in 6.7 and affect any admin module (menu module included) are:
- Removal of the Vue 2 compatibility build — plugin components must be genuinely Vue-3-compatible (no `$set`/`$delete`, check `this.$…` internal Vue API usage, `sw-field` replaced by its successor components). [Vue 3 Upgrade guide — developer.shopware.com](https://developer.shopware.com/docs/guides/upgrades-migrations/administration/vue3.html), [Removing Vue Migration Build roadmap — developer.shopware.com](https://developer.shopware.com/docs/guides/upgrades-migrations/administration/vue-migration-build.html)
- Vuex → Pinia: any plugin-registered Vuex store must move from `Shopware.State` to `Shopware.Store` (not applicable here unless AeonDumpManager adds its own store, which is not necessary for a dump list). [Vue 3 Upgrade guide — developer.shopware.com](https://developer.shopware.com/docs/guides/upgrades-migrations/administration/vue3.html)
- Webpack → Vite for the admin build (see §4).
No meteor-admin-sdk vs. core-plugin distinction is relevant here: `meteor-admin-sdk` (the "app extension SDK", formerly `admin-extension-sdk`) is the mechanism for **Shopware Apps** (no PHP backend, communicate over `postMessage`/iframe), not for a classic PHP+JS **plugin** like AeonDumpManager, which uses the core plugin administration extension mechanism documented above. This plugin is a PHP plugin (`shopware-platform-plugin`, confirmed by `CLAUDE.md`), so the core `Shopware.Module.register` path is the correct one, not the SDK.
## 2. Building the admin UI module structure
Conventional directory layout under `src/Resources/app/administration/src/`:
```
main.js # imports the module: import './module/aeon-dump-manager';
module/aeon-dump-manager/
index.js # Shopware.Module.register(...) — routes, navigation, snippets
acl/index.js # addPrivilegeMappingEntry (optional but recommended)
snippet/
en-GB.json
de-DE.json
page/
aeon-dump-manager-list/
index.js # Shopware.Component.register(...)
aeon-dump-manager-list.html.twig
```
`index.js` registers routes (e.g. `list: { component: 'aeon-dump-manager-list', path: 'list' }`), the `navigation` array (§1), and `snippets` per locale. [Add Custom Module — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/module-component-management/add-custom-module.html), [Add Custom Route — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/routing-navigation/add-custom-route.html)
**List rendering — plain array, not `EntityCollection`**: `sw-data-grid` is documented and used with a plain array of plain objects assigned to component `data()`, not necessarily an entity repository result:
```html
<sw-data-grid :data-source="dataSource" :columns="columns"></sw-data-grid>
```
```js
data() {
return {
dataSource: [ { id: 'uuid1', company: 'Wordify', name: 'Portia Jobson' }, ... ],
columns: [ { property: 'name', label: 'Name' }, { property: 'company', label: 'Company' } ]
};
}
```
[Using the Data Grid Component — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/data-handling-processing/using-the-data-grid-component.html)
This is exactly the right fit for AeonDumpManager: dump files are filesystem entries, not DAL entities, so the list page's `data()` should hold the array returned by your custom API (§3) — each row `{ id/filename, createdAt, name, sizeBytes }` — with a `columns` config of `name`, a datetime column (format via existing Shopware date filter/util), and a size column whose `label` renders `Shopware.Utils.format.fileSize(row.sizeBytes)` (§5). Do not build an `EntityCollection` or wire a `repositoryFactory` for this list — that machinery is for DAL entities and would be pure overhead here.
**Create/delete flow**: a "Create dump" `sw-button` triggers your API service's create call and reloads the list; per-row delete uses a row action (`sw-context-button`/action column) that opens a confirmation dialog before calling delete. Shopware's own standard confirmation component is `sw-confirm-modal` (added in 6.3.5.0 as the standard confirm-modal component for exactly this kind of "are you sure you want to delete" flow) — reuse it rather than hand-rolling a `sw-modal` yes/no dialog. [changelog: added-sw-confirm-modal.md — github.com/shopware/shopware](https://github.com/shopware/shopware/blob/trunk/changelog/release-6-3-5-0/2021-01-06-added-sw-confirm-modal.md), [sw-confirm-modal — component-library.shopware.com](https://component-library.shopware.com/components/sw-confirm-modal)
## 3. Frontend-to-backend communication
**JS side**: define a custom API service class extending `Shopware.Classes.ApiService`, register it through `Shopware.Application.addServiceProvider('aeonDumpManagerApiService', (container) => { const initContainer = Application.getContainer('init'); return new AeonDumpManagerApiService(initContainer.httpClient, container.loginService); })`, and inject it into components with `inject: ['aeonDumpManagerApiService']` → available as `this.aeonDumpManagerApiService`. The base class supplies `getBasicHeaders()` (auth token handling) and `ApiService.handleResponse()` for uniform error handling; a GET/POST/DELETE call is `this.httpClient.get(route, { headers: this.getBasicHeaders() })` etc. [Adding Services — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/add-custom-service.html), [Making API Requests — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/services-utilities/making-api-requests.html)
**PHP side**: create a controller extending `AbstractController`, scoped to the admin/API domain via the class-level attribute
```php
#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [ApiRouteScope::ID]])]
class DumpController extends AbstractController
{
#[Route(
path: '/api/_action/aeon-dump-manager/dumps',
name: 'api.action.aeon_dump_manager.dumps.list',
methods: ['GET']
)]
public function list(Context $context): JsonResponse { ... }
}
```
This mirrors the core `ApiController`'s own pattern (`#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [ApiRouteScope::ID]])]` at class level, with `/api/_action/...` action routes at method level, e.g. its `clone` action at `/api/_action/clone/{entity}/{id}`). [ApiController.php — github.com/shopware/core (trunk)](https://github.com/shopware/core/blob/trunk/Framework/Api/Controller/ApiController.php); Administration-specific controllers use `AdministrationRouteScope::ID` from `Shopware\Administration\Framework\Routing\AdministrationRouteScope` instead when the endpoint is administration-only rather than general Admin API. [AdministrationController.php — github.com/shopware/administration (trunk)](https://github.com/shopware/administration/blob/trunk/Controller/AdministrationController.php)
Controller discovery uses the plugin's `src/Resources/config/routes.php` (or `routes.xml`) importing `../../Controller/*Controller.php` via the `attribute` type loader — the same auto-discovery mechanism documented for storefront controllers, generalized to any controller directory. [Add Custom Controller — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/storefront/add-custom-controller.html)
**ACL/authorization**: All admin and API routes are authentication-protected by default (bearer token from the admin's own OAuth session, attached automatically by `getBasicHeaders()`/`loginService` on the JS side — no separate manual OAuth dance needed in the component code). [UPGRADE-6.1.md — github.com/shopware/shopware](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.1.md) Client-side privilege checks (`this.acl.can('aeon_dump_manager.viewer')`, `v-if="acl.can(...)"`) only toggle UI visibility and are documented as bypassable via direct API calls — the actual authorization must be enforced in the controller itself, e.g. by validating against `AclRoleDefinition` privilege constants the way `ApiController::clone()` does (`$this->validateAclPermissions($context, $definition, AclRoleDefinition::PRIVILEGE_CREATE)`, throwing `ApiException::missingPrivileges()` on failure), or via the `#[Acl(...)]` attribute mechanism that superseded the deprecated `@Acl` annotation for controller-level privilege gating. [Adding Permissions — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.html), [ApiController.php — github.com/shopware/core (trunk)](https://github.com/shopware/core/blob/trunk/Framework/Api/Controller/ApiController.php), [ADR: controller-configuration-route-defaults — developer.shopware.com](https://developer.shopware.com/docs/resources/references/adr/2022-02-09-controller-configuration-route-defaults.html)
For AeonDumpManager, declare a plugin-specific privilege set (e.g. `aeon_dump_manager.viewer` / `.creator` / `.deleter`) via `acl/index.js` (`addPrivilegeMappingEntry`), gate the menu/routes with it client-side for UX, and re-check an equivalent permission (or at minimum require an authenticated admin session, which is already default) server-side before actually running a `mysqldump`/file-delete operation — these are filesystem/process-level actions, so being defensive here matters more than for a typical read-only entity list.
*Gap note*: the official docs found do not show a first-party doc page titled specifically "add custom admin API route" with a full worked PHP example (the closest, `add-custom-route.html`, only covers the **Vue Router** side, i.e. `routes:` in `Module.register`, not the PHP controller) — the PHP-side pattern above is instead verified directly against the shipped `ApiController`/`AdministrationController` source in `shopware/core` and `shopware/administration`, which is authoritative but means there's no single canonical doc page combining both halves end-to-end for a plugin.
## 4. TypeScript setup for Shopware 6 administration
There is no dedicated "TypeScript for administration plugins" guide among the fetched official pages. What exists officially:
- **Build extension mechanism (6.6 and earlier)**: a plugin can provide `src/Resources/app/administration/build/webpack.config.js` exporting a function that returns webpack config overrides — this is the documented, supported extension point (`Extending Webpack`). [Extending Webpack — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/extending-webpack.html) That page itself contains **no TypeScript-specific guidance** (no `.ts`/`.tsx`, `ts-loader`, or `tsconfig` mention) — adding `ts-loader` or `@babel/preset-typescript` there is a community pattern layered on top of a documented extension point, not something the official page walks through.
- **6.7: Webpack → Vite**. Per the roadmap doc, plugins are only affected if they currently ship a custom `webpack.config.js`; those must migrate to a `vite.config.mts` file (note the `.mts` extension — TypeScript by convention for the config file itself) under `.../administration/src/`, and delete the old webpack config/dependencies. [Future Development Roadmap: Changing from Webpack to Vite — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/system-updates/vite.html)
- Shopware's own administration source has increasingly moved to `.ts`/`.vue`+TS internally (e.g. core factory files like `async-component.factory.ts` in `shopware/shopware` trunk), i.e. the *core team's own code* is TypeScript, but this is not the same as an officially documented, supported path for **plugin** authors to write their own module in TypeScript out of the box.
**Recommendation for AeonDumpManager**: skip TypeScript. Per the ponytail ladder, there's no existing TS need in this repo (PHP `^8.1` project per `CLAUDE.md`, no existing frontend TS tooling), and the admin plugin surface here is small (one list page, one service). Adding a custom `webpack.config.js`/`vite.config.mts` + `ts-loader`/tsconfig just to type a handful of small Vue components is speculative infrastructure for a plugin whose entire admin footprint is one grid and one API service; plain JS following the documented module/service conventions is both fully supported and the shorter path. Revisit only if the plugin's admin surface grows substantially or the team adopts TS project-wide.
## 5. File size formatting
Shopware's administration core already ships a byte-formatting helper — do not reimplement it. It's documented in the Utils reference (`Shopware.Utils.format.fileSize`, described as "Formats a number of bytes to a string with a unit") [Utils Reference — developer.shopware.com](https://developer.shopware.com/docs/resources/references/administration-reference/utils.html), and its exact implementation in the `shopware/shopware` monorepo (Administration bundle) is:
```ts
// src/Administration/Resources/app/administration/src/core/service/utils/format.utils.ts (shopware/shopware, trunk)
export function fileSize(bytes: number, locale = 'de-DE'): string {
const denominator = 1024;
const units = ['B', 'KB', 'MB', 'GB'];
let result = Number.parseInt(String(bytes), 10);
let i = 0;
for (; i < units.length; i += 1) {
const currentResult = result / denominator;
if (currentResult < 0.9) break;
result = currentResult;
}
return `${result.toFixed(2).toLocaleString(locale)}${units[i]}`;
}
```
[format.utils.ts — github.com/shopware/shopware (trunk)](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/src/core/service/utils/format.utils.ts)
Usage in a plugin component: `Shopware.Utils.format.fileSize(row.sizeBytes)` (accessed via the global `Shopware.Utils` object per the "Using utility functions" guide). [Using utility functions — developer.shopware.com](https://developer.shopware.com/docs/guides/plugins/plugins/administration/using-utils.html) This directly satisfies the "MB/GB human-readable size column" requirement with zero custom code — pass the dump file's byte size straight through it in the `sw-data-grid` column renderer/slot.
Note it only goes up to `GB` (no `TB` step) and defaults to `de-DE` locale formatting unless a locale is passed — pass the admin's current locale (`Shopware.State.get('session').currentLocale` in 6.6, or its `Shopware.Store` equivalent post-Pinia-migration in 6.7) if locale-correct number formatting matters, otherwise the default is fine for dump files (unlikely to exceed a few GB).
docs/research/dump-binary-config.md
+178
View File
@@ -0,0 +1,178 @@
# Research: Admin-configurable dump binary path — is it an attack surface?
Target: `src/Service/DumpBinaryLocator.php`'s `dumpBinaryPath` config field and how it feeds
`src/Service/DumpService.php::buildProcess()`.
## Summary / Recommendation
- **Not a shell-injection vector.** `Process` built from an array (`new Process([$binary, ...])`)
never goes through a shell — PHP's `proc_open()` execs the array directly, so whatever string sits
in `$binary` is passed straight to `exec()` as the program path. There's no shell metacharacter
parsing to exploit via that string's *content* (§1).
- **The real concern is authorization scope, not injection**: `dumpBinaryPath` is whatever
`SystemConfigService::getString()` returns, gated only by Shopware's `system_config:read`/`:update`
ACL privilege — a privilege that can be granted independently of shell/SSH access to the box. A
role with system-config write access but *no* shell access can currently point this field at any
executable already reachable on disk and have the plugin run it as `www-data`. That's a real,
if narrow, privilege-escalation surface for this one specific plugin — not a "trusts itself" non-issue,
because system-config-write and filesystem/shell access are not the same trust tier in Shopware's ACL
model (§1).
- **Recommendation for this plugin**: drop `dumpBinaryPath` (arbitrary absolute path) in favor of a
`dumpBinaryName` override, resolved through `ExecutableFinder::find($name)` exactly like the
auto-detected default — never returned as a raw path straight from config. This closes the
arbitrary-path surface (an admin can only ever get a `PATH`-resolved binary, never point at
`/etc/shadow`-adjacent binaries or an arbitrarily uploaded file) while still covering the one
legitimate reason to override at all: a distro/environment that names the client something
nonstandard. Given dockware ships `mysqldump` on `PATH` already (confirmed in the prior research doc,
`.scratch/admin-dump-manager/issues/01-detect-dump-binary.md` §3), the override will sit unused in
the common case — which is fine, it's a two-line fallback, not new infrastructure (§2, §3).
- An env-var override was considered and rejected as the *primary* mechanism for this plugin — it's
the right shape for ops-owned infra config, but this plugin already has a config-field UI and
`SystemConfigService` wired in for `maxDumps`/`retantionDays`; adding a second override channel
(env var) alongside the DB-stored one is more moving parts than the problem needs (§2, §3).
## 1. Is there a real security concern?
`DumpService::buildProcess()` builds the command as an array:
```php
$command = [$binary, '--single-transaction', '--quick', '-h', ..., '-u', ..., $dbname];
$process = new Process($command, null, ['MYSQL_PWD' => $password]);
```
Symfony's own docs are explicit that array form is the safe form and *why*:
> "Using an array of arguments is the recommended way to define commands. This saves you from any
> escaping and allows sending signals seamlessly." — and contrasts it with `Process::fromShellCommandline()`,
> where "it becomes your responsibility to deal with escaping and portability."
> [Symfony Process component docs](https://symfony.com/doc/current/components/process.html)
Mechanically: `Process` (array constructor) hands the array straight to PHP's `proc_open()`, which —
given an array `command` argument — execs the binary directly (no `/bin/sh -c` wrapping), per PHP's
own `proc_open()` behavior for array-form commands (bypasses the shell entirely on Linux since PHP
7.4). So `$binary`'s *string content* can't be used to inject additional shell commands (no `;`, `` ` ``,
`$()`, pipes, etc. get interpreted) — the entire "shell injection via a crafted path string" concern
the user was worried about does not apply to this code as written. This holds **regardless of whether
`$binary` comes from `ExecutableFinder::find()` or directly from `SystemConfigService::getString()`** —
both are just strings landing in the same array slot.
**So what is the actual concern?** Not injection — authorization scope. `dumpBinaryPath` is read via:
```php
$configuredPath = $this->systemConfigService->getString('AeonDumpManager.config.dumpBinaryPath');
if ($configuredPath !== '') {
return $configuredPath;
}
```
This value is *whatever an admin with write access to this plugin's store-config typed*, used
**verbatim** as the program to exec — no `is_executable()` check, no restriction to a known directory,
no validation at all beyond non-empty. Setting it, in Shopware's ACL model, requires the
`system_config:read`/`system_config:update` privilege (or a role with `administration` access broadly).
That privilege is not the same tier as "has a shell on the container" — Shopware routinely grants
narrower admin roles (e.g. a merchandising-ops role scoped to a handful of modules including this
plugin's settings card) without granting SSH/exec access to the underlying host. For *this specific
field*, anyone who can write plugin config can make the plugin exec an arbitrary path on disk as
`www-data` — e.g. pointing it at any already-present script/binary, or (in a shared-hosting-style setup)
a path they can write to via some unrelated upload feature. That's a real, if narrow and
low-severity-in-practice (dev-tooling plugin, dockware-only target per `CLAUDE.md`), escalation: it
turns "can edit this plugin's config" into "can execute an arbitrary path as the PHP process user,"
which is a strictly larger capability than the plugin should need to grant. It is not an
*unauthenticated-attacker* vector — Shopware's admin panel is authenticated and this requires a
specific privilege — but "only a privileged admin can trigger it" doesn't make it a non-issue when the
privilege in question (system-config write) is deliberately a narrower grant than shell access in
Shopware's own permission model.
## 2. Alternatives, evaluated
### a. Drop the field entirely, `ExecutableFinder::find()` only, fail loudly
Simplest option. `ExecutableFinder::find($name)` (confirmed against `symfony/process` source,
`ExecutableFinder.php`, current branch) searches, in order:
1. Directories from the `PATH` env var (`getenv('PATH')`, or `Path` on Windows), merged with any
`$extraDirs` argument.
2. For each directory, `is_file($dir/$name$suffix) && is_executable(...)` (suffix loop is a no-op on
Linux; Windows-only `PATHEXT` extensions).
3. As a last resort on non-Windows, shells out to `command -v -- $name` (via `escapeshellarg()`) —
this is the *only* place `ExecutableFinder` itself touches a shell, and it shell-escapes the binary
*name* being searched for, not a path being executed.
[`ExecutableFinder.php` — symfony/process, GitHub](https://github.com/symfony/process/blob/7.1/ExecutableFinder.php)
Pro: zero config-surface, nothing to misconfigure. Con: on the (rare, per the linked prior research)
case where `mysqldump`/`mariadb-dump` genuinely isn't on `PATH` for `www-data`, there's no way to
recover without an env var or code change — for a plugin whose whole job is producing dumps, a hard
dependency on `PATH` composition an admin can't influence from the plugin's own UI is a mildly awkward
dead end.
### b. Binary *name* override (`dumpBinaryName`), still resolved via `ExecutableFinder::find()`
```php
$configuredName = $this->systemConfigService->getString('AeonDumpManager.config.dumpBinaryName');
$binaryNames = $configuredName !== ''
? [$configuredName]
: ($this->isMariaDb() ? ['mariadb-dump', 'mysqldump'] : ['mysqldump']);
foreach ($binaryNames as $binaryName) {
$path = $this->executableFinder->find($binaryName);
if ($path !== null) {
return $path;
}
}
```
This is a ~3-line diff from the current code — same shape, same loop, just the value coming out of
config is *always* passed through `find()` rather than ever being returned directly. Every path
`buildProcess()` can end up executing is a `PATH`-resolved, `is_executable()`-checked file — an admin
can redirect *which name* gets looked up (covers a renamed/nonstandard binary on an unusual
distro/environment) but can never point the plugin at an arbitrary filesystem path outside `PATH`.
This directly closes the gap in §1 while preserving the one legitimate override use case the original
field existed for.
### c. Environment variable override (`getenv('AEON_DUMP_BINARY_PATH')` or similar)
Moves the override from "whoever has Shopware admin-config write access" to "whoever controls the
container/deployment env" (ops/devops, via `docker-compose.yml`, `.env`, or the container's process
environment) — a meaningfully different, generally higher, trust tier, and consistent with how
`docker-compose.yml` already configures this repo's dev container (`SSH_USER`/`SSH_PWD` env vars per
`CLAUDE.md`). This is a legitimate pattern in general. For *this* plugin specifically it's more
machinery than the problem justifies: it adds a second config source (env var) next to the existing
`SystemConfigService`-backed admin UI field, for a value that (per §3) essentially never needs
overriding in the actual target environment (dockware). It's the right tool if this were, say, a
plugin deployed across heterogeneous customer infrastructure where ops teams routinely differ from
Shopware-admin teams — not proportionate for a project-local dev-tooling plugin with one target
container image.
## 3. Recommendation for this plugin
Use **(b)** — replace `dumpBinaryPath` (text, absolute path) with `dumpBinaryName` (text, binary name,
default empty → falls back to the existing MariaDB/MySQL name-detection list) in
`src/Resources/config/config.xml`, and change `DumpBinaryLocator::locate()` to prepend the configured
name (if any) to the existing `$binaryNames` loop instead of short-circuiting with a raw path. This is
sized right for a dev-tooling plugin that per the prior research (`.scratch/.../01-detect-dump-binary.md`
§3) targets dockware, where `mysqldump` is already confirmed present on `PATH` — the override becomes
a rarely-touched escape hatch rather than the primary mechanism, and it removes the one place in this
plugin where admin-supplied config was executed as a program path with no validation. Skip (c)/env-var:
it solves a deployment-heterogeneity problem this single-container plugin doesn't have, and would be a
second override mechanism doing the same job as the config field, for no concrete gain here. Skip
(a)/no-override-at-all: it's the smallest diff but removes a genuine, if narrow, recovery path for a
`PATH`-less edge case at effectively zero cost to keep (b) instead — (b) is one loop-entry away from (a)
and already sits inside the existing `foreach ($binaryNames as $binaryName)` structure in
`DumpBinaryLocator::locate()`.
No code changes were made as part of this research task — see
`src/Service/DumpBinaryLocator.php`, `src/Service/DumpService.php::buildProcess()`, and
`src/Resources/config/config.xml` for the current state to build (b) against.
## Sources
- [Symfony Process component docs — command arrays vs `fromShellCommandline()`](https://symfony.com/doc/current/components/process.html)
- [`ExecutableFinder.php` — symfony/process, GitHub (7.1 branch)](https://github.com/symfony/process/blob/7.1/ExecutableFinder.php)
- PHP manual, `proc_open()` — array-form `command` execs directly without a shell wrapper (documented
behavior since PHP 7.4 for the array-command form on non-Windows).
- `src/Service/DumpBinaryLocator.php`, `src/Service/DumpService.php` (this repo, current state).
- `.scratch/admin-dump-manager/issues/01-detect-dump-binary.md` (prior locked research: dockware ships
`mysqldump` on `PATH`, MariaDB binary-naming history, `ExecutableFinder` recommendation).
- `.scratch/dump-manager-implementation-spec/spec.md` §0, §2.2 (locked design context for the
`dumpBinaryPath` field and `DumpBinaryLocator` shape being reconsidered here).