From 39edb7f28938df1e237ea9984678e418c6991fba Mon Sep 17 00:00:00 2001
From: Snider <snider@host.uk.com>
Date: Wed, 4 Mar 2026 17:31:03 +0000
Subject: [PATCH] fix: unify FrankenPHP commands into single php group
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Remove init() + findOrCreatePHPCmd from cmd_serve_frankenphp.go
- Use registerFrankenPHP hook pattern for CGO-conditional registration
- Rename env.go Environment → RuntimeEnvironment to avoid collision
- Add cgo build tag to handler.go and env.go

CGO build (21MB): all dev commands + serve:embedded + exec
Non-CGO build (16MB): dev commands only (shell out to system PHP)

Co-Authored-By: Virgil <virgil@lethean.io>
---
 cmd.go                  |  8 ++++++++
 cmd_serve_frankenphp.go | 24 ++++--------------------
 env.go                  | 12 ++++++------
 3 files changed, 18 insertions(+), 26 deletions(-)

diff --git a/cmd.go b/cmd.go
index 9911b9d..4cecacc 100644
--- a/cmd.go
+++ b/cmd.go
@@ -149,4 +149,12 @@ func AddPHPCommands(root *cli.Command) {
 
 	// Deployment
 	addPHPDeployCommands(phpCmd)
+
+	// FrankenPHP embedded commands (CGO only)
+	if registerFrankenPHP != nil {
+		registerFrankenPHP(phpCmd)
+	}
 }
+
+// registerFrankenPHP is set by cmd_serve_frankenphp.go when CGO is enabled.
+var registerFrankenPHP func(phpCmd *cli.Command)
diff --git a/cmd_serve_frankenphp.go b/cmd_serve_frankenphp.go
index e49292e..fba98e5 100644
--- a/cmd_serve_frankenphp.go
+++ b/cmd_serve_frankenphp.go
@@ -22,13 +22,12 @@ var (
 )
 
 func init() {
-	cli.RegisterCommands(addFrankenPHPCommands)
+	registerFrankenPHP = addFrankenPHPCommands
 }
 
-func addFrankenPHPCommands(root *cli.Command) {
-	// Find the php parent command, or create one
-	phpCmd := findOrCreatePHPCmd(root)
-
+// addFrankenPHPCommands adds FrankenPHP-specific commands to the php parent command.
+// Called from AddPHPCommands when CGO is enabled.
+func addFrankenPHPCommands(phpCmd *cli.Command) {
 	serveCmd := &cli.Command{
 		Use:   "serve:embedded",
 		Short: "Serve Laravel via embedded FrankenPHP runtime",
@@ -116,21 +115,6 @@ func runFrankenPHPExec(cmd *cli.Command, args []string) error {
 	return nil
 }
 
-// findOrCreatePHPCmd finds an existing "php" command or creates one.
-func findOrCreatePHPCmd(root *cli.Command) *cli.Command {
-	for _, c := range root.Commands() {
-		if c.Use == "php" {
-			return c
-		}
-	}
-	phpCmd := &cli.Command{
-		Use:   "php",
-		Short: "PHP/Laravel development tools",
-	}
-	root.AddCommand(phpCmd)
-	return phpCmd
-}
-
 // execResponseWriter writes HTTP response body directly to stdout.
 type execResponseWriter struct {
 	out *os.File
diff --git a/env.go b/env.go
index fdd0158..3e97da9 100644
--- a/env.go
+++ b/env.go
@@ -12,8 +12,8 @@ import (
 	"runtime"
 )
 
-// Environment holds the resolved paths for the running application.
-type Environment struct {
+// RuntimeEnvironment holds the resolved paths for the running application.
+type RuntimeEnvironment struct {
 	// DataDir is the persistent data directory (survives app updates).
 	DataDir string
 	// LaravelRoot is the extracted Laravel app in the temp directory.
@@ -22,16 +22,16 @@ type Environment struct {
 	DatabasePath string
 }
 
-// PrepareEnvironment creates data directories, generates .env, and symlinks
+// PrepareRuntimeEnvironment creates data directories, generates .env, and symlinks
 // storage so Laravel can write to persistent locations.
 // The appName is used for the data directory name (e.g. "bugseti").
-func PrepareEnvironment(laravelRoot, appName string) (*Environment, error) {
+func PrepareRuntimeEnvironment(laravelRoot, appName string) (*RuntimeEnvironment, error) {
 	dataDir, err := resolveDataDir(appName)
 	if err != nil {
 		return nil, fmt.Errorf("resolve data dir: %w", err)
 	}
 
-	env := &Environment{
+	env := &RuntimeEnvironment{
 		DataDir:      dataDir,
 		LaravelRoot:  laravelRoot,
 		DatabasePath: filepath.Join(dataDir, appName+".sqlite"),
@@ -117,7 +117,7 @@ func resolveDataDir(appName string) (string, error) {
 	return base, nil
 }
 
-func writeEnvFile(laravelRoot, appName string, env *Environment) error {
+func writeEnvFile(laravelRoot, appName string, env *RuntimeEnvironment) error {
 	appKey, err := loadOrGenerateAppKey(env.DataDir)
 	if err != nil {
 		return fmt.Errorf("app key: %w", err)