README

A comprehensive Laravel application bootstrap package for local development with automatic dependency management, database setup, and multi-server support.

Features

Multi-Server Support: Herd, Sail, or Laravel built-in server
Automatic Dependency Installation: Auto-installs missing tools (bun, composer, node, etc.)
Smart Version Management: Support for specific versions or 'latest' for safe updates
Database Auto-Setup: Interactive database creation and credential management
Queue Management: Automatic queue worker in separate terminal
Migration Auto-Run: Runs migrations automatically when available
Interactive Prompts: User-friendly setup experience
Configurable Package Managers: Choose between bun (default), yarn, or npm
DRY, SOLID, KISS: Clean, maintainable codebase following best practices

Installation

Install as a development dependency:

composer require igne-agency/laravel-bootstrap --dev

The package will auto-register via Laravel's package discovery.

Important: Always use the --dev flag to ensure this package is only installed in development environments and excluded from production deployments.

Quick Start

# Start your application (will prompt for server if not specified)
php artisan app:serve

# Or specify a server directly
php artisan app:serve herd
php artisan app:serve sail
php artisan app:serve laravel

# With options
php artisan app:serve herd --seed --update

# Stop your application
php artisan app:down

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=bootstrap-config

This creates config/bootstrap.php where you can configure all aspects of the package.

Configuration Options

Server Configuration

'server' => [
    'default' => env('BOOTSTRAP_SERVER', null), // null = always prompt
    'prompt' => env('BOOTSTRAP_PROMPT_SERVER', true),
],

Package Manager

'package_manager' => [
    'default' => env('BOOTSTRAP_PACKAGE_MANAGER', 'bun'),
    'available' => ['bun', 'yarn', 'npm'],
],

Tool Versions

'tools' => [
    'php' => env('PHP_VERSION', 'latest'),
    'node' => env('NODE_VERSION', 'latest'),
    'composer' => env('COMPOSER_VERSION', 'latest'),
    'bun' => env('BUN_VERSION', 'latest'),
    'yarn' => env('YARN_VERSION', 'latest'),
    'npm' => env('NPM_VERSION', 'latest'),
],

Use 'latest' for automatic safe version updates, or specify exact versions like '20.11.0'.

Auto-Installation

'auto_install' => [
    'enabled' => env('BOOTSTRAP_AUTO_INSTALL', true),
    'tools' => ['php', 'node', 'composer', 'bun'],
],

Database Management

'database' => [
    'auto_create' => env('BOOTSTRAP_AUTO_CREATE_DB', true),
    'prompt_credentials' => env('BOOTSTRAP_PROMPT_DB_CREDENTIALS', true),
],

Queue Configuration

'queue' => [
    'auto_start' => env('BOOTSTRAP_AUTO_START_QUEUE', true),
    'separate_terminal' => env('BOOTSTRAP_QUEUE_SEPARATE_TERMINAL', true),
    'connection' => env('QUEUE_CONNECTION', 'database'),
],

Shutdown Behavior

'shutdown' => [
    'prompt_server_stop' => env('BOOTSTRAP_PROMPT_SERVER_STOP', true),
    'default_stop_server' => env('BOOTSTRAP_DEFAULT_STOP_SERVER', false),
],

Usage

Starting Your Application

php artisan app:serve {server?} {--seed} {--migrate} {--update} {--no-frontend}

Arguments:

server (optional): Development server - herd, sail, or laravel

Options:

--seed: Seed the database after migrations
--migrate: Run migrations (default: true)
--update: Update dependencies before starting
--no-frontend: Skip frontend asset building

What happens:

