README

A development toolkit for Laravel applications with built-in Docker scaffolding, Supervisor configurations, and optional services like Horizon, Echo Server, and Scheduler.

Features

• Laravel Octane ready with RoadRunner by default and optional FrankenPHP support
• Preconfigured Supervisor process management
• Optional service configs for Horizon, Echo Server, Scheduler
• Environment-based starter mode (dev or prod)
• Ready-to-publish Docker scaffold for rapid project setup
• Works seamlessly with the public base image vanaboom/laravel-boomkit

Installation

composer require vanaboom/laravel-toolbox

Or, for the first-time setup with Docker (without Composer installed locally):

docker run --rm -it \
  --add-host=host.docker.internal:host-gateway \
  -u $(id -u):$(id -g) \
  -v "$PWD":/code -w /code \
  vanaboom/laravel-boomkit:1.10.2-alpine \
  sh -lc '
    composer require vanaboom/laravel-toolbox --no-interaction --no-scripts &&
    php artisan toolbox:publish-docker --force &&
    chmod +x .docker/app/start-container
  '

Replace alpine with your BUILD_TAG, or use alpine-frankenphp together with OCTANE_SERVER=frankenphp.

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="Vanaboom\\LaravelToolbox\\ToolboxServiceProvider" --tag="config"

The config file will be published to config/toolbox.php.

Key options:

• mode → dev or prod
• verbose_mode → Enable verbose logging for starter command
• octane_watch → Whether to enable Octane file watching in dev mode

Docker Scaffold

Publish a ready-to-use Docker scaffold into your Laravel app:

php artisan toolbox:publish-docker
# then:
# docker compose up -d

The scaffold includes:

• Dockerfile using vanaboom/laravel-boomkit:${BOOMKIT_VERSION}-${BUILD_TAG}

• Supervisor configs:

  • starter → Runs php artisan toolbox:starter
  • Optional: horizon, echo-server, scheduler (copy from .ini.example to enable)

• Configurable environment variables for user/group IDs, app directory, custom commands, Octane runtime, Docker registry mirror, and more

To avoid Composer re-running on every container start, add stamp files to your .gitignore:

*.stamp

Example docker-compose service

services:
  app:
    build:
      context: ./.docker/app
      dockerfile: Dockerfile
      args:
        UID: ${UID:-1000}
        GID: ${GID:-1000}
        CURRENT_USER: ${CURRENT_USER}
        CURRENT_GROUP: ${CURRENT_GROUP}
        APP_ENV: ${APP_ENV:-production}
        BOOMKIT_VERSION: ${BOOMKIT_VERSION:-1.10.2}
        BUILD_TAG: ${BUILD_TAG:-alpine}
        TIMEZONE: ${APP_TIMEZONE:-UTC}
        DOCKER_REGISTRY: ${DOCKER_REGISTRY:-docker.io}
    environment:
      COMPOSER_MEMORY_LIMIT: -1
      TOOLBOX_STARTER_MODE: ${TOOLBOX_STARTER_MODE:-dev}
      TOOLBOX_VERBOSE_MODE: ${TOOLBOX_VERBOSE_MODE:-false}
      OCTANE_SERVER: ${OCTANE_SERVER:-roadrunner}
      TIMEZONE: ${APP_TIMEZONE:-UTC}
      COMPOSER_MIRROR_URL: ${COMPOSER_MIRROR_URL:-https://repo.packagist.org/}
      NPM_MIRROR_URL: ${NPM_MIRROR_URL:-https://registry.npmjs.org/}
    restart: unless-stopped
    extra_hosts:
      - 'host.docker.internal:host-gateway'
    ports:
      - ${APP_PORT:-11000}:8888
    volumes:
      - ./.docker/app/conf.d/supervisord.conf:/etc/supervisord.conf
      - ./.docker/app/supervisor.d:/etc/supervisor.d
      - ./:/code
    healthcheck:
      test: curl --fail -s http://localhost:8888/health || exit 1
      interval: 1m
      timeout: 30s
      retries: 3

Octane Runtime

RoadRunner remains the default runtime for backward compatibility. To use FrankenPHP, build with the Boomkit FrankenPHP tag and set the Octane server explicitly:

BUILD_TAG=alpine-frankenphp
OCTANE_SERVER=frankenphp

For registries or Docker Hub mirrors, set DOCKER_REGISTRY to the mirror prefix used by your environment.

Healthcheck Route

Add this to your routes/web.php to make the Docker healthcheck work:

Route::get('/health', fn() => response()->noContent());

Supervisor

The scaffold comes with /etc/supervisor.d containing process configs.

Starter

Runs the Laravel Toolbox starter command based on environment:

[program:starter]
command=php artisan toolbox:starter

Horizon (optional)

Copy horizon.ini.example to horizon.ini to enable:

[program:horizon]
command=php artisan horizon

Echo Server (optional)

Copy echo-server.ini.example to echo-server.ini to enable:

[program:echo-server]
command=node /code/echo-server/server.js

Scheduler (optional)

Copy scheduler.ini.example to scheduler.ini to enable:

[program:scheduler]
command=php artisan schedule:work

License

This package is open-sourced software licensed under the MIT license.