Documentation for new module support infrastructure

Author: zcwilt

content/dev/modules/_index.md

@@ -0,0 +1,20 @@
+---
+title: Modules Infrastructure
+description: New modules infrastructure
+weight: 100 
+layout: docs
+---
+
+{{% alert title="Warning" color="warning" %}}
+The documentation in this section is Work in progress and relates to features that might not be available yet.
+{{% /alert %}}
+
+# Introduction
+
+In order to make it easier and quicker to write modules(Payment/Shipping/Order Totals) a new infrastructure for these modules has been created.
+
+This new infrastructure will reduce the amount of boilerplate code required, minimize copy/paste coding and adds helpers for common coding requirements.
+
+{{% alert title="Note" color="primary" %}}
+Previous Payment/Shipping/Order total modules will continue to work without modification.
+{{% /alert %}}

content/dev/modules/base/_index.md

@@ -0,0 +1,103 @@
+---
+title: Base Module Support
+description: 
+weight: 10
+layout: docs
+---
+
+{{% alert title="Warning" color="warning" %}}
+The documentation in this section is Work in progress and relates to features that might not be available yet.
+{{% /alert %}}
+
+# Introduction
+
+The base module support classes contain common code that is used across all module types e.g Payments, Shipping and Order Total modules.
+
+It also provides some common helper methods that you can use in you modules.
+
+## Accessing Define Values
+
+All module types store information about themselves in the database `configuration` table.
+
+The `keys` for this table will look something like 
+
+- MODULE_PAYMENT_COD_STATUS
+- MODULE_SHIPPING_FLAT_COST
+- MODULE_ORDERTOTAL_TOTAL_SORT_ORDER
+
+The structure of these defines is  
+
+MODULE_[module type]\_[module name]\_[define name]
+
+where module type is one of `PAYMENT` or `SHIPPING` or `ORDERTOTAL`
+
+The module name is taken from the $code class variable of the module, and the define name describes the purpose of the define. 
+
+In previous version of Zen Cart,these configuration values were accessed directly using the key that was stored in the database, however using 
+the new module support classes we access them through a helper method.
+
+e.g In legacy code we might have done 
+
+`$this->sort_order = defined('MODULE_PAYMENT_COD_SORT_ORDER') ? MODULE_PAYMENT_COD_SORT_ORDER : null;`
+
+With the new infratructure we can simply do 
+
+`$this->sort_order = $this->getDefine('SORT_ORDER);`
+
+The `getDefine` method is context aware, so knows which type of module you are using(PAYMENT/SHIPPING/ORDERTOTAL) and the current define name (e.g. COD) for 
+the module you are using.
+
+Furthermore, you can also set a value that will be returned from the method if the configuration value does not exist. 
+
+In the example above, the method will return `null` if the `MODULE_PAYMENT_COD_SORT_ORDER` does not exist. 
+
+However you could also do `$this->sort_order = $this->getDefine('SORT_ORDER, 0);`
+
+and the method will return `0`, if the configuration value does not exist.
+
+There are also a number of helper methods to get some of the most common module configuration keys. 
+
+### getTitle
+
+This gets the title for the Module. 
+
+It looks for defines with suffixes in an array of ['TITLE', 'TEXT_TITLE', 'CATALOG_TITLE']
+
+If your module uses a different define for the title then you should override the getTitle method.
+
+### getAdminTitle
+
+This returns a title to display on the Admin interface. In general this would be the same as the getTitle as above, but sometimes you may want it to be different.
+It expects to be passed a default title, which would normally be what the getTitle function returns, ans will use this if it does not find a define related to the admin title.
+
+This function looks for defines with a suffix in an array ['TITLE_ADMIN', 'TEXT_TITLE_ADMIN', 'ADMIN_TITLE']
+
+If your admin title is defined through other means, them you will need to override this method in your module.
+
+### getDescription
+
+returns a module define with the suffix `DESCRIPTION`  
+
+### getSortOrder
+
+returns a module define with the suffix `SORT_ORDER`  
+
+### getZone
+
+returns a module define with the suffix `ZONE`  
+
+### getDebugMode#
+
+returns a module define with the suffix `DEBUG_MODE`  
+
+### isEnabled
+
+This function checks to see if the module is enabled.
+
+it first checks to see if the module has any missing configuraitions and then check the module define suffix `STATUS`
+
+### moduleAutoloadSupportClasses
+
+This function is only called if it exists. 
+
+It allows a module to add autoload classes using the psr4autoaload Aura autoload.

content/dev/modules/base/configurationerrors/_index.md

@@ -0,0 +1,13 @@
+---
+title: Module Configuration Errors
+description: 
+weight: 100
+layout: docs
+---
+
+{{% alert title="Warning" color="warning" %}}
+The documentation in this section is Work in progress and relates to features that might not be available yet.
+{{% /alert %}}
+
+# Introduction
+

content/dev/modules/base/languagedefines/_index.md

