|
| 1 | +# PHP Configuration Guide |
| 2 | + |
| 3 | +This guide explains how PHP configuration works in Launchpad and how the smart auto-detection system works. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +Launchpad uses a **smart auto-detection system** for PHP installation: |
| 8 | +1. **Project Analysis**: Automatically analyzes your project structure |
| 9 | +2. **Framework Detection**: Identifies Laravel, WordPress, Symfony, etc. |
| 10 | +3. **Database Detection**: Determines which databases you're using |
| 11 | +4. **Optimal Configuration**: Selects the best precompiled binary for your needs |
| 12 | + |
| 13 | +## Configuration Strategies |
| 14 | + |
| 15 | +Launchpad supports two strategies for PHP installation: |
| 16 | + |
| 17 | +### 1. Auto-Detect (Recommended) |
| 18 | +```typescript |
| 19 | +services: { |
| 20 | + php: { |
| 21 | + enabled: true, |
| 22 | + strategy: 'auto-detect', |
| 23 | + version: '8.4.11', |
| 24 | + autoDetect: { |
| 25 | + enabled: true, |
| 26 | + preferredDatabase: 'auto', |
| 27 | + includeAllDatabases: false, |
| 28 | + includeEnterprise: false, |
| 29 | + }, |
| 30 | + }, |
| 31 | +} |
| 32 | +``` |
| 33 | + |
| 34 | +**How it works:** |
| 35 | +- Analyzes your project structure |
| 36 | +- Detects framework and database usage |
| 37 | +- Automatically selects the optimal configuration |
| 38 | +- Provides clear explanation of the choice |
| 39 | + |
| 40 | +### 2. Manual Configuration |
| 41 | +```typescript |
| 42 | +services: { |
| 43 | + php: { |
| 44 | + enabled: true, |
| 45 | + strategy: 'precompiled-binary', |
| 46 | + version: '8.4.11', |
| 47 | + manual: { |
| 48 | + configuration: 'laravel-mysql', // Choose specific configuration |
| 49 | + }, |
| 50 | + }, |
| 51 | +} |
| 52 | +``` |
| 53 | + |
| 54 | +**When to use:** |
| 55 | +- You know exactly which configuration you need |
| 56 | +- Auto-detection doesn't work for your project |
| 57 | +- You want to override the automatic choice |
| 58 | + |
| 59 | +## Environment Variables |
| 60 | + |
| 61 | +You can configure PHP behavior using environment variables: |
| 62 | + |
| 63 | +```bash |
| 64 | +# Strategy selection |
| 65 | +export LAUNCHPAD_PHP_STRATEGY=auto-detect # Default: auto-detect |
| 66 | +export LAUNCHPAD_PHP_STRATEGY=precompiled-binary # Manual configuration |
| 67 | + |
| 68 | +# Auto-detection settings |
| 69 | +export LAUNCHPAD_PHP_AUTO_DETECT=true # Enable auto-detection |
| 70 | +export LAUNCHPAD_PREFERRED_DATABASE=postgres # Preferred database |
| 71 | +export LAUNCHPAD_PHP_ALL_DATABASES=true # Force all database support |
| 72 | +export LAUNCHPAD_PHP_ENTERPRISE=true # Force enterprise features |
| 73 | + |
| 74 | +# Manual configuration |
| 75 | +export LAUNCHPAD_PHP_CONFIGURATION=laravel-postgres # Specific configuration |
| 76 | +export LAUNCHPAD_PHP_VERSION=8.4.11 # PHP version |
| 77 | +``` |
| 78 | + |
| 79 | +## Available Configurations |
| 80 | + |
| 81 | +| Configuration | When Used | Includes | |
| 82 | +|---------------|-----------|----------| |
| 83 | +| `laravel-mysql` | Laravel + MySQL (default) | Core + MySQL drivers + web extensions | |
| 84 | +| `laravel-postgres` | Laravel + PostgreSQL | Core + PostgreSQL drivers + web extensions | |
| 85 | +| `laravel-sqlite` | Laravel + SQLite (dev) | Core + SQLite drivers + web extensions | |
| 86 | +| `api-only` | API-only applications | Minimal: CLI, FPM, basic web extensions | |
| 87 | +| `enterprise` | Enterprise features | All major extensions + all database drivers | |
| 88 | +| `wordpress` | WordPress applications | WordPress-specific extensions | |
| 89 | +| `full-stack` | **Complete flexibility** | **All extensions + all databases** | |
| 90 | + |
| 91 | +## Smart Auto-Detection |
| 92 | + |
| 93 | +### How It Works |
| 94 | + |
| 95 | +Launchpad analyzes your project to determine the optimal PHP configuration: |
| 96 | + |
| 97 | +```typescript |
| 98 | +// Launchpad automatically detects: |
| 99 | +const analysis = { |
| 100 | + framework: 'laravel', // Laravel, WordPress, Symfony, etc. |
| 101 | + databases: ['mysql', 'sqlite'], // MySQL, PostgreSQL, SQLite |
| 102 | + hasApi: true, // API endpoints detected |
| 103 | + hasWebInterface: true, // Web interface detected |
| 104 | + hasImageProcessing: false, // Image processing needed |
| 105 | + hasEnterpriseFeatures: false, // Enterprise features detected |
| 106 | + recommendedConfig: 'laravel-mysql' |
| 107 | +} |
| 108 | +``` |
| 109 | + |
| 110 | +### Detection Logic |
| 111 | + |
| 112 | +#### Framework Detection |
| 113 | +- **Laravel**: Detects `artisan` + `composer.json` with `laravel/framework` |
| 114 | +- **WordPress**: Detects `wp-config.php` or `wp-config-sample.php` |
| 115 | +- **Symfony**: Detects `symfony.lock` or `config/bundles.php` |
| 116 | + |
| 117 | +#### Database Detection |
| 118 | +- **Laravel**: Reads `.env` file for `DB_CONNECTION` setting |
| 119 | +- **WordPress**: Checks `wp-config.php` for database settings |
| 120 | +- **SQLite**: Looks for `database.sqlite` files |
| 121 | +- **User Preference**: Respects `LAUNCHPAD_PREFERRED_DATABASE` environment variable |
| 122 | + |
| 123 | +#### Feature Detection |
| 124 | +- **API**: Checks for `routes/api.php` or `app/Http/Controllers/Api` |
| 125 | +- **Web Interface**: Checks for `routes/web.php` or `resources/views` |
| 126 | +- **Image Processing**: Checks for image directories |
| 127 | +- **Enterprise**: Checks for Services, Jobs, Events, Listeners |
| 128 | + |
| 129 | +## Configuration Examples |
| 130 | + |
| 131 | +### Auto-Detection (Recommended) |
| 132 | +```typescript |
| 133 | +// Let Launchpad figure it out |
| 134 | +services: { |
| 135 | + php: { |
| 136 | + enabled: true, |
| 137 | + strategy: 'auto-detect', |
| 138 | + autoDetect: { |
| 139 | + enabled: true, |
| 140 | + preferredDatabase: 'auto', |
| 141 | + includeAllDatabases: false, |
| 142 | + includeEnterprise: false, |
| 143 | + }, |
| 144 | + }, |
| 145 | +} |
| 146 | +``` |
| 147 | + |
| 148 | +### Manual Configuration |
| 149 | +```typescript |
| 150 | +// Choose specific configuration |
| 151 | +services: { |
| 152 | + php: { |
| 153 | + enabled: true, |
| 154 | + strategy: 'precompiled-binary', |
| 155 | + manual: { |
| 156 | + configuration: 'laravel-postgres', |
| 157 | + }, |
| 158 | + }, |
| 159 | +} |
| 160 | +``` |
| 161 | + |
| 162 | +### Environment Variables Only |
| 163 | +```bash |
| 164 | +# No config file needed - use environment variables |
| 165 | +export LAUNCHPAD_PHP_STRATEGY=auto-detect |
| 166 | +export LAUNCHPAD_PHP_AUTO_DETECT=true |
| 167 | +export LAUNCHPAD_PREFERRED_DATABASE=postgres |
| 168 | +``` |
| 169 | + |
| 170 | +## Best Practices |
| 171 | + |
| 172 | +### For Development |
| 173 | +1. **Use auto-detection**: Let Launchpad analyze your project |
| 174 | +2. **Check the explanation**: Launchpad explains why it chose each configuration |
| 175 | +3. **Use environment variables**: Simple way to influence the choice |
| 176 | + |
| 177 | +### For Production |
| 178 | +1. **Use specific configurations**: `laravel-mysql` is smaller than `full-stack` |
| 179 | +2. **Test with same config**: Ensure dev and prod use same PHP configuration |
| 180 | +3. **Monitor performance**: Enterprise config has more extensions but larger binary |
| 181 | + |
| 182 | +## Troubleshooting |
| 183 | + |
| 184 | +### "No precompiled binary found" |
| 185 | +This means no binary is available for your platform/architecture. |
| 186 | + |
| 187 | +**Solutions:** |
| 188 | +1. **Check platform support**: Linux x86_64, macOS ARM64, macOS Intel |
| 189 | +2. **Use fallback**: Launchpad will try alternative configurations |
| 190 | +3. **Request support**: Open an issue for your platform |
| 191 | + |
| 192 | +### "Auto-detection failed" |
| 193 | +The smart detection couldn't analyze your project. |
| 194 | + |
| 195 | +**Solutions:** |
| 196 | +1. **Check project structure**: Ensure framework files are present |
| 197 | +2. **Check file permissions**: Launchpad needs to read project files |
| 198 | +3. **Use manual configuration**: Set `LAUNCHPAD_PHP_STRATEGY=precompiled-binary` |
| 199 | + |
| 200 | +### "Configuration not found" |
| 201 | +The manual configuration you specified doesn't exist. |
| 202 | + |
| 203 | +**Solutions:** |
| 204 | +1. **Check available configurations**: See the table above |
| 205 | +2. **Use auto-detection**: Set `LAUNCHPAD_PHP_STRATEGY=auto-detect` |
| 206 | +3. **Use environment variable**: Set `LAUNCHPAD_PHP_CONFIGURATION=laravel-mysql` |
| 207 | + |
| 208 | +## Migration from Old Configuration |
| 209 | + |
| 210 | +If you were using the old extension-based configuration: |
| 211 | + |
| 212 | +### Before (Deprecated) |
| 213 | +```typescript |
| 214 | +// This no longer works |
| 215 | +services: { |
| 216 | + php: { |
| 217 | + extensions: { |
| 218 | + core: ['cli', 'fpm', 'mbstring'], |
| 219 | + database: ['pdo-mysql', 'pdo-pgsql'], |
| 220 | + web: ['curl', 'openssl'], |
| 221 | + }, |
| 222 | + }, |
| 223 | +} |
| 224 | +``` |
| 225 | + |
| 226 | +### After (Recommended) |
| 227 | +```typescript |
| 228 | +// Use auto-detection |
| 229 | +services: { |
| 230 | + php: { |
| 231 | + strategy: 'auto-detect', |
| 232 | + autoDetect: { |
| 233 | + enabled: true, |
| 234 | + preferredDatabase: 'auto', |
| 235 | + }, |
| 236 | + }, |
| 237 | +} |
| 238 | +``` |
| 239 | + |
| 240 | +### After (Manual) |
| 241 | +```typescript |
| 242 | +// Or choose specific configuration |
| 243 | +services: { |
| 244 | + php: { |
| 245 | + strategy: 'precompiled-binary', |
| 246 | + manual: { |
| 247 | + configuration: 'full-stack', // Includes all databases |
| 248 | + }, |
| 249 | + }, |
| 250 | +} |
| 251 | +``` |
| 252 | + |
| 253 | +## Future Improvements |
| 254 | + |
| 255 | +1. **More Framework Support**: Symfony, CodeIgniter, etc. |
| 256 | +2. **Custom Configurations**: User-defined configuration profiles |
| 257 | +3. **Performance Optimization**: Smaller binaries for specific use cases |
| 258 | +4. **Platform Expansion**: Windows, ARM Linux support |
0 commit comments