Skip to content

Paystack for Shopware 6 — 0.9.0-beta.2 - #2

Merged
KommandHub merged 51 commits into
mainfrom
develop
Jul 19, 2026
Merged

KommandHub merged 51 commits into
mainfrom
develop

Conversation

@KommandHub

Copy link
Copy Markdown
Collaborator

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

  • Debug logging is now resolved per sales channel. enableDebugging and 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.
  • Storefront bank-verification template blocks are namespaced, so they no longer collide with other plugins extending the same account templates.

Licensing

  • Relicensed from MIT to Apache-2.0 — adds an explicit patent grant and retaliation clause, an explicit reservation of trademark rights (§6), the NOTICE mechanism that carries attribution into forks, and §5 inbound=outbound contribution terms.
  • NOTICE added; 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.

  • Administration and plugin icons replaced with KommandHub branding; the unused shopware.png removed.
  • Extension label attributed to the vendor ("Paystack Payment by Kommandhub"); descriptions reworded to lead with "independent third-party" and state non-affiliation.
  • README gained an independence callout and a Trademarks & Disclaimer section; TRADEMARKS.md added.

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.

⚠️ The rebuild in this PR is not cosmetic. The branding commit swapped the administration icon in source, but Vite had inlined the previous icon as base64 into the committed bundle, so the built 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.

Build tooling

  • make prepare now works for pre-release versions and on repeat runs.
  • The test container ships shopware-cli for plugin validation.

Release metadata

  • Version bumped to 0.9.0-beta.2.
  • Changelog entries added in English, German and French; verified that shopware-cli renders the new entry.

Verification

  • make cs clean · PHPStan level 9 clean · 372 tests, 1843 assertions (4 pre-existing PHPUnit deprecations)
  • make validate-plugin → no problems
  • Administration assets rebuilt and byte-verified

Known gaps

  • No SECURITY.md or .github/ issue/PR templates yet (the sibling Flutterwave plugin has both) — SECURITY.md is the documented channel for private vulnerability reports and is worth adding before a public beta.

🤖 Generated with Claude Code

KommandHub added 30 commits June 7, 2026 12:25
- 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.
KommandHub and others added 21 commits July 13, 2026 16:30
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.
@KommandHub
KommandHub merged commit ee8465a into main Jul 19, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant