Bamboo on PHP 8.2 — Installation & Configuration Guide¶

This guide covers a complete Bamboo v0.2 setup on PHP 8.2 using the OpenSwoole runtime. The walkthrough assumes an Ubuntu/Debian host but also calls out the required changes for macOS and other Linux distributions. Follow each section to prepare the CLI, HTTP server, Redis queue worker, and optional database integration.

1. Prerequisites¶

Tip: Use a shell with sudo privileges. On macOS replace apt commands with their Homebrew equivalents (brew install ...).

2. Install PHP 8.2 and extensions¶

2.1 Ubuntu/Debian¶

# Enable the maintained PHP packaging repository (if you do not already use it)
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update

# Install PHP 8.2 and required extensions
sudo apt install -y \
  php8.2 php8.2-cli php8.2-fpm php8.2-common php8.2-dev \
  php8.2-curl php8.2-mbstring php8.2-xml php8.2-zip php8.2-intl \
  php8.2-sqlite3 php8.2-mysql php8.2-pgsql php8.2-redis php8.2-gd

# Ensure the PHP 8.2 CLI is the default on your PATH
sudo update-alternatives --set php /usr/bin/php8.2

The php8.2-dev package delivers php-config8.2, which OpenSwoole needs while building. The remaining extensions match Bamboo's dependencies (curl, mbstring, pdo_*, intl, redis, etc.).

2.2 macOS (Homebrew)¶

brew update
brew install php@8.2 composer redis mysql
brew services start redis
brew services start mysql

Add the PHP binary to your path if Homebrew does not do this automatically:

echo 'export PATH="/opt/homebrew/opt/php@8.2/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

3. Install build dependencies and OpenSwoole¶

OpenSwoole is the coroutine HTTP server that powers Bamboo. It must be compiled against PHP 8.2.

# Toolchain & headers (Ubuntu/Debian)
sudo apt install -y build-essential autoconf pkg-config libssl-dev zlib1g-dev libcurl4-openssl-dev

# Optional: remove old OpenSwoole builds if you previously installed for PHP 8.1
sudo rm -f "$(php -i | grep '^extension_dir' | awk '{print $3}')/openswoole.so"

# Install through PECL (works on Linux and macOS)
printf "\n" | sudo pecl install openswoole

When prompted, accept the defaults or enable features you require:

• --enable-openssl (recommended for HTTPS).
• --enable-swoole-curl (keeps coroutine HTTP functionality).
• --enable-swoole-json (required for JSON helpers).

Register the extension:

echo "extension=openswoole" | sudo tee /etc/php/8.2/mods-available/openswoole.ini
sudo phpenmod openswoole

Verify the setup:

php -v
php -m | grep openswoole
php --ri openswoole

All commands should report PHP 8.2 and a loaded OpenSwoole module.

4. Install Composer and project dependencies¶

If Composer is not already available:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php --install-dir=/usr/local/bin --filename=composer
rm composer-setup.php

Clone the Bamboo repository and install PHP packages:

cd /opt # or any working directory you prefer
sudo git clone https://github.com/greenarmor/bamboo.git
cd bamboo
composer install

Composer pulls all runtime dependencies defined in composer.json, such as FastRoute, Nyholm PSR-7, Guzzle, Predis, Illuminate Database, and Monolog.

5. Project configuration¶

1. Copy the environment template and generate the application key:

   cp .env.example .env
   php bin/bamboo app.key.make
   

   The key is stored in .env and powers encryption helpers.

2. Review the .env file:

3. HTTP server: HTTP_HOST, HTTP_PORT, HTTP_WORKERS, TASK_WORKERS, MAX_REQUESTS, STATIC_ENABLED.
4. Redis: REDIS_URL (e.g., tcp://127.0.0.1:6379) and REDIS_QUEUE.
5. Database: Set DB_CONNECTION, DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME, and DB_PASSWORD if you use Eloquent.
6. WebSocket: WS_HOST and WS_PORT.

7. Logging: LOG_FILE defaults to var/log/app.log; adjust if your runtime uses a different writable path.

8. Prepare runtime directories and permissions:

   mkdir -p var/cache var/log
   sudo chown -R $USER:$USER var
   sudo chmod -R 775 var
   

   The cache directory stores route caches and other runtime artifacts, while the log directory receives application logs.

9. Understand the configuration files in etc/:

10. etc/app.php reads core app settings (APP_NAME, APP_ENV, APP_DEBUG, APP_KEY, LOG_FILE).
11. etc/server.php maps .env values to OpenSwoole server options (workers, task workers, static files).
12. etc/cache.php controls where cache artifacts are stored.
13. etc/http.php defines default timeouts, headers, and retry policies for the bundled PSR-18 HTTP client along with service overrides.
14. etc/redis.php and etc/ws.php configure the Redis queue connection and WebSocket server endpoint.
15. etc/database.php defines database connections for the optional Eloquent ORM integration.

Update these files if you need to commit environment-specific defaults to source control; otherwise rely on .env overrides for per-host customization.

6. Supporting services¶

• Redis: Install and start Redis so the queue worker can connect.

  sudo apt install -y redis-server
  sudo systemctl enable --now redis-server
  

• Database (optional): Install MySQL or MariaDB if you plan to use Eloquent.

  sudo apt install -y mysql-server
  sudo mysql_secure_installation
  

  Update .env with your credentials. For SQLite, point DB_DATABASE to an absolute file path and ensure the containing directory is writable.

• Supervisor/systemd (optional): To run Bamboo as a daemon, create a systemd unit invoking php /path/to/bamboo/bin/bamboo http.serve. Ensure the service account has permissions to the project directory.

7. Running Bamboo¶

Start the OpenSwoole HTTP server:

php bin/bamboo http.serve

Open http://127.0.0.1:9501 in a browser to confirm the welcome JSON. Other useful commands:

php bin/bamboo routes.show   # Inspect registered routes
php bin/bamboo queue.work    # Start the Redis-backed queue worker
php bin/bamboo ws.serve      # Start the WebSocket echo server
php bin/bamboo client.call --url=https://httpbin.org/get

For hot reloading during development, keep dev.watch running in another terminal. It watches source changes and restarts the server automatically.

8. Troubleshooting checklist¶

See docs/OpenSwoole-Compat-and-Fixes.md for more OpenSwoole tips.

9. Next steps¶

• Commit your .env overrides to a .env.local (or similar) file outside version control.
• Configure CI/CD runners with the same PHP 8.2 + OpenSwoole toolchain so deployments match local development.
• Explore the roadmap and CLI capabilities in the README.

Bamboo should now be fully operational on PHP 8.2.