Getting Started

Minimal Steps to First Use

Installation:
```
composer require reedware/sail-lite --dev
./vendor/bin/sail install
```
This publishes the docker-compose.yml and sail script to your project root.
Start the Container:
```
sail up -d
```
Runs the PHP development container in detached mode.
Access the Container:
```
sail shell
```
Drops you into a bash shell inside the container with your project mounted at /var/www/html.

Run PHP Commands:

sail php artisan test  # Example for testing (if applicable)
sail php vendor/bin/phpunit

First Use Case: Local Package Development

Scenario: Developing a standalone PHP package (e.g., a Laravel service provider or utility library).
Workflow:
1. Write code in your local IDE (e.g., VSCode with PHP Intelephense).
2. Use sail shell to run tests, linting, or other CLI tools inside the container.
3. Leverage sail php to execute PHP scripts or run Composer commands:
```
sail php -r "require_once 'vendor/autoload.php'; echo \MyPackage\MyClass::version();"
```

Implementation Patterns

Core Workflows

1. Daily Development Loop

Start/Stop:

sail up -d       # Start in background
sail down        # Stop containers

Rebuilding:
```
sail down && sail build --no-cache && sail up -d
```
Use this when updating PHP versions or adding new dependencies.

Shell Access:

sail shell       # User-level shell (default)
sail root-shell  # Root-level shell (for admin tasks)

2. PHP Version Management

Override Default (8.5): Edit docker-compose.yml:

args:
    PHP: '8.2'  # Hardcoded override

Or set in .env:

PHP_VERSION=8.1

Rebuild After Changes:

sail down && sail build --no-cache && sail up -d

3. Customization

Publish Dockerfiles:
```
sail publish
```
This creates a /docker directory with customizable Dockerfiles and configs.

Modify docker-compose.yml: Example: Add PHP extensions or tools:

services:
    dev:
        build:
            context: ./docker
            args:
                PHP_EXTENSIONS: "pdo_mysql, gd"

4. Command Execution

Proxy Commands:

sail php -v          # Runs `php -v` inside the container
sail composer install
sail npm install      # If Node.js is added via customization

VSCode Integration: Use the php proxy (added in v1.3.0) for seamless debugging:

// .vscode/settings.json
{
    "php.validate.executablePath": "/var/www/html/vendor/bin/sail php"
}

5. CI/CD Integration

Test Locally Against CI Environment: Match your CI’s PHP version in .env:
```
PHP_VERSION=8.2
```

Example GitHub Actions Workflow:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: docker-compose up -d
      - run: docker-compose exec dev sail php vendor/bin/phpunit

Integration Tips

Composer Scripts: Add Sail commands to composer.json for convenience:

"scripts": {
    "dev": "sail shell",
    "test": "sail php vendor/bin/phpunit",
    "lint": "sail php vendor/bin/php-cs-fixer fix"
}

Now run with:

composer dev

Environment Variables: Use .env to manage container settings (e.g., PHP version, user permissions):
```
PHP_VERSION=8.1
WWWUSER=1000
```

Multi-Package Development: Rename the service in docker-compose.yml to avoid conflicts:

services:
    my-package-dev:  # Unique name
        image: sail-lite/basic
        ...

Gotchas and Tips

Pitfalls

PHP Version Mismatches:
- Issue: Forgetting to rebuild after changing PHP_VERSION in .env or docker-compose.yml.
- Fix: Always run sail build --no-cache after PHP version changes.
Permission Errors:
- Issue: Files created inside the container may have incorrect permissions (e.g., chmod: Permission denied).
- Fix: Ensure WWWUSER and WWWGROUP in docker-compose.yml match your host’s UID/GID. Use:
```
sail root-shell
id www-data  # Check UID/GID
```
Missing Extensions:
- Issue: Required PHP extensions (e.g., pdo_mysql) are missing.
- Fix: Customize the Dockerfile via sail publish and add extensions:
```
RUN docker-php-ext-install pdo_mysql gd
```
Shell Alias Conflicts:
- Issue: The sail alias may conflict with Laravel Sail or other tools.
- Fix: Use the full path (./vendor/bin/sail) or rename the alias (e.g., alias sl='./vendor/bin/sail').
Assertions Disabled:
- Issue: PHP assertions are disabled by default in some environments, which Sail Lite enables by default.
- Fix: If assertions cause issues, disable them in docker-compose.yml:
```
args:
    PHP_INI_VALUES: "assert.active=0"
```
Volume Mounts:
- Issue: Changes to docker-compose.yml volumes may not reflect immediately.
- Fix: Rebuild and restart:
```
sail down && sail up -d
```

Debugging Tips

Check Container Logs:
```
sail logs
```
Useful for diagnosing build or startup issues.

Inspect Running Containers:

docker ps
docker inspect <container_id>

Test PHP Configuration:

sail php -i | grep "assert"
sail php -m  # List loaded extensions

Configuration Quirks

.env File Location:
- Sail Lite expects .env in the project root. If missing, defaults are used.
Default PHP Version:
- Hardcoded to 8.5 unless overridden. Check docker-compose.yml for the PHP arg.
Custom Dockerfiles:
- Published files in /docker override defaults but require rebuilding:
```
sail build --no-cache
```
VSCode Debugging:
- Ensure the php proxy is configured in .vscode/settings.json (added in v1.3.0). Without it, debugging may fail.

Extension Points

Add Node.js:

Customize the Dockerfile to include Node.js:

RUN curl -fsSL https://deb.nodesource.com/setup_lts.x | bash -
RUN apt-get install -y nodejs

Add Databases:
- Extend docker-compose.yml to include services like MySQL or PostgreSQL, then link them to the PHP container.
Custom PHP.ini Settings:
- Override defaults by adding PHP_INI_VALUES to docker-compose.yml:
```
args:
    PHP_INI_VALUES: "memory_limit=2G, display_errors=1"
```
Multi-Stage Builds:
- For production-ready images, create a custom Dockerfile in /docker with multi-stage builds.

Health Checks:

Add health checks to docker-compose.yml for CI/CD readiness:

healthcheck:
    test: ["CMD", "sail", "php", "-r", "exit((file_exists('vendor/autoload.php')) ? 0 : 1);"]
    interval: 30s
    timeout: 10s
    retries: 3

Sail Lite Laravel Package