Package · Extension
Hello extension
The minimal example extension: it adds bm_hello() to the PHP that runs on the board and nothing else. Use it to check that a project builds its packages in; it needs no other package, on any platform.
ext-hello adds one function, bm_hello(), to the PHP that runs on your board. It does nothing useful on purpose.
It serves two purposes:
- Checking a project. If
bm_hello()works, the project picks up the packages it requires, builds them in and runs your script. - Showing the smallest extension package. One C file and a
composer.json; see the layout below.
Require it while setting up a new project, or when a package you required does not show up and you want to tell a project problem from a package problem. Remove it once the project works.
Requirements
Pure. It touches no hardware and requires no HAL, so conductor adds nothing for it and it builds for whatever
platform your project targets. The only requirement is php >=8.3. The extension's PHP module is hello.
Install
-
Install conductor once per machine
composer global require php-baremetal/conductorkeeps the plugin active during the first solve of a new project. -
Create the project
phpbm init my-hellowritescomposer.jsonwith conductor (^1.0, allowed as a plugin), the package registry, and the SDK, board, runtime and storage you pick. -
Require the extension
composer require php-baremetal/ext-hello -
Build and flash
phpbm flashbuilds the firmware and flashes it;phpbm monitoropens the serial console. The function exists only in a firmware built with the package.
The resulting composer.json, for a Waveshare ESP32-S3-Touch-LCD-1.85B:
{
"name": "acme/my-hello",
"type": "project",
"repositories": [
{ "type": "composer", "url": "https://repository.php-baremetal.com", "canonical": true }
],
"require": {
"php-baremetal/conductor": "^1.0",
"php-baremetal/ext-hello": "^1.0"
},
"config": {
"allow-plugins": { "php-baremetal/conductor": true },
"platform": { "php": "8.5.11" }
},
"extra": {
"baremetal": {
"sdk": "esp32@^2.0",
"board": "waveshare-esp32-s3-touch-lcd-1.85b",
"runtime": "init-loop",
"storage": "embedded"
}
}
}
PHP API
| Function | Returns | Meaning |
|---|---|---|
bm_hello() |
string |
The fixed greeting "hello from ext-hello package". |
<?php
echo bm_hello(), "\n"; // hello from ext-hello package
Full reference: PHP API.
The package, as a template
An extension package is a Composer package of type bm-ext with C sources. ext-hello is the whole of it:
{
"name": "php-baremetal/ext-hello",
"type": "bm-ext",
"require": { "php": ">=8.3" },
"extra": {
"baremetal": { "module": "hello" }
}
}
extra.baremetal.module is the module name; the C file in src/ defines the matching zend_module_entry and its
functions. A package that needs hardware adds php-baremetal/<x>-hal to require and calls the HAL header from
its C code; ext-mem is the next step up, an extension with state
and still no hardware.
Notes
bm_hello()has no arguments, no state and no side effects.- Nothing else depends on ext-hello and it provides nothing.
Related
- PHP API PHP API
- Check that a package is built in Recipe
- ext-mem Extension