From b4e84d0570df1ef94f745c31ba4d8cf01c5688b3 Mon Sep 17 00:00:00 2001 From: Haylan Date: Mon, 14 Sep 2026 22:00:26 +0200 Subject: [PATCH] docs: add dump manager research notes --- docs/research/admin-dump-manager-ui.md | 137 +++++++++++++++++++ docs/research/dump-binary-config.md | 178 +++++++++++++++++++++++++ 2 files changed, 315 insertions(+) create mode 100644 docs/research/admin-dump-manager-ui.md create mode 100644 docs/research/dump-binary-config.md diff --git a/docs/research/admin-dump-manager-ui.md b/docs/research/admin-dump-manager-ui.md new file mode 100644 index 0000000..bfbd032 --- /dev/null +++ b/docs/research/admin-dump-manager-ui.md @@ -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//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 + +``` +```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). diff --git a/docs/research/dump-binary-config.md b/docs/research/dump-binary-config.md new file mode 100644 index 0000000..3c5d95c --- /dev/null +++ b/docs/research/dump-binary-config.md @@ -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).