feat(extgen): add support for //export_php:namespace (#1721)

Author: alexandre-daubois

docs/extensions.md

@@ -335,6 +335,61 @@ func (sp *StringProcessorStruct) Process(input *C.zend_string, mode int64) unsaf
 }
 ```
 
+### Using Namespaces
+
+The generator supports organizing your PHP extension's functions, classes, and constants under a namespace using the `//export_php:namespace` directive. This helps avoid naming conflicts and provides better organization for your extension's API.
+
+#### Declaring a Namespace
+
+Use the `//export_php:namespace` directive at the top of your Go file to place all exported symbols under a specific namespace:
+
+```go
+//export_php:namespace My\Extension
+package main
+
+import "C"
+
+//export_php:function hello(): string
+func hello() string {
+    return "Hello from My\\Extension namespace!"
+}
+
+//export_php:class User
+type UserStruct struct {
+    // internal fields
+}
+
+//export_php:method User::getName(): string
+func (u *UserStruct) GetName() unsafe.Pointer {
+    return frankenphp.PHPString("John Doe", false)
+}
+
+//export_php:const
+const STATUS_ACTIVE = 1
+```
+
+#### Using Namespaced Extension in PHP
+
+When a namespace is declared, all functions, classes, and constants are placed under that namespace in PHP:
+
+```php
+<?php
+
+echo My\Extension\hello(); // "Hello from My\Extension namespace!"
+
+$user = new My\Extension\User();
+echo $user->getName(); // "John Doe"
+
+echo My\Extension\STATUS_ACTIVE; // 1
+```
+
+#### Important Notes
+
+* Only **one** namespace directive is allowed per file. If multiple namespace directives are found, the generator will return an error.
+* The namespace applies to **all** exported symbols in the file: functions, classes, methods, and constants.
+* Namespace names follow PHP namespace conventions using backslashes (`\`) as separators.
+* If no namespace is declared, symbols are exported to the global namespace as usual.
+
 ### Generating the Extension
 
 This is where the magic happens, and your extension can now be generated. You can run the generator with the following command:

docs/fr/extensions.md

@@ -335,6 +335,61 @@ func (sp *StringProcessorStruct) Process(input *C.zend_string, mode int64) unsaf
 }
 ```
 
+### Utilisation des Espaces de Noms
+
+Le générateur prend en charge l'organisation des fonctions, classes et constantes de votre extension PHP sous un espace de noms (namespace) en utilisant la directive `//export_php:namespace`. Cela aide à éviter les conflits de noms et fournit une meilleure organisation pour l'API de votre extension.
+
+#### Déclarer un Espace de Noms
+
+Utilisez la directive `//export_php:namespace` en haut de votre fichier Go pour placer tous les symboles exportés sous un espace de noms spécifique :
+
+```go
+//export_php:namespace My\Extension
+package main
+
+import "C"
+
+//export_php:function hello(): string
+func hello() string {
+    return "Bonjour depuis l'espace de noms My\\Extension !"
+}
+
+//export_php:class User
+type UserStruct struct {
+    // champs internes
+}
+
+//export_php:method User::getName(): string
+func (u *UserStruct) GetName() unsafe.Pointer {
+    return frankenphp.PHPString("Jean Dupont", false)
+}
+
+//export_php:const
+const STATUS_ACTIVE = 1
+```
+
+#### Utilisation de l'Extension avec Espace de Noms en PHP
+
+Quand un espace de noms est déclaré, toutes les fonctions, classes et constantes sont placées sous cet espace de noms en PHP :
+
+```php
+<?php
+
+echo My\Extension\hello(); // "Bonjour depuis l'espace de noms My\Extension !"
+
+$user = new My\Extension\User();
+echo $user->getName(); // "Jean Dupont"
+
+echo My\Extension\STATUS_ACTIVE; // 1
+```
+
+#### Notes Importantes
+
+* Seule **une** directive d'espace de noms est autorisée par fichier. Si plusieurs directives d'espace de noms sont trouvées, le générateur retournera une erreur.
+* L'espace de noms s'applique à **tous** les symboles exportés dans le fichier : fonctions, classes, méthodes et constantes.
+* Les noms d'espaces de noms suivent les conventions des espaces de noms PHP en utilisant les barres obliques inverses (`\`) comme séparateurs.
+* Si aucun espace de noms n'est déclaré, les symboles sont exportés vers l'espace de noms global comme d'habitude.
+
 ### Générer l'Extension
 
 C'est là que la magie opère, et votre extension peut maintenant être générée. Vous pouvez exécuter le générateur avec la commande suivante :

internal/extgen/cfile.go

@@ -22,6 +22,7 @@ type cTemplateData struct {
 	Functions []phpFunction
 	Classes   []phpClass
 	Constants []phpConstant
+	Namespace string
 }
 
 func (cg *cFileGenerator) generate() error {
@@ -44,22 +45,29 @@ func (cg *cFileGenerator) buildContent() (string, error) {
 	builder.WriteString(templateContent)
 
 	for _, fn := range cg.generator.Functions {
-		fnGen := PHPFuncGenerator{paramParser: &ParameterParser{}}
+		fnGen := PHPFuncGenerator{
+			paramParser: &ParameterParser{},
+			namespace:   cg.generator.Namespace,
+		}
 		builder.WriteString(fnGen.generate(fn))
 	}
 
 	return builder.String(), nil
 }
 
 func (cg *cFileGenerator) getTemplateContent() (string, error) {
-	tmpl := template.Must(template.New("cfile").Funcs(sprig.FuncMap()).Parse(cFileContent))
+	funcMap := sprig.FuncMap()
+	funcMap["namespacedClassName"] = NamespacedName
+
+	tmpl := template.Must(template.New("cfile").Funcs(funcMap).Parse(cFileContent))
 
 	var buf bytes.Buffer
 	if err := tmpl.Execute(&buf, cTemplateData{
 		BaseName:  cg.generator.BaseName,
 		Functions: cg.generator.Functions,
 		Classes:   cg.generator.Classes,
 		Constants: cg.generator.Constants,
+		Namespace: cg.generator.Namespace,
 	}); err != nil {
 		return "", err
 	}

internal/extgen/cfile_namespace_test.go

@@ -0,0 +1,130 @@
+package extgen
+
+import (
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"os"
+	"testing"
+)
+
+func TestNamespacedClassName(t *testing.T) {
+	tests := []struct {
+		name      string
+		namespace string
+		className string
+		expected  string
+	}{
+		{
+			name:      "no namespace",
+			namespace: "",
+			className: "MySuperClass",
+			expected:  "MySuperClass",
+		},
+		{
+			name:      "single level namespace",
+			namespace: "MyNamespace",
+			className: "MySuperClass",
+			expected:  "MyNamespace_MySuperClass",
+		},
+		{
+			name:      "multi level namespace",
+			namespace: `Go\Extension`,
+			className: "MySuperClass",
+			expected:  "Go_Extension_MySuperClass",
+		},
+		{
+			name:      "deep namespace",
+			namespace: `My\Deep\Nested\Namespace`,
+			className: "TestClass",
+			expected:  "My_Deep_Nested_Namespace_TestClass",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := NamespacedName(tt.namespace, tt.className)
+			require.Equal(t, tt.expected, result, "expected %q, got %q", tt.expected, result)
+		})
+	}
+}
+
+func TestCFileGenerationWithNamespace(t *testing.T) {
+	content := `package main
+
+//export_php:namespace Go\Extension
+
+//export_php:class MySuperClass
+type MySuperClass struct{}
+
+//export_php:method MySuperClass test(): string
+func (m *MySuperClass) Test() string {
+	return "test"
+}
+`
+
+	tmpfile, err := os.CreateTemp("", "test_cfile_namespace_*.go")
+	require.NoError(t, err, "Failed to create temp file")
+	defer func() {
+		err := os.Remove(tmpfile.Name())
+		assert.NoError(t, err, "Failed to remove temp file: %v", err)
+	}()
+
+	_, err = tmpfile.Write([]byte(content))
+	require.NoError(t, err, "Failed to write to temp file")
+
+	err = tmpfile.Close()
+	require.NoError(t, err, "Failed to close temp file")
+
+	generator := &Generator{
+		BaseName:   "test_extension",
+		SourceFile: tmpfile.Name(),
+		BuildDir:   t.TempDir(),
+		Namespace:  `Go\Extension`,
+		Classes: []phpClass{
+			{
+				Name:     "MySuperClass",
+				GoStruct: "MySuperClass",
+				Methods: []phpClassMethod{
+					{
+						Name:       "test",
+						PhpName:    "test",
+						Signature:  "test(): string",
+						ReturnType: "string",
+						ClassName:  "MySuperClass",
+					},
+				},
+			},
+		},
+	}
+
+	cFileGen := cFileGenerator{generator: generator}
+	contentResult, err := cFileGen.getTemplateContent()
+	require.NoError(t, err, "error generating C file")
+
+	expectedCall := "register_class_Go_Extension_MySuperClass()"
+	require.Contains(t, contentResult, expectedCall, "C file should contain the standard function call")
+
+	oldCall := "register_class_MySuperClass()"
+	require.NotContains(t, contentResult, oldCall, "C file should not contain old non-namespaced call")
+}
+
+func TestCFileGenerationWithoutNamespace(t *testing.T) {
+	generator := &Generator{
+		BaseName:  "test_extension",
+		BuildDir:  t.TempDir(),
+		Namespace: "",
+		Classes: []phpClass{
+			{
+				Name:     "MySuperClass",
+				GoStruct: "MySuperClass",
+			},
+		},
+	}
+
+	cFileGen := cFileGenerator{generator: generator}
+	contentResult, err := cFileGen.getTemplateContent()
+	require.NoError(t, err, "error generating C file")
+
+	expectedCall := "register_class_MySuperClass()"
+	require.Contains(t, contentResult, expectedCall, "C file should not contain the standard function call")
+}