extgen: (types) make go arrays more consistent with PHP arrays

docs/extensions.md

@@ -81,17 +81,18 @@ While the first point speaks for itself, the second may be harder to apprehend.
 
 While some variable types have the same memory representation between C/PHP and Go, some types require more logic to be directly used. This is maybe the hardest part when it comes to writing extensions because it requires understanding internals of the Zend Engine and how variables are stored internally in PHP. This table summarizes what you need to know:
 
-| PHP type           | Go type             | Direct conversion | C to Go helper        | Go to C helper         | Class Methods Support |
-|--------------------|---------------------|-------------------|-----------------------|------------------------|-----------------------|
-| `int`              | `int64`             | ✅                 | -                     | -                      | ✅                     |
-| `?int`             | `*int64`            | ✅                 | -                     | -                      | ✅                     |
-| `float`            | `float64`           | ✅                 | -                     | -                      | ✅                     |
-| `?float`           | `*float64`          | ✅                 | -                     | -                      | ✅                     |
-| `bool`             | `bool`              | ✅                 | -                     | -                      | ✅                     |
-| `?bool`            | `*bool`             | ✅                 | -                     | -                      | ✅                     |
-| `string`/`?string` | `*C.zend_string`    | ❌                 | frankenphp.GoString() | frankenphp.PHPString() | ✅                     |
-| `array`            | `*frankenphp.Array` | ❌                 | frankenphp.GoArray()  | frankenphp.PHPArray()  | ✅                     |
-| `object`           | `struct`            | ❌                 | _Not yet implemented_ | _Not yet implemented_  | ❌                     |
+| PHP type           | Go type                        | Direct conversion | C to Go helper                  | Go to C helper                   | Class Methods Support |
+|--------------------|--------------------------------|-------------------|---------------------------------|----------------------------------|-----------------------|
+| `int`              | `int64`                        | ✅                 | -                               | -                                | ✅                     |
+| `?int`             | `*int64`                       | ✅                 | -                               | -                                | ✅                     |
+| `float`            | `float64`                      | ✅                 | -                               | -                                | ✅                     |
+| `?float`           | `*float64`                     | ✅                 | -                               | -                                | ✅                     |
+| `bool`             | `bool`                         | ✅                 | -                               | -                                | ✅                     |
+| `?bool`            | `*bool`                        | ✅                 | -                               | -                                | ✅                     |
+| `string`/`?string` | `*C.zend_string`               | ❌                 | frankenphp.GoString()           | frankenphp.PHPString()           | ✅                     |
+| `array`            | `*frankenphp.AssociativeArray` | ❌                 | frankenphp.GoAssociativeArray() | frankenphp.PHPAssociativeArray() | ✅                     |
+| `array (packed)`   | `*frankenphp.PackedArray`      | ❌                 | frankenphp.GoPackedArray()      | frankenphp.PHPPackedArray()      | ✅                     |
+| `object`           | `struct`                       | ❌                 | _Not yet implemented_           | _Not yet implemented_            | ❌                     |
 
 > [!NOTE]
 > This table is not exhaustive yet and will be completed as the FrankenPHP types API gets more complete.
@@ -102,55 +103,86 @@ If you refer to the code snippet of the previous section, you can see that helpe
 
 #### Working with Arrays
 
