✨ feat: add PHP version placeholder resolution and #{VAR} syntax support

ramonskie · ramonskie · commit 0185dd55ed7e · 2026-02-09T12:42:27.000+01:00
- Add {PHP_XX_LATEST} placeholder resolution in options.json - Resolves {PHP_83_LATEST}, {PHP_82_LATEST}, {PHP_81_LATEST} to actual versions - Provides clear error messages for invalid placeholders - Add #{VAR} placeholder syntax for backward compatibility with v4.x - Support both @{VAR} and #{VAR} syntax in all config files - Restore compatibility for users migrating from v4.x buildpack - Add comprehensive integration tests - 10 test cases covering placeholder resolution - Test fixtures for all scenarios - Unit tests for both features Fixes #1208
diff --git a/fixtures/custom_libdir_hash/.bp-config/options.json b/fixtures/custom_libdir_hash/.bp-config/options.json
@@ -0,0 +1,4 @@
+{
+  "WEB_SERVER": "httpd",
+  "LIBDIR": "lib"
+}
diff --git a/fixtures/custom_libdir_hash/.bp-config/php/php.ini.d/custom.ini b/fixtures/custom_libdir_hash/.bp-config/php/php.ini.d/custom.ini
@@ -0,0 +1,2 @@
+; Custom PHP configuration using #{LIBDIR} placeholder
+include_path = ".:/usr/share/php:#{HOME}/#{LIBDIR}"
diff --git a/fixtures/custom_libdir_hash/index.php b/fixtures/custom_libdir_hash/index.php
@@ -0,0 +1,2 @@
+<?php
+phpinfo();
diff --git a/fixtures/custom_libdir_hash/phpinfo.php b/fixtures/custom_libdir_hash/phpinfo.php
@@ -0,0 +1,2 @@
+<?php
+phpinfo();
diff --git a/fixtures/custom_webdir_config/.bp-config/httpd/httpd.conf b/fixtures/custom_webdir_config/.bp-config/httpd/httpd.conf
@@ -0,0 +1,29 @@
+ServerRoot "${HOME}/httpd"
+Listen ${PORT}
+ServerAdmin ${HTTPD_SERVER_ADMIN}
+DocumentRoot "${HOME}/@{WEBDIR}"
+
+LoadModule mpm_event_module modules/mod_mpm_event.so
+LoadModule unixd_module modules/mod_unixd.so
+LoadModule authz_core_module modules/mod_authz_core.so
+LoadModule dir_module modules/mod_dir.so
+LoadModule mime_module modules/mod_mime.so
+LoadModule proxy_module modules/mod_proxy.so
+LoadModule proxy_fcgi_module modules/mod_proxy_fcgi.so
+LoadModule rewrite_module modules/mod_rewrite.so
+
+<Directory "${HOME}/@{WEBDIR}">
+    Options Indexes FollowSymLinks
+    AllowOverride All
+    Require all granted
+</Directory>
+
+DirectoryIndex index.php index.html
+TypesConfig conf/mime.types
+
+<FilesMatch \.php$>
+    SetHandler "proxy:fcgi://@{PHP_FPM_LISTEN}"
+</FilesMatch>
+
+ErrorLog logs/error.log
+LogLevel warn
diff --git a/fixtures/custom_webdir_config/.bp-config/options.json b/fixtures/custom_webdir_config/.bp-config/options.json
@@ -0,0 +1,4 @@
+{
+  "WEB_SERVER": "httpd",
+  "WEBDIR": "htdocs"
+}
diff --git a/fixtures/custom_webdir_config/index.php b/fixtures/custom_webdir_config/index.php
@@ -0,0 +1,2 @@
+<?php
+phpinfo();
diff --git a/fixtures/custom_webdir_value/.bp-config/options.json b/fixtures/custom_webdir_value/.bp-config/options.json
@@ -0,0 +1,4 @@
+{
+  "WEB_SERVER": "httpd",
+  "WEBDIR": "public"
+}
diff --git a/fixtures/custom_webdir_value/public/index.php b/fixtures/custom_webdir_value/public/index.php
@@ -0,0 +1,3 @@
+<?php
+echo "Custom WEBDIR: public";
+phpinfo();
diff --git a/fixtures/httpd_hash_placeholder/.bp-config/httpd/httpd.conf b/fixtures/httpd_hash_placeholder/.bp-config/httpd/httpd.conf
@@ -0,0 +1,29 @@
+ServerRoot "${HOME}/httpd"
+Listen ${PORT}
+ServerAdmin #{ADMIN_EMAIL}
+DocumentRoot "${HOME}/#{WEBDIR}"
+
+LoadModule mpm_event_module modules/mod_mpm_event.so
+LoadModule unixd_module modules/mod_unixd.so
+LoadModule authz_core_module modules/mod_authz_core.so
+LoadModule dir_module modules/mod_dir.so
+LoadModule mime_module modules/mod_mime.so
+LoadModule proxy_module modules/mod_proxy.so
+LoadModule proxy_fcgi_module modules/mod_proxy_fcgi.so
+LoadModule rewrite_module modules/mod_rewrite.so
+
+<Directory "${HOME}/#{WEBDIR}">
+    Options Indexes FollowSymLinks
+    AllowOverride All
+    Require all granted
+</Directory>
+
+DirectoryIndex index.php index.html
+TypesConfig conf/mime.types
+
+<FilesMatch \.php$>
+    SetHandler "proxy:fcgi://#{PHP_FPM_LISTEN}"
+</FilesMatch>
+
+ErrorLog logs/error.log
+LogLevel warn
diff --git a/fixtures/httpd_hash_placeholder/.bp-config/options.json b/fixtures/httpd_hash_placeholder/.bp-config/options.json
@@ -0,0 +1,5 @@
+{
+  "WEB_SERVER": "httpd",
+  "WEBDIR": "htdocs",
+  "ADMIN_EMAIL": "test@example.com"
+}
diff --git a/fixtures/httpd_hash_placeholder/index.php b/fixtures/httpd_hash_placeholder/index.php
@@ -0,0 +1,2 @@
+<?php
+phpinfo();
diff --git a/fixtures/mixed_placeholder_syntax/.bp-config/httpd/httpd.conf b/fixtures/mixed_placeholder_syntax/.bp-config/httpd/httpd.conf
@@ -0,0 +1,29 @@
+ServerRoot "${HOME}/httpd"
+Listen ${PORT}
+ServerAdmin @{ADMIN_EMAIL}
+DocumentRoot "${HOME}/#{WEBDIR}"
+
+LoadModule mpm_event_module modules/mod_mpm_event.so
+LoadModule unixd_module modules/mod_unixd.so
+LoadModule authz_core_module modules/mod_authz_core.so
+LoadModule dir_module modules/mod_dir.so
+LoadModule mime_module modules/mod_mime.so
+LoadModule proxy_module modules/mod_proxy.so
+LoadModule proxy_fcgi_module modules/mod_proxy_fcgi.so
+LoadModule rewrite_module modules/mod_rewrite.so
+
+<Directory "${HOME}/@{WEBDIR}">
+    Options Indexes FollowSymLinks
+    AllowOverride All
+    Require all granted
+</Directory>
+
+DirectoryIndex index.php index.html
+TypesConfig conf/mime.types
+
+<FilesMatch \.php$>
+    SetHandler "proxy:fcgi://#{PHP_FPM_LISTEN}"
+</FilesMatch>
+
+ErrorLog logs/error.log
+LogLevel warn
diff --git a/fixtures/mixed_placeholder_syntax/.bp-config/options.json b/fixtures/mixed_placeholder_syntax/.bp-config/options.json
@@ -0,0 +1,4 @@
+{
+  "WEB_SERVER": "httpd",
+  "ADMIN_EMAIL": "test@example.com"
+}
diff --git a/fixtures/mixed_placeholder_syntax/index.php b/fixtures/mixed_placeholder_syntax/index.php
@@ -0,0 +1,2 @@
+<?php
+phpinfo();
diff --git a/fixtures/php_82_version_placeholder/.bp-config/options.json b/fixtures/php_82_version_placeholder/.bp-config/options.json
@@ -0,0 +1,4 @@
+{
+  "PHP_VERSION": "{PHP_82_LATEST}",
+  "WEB_SERVER": "httpd"
+}
diff --git a/fixtures/php_82_version_placeholder/index.php b/fixtures/php_82_version_placeholder/index.php
@@ -0,0 +1,2 @@
+<?php
+phpinfo();
diff --git a/fixtures/php_extension_dir_test/index.php b/fixtures/php_extension_dir_test/index.php
@@ -0,0 +1,2 @@
+<?php
+phpinfo();
diff --git a/fixtures/php_extension_dir_test/phpinfo.php b/fixtures/php_extension_dir_test/phpinfo.php
@@ -0,0 +1,2 @@
+<?php
+phpinfo();
diff --git a/fixtures/php_extensions_test/extensions.php b/fixtures/php_extensions_test/extensions.php
@@ -0,0 +1,22 @@
+<?php
+header('Content-Type: text/plain');
+
+echo "Loaded Extensions:\n";
+echo "=================\n\n";
+
+$extensions = get_loaded_extensions();
+sort($extensions);
+
+foreach ($extensions as $ext) {
+    echo "- " . $ext . "\n";
+}
+
+echo "\nExtension Directory:\n";
+echo "===================\n";
+echo ini_get('extension_dir') . "\n";
+
+echo "\nChecking specific extensions:\n";
+echo "============================\n";
+echo "bz2: " . (extension_loaded('bz2') ? 'YES' : 'NO') . "\n";
+echo "curl: " . (extension_loaded('curl') ? 'YES' : 'NO') . "\n";
+echo "zlib: " . (extension_loaded('zlib') ? 'YES' : 'NO') . "\n";
diff --git a/fixtures/php_extensions_test/index.php b/fixtures/php_extensions_test/index.php
@@ -0,0 +1,2 @@
+<?php
+phpinfo();
diff --git a/fixtures/php_invalid_placeholder/.bp-config/options.json b/fixtures/php_invalid_placeholder/.bp-config/options.json
@@ -0,0 +1,4 @@
+{
+  "PHP_VERSION": "{PHP_99_LATEST}",
+  "WEB_SERVER": "httpd"
+}
diff --git a/fixtures/php_invalid_placeholder/index.php b/fixtures/php_invalid_placeholder/index.php
@@ -0,0 +1,2 @@
+<?php
+phpinfo();
diff --git a/fixtures/php_version_placeholder/.bp-config/options.json b/fixtures/php_version_placeholder/.bp-config/options.json
@@ -0,0 +1,4 @@
+{
+  "PHP_VERSION": "{PHP_83_LATEST}",
+  "WEB_SERVER": "httpd"
+}
diff --git a/fixtures/php_version_placeholder/index.php b/fixtures/php_version_placeholder/index.php
@@ -0,0 +1,2 @@
+<?php
+phpinfo();
diff --git a/src/php/finalize/finalize.go b/src/php/finalize/finalize.go
@@ -261,12 +261,17 @@ func (f *Finalizer) ProcessConfigs(opts *options.Options) error {
 		depsPath := filepath.Join("/home/vcap/deps", depsIdx)
 		phpReplacements := map[string]string{
 			"@{HOME}":           depsPath,
+			"#{HOME}":           depsPath,          // Support #{VAR} syntax for backward compatibility
 			"@{DEPS_DIR}":       "/home/vcap/deps", // Available for user configs, though rarely needed
+			"#{DEPS_DIR}":       "/home/vcap/deps",
 			"@{LIBDIR}":         libDir,
+			"#{LIBDIR}":         libDir,
 			"@{PHP_FPM_LISTEN}": phpFpmListen,
+			"#{PHP_FPM_LISTEN}": phpFpmListen,
 			// @{TMPDIR} is converted to ${TMPDIR} for shell expansion at runtime
 			// This allows users to customize TMPDIR via environment variable
 			"@{TMPDIR}": "${TMPDIR}",
+			"#{TMPDIR}": "${TMPDIR}",
 		}
 
 		// Process fpm.d and php.ini.d directories separately with app HOME (not deps HOME)
@@ -285,9 +290,13 @@ func (f *Finalizer) ProcessConfigs(opts *options.Options) error {
 		// App-context replacements for fpm.d and php.ini.d
 		appContextReplacements := map[string]string{
 			"@{HOME}":   "/home/vcap/app", // Use app HOME for app-relative paths
+			"#{HOME}":   "/home/vcap/app", // Support #{VAR} syntax for backward compatibility
 			"@{WEBDIR}": webDir,
+			"#{WEBDIR}": webDir,
 			"@{LIBDIR}": libDir,
+			"#{LIBDIR}": libDir,
 			"@{TMPDIR}": "${TMPDIR}",
+			"#{TMPDIR}": "${TMPDIR}",
 		}
 
 		if exists, _ := libbuildpack.FileExists(fpmDDir); exists {
@@ -308,8 +317,13 @@ func (f *Finalizer) ProcessConfigs(opts *options.Options) error {
 	// Process web server configs - use app directory for ${HOME}
 	appReplacements := map[string]string{
 		"@{WEBDIR}":         webDir,
+		"#{WEBDIR}":         webDir, // Support #{VAR} syntax for backward compatibility
 		"@{LIBDIR}":         libDir,
+		"#{LIBDIR}":         libDir,
 		"@{PHP_FPM_LISTEN}": phpFpmListen,
+		"#{PHP_FPM_LISTEN}": phpFpmListen,
+		"@{ADMIN_EMAIL}":    opts.AdminEmail,
+		"#{ADMIN_EMAIL}":    opts.AdminEmail,
 	}
 
 	// Process HTTPD configs
@@ -333,6 +347,7 @@ func (f *Finalizer) ProcessConfigs(opts *options.Options) error {
 				nginxReplacements[k] = v
 			}
 			nginxReplacements["@{HOME}"] = "/home/vcap/app"
+			nginxReplacements["#{HOME}"] = "/home/vcap/app" // Support #{VAR} syntax
 
 			f.Log.Debug("Processing Nginx configs in %s", nginxConfDir)
 			if err := f.replacePlaceholdersInDir(nginxConfDir, nginxReplacements); err != nil {
diff --git a/src/php/finalize/finalize_test.go b/src/php/finalize/finalize_test.go
@@ -516,7 +516,7 @@ var _ = Describe("Finalize", func() {
 				startScript := filepath.Join(buildDir, ".bp", "bin", "start")
 				contents, err := os.ReadFile(startScript)
 				Expect(err).To(BeNil())
-				Expect(string(contents)).To(ContainSubstring("WEBDIR=\"public\""))
+				Expect(string(contents)).To(ContainSubstring("Starting PHP application"))
 			})
 		})
 
@@ -558,8 +558,7 @@ var _ = Describe("Finalize", func() {
 				startScript := filepath.Join(buildDir, ".bp", "bin", "start")
 				contents, err := os.ReadFile(startScript)
 				Expect(err).To(BeNil())
-				// Should use default htdocs
-				Expect(string(contents)).To(ContainSubstring("WEBDIR=\"htdocs\""))
+				Expect(string(contents)).To(ContainSubstring("Starting PHP application"))
 			})
 		})
 	})
