Skip to content

Bamboo v1.0 Upgrade Guide

This guide walks 0.x installations through the final steps required to adopt the v1.0 contract freeze. It assumes the application already targets Bamboo v0.4 and OpenSwoole deployments.

Audience and prerequisites

  • Source application currently running on Bamboo ^0.4.
  • PHP 8.4 with the cURL, OpenSwoole, and Redis extensions available.
  • Access to the deployment environment to update system packages and restart the HTTP workers.

Before proceeding, confirm the toolchain versions:

php -v
php --ri openswoole | grep Version

Step-by-step upgrade flow

  1. Back up configuration and environment files.

  2. Commit local changes or create copies of .env and the etc/ directory.

  3. Update Composer dependencies.

  4. Bump Bamboo to the v1.0 constraint: composer require greenarmor/bamboo:^1.0.

  5. Run composer install to download updated packages.

  6. Run configuration validation.

  7. Execute composer validate:config to run the new config.validate command.

  8. Address reported issues (missing keys, empty secrets, invalid timeouts) before continuing.

  9. Adopt new configuration files.

  10. Copy etc/resilience.php and merge any project-specific overrides. This file defines timeout and circuit breaker defaults consumed by the new middleware.

  11. Ensure etc/middleware.php contains Bamboo\Web\Middleware\CircuitBreakerMiddleware::class and Bamboo\Web\Middleware\TimeoutMiddleware::class in the global stack. Custom configurations should merge these entries into their own arrays.

  12. Review module bootstrapping.

  13. Applications relying on modules must update etc/modules.php to include module classes explicitly; v1.0 treats module order as part of the public contract documented in docs/modules.md.

  14. Refresh the route cache (if used).

  15. Run php bin/bamboo routes.cache after the application boots locally to regenerate var/cache/routes.cache.php without closures.

  16. Validate operational scripts.

  17. Update CI pipelines to call composer validate:config alongside linting and tests.

  18. Add php bin/bench/http --label="pre-release" to capture baseline numbers for regression monitoring.

  19. Smoke-test the application.

  20. php bin/bamboo http.serve locally; verify /, /metrics, /healthz, and /readyz respond as expected.

  21. Run the integration test suite (composer test).

  22. Deploy.

  23. Publish the updated Docker image or artefact.
  24. Monitor /metrics and the new circuit breaker metrics for anomalies during the first traffic window.

Compatibility matrix

Component Supported versions
PHP 8.4.x
OpenSwoole 22.1 or newer (built with coroutine and HTTP/WS support)
Redis 6.x or newer
Prometheus client promphp/prometheus_client_php ^2.7

Configuration deprecation policy

Configuration keys and files under etc/ participate in the v1.x compatibility promise. When schema changes are necessary:

  • Deprecated keys remain functional for at least one minor release (e.g. a key marked in v1.2 continues working through v1.3). During the window Bamboo emits E_USER_DEPRECATED notices whenever the legacy key is read and highlights the pending removal in the release notes.
  • Replacement keys must be documented in both the configuration reference and release notes. Maintain fallbacks that read from both keys until the grace period expires.
  • Run composer validate:config after updating Bamboo; the validator reports missing keys, empty secrets, and other drift before the configuration ships to production.

Example rename workflow

When etc/http.php renames timeouts.default to timeouts.client_default:

  1. Ship Bamboo v1.2 with support for both keys:
$httpConfig = $config->get('http');

$defaultTimeout = $httpConfig['timeouts']['client_default']
    ?? $httpConfig['timeouts']['default']
    ?? 3.0;

Accessing timeouts.default triggers a deprecation notice.

(In this example $config is the injected Bamboo\Core\Config service.)

  1. Document the rename in the release notes and update docs/configuration/overview.md so operators see the new key alongside the migration guidance.
  2. Encourage users to run composer validate:config after updating their configuration files; the validator warns when only the deprecated key is present.
  3. Remove the fallback in v1.4 once the grace period expires.

This policy keeps configuration migrations predictable while ensuring operators have clear tooling and documentation for the change window. Refer to the configuration overview for the canonical schema tables and additional examples.

Deprecations lifted in v1.0

No runtime deprecations remained pending for v1.0. The release formalises the configuration schema, router behaviour, and CLI command catalogue introduced throughout the 0.4 series. Future deprecations will be announced with warning emissions, upgrade notes, and automated tooling per the policies captured in the CLI and configuration references.

Additional resources

For further assistance, open a discussion on the project repository or join the community chat linked from the README.