-FrankenPHP provides native support for PHP arrays through the `frankenphp.Array` type. This type represents both PHP indexed arrays (lists) and associative arrays (hashmaps) with ordered key-value pairs.
+FrankenPHP provides native support for PHP arrays through `frankenphp.AssociativeArray` and `frankenphp.PackedArray`.
+
+`AssociativeArray` represents an associative hashmap and is composed of a `Map: map[string]any` and an optional `Order: []string`.
+For unordered arrays, `Order` will be left empty.
+
+`PackedArray` is just an alias for a go slice `[]any`
 
 **Creating and manipulating arrays in Go:**
 
 ```go
-//export_php:function process_data(array $input): array
-func process_data(arr *C.zval) unsafe.Pointer {
-    // Convert PHP array to Go
-    goArray := frankenphp.GoArray(unsafe.Pointer(arr))
-
-	result := &frankenphp.Array{}
-
-    result.SetInt(0, "first")
-    result.SetInt(1, "second")
-    result.Append("third") // Automatically assigns next integer key
-
-    result.SetString("name", "John")
-    result.SetString("age", int64(30))
-
-    for i := uint32(0); i < goArray.Len(); i++ {
-        key, value := goArray.At(i)
-        if key.Type == frankenphp.PHPStringKey {
-            result.SetString("processed_"+key.Str, value)
-        } else {
-            result.SetInt(key.Int+100, value)
-        }
-    }
-
-    // Convert back to PHP array
-    return frankenphp.PHPArray(result)
+// export_php:function process_data_ordered(array $input): array
+func process_data_ordered(arr *C.zval) unsafe.Pointer {
+	// Convert PHP associative array to Go while keeping the order
+	associativeArray := frankenphp.GoAssociativeArray(unsafe.Pointer(arr), true)
+
+	// loop over the entries in order
+	for _, key := range associativeArray.Order {
+		value, _ = associativeArray.Map[key]
+		// do something with key and value
+	}
+
+	// return an ordered array
+	// if 'Order' is not empty, only the key-value paris in 'Order' will be respected
+	return frankenphp.PHPAssociativeArray(AssociativeArray{
+		Map: map[string]any{
+			"key1": "value1",
+			"key2": "value2",
+		},
+		Order: []string{"key1", "key2"},
+	})
+}
+
+// export_php:function process_data_unordered(array $input): array
+func process_data_unordered(arr *C.zval) unsafe.Pointer {
+	// Convert PHP associative array to Go without keeping the order
+	// ignoring the order will be more performant
+	associativeArray := frankenphp.GoAssociativeArray(unsafe.Pointer(arr), false)
+
+	// loop over the entries in no specific order
+	for key, value := range associativeArray.Map {
+		value, _ = associativeArray.Map[key]
+		// do something with key and value
+	}
+
+	// return an unordered array
+	return frankenphp.PHPAssociativeArray(AssociativeArray{Map: map[string]any{
+		"key1": "value1",
+		"key2": "value2",
+	}})
+}
+
+// export_php:function process_data_packed(array $input): array
+func process_data_packed(arr *C.zval) unsafe.Pointer {
+	// Convert PHP packed array to Go
+	packedArray := frankenphp.GoPackedArray(unsafe.Pointer(arr), false)
+
+	// loop over the slice in order
+	for index, value := range packedArray {
+		// do something with index and value
+	}
+
+	// return a packed array
+	return frankenphp.PHPackedArray{"value1", "value2", "value3"}
 }
 ```
 
-**Key features of `frankenphp.Array`:**
+**Key features of `frankenphp.PackedArray` and `frankenphp.AssociativeArray`:**
 
-* **Ordered key-value pairs** - Maintains insertion order like PHP arrays
-* **Mixed key types** - Supports both integer and string keys in the same array
-* **Type safety** - The `PHPKey` type ensures proper key handling
+* **Ordered key-value pairs** - Option to keep the order of the associative array
+* **Optimized for multiple cases** - Option to ditch the order for better performance or convert straight to a slice
 * **Automatic list detection** - When converting to PHP, automatically detects if array should be a packed list or hashmap
+* **Nested Arrays** - Arrays can be nested and will convert all support types automatically (int64,float64,string,bool,nil,AssociativeArray,PackedArray)
 * **Objects are not supported** - Currently, only scalar types and arrays can be used as values. Providing an object will result in a `null` value in the PHP array.
 
-**Available methods:**
+##### Available methods - packed and associative
 