@@ -0,0 +1,56 @@
+---
+title: Module Language defines
+description: 
+weight: 120
+layout: docs
+---
+
+{{% alert title="Warning" color="warning" %}}
+The documentation in this section is Work in progress and relates to features that might not be available yet.
+{{% /alert %}}
+
+# Introduction
+
+Language define files for modules follow the same format as normal language defines. 
+
+They are stored in `includes/languages/{language}/modules/` and at the very least should have an english translation. 
+
+e.g. 
+
+`includes/languages/english/modules/payment/lang.cod.php`
+
+`includes/languages/english/modules/shipping/lang.flat.php`
+
+`includes/languages/english/modules/order_total/lang.ot_subtotal.php`
+
+
+Like module configuration keys, naming of module language defines are the same 
+e.g. 
+
+`MODULE_[module type]\_[module name]\_[define name]`
+
+There are some other rules.
+
+language define names should be unique and not match any other module configuration defines. 
+
+At a minimum you should provide the following 
+
+    'TEXT_TITLE' => 'Stripe Checkout',
+ 
+    'TEXT_DESCRIPTION' => '<strong>Stripe Pay</strong>',
+
+
+e.g 
+
+```
+$define = [
+    'MODULE_PAYMENT_STRIPE_PAY_TEXT_TITLE' => 'Stripe Checkout',
+    'MODULE_PAYMENT_STRIPE_PAY_TEXT_DESCRIPTION' => '<strong>Stripe Pay</strong>',
+];
+return $define;
+```
+
+Note: also if you want to provide a different tiile in the admin interface you can add something like 
+
+`MODULE_PAYMENT_STRIPE_PAY_ADMIN_TEXT_TITLE' => 'Stripe Checkout(ADMIN)`
+

content/dev/modules/base/logging/_index.md

@@ -0,0 +1,96 @@
+---
+title: Module Logging
+description: 
+weight: 120
+layout: docs
+---
+
+{{% alert title="Warning" color="warning" %}}
+The documentation in this section is Work in progress and relates to features that might not be available yet.
+{{% /alert %}}
+
+# Introduction
+
+All modules have access to a new logging infrastructure.
+
+This logging infrastructure uses monolog as the log provider. 
+
+It provides 3 log handlers 
+
+- File logging
+- Console logging
+- Email Logging
+
+To log something in a module you can do 
+
+`$this->logger->log($logLevel, $message, $context)`
+
+$logLevel is based on the standard log levels that PSR/log supports. 
+
+i.e 
+
+```
+class LogLevel
+{
+    const EMERGENCY = 'emergency';
+    const ALERT     = 'alert';
+    const CRITICAL  = 'critical';
+    const ERROR     = 'error';
+    const WARNING   = 'warning';
+    const NOTICE    = 'notice';
+    const INFO      = 'info';
+    const DEBUG     = 'debug';
+}
+```
+
+$context is not required but if passed, should be an array of values.
+
+## File logging
+
+This logs the message and context(if passed) to a file. 
+
+Logs all messages with a level of `debug` or higher.
+
+The file name that is used is determined as follows.
+
+A prefix will be generated based on the log channel, which is based on the module type. 
+
+e.g. payment/shipping/order_total.
+
+The code of the module is then added. 
+
+e.g. `flat` or `paypal` etc.
+
+following this a string will be added based on whether the code generating the log is either admin or storefront code.
+
+The log file name will then be suffixed with the current date using a format that means logs will be aggregated daily.
+
+### For logs generated by Admin code. 
+
+This will be prefixed with `admin-`
+
+and the current session admin id will be added if applicable.
+
+Then if the code generating the error references an order, the order id will be added.
+
+### For logs generated by store front code.
+
+This will be prefixed with `store-`
+
+Then if a customer id is available in the context of the log then the customer id, and a partial customer first name and last name will be added to the log file name.
+
+
+## Console Logging
+
+This will log the error message and context(if passed) to the javascript console. 
+
+So will be viewable using your browsers developer console.
+
+Logs all messages with a level of `debug` or higher.
+
+## Email Logging
+
+This will send an email to the email address of the store owner. Currently there is no way to change this but that might change in the future.
+
+Logs all messages with a level of `error` or higher.
+

content/dev/modules/order_totals/_index.md

@@ -0,0 +1,12 @@
+---
+title: Order Totals Modules
+description: 
+weight: 140
+layout: docs
+---
+
+{{% alert title="Warning" color="warning" %}}
+The documentation in this section is Work in progress and relates to features that might not be available yet.
+{{% /alert %}}
+
+# Introduction

content/dev/modules/payment/_index.md

@@ -0,0 +1,12 @@
+---
+title: Payment Modules
+description: 
+weight: 100 
+layout: docs
+---
+
+{{% alert title="Warning" color="warning" %}}
+The documentation in this section is Work in progress and relates to features that might not be available yet.
+{{% /alert %}}
+
+# Introduction

content/dev/modules/shipping/_index.md

@@ -0,0 +1,20 @@
+---
+title: Shipping Modules
+description:
+weight: 120
+layout: docs
+---
+
+{{% alert title="Warning" color="warning" %}}
+The documentation in this section is Work in progress and relates to features that might not be available yet.
+{{% /alert %}}
+
+# Introduction
+
+In order to make it easier and quicker to write modules(Payment/Shipping/Order Totals) a new infrastructure for these modules has been created.
+
+This new infrastructure will reduce the amount of boiler plate code required, minimize copy/paste coding and adds helpers for common coding requirements.
+
+{{% alert title="Note" color="primary" %}}
+Previous Payment/Shipping/Order total modules will continue to work without modification.
+{{% /alert %}}