Repository navigation
Paystack for Shopware 6 — 0.9.0-beta.2 - #2
Merged
Merged
Conversation
- Remove dependency on `kommandhub/foundation-sw` and migrate essential core logic into the Paystack plugin.
- Relocate and reorganize foundation classes:
- `AbstractEntityReader`, `AbstractEntityWriter`, `OrderTransactionReader`, and `OrderTransactionWriter` moved to `Infrastructure/Shopware/EntityHandler`.
- `PaymentFinalizedEvent` moved to `Domain/Event`.
- Improve `PaymentMethodInstaller` to skip installation if a method with the same handler or technical name already exists, preventing duplicate errors.
- Integrate foundation migrations for African currencies and languages directly into the plugin.
- Implement comprehensive unit tests for the internalized entity handlers (`AbstractEntityReader`, `AbstractEntityWriter`, etc.) with full logical coverage.
- Fix PHPStan "Dead catch" error in `WebhookController` by adding appropriate `@throws` annotations in the application layer.
- Update `TestBootstrap` and PHPUnit configuration to support the new standalone structure and improve coverage reporting.
- Optimize `docker-compose.yml` for macOS performance using `:delegated` flags and improve volume management for IDE code completion.
- Remove dependency on `kommandhub/foundation-sw` and migrate essential core logic into the Paystack plugin.
- Relocate and reorganize foundation classes:
- `AbstractEntityReader`, `AbstractEntityWriter`, `OrderTransactionReader`, and `OrderTransactionWriter` moved to `Infrastructure/Shopware/EntityHandler`.
- `PaymentFinalizedEvent` moved to `Domain/Event`.
- Improve `PaymentMethodInstaller` to skip installation if a method with the same handler or technical name already exists, preventing duplicate errors.
- Integrate foundation migrations for African currencies and languages directly into the plugin.
- Implement comprehensive unit tests for the internalized entity handlers (`AbstractEntityReader`, `AbstractEntityWriter`, etc.) with full logical coverage.
- Fix PHPStan "Dead catch" error in `WebhookController` by adding appropriate `@throws` annotations in the application layer.
- Update `TestBootstrap` and PHPUnit configuration to support the new standalone structure and improve coverage reporting.
- Optimize `docker-compose.yml` for macOS performance using `:delegated` flags and improve volume management for IDE code completion.
Reorganized the codebase to follow a flattened, feature-first module structure as defined in the project guidelines. This improves maintainability and aligns with Shopware plugin best practices. Key changes: - Consolidated payment and cart logic under the `Checkout` module. - Moved Paystack API clients and resources to a dedicated `Client` module. - Refactored Webhook handling into a flat `Webhook` module, renaming listeners to subscribers. - Grouped Bank Verification logic into its own module. - Moved data access logic to `DataAbstractionLayer/OrderTransaction`. - Centralized cross-cutting concerns (Util, Exception, Installer, Logging, Setting) at the root level. - Updated all namespaces and imports across production and test code. - Renamed various services and subscribers for better clarity (e.g., EventListeners to Subscribers). This refactoring maintains existing functionality while providing a cleaner, more scalable directory structure.
Server (RefundController):
- require the `order:update` ACL privilege on the refund endpoint
- add a server-side over-refund cap (refundable balance from non-failed
captures / transaction total minus completed+in-progress refunds) so the
client-side bound can no longer be bypassed
Admin (Vue):
- gate the refund action on acl.can('order.editor'), the feature flag and a
positive refundable balance (canRefund)
- fix a double, concurrent capture/refund load (re-entrancy guard + single
watcher-driven trigger)
- stop sending the transaction id as orderTransactionCaptureId
- load plugin config reactively off the order's sales channel instead of a
created()-timing race
- round the max refundable amount to the currency's decimals
- remove dead code (debugRefundCalculation) and the unused orderId prop
Refactor:
- extract pure refund math into service/refund-calculator.js (+ spec) and a
shared util/paystack.js (handler identifier, isAbortError), removing the
duplicated constants and helpers across the two components
Meteor migration (first slice):
- migrate the refund-modal form controls and the empty state to Meteor
(mt-number-field, mt-text-field, mt-empty-state); data grids, modals,
labels and the tab item stay on sw-* (no drop-in Meteor equivalent yet)
Also: add CLAUDE.md, cover over-refund rejection with a test, rebuild the
administration bundle.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Introduced a specific administrative permission `paystack.refund` to allow granular control over who can process refunds through Paystack, independent of general order editing rights. Key changes: - Registered `paystack.refund` privilege in the administration under the "Additional permissions" category. - Updated `RefundController` to enforce the new `paystack.refund` ACL check on the backend. - Modified the administration frontend to gate the refund action using the new permission. - Added translation snippets for the new permission label in English, German, and French. - Integrated the ACL configuration into the main administration entry point.
…dation suite - Added `validate-plugin` command to Makefile using `shopware-cli`. - Fixed PHPStan "class.notFound" errors by adding `scanDirectories` to `phpstan.dist.neon` and using `--no-copy` flag. - Resolved ESLint warnings by removing unused imports in Administration and replacing `HttpClient` with `fetch` in Storefront. - Updated `WebhookController` and its tests to return and assert `204 No Content` for successful requests. - Increased test coverage for `TransactionVerificationProcessor` to 100%. - Added French translation for the plugin changelog (`CHANGELOG_fr-FR.md`). - Refactored `BankVerificationController` to use explicit constants from `StorefrontController`.
- Rewrite README.md as full contributor documentation: architecture, feature-first directory map, Docker/Make workflow, configuration options, build/test/CI, security, deployment and contributing. Fixes the stale hexagonal structure and the incorrect compatibility table. - Optimize composer.json keywords for Packagist and search discoverability (drop generic/vendor terms, add high-intent Shopware/payment/channel terms). - Add homepage and support (issues/source/docs) metadata, plus an author homepage. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
phpstan.dist.neon pointed scanDirectories at ../../../vendor/shopware/storefront (the host Shopware install). That path does not exist in CI or in shopware-cli, where the extension is analysed in an isolated directory, so PHPStan failed with "Scanned directory .../vendor/shopware/storefront does not exist". shopware/storefront is already a declared dependency, so PHPStan resolves Shopware\Storefront\* through the Composer autoloader once dependencies are installed. Removed the scanDirectories path. Verified `make analyse` (the CI command) passes at level 9 with no errors using the locally installed vendor. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The CI coverage gate is set to 100%, but CI ran only tests/Unit (no Shopware
kernel), which measured 91.85% — the gap being code exercised by the
integration tests. So the gate could never pass.
- CI now runs `phpunit --exclude-group kernel`, which adds the mockable
integration tests (controllers, payment handler) on top of the unit tests.
- The two integration tests that need a booted kernel + database
(KommandhubPaystackSWTest, CustomFieldsInstallerTest) are tagged
`#[Group('kernel')]` and excluded from CI; they still run in the full local
suite via `make test`.
- The plugin bootstrap class (KommandhubPaystackSW.php) is lifecycle glue that
can only be reached with a kernel, so it is excluded from the coverage
metric in phpunit.dist.xml (still covered by the kernel integration test in
the full suite).
Verified: `phpunit --exclude-group kernel` → 100.00% (1251/1251), gate passes;
full `make test` still green (303 tests).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Remove the plugin's two schema-less data migrations (Migration1780388405AddAfricanCurrencies, Migration1780389223AddAfricanLanguages) and the now-empty src/Migration/ directory. Nothing in the codebase or tests referenced them. The plugin no longer ships any migrations; payment method and custom fields are still set up through the install/update lifecycle installers. Note that African currencies and languages are no longer seeded on install — existing installs are unaffected, but new installs must add those currencies/languages manually if required. PaystackCurrencyHelper continues to handle per-currency decimals independently of the Shopware currency entities. Update README: replace the "Database Migrations" section with "Data Handling".
- Testing: Achieved 100% unit test coverage for `TransactionVerificationProcessor`, `WebhookProcessor`, and `ConfigurableLogger` by adding edge-case tests. - Webhook Security: Added amount verification and de-duplication to `WebhookSubscriber` and `RefundInitializeService` to prevent over-refunding and handle redeliveries safely. - Refund Logic: Improved `RefundInitializeService` to validate refundable amounts against the transaction total and handle synthetic captures. - Tooling: Updated `.gitignore` to exclude IDE-specific coverage reports and temporary files. - Refactor: Cleaned up deprecated `setAccessible()` calls in the test suite for PHP 8.1+ compatibility.
The African currency and language migrations were removed in 2693b09, but the README and both changelogs still advertised that the plugin adds African currencies and languages to the shop. That is no longer true and would mislead merchants evaluating the extension. State what the plugin actually does: it converts amounts correctly for every currency Paystack supports, including zero-decimal (XOF, RWF) and three-decimal (KWD) currencies, and it does not create currencies or languages — that stays a normal shop configuration step. Also document the plugin UI translations (en-GB, de-DE, fr-FR), which are real and were previously unstated.
…ariants Both recent critical defects shared one root cause: money code silently defaulted the currency to NGN when the order association was not loaded, converting amounts by the wrong power of ten. Six sites resolved currency with `?? 'NGN'`; four were safe only by accident of their criteria, and RefundAggregator re-resolved it three times inside nested loops with no control over its caller. Introduce OrderCurrencyResolver, which fails closed rather than guessing: - RefundAggregator throws (and now resolves once, not per loop iteration) - RefundInitializeService logs and aborts without creating capture/refund - WebhookSubscriber refuses to finalize the refund - RefundController returns an error response No `?? 'NGN'` remains in src/. Making the code fail closed broke 18 tests whose fixtures never set an order/currency — they had been passing on the silent default while modelling an entity graph that cannot exist. Fixtures now build the real association chain, so a missing association fails loudly. Add invariant-based tests rather than execution-based ones: minor-unit round-trip stability and monotonicity across all supported currencies, exact round-trips per decimal class, the over-refund guard proven in a 0-decimal currency, and fail-closed coverage for every call site.
ApiResource::response() used $response->toArray(), which throws on any 4xx and
discarded Paystack's response body. Paystack returns errors as a normal JSON
payload — {"status": false, "message": "...", "meta": {"nextStep": "..."}} —
alongside the 4xx status, so every `status === false` branch in this plugin was
unreachable and the merchant-facing message never surfaced. The admin refund UI
even renders errorData.meta.nextStep, which could never populate.
Use toArray(false) so the body always reaches the caller, and wrap genuine
transport failures (DNS, timeout, TLS, non-JSON bodies) in PaystackException so
the client has a coherent error contract.
Document the planned end-to-end test layers in the README roadmap rather than
shipping the suite now.
…tion The plugin was versioned 1.0.0 despite never having run against a real Paystack sandbox or live environment, and despite two full namespace restructures this session. Per the release readiness assessment (74/100): feature-complete but unproven, with no API stability guarantee yet — that is a pre-1.0 beta, not a stable release. Bump composer.json to 0.9.0-beta.1. Update all three changelogs (heading + pre-release notice) and fix CHANGELOG_fr-FR.md, which had been missed in an earlier pass and still claimed African currency/language seeding that no longer exists. Add a "Pre-1.0 status" note to the README explaining the 0.x -> 1.0.0 -> Shopware Store workflow. Update the hardcoded plugin-version fixtures in the kernel lifecycle test to match. 1.0.0 is reserved for once sandbox/live testing is complete and all critical issues are resolved.
Two failures in make prepare, neither related to plugin code. The plugin ships as a pre-release while the Shopware install it is tested against pins minimum-stability to stable, so composer refused it: "Could not find a version of package kommandhub/paystack-sw matching your minimum-stability (stable)". It is now required with a per-package stability flag. @dev is the bottom of composer's ladder (dev < alpha < beta < RC < stable) and a flag accepts its own level and everything above, so this holds for alpha, beta, RC, dev and stable alike with no edit per release. The root minimum-stability stays stable, so no other dependency can quietly resolve to a pre-release. prepare also worked only once per fresh container. Root composer.json registers custom/static-plugins/* as a path repository, so the copy the target made there became a package that outranked Packagist: the next run symlinked vendor/<pkg> back to that copy and cp then refused to copy a directory onto itself. The copies and their vendor entries are now cleared before composer resolves. That also stops the copy pinning the version — with it in place "^1.0" resolved to whatever sat on disk rather than the latest release.
Shopware's convention is CHANGELOG.md for the default language, with CHANGELOG_<locale>.md files as translations. English is the default, so the _en-GB suffix was redundant. The German and French changelogs keep their suffixes and are unchanged. Recorded as a rename, so history follows the file. The only reference to the old name was the directory tree in README.md, updated to match. No functional change: shopware-cli validate --full --store-compliance flags neither name, and get-changelog reads both.
Install shopware-cli in the plugin's isolated test image so the plugin can be validated against the same PHP version and installed Shopware as the tests, without a host-side toolchain that reports false positives. The binary is copied from the upstream shopware/shopware-cli:bin image via a multi-stage build. That image is a single static binary (~50 MB, multi-arch), so the install adds no package manager, no cleanup and one layer; the image grows by exactly the binary. The build runs `shopware-cli --version` so a broken install fails the image build, not the first validate. docker-compose.yml builds this Dockerfile; the base image, container name and volumes are otherwise unchanged. Add Makefile targets that run the CLI inside the container: validate-plugin (--full --store-compliance), a generic `cli` passthrough, changelog and zip. .dockerignore empties the build context, which copies nothing. .gitignore excludes the storefront assets `make zip` regenerates into the tree. README documents the tooling and targets. Only the plugin's own test environment is touched; the root Shopware Docker project is not modified.
The customer bank-profile templates defined blocks under generic names (page_account_overview_bank_details*, page_account_profile_bank_*) that were identical to the ones the Flutterwave plugin ships. With both plugins installed, Twig block inheritance is global, so whichever loaded second would override the other's blocks in the shared account templates — breaking one plugin's bank form. Prefix every custom block with "paystack" so the two plugins can coexist. The Shopware core extension points this feature hooks into (page_account_overview_addresses_include, page_account_profile_personal) keep their required names and are untouched. Template-only change: block names are internal, so no controller, snippet or test references them, and rendering is unchanged for a standalone install.
The plugin presented other companies' trademarks as its own identity: the
administration banner used the Paystack logo, and the README banner used the
Shopware logo captioned "Shopware Paystack Logo". Neither carried any
statement that this is an independent integration, which risks implying it is
an official or endorsed product.
- Replace the administration banner icon with the KommandHub mark.
- Replace the README banner with the KommandHub logo and drop the now-unused
shopware.png.
- composer.json: attribute the extension label to the vendor ("Paystack
Payment by Kommandhub") and reword the root and per-locale descriptions to
lead with "independent third-party" and state non-affiliation. Store
descriptions stay within the required 150-185 characters.
- README: add an independence callout, a Trademarks & Disclaimer section, and
a note that the MIT licence covers the code only and grants no trademark
rights.
- Add TRADEMARKS.md: the code is open source, the name and logo are not, and
a fork must be rebranded before redistribution.
The payment method name, configuration help texts, and snippet keys keep the
Paystack name: that is nominative use identifying the gateway a merchant is
actually paying through, and removing it would hurt usability without reducing
legal risk.
Verified: php-cs-fixer clean, PHPStan clean, 372 tests pass, and
`make validate-plugin` reports no problems.
Align with the sibling Flutterwave plugin and pick up the protections MIT lacks: an explicit patent grant and retaliation clause, an explicit reservation of trademark rights (Section 6), the NOTICE mechanism that carries attribution and trademark notices downstream into forks, and Section 5's inbound=outbound contribution terms. - LICENSE: full Apache-2.0 text, Copyright 2026 Kommandhub Limited. - NOTICE: new, per Section 4(d); carries the Paystack, Shopware and KommandHub trademark notices into any redistribution. - composer.json: license -> Apache-2.0. - README: Apache-2.0 badge, and a License section explaining the choice and linking LICENSE, NOTICE and TRADEMARKS.md. - TRADEMARKS.md: reference Apache-2.0, and require NOTICE as well as LICENSE to be retained in redistributions. - CONTRIBUTING: document that contributions are provided under Apache-2.0 via Section 5, with DCO sign-off, plus a trademark pointer. Relicensing is clean here: the git history contains only Kommandhub identities, so there are no external contributors whose consent is required, and the plugin is still pre-1.0. Verified: php-cs-fixer clean, PHPStan clean, 372 tests pass, and `make validate-plugin` reports no problems.
Second pre-release since 0.9.0-beta.1. - Bump the plugin version to 0.9.0-beta.2. - Add the 0.9.0-beta.2 changelog entry in English, German and French. - Rebuild the administration assets. The rebuild is not cosmetic. The branding change swapped the administration icon in source, but Vite had inlined the previous icon as base64 into the bundle, so the committed assets still shipped the third-party logo. The new icon exceeds the inline threshold and is now emitted as a separate asset, verified byte-identical to the source icon with no base64 image left in the bundle. Verified: php-cs-fixer clean, PHPStan clean, 372 tests pass, `make validate-plugin` reports no problems, and `make changelog` renders the new entry.
main holds a single squash commit of develop's own history (its tree is identical to develop's c16f208), so it contributes no content. Record it as merged to clear the divergence without altering develop's tree.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Second pre-release since
0.9.0-beta.1. Still for internal development, QA and sandbox/staging testing — not yet submitted to the Shopware Store.Fixes
enableDebuggingand the log levels are ordinary plugin settings, so a merchant can scope them to a single sales channel. They were previously only read from the global scope, which meant enabling debugging on one sales channel produced no output at all. Callers pass the id via the log context; entries without it keep the previous global behaviour.Licensing
NOTICEmechanism that carries attribution into forks, and §5 inbound=outbound contribution terms.NOTICEadded;TRADEMARKS.md,CONTRIBUTING.md(DCO sign-off) and the README updated to match.Relicensing is clean here: the git history contains only Kommandhub identities, so no external contributor consent is required, and the plugin is still pre-1.0.
Branding / trademark
The plugin previously presented other companies' marks as its own identity — the administration banner used the Paystack logo, and the README banner used the Shopware logo captioned "Shopware Paystack Logo" — with no statement that this is an independent integration.
shopware.pngremoved.TRADEMARKS.mdadded.The payment method name, configuration help texts and snippet keys keep the Paystack name — that is nominative use identifying the gateway a merchant actually pays through.
Build tooling
make preparenow works for pre-release versions and on repeat runs.shopware-clifor plugin validation.Release metadata
0.9.0-beta.2.Verification
make csclean · PHPStan level 9 clean · 372 tests, 1843 assertions (4 pre-existing PHPUnit deprecations)make validate-plugin→ no problemsKnown gaps
SECURITY.mdor.github/issue/PR templates yet (the sibling Flutterwave plugin has both) —SECURITY.mdis the documented channel for private vulnerability reports and is worth adding before a public beta.🤖 Generated with Claude Code