-* `SetInt(key int64, value interface{})` - Set value with integer key
-* `SetString(key string, value interface{})` - Set value with string key  
-* `Append(value interface{})` - Add value with next available integer key
-* `Len() uint32` - Get number of elements
-* `At(index uint32) (PHPKey, interface{})` - Get key-value pair at index
-* `frankenphp.PHPArray(arr *frankenphp.Array) unsafe.Pointer` - Convert to PHP array
+* `frankenphp.PHPAssociativeArray(arr frankenphp.AssociativeArray) unsafe.Pointer` - Convert to a PHP array with key-value pairs, optionally pass a specific order
+* `frankenphp.PHPPackedArray(arr frankenphp.PackedArray) unsafe.Pointer` - Convert to a PHP packed array with indexed values only
+* `frankenphp.GoAssociativeArray(arr unsafe.Pointer, ordered bool) frankenphp.AssociativeArray` - Convert a PHP array to a Go map and optionally keep the order
+* `frankenphp.GoPackedArray(arr unsafe.Pointer) frankenphp.PackedArray` - Convert a PHP array to a go slice
 
 ### Declaring a Native PHP Class
 

internal/extgen/gofile_test.go

@@ -514,18 +514,17 @@ type ArrayStruct struct {
 }
 
 //export_php:method ArrayClass::processArray(array $items): array
