3.3 documentation

An extension is a basically a package or module (package with routes) except that first it need to have a manifest file as similar as you would have composer.json for every package.

  1. Managing an Extension
  2. Basic of an Extension
  3. Configuring an Extension
  4. Adding Extension Location

Managing an Extension

Extensions will be managed by Orchestra Platform Administrator Interface. Login as an administrator and go to Extensions on the main navigation.

Few things to consider:

  • Only activated extensions will be run on runtime.
  • Orchestra Platform will register an boot every service providers listed by the extension.

Basic of an Extension

Manifest File

The manifest file will be stored in {package-name}/orchestra.json (same level as composer.json), this tell Orchestra Platform to handle the package as an extension.

{
    "name": "Robotix",
    "description": "Robots.txt",
    "author": "Mior Muhammad Zaki",
    "url": "https://github.com/crynobone/robotix",
    "version": "1.0.0",
    "config": {
        "handles": "robotix"
    },
    "provides": [
        "Robotix\\RobotixServiceProvider"
    ],
    "plugin": "Robotix\\RobotixPlugin",
    "autoload": [
        "start.php"
    ]
}
Key Type Required Description
name string Yes Unique name for the extension using {vendor}/{package} format.
description string No Description for the extension, retrieve from composer.lock if installed through Composer.
author string Yes Name of the extension author.
url string Yes URL for the project repository, or website.
version string No Current installed version, retrieve from composer.lock if installed through Composer.
config object No List of default extension configuration.
provides array No List of service providers used by the extension.
plugin string No Plugin configuration class (if needed).
autoload string No List of autoload files for the extension.

Configuring an Extension

By default, administrator are able to configure any extension based on requirement of the application including handles value using Orchestra Platform Administrator Interface. This allow non-technical administrator to take charge of the application without having to understand any of the code.

To configure an extension, the extension need to be activated. Once this is done, all extension that allow configuration can be configured. Simply click on the extension name to navigate to the configuration page.

Service Providers for Extension

Manifest file also allow extension to dynamically register service providers without having to change resources/config/app.php. To tell Orchestra Platform to automatically run your service provider, include the following:

    "provides": [
        "Robotix\\RobotixServiceProvider"
    ]

You can add multiple service provider on a single extension, it also will respect if the service provider is deferred.

Autoloading Files

Apart from service providers, you can also set pre-define PHP file to be loaded when the extension is booted. These start files allows extension to any booting script required for the extension to work (as Laravel run application start.php file).

    "autoload": [
        "start.php"
    ]

In the above example, {package-name}/start.php will be loaded.

What inside the file depends on how extension would interact with Orchestra Platform and this can be diverse depending on use cases.

Default Start File

Other than specifying the autoload file, Extension would also load the default start file will be stored in {package-name}/src/orchestra.php or {package-name}/orchestra.php.

Handling a Route

Unliked basic packages for Laravel, end users doesn't have control to manage packages routing as compared to Orchestra Platform, any extension that offer routing would only need to identify a default route option by adding:

    "config": {
        "handles": "robotix"
    }

Disabling Configuration

Extension developers can disable configuration option by adding "configurable" : false, To do this edit your manifest file.

    "config": {
        "configurable": false
    }

By doing so, Orchestra Platform will take extension as it is and will not try to modify any of the configuration.

Adding Extension Location

By default, Extension component is configured to search for extension under the following folders using glob() PHP function:

  • app
  • workbench/*/*
  • vendor/*/*

If there a requirement to add non-distributed packages feel free to include your own structure, and include the path in App\Providers\ExtensionServiceProvider.

Be sure to add modules autoloading structure to app's composer.json.