Appearance
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 8096It 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=sourcetext
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.vueThe 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-unsigned4. 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=alphatext
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, enabled5. 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:
| Who | GET /api/index.php/hello/hello |
|---|---|
alpha's admin (holds hello.view through default_groups: ["tenant_admin"]) | 200 {"hello":"world"} |
an alpha member without hello.view | 403 {"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
- Back end: more routes, your own permissions, tables, settings.
- Sign, test and release: real servers accept only signed modules.
bin/dev-sandbox.sh --stop hello-dev removes the sandbox.