✨ feat: implement APP_START_CMD for standalone PHP applications with v4.x parity

Author: ramonskie

docs/V4_V5_MIGRATION_GAP_ANALYSIS.md

@@ -6,9 +6,9 @@ This document provides a comprehensive comparison between the v4.x (Python) and
 
 | Category | v4.x Features | v5.x Status | Priority |
 |----------|---------------|-------------|----------|
-| Core Features | 15 | 12 implemented, 3 missing | High |
+| Core Features | 15 | 15 implemented, 0 missing | Complete |
 | Extensions | 5 | 4 implemented, 1 partial | Medium |
-| Configuration Options | 25+ | 20+ implemented, 5 missing | High |
+| Configuration Options | 25+ | 25+ implemented, 0 missing | Complete |
 | Placeholder Syntax | 2 types | Both implemented | Complete |
 | Service Bindings | 5 services | 4 implemented | Medium |
 
@@ -49,7 +49,7 @@ This document provides a comprehensive comparison between the v4.x (Python) and
 | `COMPOSER_INSTALL_OPTIONS` | ✅ | ✅ | ✅ | |
 | `COMPOSER_INSTALL_GLOBAL` | ✅ | ✅ | ✅ | |
 | **`ADDITIONAL_PREPROCESS_CMDS`** | ✅ | ✅ | ✅ **IMPLEMENTED** | Commands to run before app starts |
-| **`APP_START_CMD`** | ✅ | ❌ | ❌ **MISSING** | Custom start command for standalone apps |
+| **`APP_START_CMD`** | ✅ | ✅ | ✅ **IMPLEMENTED** | Custom start command for standalone apps |
 
 ### 1.2 Missing Configuration Options - Details
 
@@ -83,10 +83,18 @@ This document provides a comprehensive comparison between the v4.x (Python) and
 
 ---
 
-#### `APP_START_CMD` ❌ CRITICAL
+#### `APP_START_CMD` ✅ IMPLEMENTED
 
-**v4.x Implementation:** `php-buildpack-v4/lib/compile_helpers.py`
+**Status:** Implemented in v5.x (Feb 2026)
+
+**v5.x Implementation:**
+- `src/php/options/options.go` - `APP_START_CMD` field and `FindStandaloneApp()` method
+- `src/php/finalize/finalize.go` - `generatePHPFPMStartScript()` modified for standalone mode
+- `fixtures/standalone_app/` - Test fixture with explicit APP_START_CMD
+- `fixtures/standalone_autodetect/` - Test fixture for auto-detection
+- `src/php/integration/standalone_test.go` - Integration tests
 