Interactive server selection (if not specified)
Dependency checking and auto-installation
Database credential prompts (if needed)
Database creation (if doesn't exist)
Dependency installation (composer, npm/yarn/bun)
Migration execution
Queue worker startup (in separate terminal)
Application boot

Stopping Your Application

php artisan app:down

Interactive prompt asks whether to:

Stop only running processes (default)
Stop the server itself (Herd/Sail)

Examples

First-Time Setup

# Clone your Laravel project
git clone https://github.com/yourname/project.git
cd project

# Install composer dependencies
composer install

# Start the application
php artisan app:serve

The package will:

Prompt for server selection
Check for missing tools (node, bun, etc.)
Install missing tools automatically
Prompt for database credentials if missing
Create database if it doesn't exist
Run migrations
Start queue workers
Boot your application

Using Specific Versions

In your .env:

PHP_VERSION=8.4
NODE_VERSION=20.11.0
BUN_VERSION=1.0.25
COMPOSER_VERSION=2.7.0

Or use latest for automatic safe updates:

PHP_VERSION=latest
NODE_VERSION=latest
BUN_VERSION=latest
COMPOSER_VERSION=latest

Different Servers

Laravel Herd:

php artisan app:serve herd

Laravel Sail:

php artisan app:serve sail

Laravel Built-in Server:

php artisan app:serve laravel

Server-Specific Configuration

Development (auto-install everything):

BOOTSTRAP_AUTO_INSTALL=true
BOOTSTRAP_AUTO_CREATE_DB=true
BOOTSTRAP_AUTO_RUN_MIGRATIONS=true
BOOTSTRAP_AUTO_START_QUEUE=true

Production-like (manual control):

BOOTSTRAP_AUTO_INSTALL=false
BOOTSTRAP_AUTO_CREATE_DB=false
BOOTSTRAP_PROMPT_DB_CREDENTIALS=false
BOOTSTRAP_AUTO_START_QUEUE=false

Advanced Features

Custom Bootstrap Commands

You can hook into the bootstrap process to run your own commands (e.g., code generation, type generation). Create a class implementing ProvidesBootstrapCommands and register it in your service provider:

// app/Bootstrap/CustomBootstrapCommands.php
use Igne\LaravelBootstrap\Contracts\ProvidesBootstrapCommands;
use Igne\LaravelBootstrap\Data\DTOs\BootstrapCommand;

class CustomBootstrapCommands implements ProvidesBootstrapCommands
{
    public function beforeMigrations(): array
    {
        return [
            BootstrapCommand::artisan('wayfinder:generate', 'Generating TypeScript routes...'),
        ];
    }

    public function afterMigrations(): array
    {
        return [
            BootstrapCommand::artisan('model:typer', 'Generating model types...'),
        ];
    }
}

// AppServiceProvider
$this->app->singleton(
    ProvidesBootstrapCommands::class,
    CustomBootstrapCommands::class
);

Commands can be Artisan, Composer, or Package Manager commands. See CUSTOM_COMMANDS.md for full documentation.

Automatic Tool Installation

When enabled, the package automatically installs missing tools:

Detects missing dependencies
Downloads and installs them
Verifies versions
Updates to latest safe versions if configured

Smart Version Management

The 'latest' version option:

Checks for the latest stable/LTS version
Only updates to safe, stable releases
Caches version checks to avoid API rate limits
Falls back to sensible defaults if API unavailable

Database Auto-Creation

If database doesn't exist:

Prompts for credentials (if not in .env)
Updates .env file with credentials
Creates database with proper charset/collation
Runs migrations automatically

Queue Worker Management

Queue workers run in separate terminal windows:

macOS: Opens new Terminal.app window
Linux: Opens new gnome-terminal window
Fallback: Runs in background if terminal unavailable

Troubleshooting

Database Connection Issues

If you see database connection errors:

Check .env file has correct credentials
Ensure MySQL/PostgreSQL is running
Verify database exists
Run php artisan config:clear

Tool Installation Failures

If auto-installation fails:

Check internet connection
Verify system permissions
Install tools manually
Disable auto-install: BOOTSTRAP_AUTO_INSTALL=false

Queue Worker Not Starting

If queue worker doesn't start:

Check queue connection in .env
Verify database tables exist
Manually run: php artisan queue:work

Sail-Specific Issues

For Sail users:

Ensure Docker is installed and running
Check Docker has sufficient resources
Verify ports 80/3306 are available
Run sail up -d manually if needed

Requirements

PHP 8.4+
Laravel 12.x
Composer 2.x

Production Safety

This package is automatically excluded from production when installed with --dev. Composer will not install dev dependencies when you run:

composer install --no-dev

This ensures the package and its commands are never available in production.

Environment Detection

The package includes safety checks to prevent accidental use in non-local environments. Commands will refuse to run if:

APP_ENV is not set to local or development
The system has detected as a remote server

License

MIT License - see LICENSE for details.

Credits

Created by Rick Blanksma at IGNE

Support

For issues, questions, or contributions, please use the GitHub issue tracker.

igne-agency / laravel-bootstrap

Maintainers

Package info

Statistics

Security