Change of argument order in call() scalar method

Author: stloyd

documentation/upgrading.md

@@ -5,6 +5,26 @@ Please follow the instructions for your specific version to ensure a smooth upgr
 
 ---
 
+## Upgrading from 0.27.x to 0.28.x
+
+### 1) Change of argument order in `call()` scalar method, and enforcing string types for argument names
+
+Before:
+```php
+ref('integers')->call(lit('explode'), ['separator' => ','], refAlias: 'string', returnType: type_list(type_integer()))
+ref('integers')->call(lit('explode'), ['separator' => ','])
+ref('integers')->call(lit('explode'), [','])
+ref('integers')->call(lit('count'))
+```
+
+After:
+
+```php
+ref('integers')->call(lit('explode'), refAlias: 'string', arguments: ['separator' => ','], returnType: type_list(type_integer()))
+ref('integers')->call(lit('explode'), refAlias: 'string', arguments: ['separator' => ','])
+ref('integers')->call(lit('count'), 'value')
+```
+
 ## Upgrading from 0.26.x to 0.27.x
 
 ### 1) Force `EntryFactory $entryFactory` to be required on `array_to_row` & `array_to_row(s)`

examples/topics/transformations/call/code.php

@@ -23,7 +23,7 @@
     )
     ->withEntry(
         'integers',
-        ref('integers')->call(lit('explode'), ['separator' => ','], refAlias: 'string', returnType: type_list(type_integer()))
+        ref('integers')->call(lit('explode'), refAlias: 'string', arguments: ['separator' => ','], returnType: type_list(type_integer()))
     )
     ->write(to_stream(__DIR__ . '/output.txt', truncate: false))
     ->run();

examples/topics/transformations/match/code.php

@@ -34,7 +34,7 @@
         match_cases(
             [
                 match_condition(ref('string')->contains('-'), ref('string')->strReplace('-', ' ')),
-                match_condition(ref('string')->call('is_numeric'), ref('string')->cast(type_integer())),
+                match_condition(ref('string')->call('is_numeric', 'value'), ref('string')->cast(type_integer())),
                 match_condition(ref('string')->endsWith('%'), ref('string')->strReplace('%', '')->cast(type_integer())),
                 match_condition(ref('string')->startsWith('+'), ref('string')->strReplace('+', '')->cast(type_integer())),
             ],

src/core/etl/src/Flow/ETL/DSL/functions.php

@@ -1373,8 +1373,7 @@ function count(?EntryReference $function = null) : Count
 /**
  * Calls a user-defined function with the given parameters.
  *
- * @param callable|ScalarFunction $callable
- * @param array<mixed> $parameters
+ * @param array<string, mixed> $parameters
  * @param null|Type<mixed> $return_type
  */
 #[DocumentationDSL(module: Module::CORE, type: DSLType::SCALAR_FUNCTION)]

src/core/etl/src/Flow/ETL/Function/CallUserFunc.php

@@ -17,8 +17,7 @@ final class CallUserFunc extends ScalarFunctionChain
     private $callable;
 
     /**
-     * @param callable|ScalarFunction $callable
-     * @param array<mixed> $parameters
+     * @param array<string, mixed> $parameters
      * @param null|Type<mixed> $returnType
      */
     public function __construct(ScalarFunction|callable $callable, private readonly array $parameters, private readonly ?Type $returnType = null)
@@ -37,6 +36,10 @@ public function eval(Row $row, FlowContext $context) : mixed
         $parameters = [];
 
         foreach ($this->parameters as $key => $parameter) {
+            if (!\is_string($key)) {
+                return $context->functions()->invalidResult(new InvalidArgumentException('CallUserFunc requires a parameter names to be a string'));
+            }
+
             $parameters[$key] = (new Parameter($parameter))->eval($row, $context);
         }
 

src/core/etl/src/Flow/ETL/Function/ScalarFunctionChain.php

@@ -152,10 +152,10 @@ public function binaryLength() : BinaryLength
     }
 
     /**
-     * @param array<array-key, mixed> $arguments
-     * @param Type<mixed> $returnType
+     * @param array<string, mixed> $arguments
+     * @param null|Type<mixed> $returnType
      */
-    public function call(ScalarFunction|callable $callable, array $arguments = [], string|int $refAlias = 0, ?Type $returnType = null) : CallUserFunc
+    public function call(ScalarFunction|callable $callable, string $refAlias, array $arguments = [], ?Type $returnType = null) : CallUserFunc
     {
         return new CallUserFunc($callable, array_merge($arguments, [$refAlias => $this]), $returnType);
     }

