Bamboo on PHP 8.3 — Installation & Configuration Guide¶

This guide explains how to install and configure Bamboo v0.2 on PHP 8.3 with the OpenSwoole runtime. It targets Ubuntu/Debian systems but also documents the macOS/Homebrew equivalents. Follow the steps to bring up the CLI, OpenSwoole HTTP server, Redis queue worker, and optional database layer.

1. Prerequisites¶

Tip: Work from a shell session with sudo privileges. On macOS switch apt commands to Homebrew equivalents (brew install ...).

2. Install PHP 8.3 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.3 and required extensions
sudo apt install -y \
  php8.3 php8.3-cli php8.3-fpm php8.3-common php8.3-dev \
  php8.3-curl php8.3-mbstring php8.3-xml php8.3-zip php8.3-intl \
  php8.3-sqlite3 php8.3-mysql php8.3-pgsql php8.3-redis php8.3-gd

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

The php8.3-dev package ships php-config8.3, which OpenSwoole needs for compilation. The other extensions mirror what Bamboo and its dependencies expect (curl, mbstring, pdo_*, intl, redis, etc.).

2.2 macOS (Homebrew)¶

brew update
brew install php@8.3 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.3/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.3.

# 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.2
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.3/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.3 and a loaded OpenSwoole module.

4. Install Composer and project dependencies¶

If Composer is not already installed:

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 installs the 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; change it 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; 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¶

Consult docs/OpenSwoole-Compat-and-Fixes.md for additional OpenSwoole notes.

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.3 + 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.3.