• Apps
  • Introduction
  • Structure
  • Modules
    • Getting Class Names
    • Getting Modules
  • Routes

Apps OSC\Apps\

Introduction

Apps are self-contained packages that add new features and extend existing features without the need to edit core source code files. All files of an App are located in one main directory, with an external public directory for public resources (eg, images, javascript, stylesheets, ..).

Structure

Apps are located in the following directory:

includes/OSC/Apps/VENDOR/APP

Files that need to be publicly accessible are located at:

public/Apps/VENDOR/APP

A JSON structured oscommerce.json metadata file must exist in the top level App directory that describes the App and the modules it makes available. Modules do not need to exist in a specific directory within the package - rather the namespace is defined in the metadata file which the framework uses as a reference to find the location of the module class file.

Metadata File Example: osCommerce\Core

{
  "title":            "osCommerce Core Modules",
  "app":              "Core",
  "vendor":           "osCommerce",
  "version":          1.0.0,
  "req_core_version": 2.4.0,
  "license":          "MIT",
  "authors": [
    {
      "name":    "osCommerce",
      "company": "osCommerce",
      "email":   "[email protected]",
      "website": "https://www.oscommerce.com"
    }
  ],
  "modules": {
    "Payment": {
      "COD": "Module\\Payment\\COD"
    },
    "Shipping": {
      "Flat":  "Module\\Shipping\\Flat",
      "Zones": "Module\\Shipping\\Zones"
    },
    "Hooks": {
      "Shop/Cart": {
        "AdditionalCheckoutButtons": "Module\\Hooks\\Shop\\Cart\\AdditionalCheckoutButtons"
      }
    }
  },
  "routes": {
    "Admin": "Sites\\Admin\\Pages\\Home",
    "Shop": {
      "new-offers": "Sites\\Shop\\Pages\\NewOffers",
      "account&coupons": "Sites\\Shop\\Pages\\Coupons"
    }
  }
}

Metadata Schema

Modules that are installed and registered in the database are not stored with their full namespace class names, rather with an alias as defined in the metadata file.

For example, the core Cash on Delivery payment module is stored in the MODULE_PAYMENT_INSTALLED configuration parameter as osCommerce\Core\COD. The payment class knows that a payment module is being requested and looks up the COD alias defined in the metadata file to retrieve the class as Module\Payment\COD. The full class name reference and file location would be:

Modules

Modules that are to be made available to the framework must be defined in the Apps metadata file. Each module type has its own definition specification to be able to load the module class on request simply by referencing an alias.

Each module must implement a module type interface which dictates the functions the module must make available to the framework. Module Type Interfaces are located in the following namespace and directory:

Module Types and Interfaces

The following Module Types are available in the core:

"app": "Core",
"vendor": "osCommerce",
"modules": {
  "AdminDashboard": {
    "NewOrders": "Module\\Admin\\Dashboard\\NewOrders",
    "NewCustomers": "Module\\Admin\\Dashboard\\NewCustomers"
  }
}

"modules": {
  "AdminDashboard": {
    "ALIAS": "CLASS"
  }
}

VENDOR \ APP \ ALIAS

osCommerce\Core\NewOrders
osCommerce\Core\NewCustomers

"app": "Core",
"vendor": "osCommerce",
"modules": {
  "AdminMenu": {
    "Products": "Module\\Admin\\Menu\\Products",
    "Orders": "Module\\Admin\\Menu\\Orders"
  }
}

"modules": {
  "AdminMenu": {
    "ALIAS": "CLASS"
  }
}

VENDOR \ APP \ ALIAS

osCommerce\Core\Products
osCommerce\Core\Orders

"app": "Core",
"vendor": "osCommerce",
"modules": {
  "Content": {
    "login": {
      "Social": "Module\\Content\\SocialLogin"
    }
  }
}

"modules": {
  "Content": {
    "CONTENT MODULE GROUP": {
      "ALIAS": "CLASS"
    }
  }
}

CONTENT MODULE GROUP / VENDOR \ APP \ ALIAS

login/osCommerce\Core\Social

"app": "Core",
"vendor": "osCommerce",
"modules": {
  "Hooks": {
    "Shop/Account": {
      "Logout": "Module\\Hooks\\Shop\\Account\Logout"
    }
  }
}

"modules": {
  "Hooks": {
    "SITE / GROUP": {
      "ACTION": "CLASS"
    }
  }
}

VENDOR \ APP \ SITE / GROUP \ ACTION

osCommerce\Core\Shop/Account\Logout

"app": "Core",
"vendor": "osCommerce",
"modules": {
  "Payment": {
    "COD": "Module\\Payment\\COD"
  }
}

"modules": {
  "Payment": {
    "ALIAS": "CLASS"
  }
}

VENDOR \ APP \ ALIAS

osCommerce\Core\COD

"app": "Core",
"vendor": "osCommerce",
"modules": {
  "Shipping": {
    "Flat": "Module\\Shipping\\Flat"
  }
}

"modules": {
  "Shipping": {
    "ALIAS": "CLASS"
  }
}

VENDOR \ APP \ ALIAS

osCommerce\Core\Flat

VENDOR \ APP \ ALIAS _ SHIPPING_METHOD

DHL\Shipping\National_Express

"app": "Core",
"vendor": "osCommerce",
"modules": {
  "OrderTotal": {
    "Subtotal": "Module\\OrderTotal\\Subtotal"
  }
}

"modules": {
  "OrderTotal": {
    "ALIAS": "CLASS"
  }
}

VENDOR \ APP \ ALIAS

osCommerce\Core\Subtotal

Getting Class Names

The full namespace class name of a module can be retrieved via its alias using Apps::getModuleClass():

use OSC\OM\Apps;

$class = Apps::getModuleClass('osCommerce\Core\COD', 'Payment');

// $class = OSC\Apps\osCommerce\Core\Module\Payment\COD

Parameters

Apps::getModuleClass($module, $type)

Getting Modules

A list of available App modules can be retrieved using Apps::getModules():

use OSC\OM\Apps;

$modules = Apps::getModules('Payment');

Parameters

Apps::getModules($type, $filter_vendor_app, $filter)

Routes

Routes allow Apps to load Page controllers via the Sites route resolver method. The Shop Site allows Apps to load Page controllers depending on the url of the page requested, and the Admin Site allows one main Page controller to be loaded to administrate and configure the App on the Administration Dashboard.

"app": "Core",
"vendor": "osCommerce",
"routes": {
  "Admin": "Sites\\Admin\\Pages\\Home",
  "Shop": {
    "new-offers": "Sites\\Shop\\Pages\\NewOffers",
    "account&coupons": "Sites\\Shop\\Pages\\Coupons"
  }
}