Shopware Plugin Management Laravel Package

Getting Started

1. Install and pin the minor line. composer require ntzrbtr/shopware-plugin-management:^1.7. v1.7.1 is a documentation-only release — no API changes, no migration work — so allowing patch releases through is safe. You can bump without a QA cycle beyond a smoke test.
2. Read the README first, then the lifecycle class. The package is a thin wrapper around the Shopware 6 plugin lifecycle (install / activate / deactivate / uninstall / update / list / status). The public surface is deliberately small; the README and the single manager/service class (plus its exception types) are the whole story. Do not expect a large API to learn.
3. Confirm your runtime before writing code. This is a plain PHP library that wraps a Shopware 6 installation. It requires a bootstrapped Shopware kernel/container in whatever process calls it — a CLI script, a deployment hook, or a Laravel command/job. Verify that path works in your target environment before designing around it.
4. First use case — a read-only smoke test. Write a throwaway console command that lists installed plugins and prints name, version, and active state. This validates the bootstrap, the autoload, and the connection to the Shopware instance without mutating anything. Then run a single install + activate against a disposable plugin on a test instance.
5. Prove the failure path. Deliberately call activate on an already-active plugin to see what exception type and message you get. That tells you how much guarding your automation will need (see Gotchas).

Implementation Patterns

• One command per lifecycle operation. plugin:install, plugin:activate, plugin:deactivate, plugin:update, each taking a --plugin argument and a --dry-run flag. Keep the command as a thin adapter: resolve the manager, call one method, format the result. This makes it re-runnable in deployment scripts and testable in isolation.
• Idempotency by inspection, not by catching. Before mutating, call the list/status method to read current state; skip if already in the desired state. Do not rely on "activate throws if already active" as your idempotency mechanism — the exception is indistinguishable from a real failure unless you inspect it closely. A status check up front is cheaper and more reliable.
• Wrap the manager in a small service class. Inject it via the container (or just pass it explicitly). This gives you one place to add logging, timing, and result collection, and lets you mock the manager in tests rather than mocking Shopware.
• Batch operations report per-plugin, not per-batch. Iterate a list of plugins, collect a result per plugin (success / skipped / failed + reason), and only fail the overall command at the end. One bad plugin should not block the rest of the batch; you want the full reconciliation report.
• Queue long-running updates. Plugin updates can run migrations and touch the schema. Dispatch each update as a job with withoutOverlapping() so two workers never run lifecycle operations against the same installation concurrently. Pass the plugin name in the payload; fetch fresh state inside the job rather than serialising a stale plugin object.
• Deployment pipeline placement. Activate/update as a post-deploy step after code is in place and before traffic shifts. Keep the step idempotent so a retried deploy is harmless. Log the before/after plugin versions so a failed deploy can be reasoned about from CI output alone.
• Ground-truth checks during rollout. While you build confidence in the wrapper, compare its list output against Shopware's own bin/console plugin:list on the same instance. Any divergence usually means a bootstrap/environment difference, which is the most likely class of bug here.

Gotchas and Tips

• It is a wrapper, not a Shopware runtime. Everything the package does routes through Shopware's plugin manager, so you must bootstrap the kernel/container yourself in CLI scripts and queue workers. "Works in a command, fails in a queued job" is almost always a bootstrap or working-directory difference, not a package bug.
• "Laravel console commands, queued jobs" in the description is about where you call it, not what it depends on. There is no Laravel facade, no service provider contract to lean on. Treat it as framework-agnostic PHP and do your own integration.
• Pin ^1.7 and read the CHANGELOG. The changelog now follows Keep a Changelog, so from the next release forward, breaking changes and deprecations will be categorised. Build your upgrade triage around those categories rather than diffing source. v1.7.1 itself is docs-only — a free bump.
• Distinguish "already in state" from "actual failure." Whatever exceptions the package throws, log the plugin name, the operation, and the prior state alongside the message. Without that context, a batch failure is unreadable.
• Snapshot before programmatic updates. Plugin updates can alter the database schema and filesystem. Run them against a snapshot or a disposable instance until you trust the path; lifecycle operations are not trivially reversible.
• No concurrency. File locks and DB state make concurrent install/activate/update unsafe. Serialise per installation (queue withoutOverlapping, or a deploy-lock) even when operating on different plugins.
• Verify the maintenance signals yourself. At this adoption level, the release history is quiet (docs and changelog housekeeping). Before making this load-bearing in production automation, check test coverage, CI status, and issue/PR activity. Plan for a fork-and-maintain fallback: the wrapper surface is small, so replacing it is a bounded task, not a rewrite.
• Extension point is the wrapper itself. If you need behaviour the API does not expose (rollback, dry-run diffs, dependency checks between plugins), add it in your service layer around the manager — not by patching the vendor. That keeps the dependency upgradable on patch releases.