feat/separate compat interfaces from V3

src/V3/Action.php

@@ -17,8 +17,6 @@
 
 namespace Horde\Form\V3;
 
-use Horde\Form\Form;
-
 /**
  * The Action interface provides an API for adding actions to Form variables.
  *
@@ -28,12 +26,17 @@
  * - Perform calculations
  * - Trigger JavaScript behaviors
  *
+ * Extends both ActionMigrationInterface (lib/ compatibility methods)
+ * and ActionV3Interface (V3-native methods) to provide the complete
+ * Action API.
+ *
  * V3 improvements over lib/:
  * - Strict typing
  * - No singleton pattern (just use new)
  * - Named parameters
  * - Removed PHP 4 constructor
  * - Modern factory pattern
+ * - Added id() method for action tracking
  *
  * @author    Chuck Hagenbuch <chuck@horde.org>
  * @author    Ralf Lang <ralf.lang@ralf-lang.de>
@@ -43,53 +46,6 @@
  * @license   http://www.horde.org/licenses/lgpl21 LGPL 2.1
  * @package   Form
  */
-interface Action
+interface Action extends ActionMigrationInterface, ActionV3Interface
 {
-    /**
-     * Get action trigger events.
-     *
-     * @return array<string>|null  Event names (e.g., ['onload', 'onchange']) or null
-     */
-    public function getTrigger(): ?array;
-
-    /**
-     * Get action ID.
-     *
-     * @return string  Unique action identifier
-     */
-    public function id(): string;
-
-    /**
-     * Get JavaScript code for this action.
-     *
-     * @param Form $form  The form instance
-     * @param mixed $renderer  The form renderer
-     * @param string $varname  Variable name this action applies to
-     * @return string  JavaScript code
-     */
-    public function getActionScript(Form $form, $renderer, string $varname): string;
-
-    /**
-     * Print JavaScript for this action.
-     *
-     * Some actions may need to output JavaScript directly.
-     */
-    public function printJavaScript(): void;
-
-    /**
-     * Get target field name for this action.
-     *
-     * @return string|null  Target field name or null
-     */
-    public function getTarget(): ?string;
-
-    /**
-     * Set values based on action logic.
-     *
-     * @param mixed $vars  Form variables
-     * @param mixed $sourceVal  Source value
-     * @param int|null $index  Array index (if applicable)
-     * @param bool $arrayVal  Whether value is an array
-     */
-    public function setValues($vars, $sourceVal, ?int $index = null, bool $arrayVal = false): void;
 }

src/V3/ActionMigrationInterface.php