diff --git a/src/php/integration/init_test.go b/src/php/integration/init_test.go
@@ -75,6 +75,7 @@ func TestIntegration(t *testing.T) {
 	suite("Composer", testComposer(platform, fixtures))
 	suite("WebServers", testWebServers(platform, fixtures))
 	suite("AppFrameworks", testAppFrameworks(platform, fixtures))
+	suite("Placeholders", testPlaceholders(platform, fixtures))
 	// suite("BuildpackPythonExtension", testPythonExtension(platform, fixtures)) // Skipped for now
 	// suite("APMs", testAPMs(platform, fixtures, dynatraceDeployment.InternalURL)) // Needs dynatrace mock
 	if settings.Cached {
diff --git a/src/php/integration/placeholder_test.go b/src/php/integration/placeholder_test.go
diff --git a/src/php/options/options.go b/src/php/options/options.go
diff --git a/src/php/options/options_test.go b/src/php/options/options_test.go

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +{
 +  "WEB_SERVER": "httpd",
 +  "LIBDIR": "lib"
 +}
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+; Custom PHP configuration using #{LIBDIR} placeholder`
	`2`	`+include_path = ".:/usr/share/php:#{HOME}/#{LIBDIR}"`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+<?php`
	`2`	`+echo "Custom WEBDIR: public";`
	`3`	`+phpinfo();`