Skip to content
How-toForDeveloper⏱ About 30 min
Before you start:
  • A checkout of BMA's repository
  • PHP 8.2+
  • Node 20
  • a sandbox

Tutorial: your first module ​

You'll make hello: an API route that answers {"hello":"world"}, a screen with a button that calls it, a menu item, and a permission. Every step below was run on a sandbox exactly as written.

Run php bin/console … from the install's appcenter-next/ folder, and the bin/*.sh scripts from the repository root.

1. A sandbox ​

bash
SANDBOX_ENV=local bash bin/dev-sandbox.sh hello-dev 8096

It copies the code into a throwaway SQLite install on http://127.0.0.1:8096, with test organizations (alpha, beta) and users. SANDBOX_ENV=local lets it register unsigned modules, which real servers never do. The output names the sandbox folder: cd into it for the next steps.

2. Scaffold ​

bash
php bin/console module:new hello --kind=source
text
modules/source/hello/
├── module.json          id, version 1.0.0, API prefix /hello, a route and menu item /hello, permission hello.view
├── api/routes.php       the router: function hello_route($method, $path, $body)
└── ui/
    ├── vite.config.ts   entry src/index.ts → dist/index.js
    └── src/
        ├── index.ts     register(): the screens this bundle provides
        ├── host.ts      access to BMA's API client and settings
        └── HelloView.vue

The router answers its own paths and ignores everything else:

php
function hello_route($method, $path, $body)
{
    if ($path !== '/hello' && strpos((string) $path, '/hello/') !== 0) {
        return; // not ours
    }
    if ($path === '/hello/hello' && $method === 'GET') {
        ApiResponse::ok(array('tenant_id' => Tenant::currentId(), 'hello' => 'world'));
    }
    ApiResponse::error('Not found', 404);
}

The screen calls it through BMA's API client:

vue
<v-btn color="primary" :loading="loading" @click="load">Say hello</v-btn>
…
const { data } = await host().api.get('/hello/hello')

3. Build and stamp ​

From the repository root, build the UI bundles of the sandbox copy and write each module's file checksums:

bash
bash bin/build-modules.sh <sandbox folder>
text
stamped [email protected] (6 files, UNSIGNED)

Then, in the sandbox folder, check the manifest:

bash
php bin/console module:validate modules/source/hello --allow-unsigned

4. Register, install, enable ​

bash
php bin/console module:register modules/source/hello
php bin/console module:install hello --tenant=alpha
php bin/console module:enable hello --tenant=alpha
text
registered [email protected] (source, origin repo, channel stable, unsigned)
installed hello for tenant alpha (id 3): version 1.0.0, channel stable, disabled
enabled hello for tenant alpha (id 3): version 1.0.0, channel stable, enabled

5. See it work ​

Sign in at http://127.0.0.1:8096/next/ as ta_alpha (the alpha organization's admin; the sandbox prints the password). Hello is in the navigation; click it, then Say hello: {"tenant_id":3,"hello":"world"}.

The gate does its job:

WhoGET /api/index.php/hello/hello
alpha's admin (holds hello.view through default_groups: ["tenant_admin"])200 {"hello":"world"}
an alpha member without hello.view403 {"permission":"hello.view"}
anyone in beta (module not enabled)403 {"code":"module_not_enabled"}

6. Change it ​

Versions are immutable. To change anything: edit, bump version in module.json (say 1.0.1), build and stamp, register, then upgrade the organization in Tenant Modules (or POST /tenants/<id>/modules/hello/upgrade). Reload the browser to pick up the new bundle.

Next ​

bin/dev-sandbox.sh --stop hello-dev removes the sandbox.