@@ -0,0 +1,73 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Copyright 2002-2026 Horde LLC (http://www.horde.org/)
+ *
+ * See the enclosed file LICENSE for license information (LGPL). If you
+ * did not receive this file, see http://www.horde.org/licenses/lgpl21.
+ *
+ * @author   Chuck Hagenbuch <chuck@horde.org>
+ * @category Horde
+ * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
+ * @package  Form
+ */
+
+namespace Horde\Form\V3;
+
+use Horde\Form\Form;
+
+/**
+ * Migration interface for Action methods that existed in lib/ (Horde_Form_Action).
+ *
+ * These methods provide backward compatibility with the lib/ implementation.
+ * Code migrating from lib/ to V3 can rely on these methods having similar
+ * signatures and behavior.
+ *
+ * @category Horde
+ * @package  Form
+ */
+interface ActionMigrationInterface
+{
+    /**
+     * Get action trigger events.
+     *
+     * @return array<string>|null  Event names (e.g., ['onload', 'onchange']) or null
+     */
+    public function getTrigger(): ?array;
+
+    /**
+     * Get JavaScript code for this action.
+     *
+     * @param Form $form       The form instance
+     * @param mixed $renderer  The form renderer
+     * @param string $varname  Variable name this action applies to
+     *
+     * @return string  JavaScript code
+     */
+    public function getActionScript(Form $form, $renderer, string $varname): string;
+
+    /**
+     * Print JavaScript for this action.
+     *
+     * Some actions may need to output JavaScript directly.
+     */
+    public function printJavaScript(): void;
+
+    /**
+     * Get target field name for this action.
+     *
+     * @return string|null  Target field name or null
+     */
+    public function getTarget(): ?string;
+
+    /**
+     * Set values based on action logic.
+     *
+     * @param mixed $vars       Form variables
+     * @param mixed $sourceVal  Source value
+     * @param int|null $index   Array index (if applicable)
+     * @param bool $arrayVal    Whether value is an array
+     */
+    public function setValues($vars, $sourceVal, ?int $index = null, bool $arrayVal = false): void;
+}

src/V3/ActionV3Interface.php

@@ -0,0 +1,38 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Copyright 2002-2026 Horde LLC (http://www.horde.org/)
+ *
+ * See the enclosed file LICENSE for license information (LGPL). If you
+ * did not receive this file, see http://www.horde.org/licenses/lgpl21.
+ *
+ * @author   Chuck Hagenbuch <chuck@horde.org>
+ * @category Horde
+ * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
+ * @package  Form
+ */
+
+namespace Horde\Form\V3;
+
+/**
+ * V3-native interface for Action methods introduced in the V3 implementation.
+ *
+ * These methods are new to V3 and provide modernized functionality
+ * not present in lib/ (Horde_Form_Action).
+ *
+ * @category Horde
+ * @package  Form
+ */
+interface ActionV3Interface
+{
+    /**
+     * Get action ID.
+     *
+     * Returns a unique identifier for this action instance. This is new
+     * in V3 for better action tracking and debugging.
+     *
+     * @return string  Unique action identifier
+     */
+    public function id(): string;
+}

src/V3/AddressVariable.php

@@ -111,6 +111,8 @@ public function parse($address)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {

src/V3/AddresslinkVariable.php

@@ -23,6 +23,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {

src/V3/AssignVariable.php

@@ -33,6 +33,8 @@ class AssignVariable extends BaseVariable
      *                      - $params[3]: string $rightHeader - Right column header (default: '')
      *                      - $params[4]: int $size - Number of visible rows (default: 8)
      *                      - $params[5]: string $width - Width in CSS units (default: '200px')
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -54,6 +56,8 @@ public function isValid(Horde_Variables $vars, $value): bool
      *
      * @param array $params Variable arguments:
      *                      - $params[0]: mixed $side - Which side to get values for (empty/0 = right, truthy = left)
+      *
+      * @api
      */
     public function getValues(...$params): ?array
     {
@@ -144,6 +148,8 @@ protected function getInfoV3($vars)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {

src/V3/BaseAction.php

@@ -65,6 +65,8 @@ abstract class BaseAction implements Action
      * Create a new action.
      *
      * @param array<string, mixed>|null $params  Action parameters
+      *
+      * @api
      */
     public function __construct(?array $params = null)
     {
@@ -76,6 +78,8 @@ public function __construct(?array $params = null)
      * Get action trigger events.
      *
      * @return array<string>|null  Event names or null
+      *
+      * @api
      */
     public function getTrigger(): ?array
     {
@@ -84,6 +88,8 @@ public function getTrigger(): ?array
 
     /**
      * Get action ID.
+      *
+      * @api
      */
     public function id(): string
     {
@@ -99,6 +105,8 @@ public function id(): string
      * @param mixed $renderer  The form renderer
      * @param string $varname  Variable name
      * @return string  JavaScript code
+      *
+      * @api
      */
     public function getActionScript(Form $form, $renderer, string $varname): string
     {
@@ -109,6 +117,8 @@ public function getActionScript(Form $form, $renderer, string $varname): string
      * Print JavaScript for this action.
      *
      * Default implementation does nothing. Subclasses override if needed.
+      *
+      * @api
      */
     public function printJavaScript(): void
     {
@@ -119,6 +129,8 @@ public function printJavaScript(): void
      * Get target field name for this action.
      *
      * @return string|null  Target field name or null
+      *
+      * @api
      */
     public function getTarget(): ?string
     {
@@ -134,6 +146,8 @@ public function getTarget(): ?string
      * @param mixed $sourceVal  Source value
      * @param int|null $index  Array index (if applicable)
      * @param bool $arrayVal  Whether value is an array
+      *
+      * @api
      */
     public function setValues($vars, $sourceVal, ?int $index = null, bool $arrayVal = false): void
     {
@@ -154,6 +168,8 @@ public function setValues($vars, $sourceVal, ?int $index = null, bool $arrayVal
      * @param array<string, mixed>|null $params  Action parameters
      * @return Action  Created action instance
      * @throws \InvalidArgumentException  If action class not found
+      *
+      * @api
      */
     public static function factory(string|array $action, ?array $params = null): Action
     {