Extending the shop #

This part is for developers who need the shop to do something it does not do out of the box. The Exponential shop is built around replaceable handlers: a setting names a handler, the kernel finds its file by a naming convention and calls it in place of its own. Everything on these pages goes into an extension of your own, never into kernel/.

Contents #

1. All extension points
2. The handler pattern
3. Packaging
4. Testing an extension of the shop

All extension points #

The handler pattern #

1. A setting names the handler, for example Handler=mystore.
2. The kernel searches the repository directories and the listed extensions for <name><suffix>.php.
3. It includes the file and instantiates <name><Suffix>, for example mystoreShippingHandler (PHP class names are not case sensitive, so MyStoreShippingHandler works too).
4. If the file is missing, an error is written to the debug log and the kernel falls back or does nothing; it does not stop the request. Check the log after every change.

The RAD tool Setup > RAD has a handler wizard (setup/handlerextension/<kind>) with recipes for payment gateways, VAT, shipping, basket info and exchange rate handlers; it writes the class, the setting and an extension around them (Extensions). A payment gateway made by the wizard is written to extension/<name>/paymentgateways/<alias>/classes/<alias>gateway.php, the path the gateway loader reads through paymentgateways.ini [PaymentGatewaySettings] GatewaysDirectories[]. A gateway generated before 6.0.15 sits one level higher and is not loaded: move it as the RAD extension points note explains.

Packaging #

• One extension per store or per integration, for example mystore_shop, with its own settings/*.ini.append.php (Packaging as an extension).
• Regenerate autoloads after adding classes (php bin/php/ezpgenerateautoloads.php -e) and check that every class loads (php bin/php/checkclasses.php --quiet-ok).
• Keep provider credentials out of the extension: read them from settings/override/ (Environment settings and secrets).
• If the extension is useful to others, consider contributing it back.

Testing an extension of the shop #

• Unit tests for calculations (shipping, VAT) without a database: DB-less PHPUnit tests.
• A full test order for each path the extension changes: Testing a store.
• The Store dashboard's "How your shop works" after deployment: it names the handlers and workflows in effect.

Related pages #

• Developer path
• Extension anatomy
• Settings and ini files
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.