+**v4.x Reference Implementation:**
 ```python
 def find_stand_alone_app_to_run(ctx):
     app = ctx.get('APP_START_CMD', None)
@@ -120,7 +128,9 @@ def find_stand_alone_app_to_run(ctx):
 - CLI applications
 - Scheduled tasks
 
-**Impact:** MEDIUM - Required for standalone PHP applications
+**Test Fixture:** `fixtures/standalone_app/` and `fixtures/standalone_autodetect/`
+
+**Impact:** MEDIUM - Required for standalone PHP applications (now implemented)
 
 ---
 
@@ -331,7 +341,7 @@ def service_environment(ctx):
 | Signal handling | ✅ | ✅ | ✅ | |
 | Graceful shutdown | ✅ | ✅ | ✅ | |
 | Pre-start script | ❌ | ✅ | ✅ | New in v5.x |
-| **Standalone PHP mode** | ✅ | ⚠️ | ⚠️ **PARTIAL** | Missing APP_START_CMD |
+| **Standalone PHP mode** | ✅ | ✅ | ✅ **COMPLETE** | With APP_START_CMD |
 
 ### 8.2 Environment Setup
 
@@ -347,14 +357,14 @@ def service_environment(ctx):
 
 ## 9. Priority Implementation Roadmap
 
-### 9.1 Critical (Must Have for v5.x GA)
+### 9.1 Completed ✅
 
-| Feature | Effort | Impact | Issue |
-|---------|--------|--------|-------|
-| `ADDITIONAL_PREPROCESS_CMDS` | Medium | HIGH | #1208 (akf) |
-| `APP_START_CMD` | Low | MEDIUM | Standalone apps |
+| Feature | Effort | Impact | Status |
+|---------|--------|--------|--------|
+| `ADDITIONAL_PREPROCESS_CMDS` | Medium | HIGH | ✅ Implemented (#1208) |
+| `APP_START_CMD` | Low | MEDIUM | ✅ Implemented (Feb 2026) |
 
-### 9.2 High Priority
+### 9.2 High Priority (Remaining)
 
 | Feature | Effort | Impact |
 |---------|--------|--------|
@@ -468,10 +478,10 @@ func LoadUserExtensions(buildDir string, registry *Registry) error {
 
 | Test | Status | Priority |
 |------|--------|----------|
-| ADDITIONAL_PREPROCESS_CMDS - string format | ❌ | HIGH |
-| ADDITIONAL_PREPROCESS_CMDS - array format | ❌ | HIGH |
-| APP_START_CMD - explicit | ❌ | MEDIUM |
-| APP_START_CMD - auto-detect | ❌ | MEDIUM |
+| ADDITIONAL_PREPROCESS_CMDS - string format | ✅ | HIGH |
+| ADDITIONAL_PREPROCESS_CMDS - array format | ✅ | HIGH |
+| APP_START_CMD - explicit | ✅ | MEDIUM |
+| APP_START_CMD - auto-detect | ✅ | MEDIUM |
 | User extensions | ❌ | LOW |
 | Multi-buildpack with apt-buildpack | ⚠️ | HIGH |
 

fixtures/standalone_app/.bp-config/options.json

@@ -0,0 +1,4 @@
+{
+  "WEB_SERVER": "none",
+  "APP_START_CMD": "worker.php"
+}

fixtures/standalone_app/worker.php

@@ -0,0 +1,31 @@
+<?php
+// Standalone PHP worker application for testing APP_START_CMD
+// This simulates a background worker or queue processor
+
+echo "Standalone PHP Worker Started\n";
+echo "PHP Version: " . phpversion() . "\n";
+echo "Working Directory: " . getcwd() . "\n";
+echo "Script: " . __FILE__ . "\n";
+
+// Create a marker file to verify the worker ran
+$markerFile = getenv('HOME') . '/worker_ran.txt';
+file_put_contents($markerFile, "WORKER_EXECUTED\n");
+echo "Created marker file: $markerFile\n";
+
+// Simulate worker loop (in real app this would process queue items)
+$counter = 0;
+$maxIterations = 5;
+
+while ($counter < $maxIterations) {
+    $counter++;
+    echo "Worker iteration: $counter/$maxIterations\n";
+    
+    // Write status to file for test verification
+    $statusFile = getenv('HOME') . '/worker_status.txt';
+    file_put_contents($statusFile, "ITERATION_$counter\n", FILE_APPEND);
+    
+    sleep(1);
+}
+
+echo "Worker completed successfully\n";
+exit(0);

fixtures/standalone_autodetect/.bp-config/options.json

@@ -0,0 +1,3 @@
+{
+  "WEB_SERVER": "none"
+}

fixtures/standalone_autodetect/app.php

@@ -0,0 +1,10 @@
+<?php
+// Auto-detected standalone app (app.php has highest priority)
+echo "Auto-detected app.php\n";
+echo "PHP Version: " . phpversion() . "\n";
+
+// Create marker to verify correct file was detected
+file_put_contents(getenv('HOME') . '/autodetect_result.txt', "app.php\n");
+
+echo "Auto-detection test: SUCCESS\n";
+exit(0);

src/php/finalize/finalize.go

@@ -704,7 +704,8 @@ wait $PHP_FPM_PID $NGINX_PID
 `, depsIdx, depsIdx, depsIdx, depsIdx, depsIdx, depsIdx, depsIdx, depsIdx)
 }
 
