PHP extensions
Optional PHP extensions are added with composer require php-baremetal/php-name and cost flash and PSRAM only when required. How to use the common ones on the board, and how pure-PHP Composer libraries travel inside the firmware.
The firmware runs the real PHP engine. Eight modules are always built in (core, hash, json, pcre,
random, reflection, spl, standard; PHP 8.5 adds uri), with no package to require. Every other extension is
optional: a project that does not require it pays nothing in flash or PSRAM.
Enable an extension
Require the package named after the extension, then build:
- The package name is
php-baremetal/php-<extension>:php-baremetal/php-pdo_sqliteaddspdo_sqlite. - The thirteen optional extensions are
bcmath,ctype,date,filter,mbstring,opcache,openssl,pdo,pdo_sqlite,session,sqlite3,tokenizerandzlib. They exist on PHP 8.3, 8.4 and 8.5. Sizes and the versions are in PHP versions and extensions. pdo_sqliteneedspdo. Without it the build stops withphp extension 'pdo_sqlite' needs 'pdo': composer require php-baremetal/php-pdo.- Some extensions have options in
extra.baremetal.options(date-timezones,mbstring-cjk,mbstring-regex,opcache-memory,opcache-validate). They are accepted only once the extension is required; see Options. - Extensions are compiled in. There are no
.sofiles and nozend_extension. - Not available at all:
intl,iconv,fileinfo,gd,curl, the fullopenssland TLS. - Check at run time with
extension_loaded('mbstring')orfunction_exists('mb_strlen').
The examples of this page are in 02-extensions/. Each one is a full project; copy its composer.json.
Memory outside memory_limit
Several extensions allocate from the PSRAM the firmware keeps for itself, not from memory_limit: the SQLite page
cache (up to 256 KB per open connection), the memory session handler (up to 64 KB), the garbage collector's
buffer. Each extension also takes a fixed share of PSRAM at boot. If a script runs out of memory with a free
memory_limit, raise the firmware-reserve option. The split is explained in
Memory, flash and partitions.
SQLite
Packages: php-baremetal/php-pdo and php-baremetal/php-pdo_sqlite for PDO, php-baremetal/php-sqlite3 for the
SQLite3 class. Both embed the SQLite 3.54.1 engine, so with both installed the engine is compiled once.
The example 02-extensions/sqlite writes one row on each boot into a database on the microSD, so the row survives
resets. It needs a board with a microSD slot and storage set to microsd; the project uses
waveshare-esp32-p4-pico.
On the board:
- Put the database on the card (
/sdcard/...). Withembeddedstorage the sources are in a read-only image, so a database cannot live there. - The card is a FAT file system, which has no
fcntllocking. SQLite opens databases exclusively, which keeps a reset in the middle of a transaction from corrupting the file. The example opens afile:URI with?nolock=1and keeps the journal in RAM (journal_mode = MEMORY,synchronous = OFF), as a single-process device needs no locking. - The page cache is allocated outside
memory_limit, up to 256 KB per open connection. Close connections you no longer use. - The
pdo_sqlitebusy timeout is 5 s by default;PDO::ATTR_TIMEOUTchanges it.
Sessions
Package: php-baremetal/php-session. The default memory handler keeps up to 64 sessions, 64 KB in all, in PSRAM;
they are gone after a reset. The files handler needs the microsd storage and writes to /sdcard/sessions.
The example 02-extensions/session uses the files handler on the card, so the visit counter survives resets:
In the web-server runtime the same handlers carry a session across HTTP requests.
Strings and text
php-baremetal/php-mbstring gives the mb_* functions. It is the replacement for iconv, which is not available:
mb_convert_encoding() does the conversions. Two options shape its size:
mbstring-cjk(defaulttrue):falsedrops the Chinese, Japanese and Korean encodings and saves most of the extension's flash. UTF-8, UTF-16, UTF-32, Latin and Cyrillic stay.mbstring-regex(defaultfalse):trueaddsmb_ereg*()andmb_split()with the oniguruma library, about 445 KB more flash.
The example sets "mbstring-regex": true in its options and guards the regex part with
function_exists('mb_ereg'). ctype (02-extensions/ctype) adds ctype_alpha(), ctype_digit() and the other
character-class checks in about 3 KB; filter (02-extensions/filter) adds filter_var() for validating and
sanitizing input:
Date and time
Without php-baremetal/php-date the firmware has a small stand-in: time() and a minimal formatting, in the UTC
zone. With it you get DateTime, DateTimeImmutable, DateTimeZone, DateInterval and named zones.
date-timezones sets how much of the zone database is built: full (the default, about 610 KB of flash) knows
every named zone; utc (about 255 KB) knows UTC only, and a named zone such as Europe/Rome is rejected. The
example 02-extensions/date uses the full database:
Tokenizer
php-baremetal/php-tokenizer gives token_get_all() and PhpToken, the engine's own lexer, which frameworks
lean on. It works in memory and needs no file system (02-extensions/tokenizer).
OpenSSL
php-baremetal/php-openssl is a partial API on top of the mbedTLS of ESP-IDF: AES-CBC, AES-CTR and AES-GCM
through openssl_encrypt() and openssl_decrypt(), digests (openssl_digest()) and openssl_random_pseudo_bytes(). Only the
OPENSSL_RAW_DATA, OPENSSL_ZERO_PADDING and OPENSSL_DONT_ZERO_PAD_KEY constants exist. There are no keys,
signatures, X.509 or TLS. The output is byte-for-byte the one of desktop OpenSSL, so data encrypted on the board
decrypts elsewhere.
A library that needs RSA keys, signatures, certificates or TLS does not work with php-openssl. The compact build
covers what a framework's encrypter needs: symmetric ciphers.
Other extensions
| Extension | Use on the board |
|---|---|
zlib |
Deflate needs about 260 KB of memory_limit while it runs. gzopen() and compress.zlib:// work. |
bcmath |
Arbitrary precision arithmetic, about 25 KB. |
opcache |
A bytecode cache in PSRAM, no JIT. opcache-memory (256 to 16384 KB, default 1024) is taken from memory_limit; a board with less than 4 MB of PSRAM disables it at boot. opcache-validate is for microsd storage. |
Composer libraries in your project
The extension packages above are installed by the conductor into .phpbm/packages/ and compiled into the
firmware. A pure-PHP library is different: it is plain PHP, so it travels with your sources. The build and
phpbm sync ship the contents of the source directory (project-src by default) to the board, and nothing
outside it. The vendor/ folder next to your root composer.json belongs to the conductor and is not shipped.
To use a library such as illuminate/collections, give the source directory its own Composer project:
The example 01-language/composer-collections has a project-src/composer.json:
and its index.php loads the autoloader and uses the library:
- Run
composer install --no-dev -oinproject-srcbeforephpbm buildorphpbm flash. Thevendor/folder is packed with the sources (about 1.1 MB for this example). - With
embeddedstorage the sources and the vendor folder go into the read-only image in flash, so a largevendor/shrinks the firmware's flash budget; withmicrosdthey are copied to the card (Storage). Keep--no-devand the optimized autoloader. - The nested Composer does not see the extensions the firmware has. If it refuses a library for a missing
ext-*, declare the extension underconfig.platformofproject-src/composer.json, as the Symfony example does (PHP frameworks). - A library that needs an extension the firmware does not have (
intl,curl,gd) will not run.
Without Composer, require works as on any PHP. The example 01-language/require-demo splits a program across
index.php, config.php and lib/shapes.php with require_once __DIR__ . '/lib/shapes.php': the whole source
directory is packed with its layout.
Common errors
| Symptom | Cause |
|---|---|
php extension 'pdo_sqlite' needs 'pdo': composer require php-baremetal/php-pdo |
A required extension package is missing. |
unknown option 'mbstring-regex' in extra.baremetal.options |
The option belongs to an extension that is not required yet. |
Call to undefined function mb_strlen() |
The extension package is not required, or the build did not run again. |
Uri\WhatWg\Url throws an Error (PHP 8.5) |
The WHATWG parser is not built; parse_url() and the RFC 3986 parser work. |
mb_split() undefined with mbstring required |
mbstring-regex is off. |
| A named time zone is rejected | date-timezones is utc. |
Out of memory while memory_limit is free |
SQLite, sessions or another extension use the PSRAM outside memory_limit; raise firmware-reserve. |
Class not found for a library |
vendor/autoload.php is missing from project-src: run composer install there. |