src/core/etl/tests/Flow/ETL/Tests/Integration/Function/CallUserFuncTest.php

@@ -23,7 +23,7 @@ public function test_call() : void
             )
             ->withEntry(
                 'integers',
-                ref('integers')->call(lit('explode'), ['separator' => ','], refAlias: 'string', returnType: type_list(type_integer()))
+                ref('integers')->call(lit('explode'), refAlias: 'string', arguments: ['separator' => ','], returnType: type_list(type_integer()))
             )
             ->write(to_memory($memory = new ArrayMemory()))
             ->run();

src/core/etl/tests/Flow/ETL/Tests/Integration/Function/MatchCasesTest.php

@@ -27,7 +27,7 @@ public function test_case_match() : void
                 match_cases(
                     [
                         match_condition(ref('string')->contains('-'), ref('string')->strReplace('-', ' ')),
-                        match_condition(ref('string')->call('is_numeric'), ref('string')->cast(type_integer())),
+                        match_condition(ref('string')->call('is_numeric', 'value'), ref('string')->cast(type_integer())),
                         match_condition(ref('string')->endsWith('%'), ref('string')->strReplace('%', '')->cast(type_integer())),
                         match_condition(ref('string')->startsWith('+'), ref('string')->strReplace('+', '')->cast(type_integer())),
                     ],

src/core/etl/tests/Flow/ETL/Tests/Unit/Function/CallUserFuncTest.php

@@ -7,10 +7,10 @@
 use function Flow\ETL\DSL\{call, flow_context, list_entry, lit, ref, row, string_entry};
 use function Flow\Types\DSL\{type_integer, type_list};
 use Flow\ETL\Function\ScalarFunction\ScalarResult;
-use Flow\ETL\Tests\FlowTestCase;
 use Flow\ETL\Tests\Unit\Function\Fixtures\CallUserFunc\StaticCalculator;
+use PHPUnit\Framework\TestCase;
 
-final class CallUserFuncTest extends FlowTestCase
+final class CallUserFuncTest extends TestCase
 {
     public function test_call_user_func_as_dsl() : void
     {
@@ -26,7 +26,33 @@ public function test_call_user_func_with_native_function() : void
         self::assertSame(
             3,
             ref('list')
-                ->call(lit('count'))
+                ->call(lit('count'), 'value')
+                ->eval($row, flow_context())
+        );
+    }
+
+    public function test_call_user_func_with_non_callable_function() : void
+    {
+        $row = row(
+            list_entry('list', [1, 2, 3], type_list(type_integer())),
+        );
+
+        self::assertNull(
+            ref('list')
+                ->call(lit('unknown'), 'whatever')
+                ->eval($row, flow_context())
+        );
+    }
+
+    public function test_call_user_func_with_non_string_argument_keys() : void
+    {
+        $row = row(
+            list_entry('list', [1, 2, 3], type_list(type_integer())),
+        );
+
+        self::assertNull(
+            ref('list')
+                ->call(lit('explode'), refAlias: 'string', arguments: [','])
                 ->eval($row, flow_context())
         );
     }
@@ -42,7 +68,7 @@ public function test_call_user_func_with_object_method() : void
         self::assertSame(
             3,
             ref('list')
-                ->call(lit($calculator->count(...)))
+                ->call(lit($calculator->count(...)), 'array')
                 ->eval($row, flow_context())
         );
     }
@@ -56,7 +82,7 @@ public function test_call_user_func_with_ref_alias_and_optional_arguments() : vo
         self::assertSame(
             ['1', '2', '3'],
             ref('item_ids')
-                ->call(lit('explode'), ['separator' => ','], refAlias: 'string')
+                ->call(lit('explode'), refAlias: 'string', arguments: ['separator' => ','])
                 ->eval($row, flow_context())
         );
     }
@@ -70,7 +96,7 @@ public function test_call_user_func_with_ref_alias_and_optional_arguments_and_re
         self::assertEquals(
             new ScalarResult([1, 2, 3], type_list(type_integer())),
             ref('item_ids')
-                ->call(lit('explode'), ['separator' => ','], refAlias: 'string', returnType: type_list(type_integer()))
+                ->call(lit('explode'), refAlias: 'string', arguments: ['separator' => ','], returnType: type_list(type_integer()))
                 ->eval($row, flow_context())
         );
     }
@@ -84,7 +110,7 @@ public function test_call_user_func_with_static_method() : void
         self::assertSame(
             3,
             ref('list')
-                ->call(lit(StaticCalculator::class . '::count'))
+                ->call(lit(StaticCalculator::class . '::count'), 'array')
                 ->eval($row, flow_context())
         );
     }