This document lists everything operators and integrators must prepare for when upgrading to BillRun 6.0.0. Items marked [ACTION REQUIRED] need a deliberate step during upgrade; items marked [HEADS UP] may affect custom code or configuration.
Docker deployments handle most of these steps automatically (see each item). Manual / bare-metal deployments must perform them explicitly.
composer install [ACTION REQUIRED]The vendor/ directory and composer.lock are no longer tracked in the repository (both are now gitignored). Previously BillRun shipped its PHP dependencies inside the repo.
What you must do:
composer install to fetch dependencies before starting the application.composer install during build/startup. No manual action needed.Note: because composer.lock is no longer committed, installs resolve against the version constraints in composer.json. If you need byte-for-byte reproducible builds, generate and store your own composer.lock in your deployment artifact.
BillRun 6.0.0 supports and is tested on PHP 8.1 through 8.5. Official Docker images are provided for php 8.5.
What you must do:
billrun-php85).BillRun 6.0.0 ships against the latest mongodb PECL extension (e.g. mongodb-2.1.x on PHP 8.2+, mongodb-1.19.x on PHP 7.4/8.1), together with the mongodb/mongodb library. The legacy mongo extension has not been used since BillRun 5.0, so no driver migration is required for 5.x-era operators.
What you should do:
mongodb PECL extension is installed and reasonably up to date on your PHP runtime.BillRun 6.0.0 targets MongoDB Server 8.0 (compose files now use mongo:8.0). Sharding is configured automatically at initialization.
What you must do:
Ubuntu 26.04 note: Ubuntu 26.04 currently ships with a kernel that is not supported by MongoDB 8.0. On Ubuntu 26.04, the maximum supported MongoDB version is 7.0. BillRun 6.0.0 remains compatible with MongoDB 7.0 - upgrade to MongoDB 8.0 once Ubuntu provides a kernel that MongoDB 8.0 supports.
Database initialization and migration no longer rely on JavaScript Mongo-shell scripts. They are now driven by a PHP-native migration framework that is idempotent and tracks applied tasks.
What you must do:
mongo/*.js scripts manually.The legacy single billrun document is split into two new sharded collections - billrun_subs (subscriber-level data) and billrun_grouping (per-cycle aggregations) - declared in container.ini with dedicated indexes. A migration script ships with the release and runs as part of the PHP-native migration framework on first boot. Backward-compatible reads remain for any legacy billrun objects that still embed subs.
What you must do / know:
billrun.subs.* / billrun.grouping.* directly in MongoDB should switch to the new billrun_subs / billrun_grouping collections, or use the Billrun model API which transparently resolves both layouts.BillRun 6.0.0 introduces a customer hierarchy model: accounts can have a parent account, with up to 4 levels in phase 1. Migration application/migrations/20260527_001_BRCD-785.php adds three system fields to accounts (in the subscribers collection, type=account) and an index on parent_aid:
| Field | Type | Default | Meaning |
|---|---|---|---|
parent_aid |
int/null | null |
Parent account id (null = root / no parent). |
issues_invoice |
bool | true |
If false, charges roll up to nearest invoicing ancestor. |
is_payer |
bool | true |
If false, payment resolves to nearest is_payer=true ancestor. |
Rules:
issues_invoice=false implies is_payer=false.parent_aid=null) are always issues_invoice=true and is_payer=true.aid and persist there even if issues_invoice later flips - there is no subtree summing.What you must do / know:
parent_aid set. Flat tenants behave exactly as in 5.x with no change.Billrun_Bill_Payment::makePayment - it walks up to the nearest is_payer=true ancestor. Custom payment-pipeline plugins should be aware.aid and works automatically.gethierarchy (BillAPI) returns the hierarchy with issues_invoice / is_payer for an account subtree.phpoffice/phpspreadsheet: 1.15.0 -> ^1.16. Relevant if you have custom invoice/report/export code that calls PhpSpreadsheet directly.^2.0 (module-rest, module-mongodb, module-db, module-phpbrowser 1.0.3). If you maintain custom acceptance tests, update them accordingly.The admin/customer UI is upgraded to React 19, with legacy Bootstrap 3 patterns removed and asset bundles regenerated (new hashed filenames). The compiled frontend assets ship inside the repository, so no client-side build step is required during upgrade.
What you should do:
cache.* namespace and now ships with a dedicated clearCache script/action that also resets OPcache. Update your config if you previously set this flag.BR_MDB_* environment overrides: if you are upgrading from a version earlier than 5.25.0, note the 5.25.0 breaking change where BR_MDB_* environment variables override MongoDB connection config.billrun_roles path and any custom scopes after upgrade.docker pull billrun/billrun:6.0.0 (published automatically per tagged version as billrun/billrun:<version>, from 5.25.0+).-p 8074:8074).APPLICATION_MULTITENANT (default 0) controls single- vs. multi-tenant nginx routing; set to 1 for multi-tenant.mongodb PECL extension installed.composer install.billrun_subs / billrun_grouping split - §5a - and the customer-hierarchy field migration - §5b).billrun_subs / billrun_grouping. If you adopt the customer hierarchy, validate invoice consolidation and payment-gateway resolution on a non-production tenant first.