-// generatePHPFPMStartScript generates a start script for PHP-FPM only (no web server)
+// generatePHPFPMStartScript generates a start script for standalone PHP applications (no web server)
+// When WEB_SERVER=none, this runs a PHP script directly instead of PHP-FPM
 func (f *Finalizer) generatePHPFPMStartScript(depsIdx string, opts *options.Options) string {
 	// Load options to get WEBDIR and other config values
 	webDir := os.Getenv("WEBDIR")
@@ -720,8 +721,19 @@ func (f *Finalizer) generatePHPFPMStartScript(depsIdx string, opts *options.Opti
 		libDir = "lib" // default
 	}
 
+	// Find the standalone app to run
+	appFile, err := opts.FindStandaloneApp(f.Stager.BuildDir())
+	if err != nil {
+		// Log error but continue - the start script will fail at runtime with clear message
+		f.Log.Warning("Failed to find standalone app: %v", err)
+		f.Log.Warning("The application will fail to start. Set APP_START_CMD or create one of: app.php, main.php, run.php, start.php")
+		appFile = "" // Will generate error in start script
+	} else {
+		f.Log.Info("Standalone app mode: will run %s", appFile)
+	}
+
 	return fmt.Sprintf(`#!/usr/bin/env bash
-# PHP Application Start Script (PHP-FPM only)
+# PHP Application Start Script (Standalone Mode)
 set -e
 
 # Set DEPS_DIR with fallback for different environments
@@ -748,13 +760,14 @@ export PHP_INI_SCAN_DIR="$DEPS_DIR/%s/php/etc/php.ini.d"
 # Add PHP binaries to PATH for CLI commands
 export PATH="$DEPS_DIR/%s/php/bin:$PATH"
 
-echo "Starting PHP-FPM only..."
+echo "Starting standalone PHP application..."
 echo "DEPS_DIR: $DEPS_DIR"
 echo "TMPDIR: $TMPDIR"
-echo "PHP-FPM path: $DEPS_DIR/%s/php/sbin/php-fpm"
+echo "PHP: $DEPS_DIR/%s/php/bin/php"
 
-# Expand ${TMPDIR} in PHP configs
-for config_file in "$PHPRC/php.ini" "$PHPRC/php-fpm.conf"; do
+# Expand ${TMPDIR} in PHP configs (php.ini uses ${TMPDIR} placeholder)
+# This allows users to customize TMPDIR via environment variable
+for config_file in "$PHPRC/php.ini"; do
     if [ -f "$config_file" ]; then
         sed "s|\${TMPDIR}|$TMPDIR|g" "$config_file" > "$config_file.tmp"
         mv "$config_file.tmp" "$config_file"
@@ -771,13 +784,21 @@ if [ -d "$PHP_INI_SCAN_DIR" ]; then
     done
 fi
 
-# Create PHP-FPM socket directory if it doesn't exist
-mkdir -p "$DEPS_DIR/%s/php/var/run"
+# Create required directories
 mkdir -p "$TMPDIR"
 
-# Start PHP-FPM in foreground
-exec $DEPS_DIR/%s/php/sbin/php-fpm -F -y $PHPRC/php-fpm.conf
-`, depsIdx, depsIdx, depsIdx, depsIdx, depsIdx, depsIdx)
+# Run the standalone PHP application
+if [ -z "%s" ]; then
+    echo "ERROR: No standalone application found!"
+    echo "Please set APP_START_CMD in .bp-config/options.json"
+    echo "Or create one of: app.php, main.php, run.php, start.php"
+    exit 1
+fi
+
+echo "Running: php %s"
+cd "$HOME"
+exec $DEPS_DIR/%s/php/bin/php "%s"
+`, depsIdx, depsIdx, depsIdx, depsIdx, appFile, appFile, depsIdx, appFile)
 }
 
 // SetupProcessTypes creates the process types for the application

src/php/integration/init_test.go

@@ -77,6 +77,7 @@ func TestIntegration(t *testing.T) {
 	suite("AppFrameworks", testAppFrameworks(platform, fixtures))
 	suite("Placeholders", testPlaceholders(platform, fixtures))
 	suite("PreprocessCmds", testPreprocessCmds(platform, fixtures))
+	suite("StandaloneApp", testStandaloneApp(platform, fixtures))
 	// suite("BuildpackPythonExtension", testPythonExtension(platform, fixtures)) // Skipped for now
 	// suite("APMs", testAPMs(platform, fixtures, dynatraceDeployment.InternalURL)) // Needs dynatrace mock
 	if settings.Cached {

src/php/integration/standalone_test.go

@@ -0,0 +1,75 @@
+package integration_test
+
+import (
+	"path/filepath"
+	"testing"
+
+	"github.com/cloudfoundry/switchblade"
+	"github.com/sclevine/spec"
+
+	. "github.com/onsi/gomega"
+)
+
+func testStandaloneApp(platform switchblade.Platform, fixtures string) func(*testing.T, spec.G, spec.S) {
+	return func(t *testing.T, context spec.G, it spec.S) {
+		var (
+			Expect = NewWithT(t).Expect
+
+			name string
+		)
+
+		it.Before(func() {
+			var err error
+			name, err = switchblade.RandomName()
+			Expect(err).NotTo(HaveOccurred())
+		})
+
+		it.After(func() {
+			if t.Failed() && name != "" {
+				t.Logf("❌ FAILED TEST - App/Container: %s", name)
+				t.Logf("   Platform: %s", settings.Platform)
+			}
+			if name != "" && (!settings.KeepFailedContainers || !t.Failed()) {
+				Expect(platform.Delete.Execute(name)).To(Succeed())
+			}
+		})
+
+		context("APP_START_CMD with WEB_SERVER=none", func() {
+			it("builds with explicit APP_START_CMD", func() {
+				_, logs, err := platform.Deploy.
+					WithEnv(map[string]string{
+						"BP_DEBUG": "1",
+					}).
+					Execute(name, filepath.Join(fixtures, "standalone_app"))
+				Expect(err).NotTo(HaveOccurred(), logs.String)
+
+				// Verify the buildpack detected standalone mode
+				Expect(logs).To(ContainSubstring("Standalone app mode: will run worker.php"))
+
+				// Verify the finalize phase completed successfully
+				Expect(logs).To(ContainSubstring("PHP buildpack finalize phase complete"))
+
+				// Verify start script was created
+				Expect(logs).To(ContainSubstring("Created start script for none"))
+			})
+
+			it("builds with auto-detected app.php", func() {
+				_, logs, err := platform.Deploy.
+					WithEnv(map[string]string{
+						"BP_DEBUG": "1",
+					}).
+					Execute(name, filepath.Join(fixtures, "standalone_autodetect"))
+				Expect(err).NotTo(HaveOccurred(), logs.String)
+
+				// Verify the buildpack detected standalone mode and found app.php
+				Expect(logs).To(ContainSubstring("Standalone app mode: will run app.php"))
+
+				// Verify the finalize phase completed successfully
+				Expect(logs).To(ContainSubstring("PHP buildpack finalize phase complete"))
+
+				// Verify start script was created
+				Expect(logs).To(ContainSubstring("Created start script for none"))
+			})
+		})
+	}
+}

src/php/options/options.go

@@ -48,6 +48,10 @@ type Options struct {
 	// Supports: string, []string, or [][]string formats (v4.x compatibility)
 	AdditionalPreprocessCmds interface{} `json:"ADDITIONAL_PREPROCESS_CMDS,omitempty"`
 
+	// Custom start command for standalone PHP applications (when WEB_SERVER=none)
+	// If not set, auto-detects: app.php, main.php, run.php, start.php
+	AppStartCmd string `json:"APP_START_CMD,omitempty"`
+
 	// Internal flags
 	OptionsJSONHasPHPExtensions bool `json:"OPTIONS_JSON_HAS_PHP_EXTENSIONS,omitempty"`
 
@@ -204,6 +208,11 @@ func (o *Options) mergeUserOptions(user *Options) {
 		o.AdditionalPreprocessCmds = user.AdditionalPreprocessCmds
 	}
 
+	// Merge APP_START_CMD if user specified
+	if user.AppStartCmd != "" {
+		o.AppStartCmd = user.AppStartCmd
+	}
+
 	// Note: Boolean fields are not merged because we can't distinguish between
 	// false (user set) and false (default zero value). If needed, use pointers.
 }
@@ -300,3 +309,39 @@ func (o *Options) GetPreprocessCommands() []string {
 
 	return commands
 }
+
+// FindStandaloneApp returns the PHP file to run for standalone applications (WEB_SERVER=none).
+// If APP_START_CMD is set, returns that. Otherwise auto-detects in order:
+//  1. app.php
+//  2. main.php
+//  3. run.php
+//  4. start.php
+//
+// Returns empty string if no standalone app found.
+func (o *Options) FindStandaloneApp(buildDir string) (string, error) {
+	// If user explicitly set APP_START_CMD, use it
+	if o.AppStartCmd != "" {
+		// Verify the file exists
+		appPath := filepath.Join(buildDir, o.AppStartCmd)
+		if exists, err := libbuildpack.FileExists(appPath); err != nil {
+			return "", fmt.Errorf("failed to check APP_START_CMD file: %w", err)
+		} else if !exists {
+			return "", fmt.Errorf("APP_START_CMD file not found: %s", o.AppStartCmd)
+		}
+		return o.AppStartCmd, nil
+	}
+
+	// Auto-detect standalone app (v4.x compatibility)
+	candidates := []string{"app.php", "main.php", "run.php", "start.php"}
+	for _, candidate := range candidates {
+		appPath := filepath.Join(buildDir, candidate)
+		if exists, err := libbuildpack.FileExists(appPath); err != nil {
+			return "", fmt.Errorf("failed to check for %s: %w", candidate, err)
+		} else if exists {
+			return candidate, nil
+		}
+	}
+
+	// No standalone app found
+	return "", fmt.Errorf("no standalone app found: set APP_START_CMD or create one of: %s", strings.Join(candidates, ", "))
+}