-func (as *ArrayStruct) ProcessArray(items *frankenphp.Array) *frankenphp.Array {
-	result := &frankenphp.Array{}
-	for i := uint32(0); i < items.Len(); i++ {
-		key, value := items.At(i)
-		result.SetString(fmt.Sprintf("processed_%d", i), value)
+func (as *ArrayStruct) ProcessArray(items frankenphp.AssociativeArray) frankenphp.AssociativeArray {
+	result := frankenphp.AssociativeArray{}
+	for key, value := range items.Map {
+		result.Set("processed_"+key, value)
 	}
 	return result
 }
 
 //export_php:method ArrayClass::filterData(array $data, string $filter): array
-func (as *ArrayStruct) FilterData(data *frankenphp.Array, filter string) *frankenphp.Array {
-	result := &frankenphp.Array{}
+func (as *ArrayStruct) FilterData(data frankenphp.AssociativeArray, filter string) frankenphp.AssociativeArray {
+	result := frankenphp.AssociativeArray{}
 	// Filter logic here
 	return result
 }`
@@ -543,11 +542,10 @@ func (as *ArrayStruct) FilterData(data *frankenphp.Array, filter string) *franke
 			Params: []phpParameter{
 				{Name: "items", PhpType: phpArray, IsNullable: false},
 			},
-			GoFunction: `func (as *ArrayStruct) ProcessArray(items *frankenphp.Array) *frankenphp.Array {
-	result := &frankenphp.Array{}
-	for i := uint32(0); i < items.Len(); i++ {
-		key, value := items.At(i)
-		result.SetString(fmt.Sprintf("processed_%d", i), value)
+			GoFunction: `func (as *ArrayStruct) ProcessArray(items frankenphp.AssociativeArray) frankenphp.AssociativeArray {
+	result := frankenphp.AssociativeArray{}
+	for key, value := range items.Entries() {
+		result.Set("processed_"+key, value)
 	}
 	return result
 }`,
@@ -562,8 +560,8 @@ func (as *ArrayStruct) FilterData(data *frankenphp.Array, filter string) *franke
 				{Name: "data", PhpType: phpArray, IsNullable: false},
 				{Name: "filter", PhpType: phpString, IsNullable: false},
 			},
-			GoFunction: `func (as *ArrayStruct) FilterData(data *frankenphp.Array, filter string) *frankenphp.Array {
-	result := &frankenphp.Array{}
+			GoFunction: `func (as *ArrayStruct) FilterData(data frankenphp.AssociativeArray, filter string) frankenphp.AssociativeArray {
+	result := frankenphp.AssociativeArray{}
 	return result
 }`,
 		},
@@ -613,11 +611,8 @@ func TestGoFileGenerator_MethodWrapperWithNullableArrayParams(t *testing.T) {
 type NullableArrayStruct struct{}
 
 //export_php:method NullableArrayClass::processOptionalArray(?array $items, string $name): string
-func (nas *NullableArrayStruct) ProcessOptionalArray(items *frankenphp.Array, name string) string {
-	if items == nil {
-		return "No items: " + name
-	}
-	return fmt.Sprintf("Processing %d items for %s", items.Len(), name)
+func (nas *NullableArrayStruct) ProcessOptionalArray(items frankenphp.AssociativeArray, name string) string {
+	return fmt.Sprintf("Processing %d items for %s", len(items.Map), name)
 }`
 
 	sourceFile := filepath.Join(tmpDir, "test.go")
@@ -634,11 +629,8 @@ func (nas *NullableArrayStruct) ProcessOptionalArray(items *frankenphp.Array, na
 				{Name: "items", PhpType: phpArray, IsNullable: true},
 				{Name: "name", PhpType: phpString, IsNullable: false},
 			},
-			GoFunction: `func (nas *NullableArrayStruct) ProcessOptionalArray(items *frankenphp.Array, name string) string {
-	if items == nil {
-		return "No items: " + name
-	}
-	return fmt.Sprintf("Processing %d items for %s", items.Len(), name)
+			GoFunction: `func (nas *NullableArrayStruct) ProcessOptionalArray(items frankenphp.AssociativeArray, name string) string {
+	return fmt.Sprintf("Processing %d items for %s", len(items.Map), name)
 }`,
 		},
 	}

threadtasks_test.go

@@ -0,0 +1,90 @@
+package frankenphp
+
+import (
+	"sync"
+)
+
+// representation of a thread that handles tasks directly assigned by go
+// implements the threadHandler interface
+type taskThread struct {
+	thread   *phpThread
+	execChan chan *task
+}
+
+// task callbacks will be executed directly on the PHP thread
+// therefore having full access to the PHP runtime
+type task struct {
+	callback func()
+	done     sync.Mutex
+}
+
+func newTask(cb func()) *task {
+	t := &task{callback: cb}
+	t.done.Lock()
+
+	return t
+}
+
+func (t *task) waitForCompletion() {
+	t.done.Lock()
+}
+
+func convertToTaskThread(thread *phpThread) *taskThread {
+	handler := &taskThread{
+		thread:   thread,
+		execChan: make(chan *task),
+	}
+	thread.setHandler(handler)
+	return handler
+}
+
+func (handler *taskThread) beforeScriptExecution() string {
+	thread := handler.thread
+
+	switch thread.state.get() {
+	case stateTransitionRequested:
+		return thread.transitionToNewHandler()
+	case stateBooting, stateTransitionComplete:
+		thread.state.set(stateReady)
+		handler.waitForTasks()
+
+		return handler.beforeScriptExecution()
+	case stateReady:
+		handler.waitForTasks()
+
+		return handler.beforeScriptExecution()
+	case stateShuttingDown:
+		// signal to stop
+		return ""
+	}
+	panic("unexpected state: " + thread.state.name())
+}
+
+func (handler *taskThread) afterScriptExecution(int) {
+	panic("task threads should not execute scripts")
+}
+
+func (handler *taskThread) getRequestContext() *frankenPHPContext {
+	return nil
+}
+
+func (handler *taskThread) name() string {
+	return "Task PHP Thread"
+}
+
+func (handler *taskThread) waitForTasks() {
+	for {
+		select {
+		case task := <-handler.execChan:
+			task.callback()
+			task.done.Unlock() // unlock the task to signal completion
+		case <-handler.thread.drainChan:
+			// thread is shutting down, do not execute the function
+			return
+		}
+	}
+}
+
+func (handler *taskThread) execute(t *task) {
+	handler.execChan <- t
+}