From 572338bb3db13361ea2bfb34ec3f252c00e956f4 Mon Sep 17 00:00:00 2001
From: Ralf Lang <ralf.lang@ralf-lang.de>
Date: Sun, 8 Mar 2026 07:20:11 +0100
Subject: [PATCH 1/5] fix: Restore deprecation warning for legacy getInfo()
 signature

Add back warning when the getInfo() compat method is called with the old lib/ signature
that passes $info by reference. This helps identify legacy code that
needs migration to V3 pattern. We will probably port this to a PSR-3 logger warning later.

Ref: bd4905cbdc7bbdb142a8b8d86e5a2340d9f66ef8
---
 src/V3/BaseVariable.php | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/V3/BaseVariable.php b/src/V3/BaseVariable.php
index d73c32d..6e6b437 100644
--- a/src/V3/BaseVariable.php
+++ b/src/V3/BaseVariable.php
@@ -429,8 +429,12 @@ public function getOption($option)
      * @param Horde_Variables $vars  The variables object
      * @param mixed ...$args  Ignored (for interface compatibility)
      * @return mixed  The variable value
+     * @deprecated The second parameter ($info) is deprecated/ignored
      */
     public function getInfo($vars, ...$args) {
+        if (count($args) > 0) {
+            self::Deprecated('Warning: The second ($info) parameter in getInfo() is deprecated/ignored');
+        }
         return $this->getInfoV3($vars);
     }
 

From 3c6944f388434c56b42f0fced1112d15ab6c68e5 Mon Sep 17 00:00:00 2001
From: Ralf Lang <ralf.lang@ralf-lang.de>
Date: Sun, 8 Mar 2026 08:03:05 +0100
Subject: [PATCH 2/5] docs: complete missing PHPDoc blocks in V3 codebase

Add comprehensive PHPDoc blocks for methods missing documentation:

All methods now have complete @param, @return tags and clear descriptions
of what they do.
---
 src/V3/BaseVariable.php             | 70 +++++++++++++++++++++++++++--
 src/V3/BooleanVariable.php          | 11 +++++
 src/V3/EmailVariable.php            | 66 ++++++++++++++++++++++-----
 src/V3/FileVariable.php             | 12 +++++
 src/V3/HourminutesecondVariable.php | 22 +++++++++
 src/V3/IntVariable.php              | 11 +++++
 src/V3/MultienumVariable.php        | 12 +++++
 7 files changed, 189 insertions(+), 15 deletions(-)

diff --git a/src/V3/BaseVariable.php b/src/V3/BaseVariable.php
index 6e6b437..049f5c5 100644
--- a/src/V3/BaseVariable.php
+++ b/src/V3/BaseVariable.php
@@ -225,6 +225,11 @@ public function isHidden()
 
     /**
      * Disables this variable.
+     *
+     * Disabled fields are not submitted by browsers and are skipped
+     * during form processing and validation.
+     *
+     * @return void
      */
     public function disable()
     {
@@ -559,7 +564,19 @@ public function validate($vars, ...$args)
 
     // Former Type-related methods
 
-    //TODO: Does not belong here
+    /**
+     * Logs a deprecation warning message.
+     *
+     * Helper method for logging deprecation warnings during the lib/ to V3
+     * migration. Includes file and line number from the call stack.
+     *
+     * @param string $message  The deprecation warning message
+     * @param int $level       Stack trace depth (default: 2)
+     *
+     * @return void
+     *
+     * @todo This method should be removed after V3 transition is complete
+     */
     public static function Deprecated($message, $level = 2) {
         $trace = debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, $level + 1);
         if (isset($trace[$level])) {
@@ -570,6 +587,16 @@ public static function Deprecated($message, $level = 2) {
         Horde::log($message, 'WARN');
     }
 
+    /**
+     * Gets internal property value by name.
+     *
+     * Accesses internal properties using underscore-prefixed naming convention
+     * (e.g., 'size' accesses $this->_size).
+     *
+     * @param string $property  Property name (without underscore prefix)
+     *
+     * @return mixed  Property value, or null if not set
+     */
     public function getProperty($property)
     {
         $prop = '_' . $property;
@@ -577,7 +604,15 @@ public function getProperty($property)
     }
 
     /**
-     * Not part of the interface, implementation detail
+     * Magic getter for accessing internal properties.
+     *
+     * Provides property access using underscore-prefixed naming convention.
+     * Special handling for deprecated 'type' property which triggers a
+     * deprecation warning.
+     *
+     * @param string $property  Property name
+     *
+     * @return mixed  Property value, or $this for deprecated 'type' property
      */
     public function __get($property)
     {
@@ -590,6 +625,17 @@ public function __get($property)
         return $this->getProperty($property);
     }
 
+    /**
+     * Sets internal property value by name.
+     *
+     * Sets internal properties using underscore-prefixed naming convention
+     * (e.g., 'size' sets $this->_size).
+     *
+     * @param string $property  Property name (without underscore prefix)
+     * @param mixed $value      Value to set
+     *
+     * @return void
+     */
     public function setProperty($property, $value)
     {
         $prop = '_' . $property;
@@ -597,7 +643,14 @@ public function setProperty($property, $value)
     }
 
     /**
-     * Not part of the interface, implementation detail
+     * Magic setter for internal properties.
+     *
+     * Delegates to setProperty() for underscore-prefixed property access.
+     *
+     * @param string $property  Property name
+     * @param mixed $value      Value to set
+     *
+     * @return void
      */
     public function __set($property, $value)
     {
@@ -609,6 +662,17 @@ public function __set($property, $value)
      */
     public function init(...$params) {}
 
+    /**
+     * Hook called on form submission.
+     *
+     * Override this method in subclasses to perform actions when the form
+     * containing this variable is submitted. This is called after validation
+     * but before data processing.
+     *
+     * @param Horde_Variables $vars  Submitted form variables
+     *
+     * @return void
+     */
     public function onSubmit($vars) {}
 
     /**
diff --git a/src/V3/BooleanVariable.php b/src/V3/BooleanVariable.php
index 4ba19bf..819a656 100644
--- a/src/V3/BooleanVariable.php
+++ b/src/V3/BooleanVariable.php
@@ -10,6 +10,17 @@
  */
 class BooleanVariable extends BaseVariable
 {
+    /**
+     * Validates boolean field value.
+     *
+     * Boolean fields always validate successfully as they can only be
+     * checked or unchecked (on or off). No validation errors are possible.
+     *
+     * @param Horde_Variables $vars  Form variables
+     * @param mixed $value           Field value to validate
+     *
+     * @return bool  Always returns true
+     */
     public function isValid(Horde_Variables $vars, $value): bool
     {
         return true;
diff --git a/src/V3/EmailVariable.php b/src/V3/EmailVariable.php
index 30da6d0..51d2bd1 100644
--- a/src/V3/EmailVariable.php
+++ b/src/V3/EmailVariable.php
@@ -123,13 +123,15 @@ public function isValid(Horde_Variables $vars, $value): bool
     }
 
     /**
-     * Explodes an RFC 2822 string, ignoring a delimiter if preceded
-     * by a "\" character, or if the delimiter is inside single or
-     * double quotes.
+     * Splits RFC 2822 formatted email address string into individual addresses.
      *
-     * @param string $string     The RFC 822 string.
+     * Parses email address lists, handling quoted strings, escape characters,
+     * and group syntax (name:addr1,addr2;). Ignores delimiters inside quotes
+     * or preceded by backslash.
      *
-     * @return array  The exploded string in an array.
+     * @param string $string  The RFC 822 formatted email address string
+     *
+     * @return array  Array of individual email addresses (strings)
      */
     public function splitEmailAddresses($string)
     {
@@ -195,9 +197,14 @@ public function splitEmailAddresses($string)
     }
 
     /**
-     * @param string $email An individual email address to validate.
+     * Validates an email address.
+     *
+     * Performs RFC 3696 validation on the email address. If SMTP checking
+     * is enabled, also attempts SMTP validation.
      *
-     * @return boolean
+     * @param string $email  An individual email address to validate
+     *
+     * @return bool  True if email is valid, false otherwise
      */
     public function validateEmailAddress($email)
     {
@@ -209,11 +216,15 @@ public function validateEmailAddress($email)
     }
 
     /**
-     * Attempt partial delivery of mail to an address to validate it.
+     * Validates email address via SMTP connection.
+     *
+     * Attempts partial mail delivery to validate the email address exists.
+     * Connects to the mail server via SMTP and checks if RCPT TO command
+     * succeeds. Uses MX records if available, falls back to domain A record.
      *
-     * @param string $email An individual email address to validate.
+     * @param string $email  An individual email address to validate
      *
-     * @return boolean
+     * @return bool  True if SMTP server accepts the address, false otherwise
      */
     public function validateEmailAddressSmtp($email)
     {
@@ -270,13 +281,29 @@ public function allowMulti()
     }
 
     /**
-     * RFC3696 Email Parser
+     * Validates email address according to RFC 3696 specification.
+     *
+     * Performs comprehensive RFC 3696 validation including:
+     * - Local part and domain length limits (64 and 255 chars)
+     * - Address format validation (dot-atom, quoted-string, domain-literal)
+     * - Domain literal validation (IPv4 and IPv6 addresses)
+     * - Label validation (length, hyphens, numeric TLD checks)
+     * - Comment stripping and nested comment handling
      *
+     * Implementation uses complex regex patterns built from RFC grammar rules
+     * to validate all address components. Handles obsolete syntax from RFC 2822
+     * and domain literals from RFC 2821.
+     *
+     * RFC3696 Email Parser
      * By Cal Henderson <cal@iamcal.com>
      *
      * This code is dual licensed:
      * CC Attribution-ShareAlike 2.5 - http://creativecommons.org/licenses/by-sa/2.5/
      * GPLv3 - http://www.gnu.org/copyleft/gpl.html
+     *
+     * @param string $email  Email address to validate
+     *
+     * @return int  1 if valid RFC 3696 address, 0 otherwise
      */
     protected function _isRfc3696ValidEmailAddress($email)
     {
@@ -629,8 +656,17 @@ protected function _isRfc3696ValidEmailAddress($email)
     }
 
     /**
-     * RFC3696 Email Parser
+     * Strips RFC 2822 comments from email address string.
+     *
+     * Recursively removes comments matching the provided regex pattern until
+     * no more matches are found. Comments in RFC 2822 format are enclosed in
+     * parentheses and can be nested. This method handles nested comments by
+     * repeatedly applying the regex replacement until the string stabilizes.
      *
+     * Used during RFC 3696 email validation to remove comments from the
+     * local part and domain before performing length and format checks.
+     *
+     * RFC3696 Email Parser
      * By Cal Henderson <cal@iamcal.com>
      *
      * This code is dual licensed:
@@ -638,6 +674,12 @@ protected function _isRfc3696ValidEmailAddress($email)
      * GPLv3 - http://www.gnu.org/copyleft/gpl.html
      *
      * $Revision: 5039 $
+     *
+     * @param string $comment  Regex pattern matching RFC 2822 comment syntax
+     * @param string $email    Email address string to process
+     * @param string $replace  Replacement string for matched comments (default: empty string)
+     *
+     * @return string  Email address with all matching comments removed
      */
     protected function _rfc3696StripComments($comment, $email, $replace = '')
     {
diff --git a/src/V3/FileVariable.php b/src/V3/FileVariable.php
index c980865..907324d 100644
--- a/src/V3/FileVariable.php
+++ b/src/V3/FileVariable.php
@@ -11,6 +11,18 @@
  */
 class FileVariable extends BaseVariable
 {
+    /**
+     * Validates file upload field.
+     *
+     * Checks if a file was successfully uploaded using the browser's upload
+     * detection. Required fields must have a file uploaded. Optional fields
+     * pass validation even without a file.
+     *
+     * @param Horde_Variables $vars  Form variables
+     * @param mixed $value           Field value (not used; checks $_FILES directly)
+     *
+     * @return bool  True if valid, false with error message set if required file missing
+     */
     public function isValid(Horde_Variables $vars, $value): bool
     {
         if ($this->isRequired()) {
diff --git a/src/V3/HourminutesecondVariable.php b/src/V3/HourminutesecondVariable.php
index 436f892..1472976 100644
--- a/src/V3/HourminutesecondVariable.php
+++ b/src/V3/HourminutesecondVariable.php
@@ -42,6 +42,18 @@ public function isValid(Horde_Variables|array $vars, $time): bool
         return true;
     }
 
+    /**
+     * Validates time component values.
+     *
+     * Checks that hour (0-23), minute (0-60), and second (0-60) are within
+     * valid ranges and not empty. All three components must be set.
+     *
+     * @param int|string $hour    Hour value (0-23)
+     * @param int|string $minute  Minute value (0-60)
+     * @param int|string $second  Second value (0-60)
+     *
+     * @return bool  True if all components are valid, false otherwise
+     */
     public function checktime($hour, $minute, $second)
     {
         if (!isset($hour) || $hour == '' || ($hour < 0 || $hour > 23)) {
@@ -107,6 +119,16 @@ public function getTimeParts($time_in)
             'second' => $time->sec];
     }
 
+    /**
+     * Checks if time array is empty.
+     *
+     * A time array is considered empty if hour and minute are not set or have
+     * empty string values. If seconds are shown, second must also be empty.
+     *
+     * @param array|mixed $time  Time array with 'hour', 'minute', 'second' keys
+     *
+     * @return bool  True if time array is empty, false otherwise
+     */
     public function emptyTimeArray($time)
     {
         return (is_array($time)
diff --git a/src/V3/IntVariable.php b/src/V3/IntVariable.php
index d6b0008..100349d 100644
--- a/src/V3/IntVariable.php
+++ b/src/V3/IntVariable.php
@@ -9,6 +9,17 @@
  */
 class IntVariable extends BaseVariable
 {
+    /**
+     * Validates integer field value.
+     *
+     * Checks that the value contains only digits (0-9). Required fields
+     * must have a non-empty value. Empty optional fields pass validation.
+     *
+     * @param Horde_Variables $vars  Form variables
+     * @param mixed $value           Field value to validate
+     *
+     * @return bool  True if valid, false with error message set if invalid
+     */
     public function isValid(Horde_Variables $vars, $value): bool
     {
         if ($this->isRequired() && empty($value) && ((string) (int) $value !== $value)) {
diff --git a/src/V3/MultienumVariable.php b/src/V3/MultienumVariable.php
index 10b502b..dbdf83e 100644
--- a/src/V3/MultienumVariable.php
+++ b/src/V3/MultienumVariable.php
@@ -34,6 +34,18 @@ public function init(...$params)
         parent::init($values);
     }
 
+    /**
+     * Validates multiple selection field value.
+     *
+     * Accepts arrays (multiple selections) or single values. Each selected
+     * value must exist in the configured values list. Required fields must
+     * have at least one selection. Recursively validates array values.
+     *
+     * @param Horde_Variables $vars  Form variables
+     * @param mixed $value           Single value or array of values to validate
+     *
+     * @return bool  True if all values valid, false with error message if invalid
+     */
     public function isValid(Horde_Variables $vars, $value): bool
     {
         if (is_array($value)) {

From ae5d87bdfd8bc608598ecb7f8ce6ff30248863f5 Mon Sep 17 00:00:00 2001
From: Ralf Lang <ralf.lang@ralf-lang.de>
Date: Sun, 8 Mar 2026 08:39:52 +0100
Subject: [PATCH 3/5] docs(api): add @api and @internal tags to V3 methods, add
 missing phpdoc

- Migration interface methods (existed in lib/ with similar signatures)
- V3-native public methods (getProperty, setProperty, init, onSubmit, etc.)

Add @internal tags to 2 protected methods:
- getInfoV3() - Internal extraction method, subclasses override.
  We may want to change that name to something more descriptive going forward.
- isValid() - Internal validation method, subclasses override

All public API methods and all Form Variable Type classes are now marked with @api
for clear interface documentation. Internal implementation details marked with @internal.
---
 src/V3/Action.php                    | 12 ++++
 src/V3/AddressVariable.php           |  2 +
 src/V3/AddresslinkVariable.php       |  2 +
 src/V3/AssignVariable.php            |  6 ++
 src/V3/BaseAction.php                | 16 +++++
 src/V3/BaseForm.php                  | 72 +++++++++++++++++++++
 src/V3/BaseRenderer.php              | 34 ++++++++++
 src/V3/BaseVariable.php              | 94 ++++++++++++++++++++++++++++
 src/V3/BooleanVariable.php           |  4 ++
 src/V3/CaptchaVariable.php           |  2 +
 src/V3/CategoryVariable.php          |  2 +
 src/V3/CellphoneVariable.php         |  2 +
 src/V3/ColorpickerVariable.php       |  2 +
 src/V3/ConditionalenableAction.php   |  2 +
 src/V3/ConditionalsetvalueAction.php |  8 +++
 src/V3/CountedtextVariable.php       |  4 ++
 src/V3/CountryVariable.php           |  4 ++
 src/V3/CreditcardVariable.php        |  2 +
 src/V3/DateVariable.php              |  4 ++
 src/V3/DatetimeVariable.php          |  4 ++
 src/V3/DblookupVariable.php          |  4 ++
 src/V3/DescriptionVariable.php       |  2 +
 src/V3/EmailVariable.php             | 16 +++++
 src/V3/EmailconfirmVariable.php      |  2 +
 src/V3/EnumVariable.php              |  4 ++
 src/V3/FigletVariable.php            |  4 ++
 src/V3/FileVariable.php              |  4 ++
 src/V3/HeaderVariable.php            |  2 +
 src/V3/HourminutesecondVariable.php  | 12 ++++
 src/V3/HtmlRenderer.php              | 26 ++++++++
 src/V3/HtmlVariable.php              |  2 +
 src/V3/ImageVariable.php             | 12 ++++
 src/V3/IntVariable.php               |  4 ++
 src/V3/IntlistVariable.php           |  2 +
 src/V3/InvalidVariable.php           |  4 ++
 src/V3/Ip6addressVariable.php        |  2 +
 src/V3/IpaddressVariable.php         |  2 +
 src/V3/KeyvalMultienumVariable.php   |  2 +
 src/V3/LinkVariable.php              |  4 ++
 src/V3/LongtextVariable.php          |  4 ++
 src/V3/MatrixVariable.php            |  4 ++
 src/V3/MlenumVariable.php            |  4 ++
 src/V3/MonthdayyearVariable.php      | 12 ++++
 src/V3/MonthyearVariable.php         |  4 ++
 src/V3/MultienumVariable.php         |  6 ++
 src/V3/NumberVariable.php            |  4 ++
 src/V3/ObrowserVariable.php          |  2 +
 src/V3/OctalVariable.php             |  2 +
 src/V3/PasswordVariable.php          |  2 +
 src/V3/PasswordconfirmVariable.php   |  2 +
 src/V3/PgpVariable.php               |  4 ++
 src/V3/PhoneVariable.php             |  4 ++
 src/V3/RadioVariable.php             |  2 +
 src/V3/ReloadAction.php              |  2 +
 src/V3/Renderer.php                  | 18 ++++++
 src/V3/SelectfilesVariable.php       |  4 ++
 src/V3/SetVariable.php               |  4 ++
 src/V3/SetcursorposAction.php        |  4 ++
 src/V3/SmimeVariable.php             |  4 ++
 src/V3/SorterVariable.php            |  4 ++
 src/V3/SoundVariable.php             |  4 ++
 src/V3/SpacerVariable.php            |  2 +
 src/V3/StringarrayVariable.php       |  2 +
 src/V3/StringlistVariable.php        |  2 +
 src/V3/SubmitAction.php              |  2 +
 src/V3/SumfieldsAction.php           |  2 +
 src/V3/TablesetVariable.php          |  4 ++
 src/V3/TextVariable.php              |  4 ++
 src/V3/TimeVariable.php              |  2 +
 src/V3/UpdatefieldAction.php         |  6 ++
 70 files changed, 514 insertions(+)

diff --git a/src/V3/Action.php b/src/V3/Action.php
index fdec10b..8742a2d 100644
--- a/src/V3/Action.php
+++ b/src/V3/Action.php
@@ -49,6 +49,8 @@ interface Action
      * Get action trigger events.
      *
      * @return array<string>|null  Event names (e.g., ['onload', 'onchange']) or null
+      *
+      * @api
      */
     public function getTrigger(): ?array;
 
@@ -56,6 +58,8 @@ public function getTrigger(): ?array;
      * Get action ID.
      *
      * @return string  Unique action identifier
+      *
+      * @api
      */
     public function id(): string;
 
@@ -66,6 +70,8 @@ public function id(): string;
      * @param mixed $renderer  The form renderer
      * @param string $varname  Variable name this action applies to
      * @return string  JavaScript code
+      *
+      * @api
      */
     public function getActionScript(Form $form, $renderer, string $varname): string;
 
@@ -73,6 +79,8 @@ public function getActionScript(Form $form, $renderer, string $varname): string;
      * Print JavaScript for this action.
      *
      * Some actions may need to output JavaScript directly.
+      *
+      * @api
      */
     public function printJavaScript(): void;
 
@@ -80,6 +88,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;
 
@@ -90,6 +100,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;
 }
diff --git a/src/V3/AddressVariable.php b/src/V3/AddressVariable.php
index 561f2b3..2d02cd9 100644
--- a/src/V3/AddressVariable.php
+++ b/src/V3/AddressVariable.php
@@ -111,6 +111,8 @@ public function parse($address)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/AddresslinkVariable.php b/src/V3/AddresslinkVariable.php
index 0a2c73f..7a602b7 100644
--- a/src/V3/AddresslinkVariable.php
+++ b/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
     {
diff --git a/src/V3/AssignVariable.php b/src/V3/AssignVariable.php
index d5d7bfb..93b31a3 100644
--- a/src/V3/AssignVariable.php
+++ b/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
     {
diff --git a/src/V3/BaseAction.php b/src/V3/BaseAction.php
index 391e572..d1892f0 100644
--- a/src/V3/BaseAction.php
+++ b/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
     {
diff --git a/src/V3/BaseForm.php b/src/V3/BaseForm.php
index bb85774..28c8aa0 100644
--- a/src/V3/BaseForm.php
+++ b/src/V3/BaseForm.php
@@ -149,6 +149,8 @@ class BaseForm implements \Horde\Form\Form
      * @param Horde_Variables|ServerRequestInterface|array $vars  Form data
      * @param string $title  Form display title
      * @param string|null $name  Form name (auto-generated from class if null)
+      *
+      * @api
      */
     public function __construct(
         Horde_Variables|ServerRequestInterface|array $vars,
@@ -177,6 +179,8 @@ public function __construct(
      *
      * @param Horde_Variables|ServerRequestInterface|array $vars
      * @return array<string, mixed>
+      *
+      * @internal
      */
     private function normalizeVars(
         Horde_Variables|ServerRequestInterface|array $vars
@@ -194,6 +198,8 @@ private function normalizeVars(
      * Returns a copy to prevent external mutation.
      *
      * @return array<string, mixed>
+      *
+      * @api
      */
     public function getVars(): array
     {
@@ -206,6 +212,8 @@ public function getVars(): array
      * Replaces all form data. Accepts same types as constructor.
      *
      * @param Horde_Variables|ServerRequestInterface|array $vars
+      *
+      * @api
      */
     public function setVars(Horde_Variables|ServerRequestInterface|array $vars): void
     {
@@ -218,6 +226,8 @@ public function setVars(Horde_Variables|ServerRequestInterface|array $vars): voi
      * @param string $name  Variable name
      * @param mixed $default  Default value if not set
      * @return mixed  Variable value or default
+      *
+      * @api
      */
     public function getVar(string $name, mixed $default = null): mixed
     {
@@ -231,6 +241,8 @@ public function getVar(string $name, mixed $default = null): mixed
      *
      * @param string $name  Variable name
      * @param mixed $value  Variable value
+      *
+      * @api
      */
     public function setVar(string $name, mixed $value): void
     {
@@ -239,6 +251,8 @@ public function setVar(string $name, mixed $value): void
 
     /**
      * Get form title.
+      *
+      * @api
      */
     public function getTitle(): string
     {
@@ -247,6 +261,8 @@ public function getTitle(): string
 
     /**
      * Set form title.
+      *
+      * @api
      */
     public function setTitle(string $title): void
     {
@@ -255,6 +271,8 @@ public function setTitle(string $title): void
 
     /**
      * Get extra form content.
+      *
+      * @api
      */
     public function getExtra(): string
     {
@@ -263,6 +281,8 @@ public function getExtra(): string
 
     /**
      * Set extra form content (HTML, etc.).
+      *
+      * @api
      */
     public function setExtra(string $extra): void
     {
@@ -271,6 +291,8 @@ public function setExtra(string $extra): void
 
     /**
      * Get form name.
+      *
+      * @api
      */
     public function getName(): string
     {
@@ -282,6 +304,8 @@ public function getName(): string
      *
      * @param bool|null $token  If specified, sets whether to use tokens
      * @return bool  Current token usage setting
+      *
+      * @api
      */
     public function useToken(?bool $token = null): bool
     {
@@ -300,6 +324,8 @@ public function useToken(?bool $token = null): bool
      * @param string $desc  Section description
      * @param string $image  Section icon/image URL
      * @param bool $expanded  Whether section starts expanded
+      *
+      * @api
      */
     public function setSection(
         string|int $section = '',
@@ -321,6 +347,8 @@ public function setSection(
 
     /**
      * Get section description.
+      *
+      * @api
      */
     public function getSectionDesc(string|int $section): string
     {
@@ -329,6 +357,8 @@ public function getSectionDesc(string|int $section): string
 
     /**
      * Get section image/icon URL.
+      *
+      * @api
      */
     public function getSectionImage(string|int $section): string
     {
@@ -339,6 +369,8 @@ public function getSectionImage(string|int $section): string
      * Set which section is currently open.
      *
      * @param string|int $section  Section identifier
+      *
+      * @api
      */
     public function setOpenSection(string|int $section): void
     {
@@ -349,6 +381,8 @@ public function setOpenSection(string|int $section): void
      * Get which section is currently open.
      *
      * @return string|int|null  Open section identifier or null
+      *
+      * @api
      */
     public function getOpenSection(): string|int|null
     {
@@ -361,6 +395,8 @@ public function getOpenSection(): string|int|null
      * @param string|int $section  Section identifier
      * @param bool $boolean  If true, return bool; if false, return CSS value
      * @return bool|string  Expanded state as bool or 'block'/'none' for CSS
+      *
+      * @api
      */
     public function getSectionExpandedState(string|int $section, bool $boolean = false): bool|string
     {
@@ -386,6 +422,8 @@ public function getSectionExpandedState(string|int $section, bool $boolean = fal
      * @param string|null $description  Field description/help text
      * @param array $params  Type-specific parameters (e.g., enum values)
      * @return Variable  The created variable instance
+      *
+      * @api
      */
     public function addVariable(
         string $humanName,
@@ -422,6 +460,8 @@ public function addVariable(
      * @param string|null $description  Field description/help text
      * @param array $params  Type-specific parameters
      * @return Variable  The created variable instance
+      *
+      * @api
      */
     public function insertVariableBefore(
         ?string $before,
@@ -514,6 +554,8 @@ public function insertVariableBefore(
      * @param string|null $description  Field description
      * @param array $params  Type-specific parameters
      * @return Variable  Created variable instance
+      *
+      * @internal
      */
     private function createVariable(
         string $humanName,
@@ -559,6 +601,8 @@ private function createVariable(
      *
      * @param Variable|string $var  Variable instance or variable name
      * @return bool  True if variable was found and removed
+      *
+      * @api
      */
     public function removeVariable(Variable|string $var): bool
     {
@@ -591,6 +635,8 @@ public function removeVariable(Variable|string $var): bool
      * @param string|null $description  Field description
      * @param array $params  Type-specific parameters
      * @return Variable  The created variable instance
+      *
+      * @api
      */
     public function addHidden(
         string $humanName,
@@ -623,6 +669,8 @@ public function addHidden(
      * @param bool $flat  If true, return flat array; if false, return by section
      * @param bool $withHidden  If true, include hidden variables
      * @return array<Variable>|array<string, array<Variable>>
+      *
+      * @api
      */
     public function getVariables(bool $flat = true, bool $withHidden = false): array
     {
@@ -649,6 +697,8 @@ public function getVariables(bool $flat = true, bool $withHidden = false): array
      *
      * @param array<string>|string|bool $submit  Submit button label(s) or true for default
      * @param string|bool $reset  Reset button label or false for none
+      *
+      * @api
      */
     public function setButtons(array|string|bool $submit, string|bool $reset = false): void
     {
@@ -671,6 +721,8 @@ public function setButtons(array|string|bool $submit, string|bool $reset = false
      * Append additional submit buttons.
      *
      * @param array<string>|string $submit  Button label(s) to append
+      *
+      * @api
      */
     public function appendButtons(array|string $submit): void
     {
@@ -688,6 +740,8 @@ public function appendButtons(array|string $submit): void
      *
      * @param mixed $vars  Optional variables to validate against (null = use form's vars)
      * @return bool  True if validation passed, false if errors exist
+      *
+      * @api
      */
     public function validate($vars = null): bool
     {
@@ -734,6 +788,8 @@ public function validate($vars = null): bool
      * Must call validate() first.
      *
      * @return bool  True if no validation errors exist
+      *
+      * @api
      */
     public function isValid(): bool
     {
@@ -744,6 +800,8 @@ public function isValid(): bool
      * Get validation errors.
      *
      * @return array<string, string>  Map of variable name => error message
+      *
+      * @api
      */
     public function getErrors(): array
     {
@@ -755,6 +813,8 @@ public function getErrors(): array
      *
      * @param string $varName  Variable name
      * @return string|null  Error message or null if no error
+      *
+      * @api
      */
     public function getError(string $varName): ?string
     {
@@ -766,6 +826,8 @@ public function getError(string $varName): ?string
      *
      * @param string $varName  Variable name
      * @param string $message  Error message
+      *
+      * @api
      */
     public function setError(string $varName, string $message): void
     {
@@ -776,6 +838,8 @@ public function setError(string $varName, string $message): void
      * Clear all errors or error for specific variable.
      *
      * @param string|null $varName  Variable name to clear (null = clear all)
+      *
+      * @api
      */
     public function clearError(?string $varName = null): void
     {
@@ -793,6 +857,8 @@ public function clearError(?string $varName = null): void
      *
      * @param mixed $vars  Optional variables to extract from (null = use form's vars)
      * @return array<string, mixed>  Associative array of field name => value
+      *
+      * @api
      */
     public function getInfo($vars = null): array
     {
@@ -817,6 +883,8 @@ public function getInfo($vars = null): array
      * @param array<Variable> $variables  Variables to extract from
      * @param array $vars  Variable data
      * @return array<string, mixed>  Extracted field values
+      *
+      * @internal
      */
     private function getInfoFromVariables(array $variables, array $vars): array
     {
@@ -848,6 +916,8 @@ private function getInfoFromVariables(array $variables, array $vars): array
      * Check if form has been submitted.
      *
      * @return bool  True if form was submitted
+      *
+      * @api
      */
     public function isSubmitted(): bool
     {
@@ -867,6 +937,8 @@ public function isSubmitted(): bool
      * Get form encoding type.
      *
      * @return string|null  Encoding type (e.g., 'multipart/form-data') or null
+      *
+      * @api
      */
     public function getEnctype(): ?string
     {
diff --git a/src/V3/BaseRenderer.php b/src/V3/BaseRenderer.php
index d31216f..428c061 100644
--- a/src/V3/BaseRenderer.php
+++ b/src/V3/BaseRenderer.php
@@ -105,6 +105,8 @@ abstract class BaseRenderer implements Renderer
      * @param ErrorRenderer|null $errorRenderer  Error renderer
      * @param AssetManager|null $assetManager  Asset manager
      * @param array<string, mixed> $config  Configuration options
+      *
+      * @api
      */
     public function __construct(
         ?ControlRenderer $controlRenderer = null,
@@ -169,6 +171,8 @@ abstract protected function createDefaultAssetManager(): AssetManager;
      * Render the complete form.
      *
      * Template method - defines the rendering flow.
+      *
+      * @api
      */
     public function render(Form $form, string $action = '', string $method = 'post'): string
     {
@@ -233,6 +237,8 @@ public function render(Form $form, string $action = '', string $method = 'post')
      * @param array<Variable> $variables  Variables to render
      * @param Form $form  Parent form
      * @return string  Rendered variables
+      *
+      * @internal
      */
     protected function renderVariables(array $variables, Form $form): string
     {
@@ -245,6 +251,8 @@ protected function renderVariables(array $variables, Form $form): string
 
     /**
      * Render a single variable.
+      *
+      * @api
      */
     public function renderVariable(Variable $variable, Form $form): string
     {
@@ -281,6 +289,8 @@ public function renderVariable(Variable $variable, Form $form): string
 
     /**
      * Render a form section.
+      *
+      * @api
      */
     public function renderSection(string|int $sectionName, array $variables, Form $form): string
     {
@@ -299,6 +309,8 @@ public function renderSection(string|int $sectionName, array $variables, Form $f
 
     /**
      * Render validation errors.
+      *
+      * @api
      */
     public function renderErrors(Form $form): string
     {
@@ -312,6 +324,8 @@ public function renderErrors(Form $form): string
 
     /**
      * Render hidden fields.
+      *
+      * @api
      */
     public function renderHidden(Form $form): string
     {
@@ -345,6 +359,8 @@ public function renderHidden(Form $form): string
      * Get CSS class for current row (for striped rows).
      *
      * @return string  CSS class
+      *
+      * @internal
      */
     protected function getRowClass(): string
     {
@@ -362,6 +378,8 @@ protected function getRowClass(): string
      * @param array<string, mixed> $attrs  Attributes (null values are skipped)
      * @param string|null $content  Tag content (null = self-closing)
      * @return string  HTML tag
+      *
+      * @internal
      */
     protected function buildTag(string $tag, array $attrs = [], ?string $content = null): string
     {
@@ -387,6 +405,8 @@ protected function buildTag(string $tag, array $attrs = [], ?string $content = n
 
     /**
      * Set whether to show form header.
+      *
+      * @api
      */
     public function setShowHeader(bool $show): void
     {
@@ -395,6 +415,8 @@ public function setShowHeader(bool $show): void
 
     /**
      * Set required field marker.
+      *
+      * @api
      */
     public function setRequiredMarker(string $marker): void
     {
@@ -403,6 +425,8 @@ public function setRequiredMarker(string $marker): void
 
     /**
      * Set help text marker.
+      *
+      * @api
      */
     public function setHelpMarker(string $marker): void
     {
@@ -411,6 +435,8 @@ public function setHelpMarker(string $marker): void
 
     /**
      * Set whether to encode form title.
+      *
+      * @api
      */
     public function setEncodeTitle(bool $encode): void
     {
@@ -419,6 +445,8 @@ public function setEncodeTitle(bool $encode): void
 
     /**
      * Get control renderer.
+      *
+      * @api
      */
     public function getControlRenderer(): ControlRenderer
     {
@@ -427,6 +455,8 @@ public function getControlRenderer(): ControlRenderer
 
     /**
      * Get layout strategy.
+      *
+      * @api
      */
     public function getLayoutStrategy(): LayoutStrategy
     {
@@ -435,6 +465,8 @@ public function getLayoutStrategy(): LayoutStrategy
 
     /**
      * Get error renderer.
+      *
+      * @api
      */
     public function getErrorRenderer(): ErrorRenderer
     {
@@ -443,6 +475,8 @@ public function getErrorRenderer(): ErrorRenderer
 
     /**
      * Get asset manager.
+      *
+      * @api
      */
     public function getAssetManager(): AssetManager
     {
diff --git a/src/V3/BaseVariable.php b/src/V3/BaseVariable.php
index 049f5c5..76a1aa7 100644
--- a/src/V3/BaseVariable.php
+++ b/src/V3/BaseVariable.php
@@ -128,11 +128,29 @@ class BaseVariable implements Variable
      */
     protected string $message = '';
 
+    /**
+     * Returns the validation error message.
+     *
+     * @return string  The validation error message
+     *
+     * @api
+     */
     public function getMessage()
     {
         return $this->message;
     }
 
+    /**
+     * Creates a new form variable.
+     *
+     * @param string $humanName    Short description of the variable's purpose
+     * @param string $varName      Internally used variable name
+     * @param bool $required       Whether this is a required variable
+     * @param bool $readonly       Whether this is a readonly variable
+     * @param string|null $description  Long description, special instructions, etc.
+     *
+     * @api
+     */
     public function __construct(
         $humanName,
         $varName,
@@ -153,6 +171,8 @@ public function __construct(
      * Assign this variable to the specified form.
      *
      * @param Horde_Form $form  The form instance to assign this variable to.
+      *
+      * @api
      */
     public function setFormOb($form)
     {
@@ -163,6 +183,8 @@ public function setFormOb($form)
      * Sets a default value for this variable.
      *
      * @param mixed $value  A variable value.
+      *
+      * @api
      */
     public function setDefault($value)
     {
@@ -173,6 +195,8 @@ public function setDefault($value)
      * Returns this variable's default value.
      *
      * @return mixed  This variable's default value.
+      *
+      * @api
      */
     public function getDefault()
     {
@@ -189,6 +213,8 @@ public function getDefault()
      * ```
      *
      * @param Action $action  An {@link Action} instance.
+      *
+      * @api
      */
     public function setAction($action)
     {
@@ -199,6 +225,8 @@ public function setAction($action)
      * Returns whether this variable has an attached action.
      *
      * @return boolean  True if this variable has an attached action.
+      *
+      * @api
      */
     public function hasAction()
     {
@@ -207,6 +235,8 @@ public function hasAction()
 
     /**
      * Makes this a hidden variable.
+      *
+      * @api
      */
     public function hide()
     {
@@ -217,6 +247,8 @@ public function hide()
      * Returns whether this is a hidden variable.
      *
      * @return boolean  True if this a hidden variable.
+      *
+      * @api
      */
     public function isHidden()
     {
@@ -230,6 +262,8 @@ public function isHidden()
      * during form processing and validation.
      *
      * @return void
+      *
+      * @api
      */
     public function disable()
     {
@@ -240,6 +274,8 @@ public function disable()
      * Returns whether this variable is disabled.
      *
      * @return boolean  True if this variable is disabled.
+      *
+      * @api
      */
     public function isDisabled()
     {
@@ -250,6 +286,8 @@ public function isDisabled()
      * Return the short description of this variable.
      *
      * @return string  A short description
+      *
+      * @api
      */
     public function getHumanName()
     {
@@ -260,6 +298,8 @@ public function getHumanName()
      * Returns the internally used variable name.
      *
      * @return string  This variable's internal name.
+      *
+      * @api
      */
     public function getVarName()
     {
@@ -285,6 +325,8 @@ public function getType()
      * @return string  This variable's {@link Horde_Form_Type} name.
      *
      * Override with a simple return 'literal' string in your own types.
+      *
+      * @api
      */
     public function getTypeName(): string
     {
@@ -295,6 +337,8 @@ public function getTypeName(): string
      * Returns whether this is a required variable.
      *
      * @return boolean  True if this is a required variable.
+      *
+      * @api
      */
     public function isRequired()
     {
@@ -305,6 +349,8 @@ public function isRequired()
      * Returns whether this is a readonly variable.
      *
      * @return boolean  True if this a readonly variable.
+      *
+      * @api
      */
     public function isReadonly()
     {
@@ -315,6 +361,8 @@ public function isReadonly()
      * Returns the possible values of this variable.
      *
      * @return array  The possible values of this variable or null.
+      *
+      * @api
      */
     public function getValues(...$params): ?array
     {
@@ -325,6 +373,8 @@ public function getValues(...$params): ?array
      * Returns whether this variable has a long description.
      *
      * @return boolean  True if this variable has a long description.
+      *
+      * @api
      */
     public function hasDescription(): bool
     {
@@ -335,6 +385,8 @@ public function hasDescription(): bool
      * Returns this variable's long description.
      *
      * @return string  This variable's long description.
+      *
+      * @api
      */
     public function getDescription()
     {
@@ -345,6 +397,8 @@ public function getDescription()
      * Returns whether this is an array variable.
      *
      * @return boolean  True if this an array variable.
+      *
+      * @api
      */
     public function isArrayVal()
     {
@@ -355,6 +409,8 @@ public function isArrayVal()
      * Returns whether this variable is to upload a file.
      *
      * @return boolean  True if variable is to upload a file.
+      *
+      * @api
      */
     public function isUpload()
     {
@@ -365,6 +421,8 @@ public function isUpload()
      * Assigns a help text to this variable.
      *
      * @param string $help  The variable help text.
+      *
+      * @api
      */
     public function setHelp($help)
     {
@@ -376,6 +434,8 @@ public function setHelp($help)
      * Returns whether this variable has some help text assigned.
      *
      * @return boolean  True if this variable has a help text.
+      *
+      * @api
      */
     public function hasHelp()
     {
@@ -386,6 +446,8 @@ public function hasHelp()
      * Returns the help text of this variable.
      *
      * @return string  This variable's help text.
+      *
+      * @api
      */
     public function getHelp()
     {
@@ -397,6 +459,8 @@ public function getHelp()
      *
      * @param string $option  The option name.
      * @param mixed $val      The option's value.
+      *
+      * @api
      */
     public function setOption($option, $val)
     {
@@ -409,6 +473,8 @@ public function setOption($option, $val)
      * @param string $option  The option name.
      *
      * @return mixed          The option's value.
+      *
+      * @api
      */
     public function getOption($option)
     {
@@ -435,6 +501,8 @@ public function getOption($option)
      * @param mixed ...$args  Ignored (for interface compatibility)
      * @return mixed  The variable value
      * @deprecated The second parameter ($info) is deprecated/ignored
+      *
+      * @api
      */
     public function getInfo($vars, ...$args) {
         if (count($args) > 0) {
@@ -443,6 +511,18 @@ public function getInfo($vars, ...$args) {
         return $this->getInfoV3($vars);
     }
 
+    /**
+     * Extract variable value from form variables.
+     *
+     * Internal method used by getInfo() wrapper. Subclasses override this
+     * to provide type-specific value extraction logic.
+     *
+     * @param Horde_Variables $vars  Form variables
+     *
+     * @return mixed  Extracted value
+     *
+     * @internal
+     */
     //TODO: Rename back to getInfo() after the V3 transition
     protected function getInfoV3($vars)
     {
@@ -459,6 +539,8 @@ protected function getInfoV3($vars)
      * @return ?boolean Null if this variable doesn't have the "trackchange"
      *                  option set or the form wasn't submitted yet. A boolean
      *                  indicating whether the variable was changed otherwise.
+      *
+      * @api
      */
     public function wasChanged($vars)
     {
@@ -479,6 +561,8 @@ public function wasChanged($vars)
      *                         form.
      *
      * @return boolean  True if the variable validated.
+      *
+      * @api
      */
     public function validate($vars, ...$args)
     {
@@ -596,6 +680,8 @@ public static function Deprecated($message, $level = 2) {
      * @param string $property  Property name (without underscore prefix)
      *
      * @return mixed  Property value, or null if not set
+      *
+      * @api
      */
     public function getProperty($property)
     {
@@ -635,6 +721,8 @@ public function __get($property)
      * @param mixed $value      Value to set
      *
      * @return void
+      *
+      * @api
      */
     public function setProperty($property, $value)
     {
@@ -659,6 +747,8 @@ public function __set($property, $value)
 
     /**
      * Initialize (kind of constructor) - Parameter list may vary on overloading
+      *
+      * @api
      */
     public function init(...$params) {}
 
@@ -672,11 +762,15 @@ public function init(...$params) {}
      * @param Horde_Variables $vars  Submitted form variables
      *
      * @return void
+      *
+      * @api
      */
     public function onSubmit($vars) {}
 
     /**
      * Use $this->getMessage() to retrieve error messages.
+      *
+      * @internal
      */
     protected function isValid(Horde_Variables $vars, $value): bool
     {
diff --git a/src/V3/BooleanVariable.php b/src/V3/BooleanVariable.php
index 819a656..d865c95 100644
--- a/src/V3/BooleanVariable.php
+++ b/src/V3/BooleanVariable.php
@@ -20,6 +20,8 @@ class BooleanVariable extends BaseVariable
      * @param mixed $value           Field value to validate
      *
      * @return bool  Always returns true
+      *
+      * @api
      */
     public function isValid(Horde_Variables $vars, $value): bool
     {
@@ -34,6 +36,8 @@ protected function getInfoV3($vars)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/CaptchaVariable.php b/src/V3/CaptchaVariable.php
index 7697c4f..d904039 100644
--- a/src/V3/CaptchaVariable.php
+++ b/src/V3/CaptchaVariable.php
@@ -14,6 +14,8 @@ class CaptchaVariable extends FigletVariable
 {
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/CategoryVariable.php b/src/V3/CategoryVariable.php
index 4465df0..db1bac7 100644
--- a/src/V3/CategoryVariable.php
+++ b/src/V3/CategoryVariable.php
@@ -39,6 +39,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/CellphoneVariable.php b/src/V3/CellphoneVariable.php
index d215443..5c0efd2 100644
--- a/src/V3/CellphoneVariable.php
+++ b/src/V3/CellphoneVariable.php
@@ -13,6 +13,8 @@ class CellphoneVariable extends PhoneVariable
 {
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/ColorpickerVariable.php b/src/V3/ColorpickerVariable.php
index d30302a..4bf378d 100644
--- a/src/V3/ColorpickerVariable.php
+++ b/src/V3/ColorpickerVariable.php
@@ -24,6 +24,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/ConditionalenableAction.php b/src/V3/ConditionalenableAction.php
index f9abfe2..84822f9 100644
--- a/src/V3/ConditionalenableAction.php
+++ b/src/V3/ConditionalenableAction.php
@@ -64,6 +64,8 @@ class ConditionalenableAction extends BaseAction
      * @param mixed $renderer  The form renderer
      * @param string $varname  Variable name this action applies to
      * @return string  JavaScript code
+      *
+      * @api
      */
     public function getActionScript(\Horde\Form\Form $form, $renderer, string $varname): string
     {
diff --git a/src/V3/ConditionalsetvalueAction.php b/src/V3/ConditionalsetvalueAction.php
index c09c14f..63e44ca 100644
--- a/src/V3/ConditionalsetvalueAction.php
+++ b/src/V3/ConditionalsetvalueAction.php
@@ -71,6 +71,8 @@ class ConditionalsetvalueAction extends BaseAction
      * @param mixed $renderer  The form renderer
      * @param string $varname  Variable name this action applies to
      * @return string  JavaScript code
+      *
+      * @api
      */
     public function getActionScript(\Horde\Form\Form $form, $renderer, string $varname): string
     {
@@ -89,6 +91,8 @@ public function getActionScript(\Horde\Form\Form $form, $renderer, string $varna
      * @param \Horde_Variables $vars  The variables object
      * @param mixed $sourceVal  The source value
      * @param bool $arrayVal  Whether dealing with array values
+      *
+      * @api
      */
     public function setValues(\Horde_Variables $vars, $sourceVal, bool $arrayVal = false): void
     {
@@ -120,6 +124,8 @@ public function setValues(\Horde_Variables $vars, $sourceVal, bool $arrayVal = f
      * Print JavaScript code for this action.
      *
      * @return string  JavaScript code
+      *
+      * @api
      */
     public function printJavaScript(): string
     {
@@ -181,6 +187,8 @@ function mapValue_{$this->id}(sourceId, targetId) {
      * @param mixed $renderer  The renderer
      * @param string $varname  Variable name
      * @return string  Field ID
+      *
+      * @internal
      */
     protected function getFieldId($renderer, string $varname): string
     {
diff --git a/src/V3/CountedtextVariable.php b/src/V3/CountedtextVariable.php
index 5a4bd53..39e2f2d 100644
--- a/src/V3/CountedtextVariable.php
+++ b/src/V3/CountedtextVariable.php
@@ -27,6 +27,8 @@ class CountedtextVariable extends LongtextVariable
      *                      - $params[0]: int $rows - Number of rows (default: 8, from parent)
      *                      - $params[1]: int $cols - Number of columns (default: 80, from parent)
      *                      - $params[2]: int $chars - Maximum number of characters (default: 1000)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -56,6 +58,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/CountryVariable.php b/src/V3/CountryVariable.php
index a3ece77..d614c8b 100644
--- a/src/V3/CountryVariable.php
+++ b/src/V3/CountryVariable.php
@@ -18,6 +18,8 @@ class CountryVariable extends EnumVariable
      *
      * @param array $params Variable arguments:
      *                      - $params[0]: string|bool|null $prompt - Prompt text for selection
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -28,6 +30,8 @@ public function init(...$params)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/CreditcardVariable.php b/src/V3/CreditcardVariable.php
index 228909e..8c3fbb8 100644
--- a/src/V3/CreditcardVariable.php
+++ b/src/V3/CreditcardVariable.php
@@ -99,6 +99,8 @@ public static function getCardType(string $ccnum)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/DateVariable.php b/src/V3/DateVariable.php
index 95cae47..9f2db86 100644
--- a/src/V3/DateVariable.php
+++ b/src/V3/DateVariable.php
@@ -20,6 +20,8 @@ class DateVariable extends BaseVariable
      *
      * @param array $params Variable arguments:
      *                      - $params[0]: string $format - The date format string (default: '%a %d %B')
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -93,6 +95,8 @@ public function getFormattedTime($timestamp, $format = null, $showago = true)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/DatetimeVariable.php b/src/V3/DatetimeVariable.php
index 5f0c128..db52bf3 100644
--- a/src/V3/DatetimeVariable.php
+++ b/src/V3/DatetimeVariable.php
@@ -29,6 +29,8 @@ class DatetimeVariable extends BaseVariable
      *                      - $params[3]: string|null $format_in - The format to use when sending the date for storage. Defaults to Unix epoch. Similar to the strftime() function. (default: null)
      *                      - $params[4]: string $format_out - The format to use when displaying the date. Similar to the strftime() function. (default: '%x')
      *                      - $params[5]: bool $show_seconds - Include a form input for seconds (default: false)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -160,6 +162,8 @@ public function formatDate($date)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/DblookupVariable.php b/src/V3/DblookupVariable.php
index 6fe1768..af29817 100644
--- a/src/V3/DblookupVariable.php
+++ b/src/V3/DblookupVariable.php
@@ -20,6 +20,8 @@ class DblookupVariable extends EnumVariable
      *                      - $params[0]: Horde_Db_Adapter $db - Database adapter instance
      *                      - $params[1]: string $sql - SQL statement for value lookups
      *                      - $params[2]: string|null $prompt - Prompt text (optional)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -39,6 +41,8 @@ public function init(...$params)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/DescriptionVariable.php b/src/V3/DescriptionVariable.php
index 27fb8ac..0d7140f 100644
--- a/src/V3/DescriptionVariable.php
+++ b/src/V3/DescriptionVariable.php
@@ -16,6 +16,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/EmailVariable.php b/src/V3/EmailVariable.php
index 51d2bd1..c46be84 100644
--- a/src/V3/EmailVariable.php
+++ b/src/V3/EmailVariable.php
@@ -76,6 +76,8 @@ class EmailVariable extends BaseVariable
      *                      - $params[3]: string|null $link_name - The name to use when linking to the compose page (default: null)
      *                      - $params[4]: string $delimiters - Character to split multiple addresses with (default: ',')
      *                      - $params[5]: int|null $size - The size of the input field (default: null)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -88,6 +90,8 @@ public function init(...$params)
     }
 
     /**
+      *
+      * @api
      */
     public function isValid(Horde_Variables $vars, $value): bool
     {
@@ -132,6 +136,8 @@ public function isValid(Horde_Variables $vars, $value): bool
      * @param string $string  The RFC 822 formatted email address string
      *
      * @return array  Array of individual email addresses (strings)
+      *
+      * @api
      */
     public function splitEmailAddresses($string)
     {
@@ -205,6 +211,8 @@ public function splitEmailAddresses($string)
      * @param string $email  An individual email address to validate
      *
      * @return bool  True if email is valid, false otherwise
+      *
+      * @api
      */
     public function validateEmailAddress($email)
     {
@@ -225,6 +233,8 @@ public function validateEmailAddress($email)
      * @param string $email  An individual email address to validate
      *
      * @return bool  True if SMTP server accepts the address, false otherwise
+      *
+      * @api
      */
     public function validateEmailAddressSmtp($email)
     {
@@ -304,6 +314,8 @@ public function allowMulti()
      * @param string $email  Email address to validate
      *
      * @return int  1 if valid RFC 3696 address, 0 otherwise
+      *
+      * @internal
      */
     protected function _isRfc3696ValidEmailAddress($email)
     {
@@ -680,6 +692,8 @@ protected function _isRfc3696ValidEmailAddress($email)
      * @param string $replace  Replacement string for matched comments (default: empty string)
      *
      * @return string  Email address with all matching comments removed
+      *
+      * @internal
      */
     protected function _rfc3696StripComments($comment, $email, $replace = '')
     {
@@ -694,6 +708,8 @@ protected function _rfc3696StripComments($comment, $email, $replace = '')
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/EmailconfirmVariable.php b/src/V3/EmailconfirmVariable.php
index d82697b..e3ec01a 100644
--- a/src/V3/EmailconfirmVariable.php
+++ b/src/V3/EmailconfirmVariable.php
@@ -34,6 +34,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/EnumVariable.php b/src/V3/EnumVariable.php
index 78c5a5a..527e403 100644
--- a/src/V3/EnumVariable.php
+++ b/src/V3/EnumVariable.php
@@ -22,6 +22,8 @@ class EnumVariable extends BaseVariable
      * @param array $params Variable arguments:
      *                      - $params[0]: array $values - A hash map where the key is the internal 'value' to process and the value is the caption presented to the user
      *                      - $params[1]: string|bool $prompt - A null value text to prompt user selecting a value. Use a default if boolean true, else use the supplied string. No prompt on false.
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -64,6 +66,8 @@ public function getPrompt()
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/FigletVariable.php b/src/V3/FigletVariable.php
index 565aab9..de04689 100644
--- a/src/V3/FigletVariable.php
+++ b/src/V3/FigletVariable.php
@@ -22,6 +22,8 @@ class FigletVariable extends BaseVariable
      * @param array $params Variable arguments:
      *                      - $params[0]: string $text - The CAPTCHA text
      *                      - $params[1]: string $font - The Figlet font to use
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -54,6 +56,8 @@ public function getText()
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/FileVariable.php b/src/V3/FileVariable.php
index 907324d..8d48f56 100644
--- a/src/V3/FileVariable.php
+++ b/src/V3/FileVariable.php
@@ -22,6 +22,8 @@ class FileVariable extends BaseVariable
      * @param mixed $value           Field value (not used; checks $_FILES directly)
      *
      * @return bool  True if valid, false with error message set if required file missing
+      *
+      * @api
      */
     public function isValid(Horde_Variables $vars, $value): bool
     {
@@ -58,6 +60,8 @@ protected function getInfoV3($vars)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/HeaderVariable.php b/src/V3/HeaderVariable.php
index 5ae15a6..e1d4dc8 100644
--- a/src/V3/HeaderVariable.php
+++ b/src/V3/HeaderVariable.php
@@ -16,6 +16,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/HourminutesecondVariable.php b/src/V3/HourminutesecondVariable.php
index 1472976..5695c2b 100644
--- a/src/V3/HourminutesecondVariable.php
+++ b/src/V3/HourminutesecondVariable.php
@@ -19,6 +19,8 @@ class HourminutesecondVariable extends BaseVariable
      *
      * @param array $params Variable arguments:
      *                      - $params[0]: bool $show_seconds - Include a form input for seconds (default: false)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -53,6 +55,8 @@ public function isValid(Horde_Variables|array $vars, $time): bool
      * @param int|string $second  Second value (0-60)
      *
      * @return bool  True if all components are valid, false otherwise
+      *
+      * @api
      */
     public function checktime($hour, $minute, $second)
     {
@@ -80,6 +84,8 @@ public function checktime($hour, $minute, $second)
      *                         UNIX epoch).
      *
      * @return Horde_Date  The time object.
+      *
+      * @api
      */
     public function getTimeOb($time_in)
     {
@@ -101,6 +107,8 @@ public function getTimeOb($time_in)
      *                         UNIX epoch).
      *
      * @return array  Array with three elements - hour, minute and seconds.
+      *
+      * @api
      */
     public function getTimeParts($time_in)
     {
@@ -128,6 +136,8 @@ public function getTimeParts($time_in)
      * @param array|mixed $time  Time array with 'hour', 'minute', 'second' keys
      *
      * @return bool  True if time array is empty, false otherwise
+      *
+      * @api
      */
     public function emptyTimeArray($time)
     {
@@ -139,6 +149,8 @@ public function emptyTimeArray($time)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/HtmlRenderer.php b/src/V3/HtmlRenderer.php
index 18f6321..e380305 100644
--- a/src/V3/HtmlRenderer.php
+++ b/src/V3/HtmlRenderer.php
@@ -68,6 +68,8 @@ class HtmlRenderer extends BaseRenderer
      * @param ErrorRenderer|null $errorRenderer  Error renderer
      * @param AssetManager|null $assetManager  Asset manager
      * @param array<string, mixed> $config  Configuration options
+      *
+      * @api
      */
     public function __construct(
         ?ControlRenderer $controlRenderer = null,
@@ -93,6 +95,8 @@ public function __construct(
 
     /**
      * Create default control renderer.
+      *
+      * @internal
      */
     protected function createDefaultControlRenderer(): ControlRenderer
     {
@@ -107,6 +111,8 @@ protected function createDefaultControlRenderer(): ControlRenderer
 
     /**
      * Create default layout strategy.
+      *
+      * @internal
      */
     protected function createDefaultLayoutStrategy(): LayoutStrategy
     {
@@ -115,6 +121,8 @@ protected function createDefaultLayoutStrategy(): LayoutStrategy
 
     /**
      * Create default error renderer.
+      *
+      * @internal
      */
     protected function createDefaultErrorRenderer(): ErrorRenderer
     {
@@ -123,6 +131,8 @@ protected function createDefaultErrorRenderer(): ErrorRenderer
 
     /**
      * Create default asset manager.
+      *
+      * @internal
      */
     protected function createDefaultAssetManager(): AssetManager
     {
@@ -131,6 +141,8 @@ protected function createDefaultAssetManager(): AssetManager
 
     /**
      * Render form opening tag.
+      *
+      * @api
      */
     public function renderOpen(\Horde\Form\Form $form, string $action, string $method): string
     {
@@ -153,6 +165,8 @@ public function renderOpen(\Horde\Form\Form $form, string $action, string $metho
 
     /**
      * Render form closing tag.
+      *
+      * @api
      */
     public function renderClose(): string
     {
@@ -161,6 +175,8 @@ public function renderClose(): string
 
     /**
      * Render form header.
+      *
+      * @api
      */
     public function renderHeader(\Horde\Form\Form $form): string
     {
@@ -189,6 +205,8 @@ public function renderHeader(\Horde\Form\Form $form): string
 
     /**
      * Render form buttons.
+      *
+      * @api
      */
     public function renderButtons(\Horde\Form\Form $form): string
     {
@@ -211,6 +229,8 @@ public function renderButtons(\Horde\Form\Form $form): string
      * Set rendering mode.
      *
      * @param string $mode  Mode: active, inactive, print
+      *
+      * @api
      */
     public function setMode(string $mode): void
     {
@@ -219,6 +239,8 @@ public function setMode(string $mode): void
 
     /**
      * Get rendering mode.
+      *
+      * @api
      */
     public function getMode(): string
     {
@@ -229,6 +251,8 @@ public function getMode(): string
      * Set control rendering mode.
      *
      * @param string $mode  Control mode: modern, legacy, fallback
+      *
+      * @api
      */
     public function setControlMode(string $mode): void
     {
@@ -244,6 +268,8 @@ public function setControlMode(string $mode): void
      * Get control rendering mode.
      *
      * @return string  Control mode
+      *
+      * @api
      */
     public function getControlMode(): string
     {
diff --git a/src/V3/HtmlVariable.php b/src/V3/HtmlVariable.php
index 93c3d1d..99a55c1 100644
--- a/src/V3/HtmlVariable.php
+++ b/src/V3/HtmlVariable.php
@@ -16,6 +16,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/ImageVariable.php b/src/V3/ImageVariable.php
index 3679fca..0655ad7 100644
--- a/src/V3/ImageVariable.php
+++ b/src/V3/ImageVariable.php
@@ -67,6 +67,8 @@ class ImageVariable extends BaseVariable
      *                      - $params[0]: bool $show_upload - Show the upload button (default: true)
      *                      - $params[1]: bool $show_keeporig - Show the option to upload also original non-modified image (default: false)
      *                      - $params[2]: int|null $max_filesize - Limit the file size in bytes (default: null)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -76,6 +78,8 @@ public function init(...$params)
     }
 
     /**
+      *
+      * @api
      */
     public function onSubmit($vars)
     {
@@ -106,6 +110,8 @@ public function onSubmit($vars)
      * @param Horde_Form_Variable $var  The Form field object to check
      * @param Horde_Variables $vars     The form state to check this field for
      * @param array $value              The field value array - should contain a key ['hash'] which holds the key for the image on temp storage
+      *
+      * @api
      */
     public function isValid(Horde_Variables $vars, $value): bool
     {
@@ -348,6 +354,8 @@ public function getUploadedFileType($field)
      *
      * @param Horde_Variables $vars     The form state to check this field for
      * @return array  The current image hash.
+      *
+      * @api
      */
     public function getImage($vars)
     {
@@ -376,6 +384,8 @@ public function getImage($vars)
      *   $image['load']['data'] - the raw image data.
      *
      * @param array $image  The image array.
+      *
+      * @api
      */
     public function loadImageData($image)
     {
@@ -408,6 +418,8 @@ public function getRandomId()
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/IntVariable.php b/src/V3/IntVariable.php
index 100349d..4f36f7d 100644
--- a/src/V3/IntVariable.php
+++ b/src/V3/IntVariable.php
@@ -19,6 +19,8 @@ class IntVariable extends BaseVariable
      * @param mixed $value           Field value to validate
      *
      * @return bool  True if valid, false with error message set if invalid
+      *
+      * @api
      */
     public function isValid(Horde_Variables $vars, $value): bool
     {
@@ -35,6 +37,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/IntlistVariable.php b/src/V3/IntlistVariable.php
index df00329..2db70ce 100644
--- a/src/V3/IntlistVariable.php
+++ b/src/V3/IntlistVariable.php
@@ -24,6 +24,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/InvalidVariable.php b/src/V3/InvalidVariable.php
index d90ede7..d5fb964 100644
--- a/src/V3/InvalidVariable.php
+++ b/src/V3/InvalidVariable.php
@@ -16,6 +16,8 @@ class InvalidVariable extends BaseVariable
      *
      * @param array $params Variable arguments:
      *                      - $params[0]: string $message - The error message to display (default: '')
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -29,6 +31,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/Ip6addressVariable.php b/src/V3/Ip6addressVariable.php
index 0ff9d03..8879cb7 100644
--- a/src/V3/Ip6addressVariable.php
+++ b/src/V3/Ip6addressVariable.php
@@ -29,6 +29,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/IpaddressVariable.php b/src/V3/IpaddressVariable.php
index 54d258f..2aa1d4d 100644
--- a/src/V3/IpaddressVariable.php
+++ b/src/V3/IpaddressVariable.php
@@ -41,6 +41,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/KeyvalMultienumVariable.php b/src/V3/KeyvalMultienumVariable.php
index d073117..5e174d8 100644
--- a/src/V3/KeyvalMultienumVariable.php
+++ b/src/V3/KeyvalMultienumVariable.php
@@ -26,6 +26,8 @@ protected function getInfoV3($vars)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/LinkVariable.php b/src/V3/LinkVariable.php
index 3258d66..4dfac1f 100644
--- a/src/V3/LinkVariable.php
+++ b/src/V3/LinkVariable.php
@@ -24,6 +24,8 @@ class LinkVariable extends BaseVariable
      *
      * @param array $params Variable arguments:
      *                      - $params[0]: array|null $values - List of hashes containing link parameters. Possible keys: 'url', 'text', 'target', 'onclick', 'title', 'accesskey', 'class' (default: null)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -37,6 +39,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/LongtextVariable.php b/src/V3/LongtextVariable.php
index 8c6f2e8..7705ab0 100644
--- a/src/V3/LongtextVariable.php
+++ b/src/V3/LongtextVariable.php
@@ -27,6 +27,8 @@ class LongtextVariable extends TextVariable
      *                      - $params[0]: int $rows - Number of rows (default: 8)
      *                      - $params[1]: int $cols - Number of columns (default: 80)
      *                      - $params[2]: array $helper - Array of helper options (default: [])
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -72,6 +74,8 @@ public function hasHelper($option = '')
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/MatrixVariable.php b/src/V3/MatrixVariable.php
index 31436be..56d92bb 100644
--- a/src/V3/MatrixVariable.php
+++ b/src/V3/MatrixVariable.php
@@ -37,6 +37,8 @@ class MatrixVariable extends BaseVariable
      *                      - $params[1]: array $rows - A hash with row IDs as the keys and row labels as the values (default: [])
      *                      - $params[2]: array $matrix - A two dimensional hash with the field values (default: [])
      *                      - $params[3]: bool|array $new_input - If true, a free text field to add a new row is displayed on the top, a select box if this parameter is a value (default: false)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -86,6 +88,8 @@ protected function getInfoV3($vars)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/MlenumVariable.php b/src/V3/MlenumVariable.php
index 63b7dbc..205c9bc 100644
--- a/src/V3/MlenumVariable.php
+++ b/src/V3/MlenumVariable.php
@@ -21,6 +21,8 @@ class MlenumVariable extends BaseVariable
      * @param array $params Variable arguments:
      *                      - $params[0]: array $values - Values to select from (passed by reference)
      *                      - $params[1]: bool|string|array|null $prompts - Prompt text. If true, uses default "-- select --" for both levels. If string, uses same prompt for both levels. If array, uses different prompts for each level. (default: null)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -78,6 +80,8 @@ protected function getInfoV3($vars)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/MonthdayyearVariable.php b/src/V3/MonthdayyearVariable.php
index e3abb55..ad20f03 100644
--- a/src/V3/MonthdayyearVariable.php
+++ b/src/V3/MonthdayyearVariable.php
@@ -31,6 +31,8 @@ class MonthdayyearVariable extends BaseVariable
      *                      - $params[2]: bool $picker - Do we show the DHTML calendar (default: true)
      *                      - $params[3]: string|null $format_in - The format to use when sending the date for storage. Defaults to Unix epoch. Similar to the strftime() function. (default: null)
      *                      - $params[4]: string $format_out - The format to use when displaying the date. Similar to the strftime() function. (default: '%x')
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -84,6 +86,8 @@ public function isValid(Horde_Variables|array $vars, $date): bool
      *
      * @return integer  0 for non-empty, 1 for completely empty or -1 for
      *                  partially empty.
+      *
+      * @api
      */
     public function emptyDateArray($date)
     {
@@ -121,6 +125,8 @@ public function emptyDateArray($date)
      *                         and UNIX epoch) plus the fourth YYYY-MM-DD.
      *
      * @return array  Array with three elements - year, month and day.
+      *
+      * @api
      */
     public function getDateParts($date_in)
     {
@@ -148,6 +154,8 @@ public function getDateParts($date_in)
      *                         and UNIX epoch) plus the fourth YYYY-MM-DD.
      *
      * @return Horde_Date  The date object.
+      *
+      * @api
      */
     public function getDateOb($date_in)
     {
@@ -180,6 +188,8 @@ public function getDateOb($date_in)
      *
      * @return string  The date formatted according to the $format_out
      *                 parameter when setting up the monthdayyear field.
+      *
+      * @api
      */
     public function formatDate($date)
     {
@@ -227,6 +237,8 @@ public function _validateAndFormat($value)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/MonthyearVariable.php b/src/V3/MonthyearVariable.php
index 5aa97a3..09b5792 100644
--- a/src/V3/MonthyearVariable.php
+++ b/src/V3/MonthyearVariable.php
@@ -21,6 +21,8 @@ class MonthyearVariable extends BaseVariable
      * @param array $params Variable arguments:
      *                      - $params[0]: int|null $start_year - The first available year for input (default: 1920)
      *                      - $params[1]: int|null $end_year - The last available year for input (default: current year)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -63,6 +65,8 @@ public function getYearVar()
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/MultienumVariable.php b/src/V3/MultienumVariable.php
index dbdf83e..af956d8 100644
--- a/src/V3/MultienumVariable.php
+++ b/src/V3/MultienumVariable.php
@@ -21,6 +21,8 @@ class MultienumVariable extends EnumVariable
      * @param array $params Variable arguments:
      *                      - $params[0]: array $values - A hash map where the key is the internal 'value' to process and the value is the caption presented to the user
      *                      - $params[1]: int|null $size - The number of rows the multienum should display before scrolling (optional)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -45,6 +47,8 @@ public function init(...$params)
      * @param mixed $value           Single value or array of values to validate
      *
      * @return bool  True if all values valid, false with error message if invalid
+      *
+      * @api
      */
     public function isValid(Horde_Variables $vars, $value): bool
     {
@@ -73,6 +77,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/NumberVariable.php b/src/V3/NumberVariable.php
index 8945a8a..a6216dd 100644
--- a/src/V3/NumberVariable.php
+++ b/src/V3/NumberVariable.php
@@ -19,6 +19,8 @@ class NumberVariable extends BaseVariable
      *
      * @param array $params Variable arguments:
      *                      - $params[0]: int|null $fraction - Maximum number of decimal places allowed (default: null, unlimited)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -95,6 +97,8 @@ protected function getInfoV3($vars)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/ObrowserVariable.php b/src/V3/ObrowserVariable.php
index fe69a1d..e54d45f 100644
--- a/src/V3/ObrowserVariable.php
+++ b/src/V3/ObrowserVariable.php
@@ -16,6 +16,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/OctalVariable.php b/src/V3/OctalVariable.php
index 71bd1db..f3df835 100644
--- a/src/V3/OctalVariable.php
+++ b/src/V3/OctalVariable.php
@@ -24,6 +24,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/PasswordVariable.php b/src/V3/PasswordVariable.php
index 763493c..bfdf374 100644
--- a/src/V3/PasswordVariable.php
+++ b/src/V3/PasswordVariable.php
@@ -20,6 +20,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/PasswordconfirmVariable.php b/src/V3/PasswordconfirmVariable.php
index a2d3184..6512f04 100644
--- a/src/V3/PasswordconfirmVariable.php
+++ b/src/V3/PasswordconfirmVariable.php
@@ -31,6 +31,8 @@ protected function getInfoV3($vars)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/PgpVariable.php b/src/V3/PgpVariable.php
index f57a41c..7b241d4 100644
--- a/src/V3/PgpVariable.php
+++ b/src/V3/PgpVariable.php
@@ -40,6 +40,8 @@ class PgpVariable extends LongtextVariable
      *                      - $params[1]: string|null $temp_dir - A temporary directory
      *                      - $params[2]: int $rows - Number of rows (default: 8, from parent)
      *                      - $params[3]: int $cols - Number of columns (default: 80, from parent)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -65,6 +67,8 @@ public function getPGPParams()
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/PhoneVariable.php b/src/V3/PhoneVariable.php
index fe0c451..70b903f 100644
--- a/src/V3/PhoneVariable.php
+++ b/src/V3/PhoneVariable.php
@@ -23,6 +23,8 @@ class PhoneVariable extends BaseVariable
      *
      * @param array $params Variable arguments:
      *                      - $params[0]: int $size - The size of the input field (default: 15)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -49,6 +51,8 @@ public function getSize()
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/RadioVariable.php b/src/V3/RadioVariable.php
index fa9870f..48fcc3a 100644
--- a/src/V3/RadioVariable.php
+++ b/src/V3/RadioVariable.php
@@ -17,6 +17,8 @@ class RadioVariable extends EnumVariable
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/ReloadAction.php b/src/V3/ReloadAction.php
index 9e5b18c..ac08d23 100644
--- a/src/V3/ReloadAction.php
+++ b/src/V3/ReloadAction.php
@@ -54,6 +54,8 @@ class ReloadAction extends BaseAction
      * @param mixed $renderer  The form renderer
      * @param string $varname  Variable name
      * @return string  JavaScript code
+      *
+      * @api
      */
     public function getActionScript(\Horde\Form\Form $form, $renderer, string $varname): string
     {
diff --git a/src/V3/Renderer.php b/src/V3/Renderer.php
index 4dd9a64..9549866 100644
--- a/src/V3/Renderer.php
+++ b/src/V3/Renderer.php
@@ -56,6 +56,8 @@ interface Renderer
      * @param string $action  Form action URL
      * @param string $method  HTTP method (get/post)
      * @return string  Complete rendered output
+      *
+      * @api
      */
     public function render(Form $form, string $action = '', string $method = 'post'): string;
 
@@ -66,6 +68,8 @@ public function render(Form $form, string $action = '', string $method = 'post')
      * @param string $action  Form action URL
      * @param string $method  HTTP method
      * @return string  Opening form tag
+      *
+      * @api
      */
     public function renderOpen(Form $form, string $action, string $method): string;
 
@@ -73,6 +77,8 @@ public function renderOpen(Form $form, string $action, string $method): string;
      * Render form closing tag.
      *
      * @return string  Closing form tag
+      *
+      * @api
      */
     public function renderClose(): string;
 
@@ -81,6 +87,8 @@ public function renderClose(): string;
      *
      * @param Form $form  The form to render
      * @return string  Form header HTML
+      *
+      * @api
      */
     public function renderHeader(Form $form): string;
 
@@ -90,6 +98,8 @@ public function renderHeader(Form $form): string;
      * @param Variable $variable  The variable to render
      * @param Form $form  The parent form
      * @return string  Rendered field
+      *
+      * @api
      */
     public function renderVariable(Variable $variable, Form $form): string;
 
@@ -100,6 +110,8 @@ public function renderVariable(Variable $variable, Form $form): string;
      * @param array<Variable> $variables  Variables in this section
      * @param Form $form  The parent form
      * @return string  Rendered section
+      *
+      * @api
      */
     public function renderSection(string|int $sectionName, array $variables, Form $form): string;
 
@@ -108,6 +120,8 @@ public function renderSection(string|int $sectionName, array $variables, Form $f
      *
      * @param Form $form  The form to render
      * @return string  Form buttons HTML
+      *
+      * @api
      */
     public function renderButtons(Form $form): string;
 
@@ -116,6 +130,8 @@ public function renderButtons(Form $form): string;
      *
      * @param Form $form  The form to render
      * @return string  Errors HTML
+      *
+      * @api
      */
     public function renderErrors(Form $form): string;
 
@@ -124,6 +140,8 @@ public function renderErrors(Form $form): string;
      *
      * @param Form $form  The form to render
      * @return string  Hidden fields HTML
+      *
+      * @api
      */
     public function renderHidden(Form $form): string;
 }
diff --git a/src/V3/SelectfilesVariable.php b/src/V3/SelectfilesVariable.php
index f2baf16..2f01776 100644
--- a/src/V3/SelectfilesVariable.php
+++ b/src/V3/SelectfilesVariable.php
@@ -50,6 +50,8 @@ class SelectfilesVariable extends BaseVariable
      *                      - $params[1]: string|null $link_text - The text to use in the link (default: "Select Files")
      *                      - $params[2]: string $link_style - The style to use for the link (default: '')
      *                      - $params[3]: bool $icon - Create the link with an icon instead of text (default: false)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -81,6 +83,8 @@ protected function getInfoV3($vars)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/SetVariable.php b/src/V3/SetVariable.php
index b3d200a..aa2a189 100644
--- a/src/V3/SetVariable.php
+++ b/src/V3/SetVariable.php
@@ -21,6 +21,8 @@ class SetVariable extends BaseVariable
      * @param array $params Variable arguments:
      *                      - $params[0]: array $values - Values available for selection
      *                      - $params[1]: bool $checkAll - Show "check all" option (default: false)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -50,6 +52,8 @@ public function getValues(...$params): ?array
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/SetcursorposAction.php b/src/V3/SetcursorposAction.php
index 2dcba82..f9909ad 100644
--- a/src/V3/SetcursorposAction.php
+++ b/src/V3/SetcursorposAction.php
@@ -65,6 +65,8 @@ class SetcursorposAction extends BaseAction
      * @param mixed $renderer  The form renderer
      * @param string $varname  Variable name this action applies to
      * @return string  JavaScript code
+      *
+      * @api
      */
     public function getActionScript(\Horde\Form\Form $form, $renderer, string $varname): string
     {
@@ -83,6 +85,8 @@ public function getActionScript(\Horde\Form\Form $form, $renderer, string $varna
      * Print JavaScript code for this action.
      *
      * @return string  JavaScript code
+      *
+      * @api
      */
     public function printJavaScript(): string
     {
diff --git a/src/V3/SmimeVariable.php b/src/V3/SmimeVariable.php
index e1847ff..34cde4f 100644
--- a/src/V3/SmimeVariable.php
+++ b/src/V3/SmimeVariable.php
@@ -31,6 +31,8 @@ class SmimeVariable extends LongtextVariable
      *                      - $params[0]: string|null $temp_dir - A temporary directory
      *                      - $params[1]: int $rows - Number of rows (default: 8, from parent)
      *                      - $params[2]: int $cols - Number of columns (default: 80, from parent)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -54,6 +56,8 @@ public function getSMIMEParams()
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/SorterVariable.php b/src/V3/SorterVariable.php
index 8951fc1..35aa342 100644
--- a/src/V3/SorterVariable.php
+++ b/src/V3/SorterVariable.php
@@ -26,6 +26,8 @@ class SorterVariable extends BaseVariable
      *                      - $params[0]: array $values - Values available for sorting
      *                      - $params[1]: int $size - Size of the select list (default: 8)
      *                      - $params[2]: string $header - Header text for the select list (default: '')
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -97,6 +99,8 @@ protected function getInfoV3($vars)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/SoundVariable.php b/src/V3/SoundVariable.php
index 5b51ac7..9214366 100644
--- a/src/V3/SoundVariable.php
+++ b/src/V3/SoundVariable.php
@@ -18,6 +18,8 @@ class SoundVariable extends BaseVariable
      * Initialize a sound selection field.
      *
      * @param array $params Variable arguments (none used, sounds are loaded from theme)
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -44,6 +46,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/SpacerVariable.php b/src/V3/SpacerVariable.php
index 56889f1..b2d1857 100644
--- a/src/V3/SpacerVariable.php
+++ b/src/V3/SpacerVariable.php
@@ -16,6 +16,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/StringarrayVariable.php b/src/V3/StringarrayVariable.php
index b4d1f70..764b010 100644
--- a/src/V3/StringarrayVariable.php
+++ b/src/V3/StringarrayVariable.php
@@ -21,6 +21,8 @@ protected function getInfoV3($vars)
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/StringlistVariable.php b/src/V3/StringlistVariable.php
index a9a03e7..564eda7 100644
--- a/src/V3/StringlistVariable.php
+++ b/src/V3/StringlistVariable.php
@@ -15,6 +15,8 @@ class StringlistVariable extends TextVariable
 {
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/SubmitAction.php b/src/V3/SubmitAction.php
index d5f8858..9a924c6 100644
--- a/src/V3/SubmitAction.php
+++ b/src/V3/SubmitAction.php
@@ -51,6 +51,8 @@ class SubmitAction extends BaseAction
      * @param mixed $renderer  The form renderer
      * @param string $varname  Variable name
      * @return string  JavaScript code
+      *
+      * @api
      */
     public function getActionScript(\Horde\Form\Form $form, $renderer, string $varname): string
     {
diff --git a/src/V3/SumfieldsAction.php b/src/V3/SumfieldsAction.php
index 528f530..238cb43 100644
--- a/src/V3/SumfieldsAction.php
+++ b/src/V3/SumfieldsAction.php
@@ -55,6 +55,8 @@ class SumfieldsAction extends BaseAction
      * @param mixed $renderer  The form renderer
      * @param string $varname  Variable name (the target sum field)
      * @return string  JavaScript code
+      *
+      * @api
      */
     public function getActionScript(\Horde\Form\Form $form, $renderer, string $varname): string
     {
diff --git a/src/V3/TablesetVariable.php b/src/V3/TablesetVariable.php
index b735e52..002015e 100644
--- a/src/V3/TablesetVariable.php
+++ b/src/V3/TablesetVariable.php
@@ -21,6 +21,8 @@ class TablesetVariable extends BaseVariable
      * @param array $params Variable arguments:
      *                      - $params[0]: array $values - The values for the table set.
      *                      - $params[1]: array $header - The headers for the table set.
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -57,6 +59,8 @@ public function getValues(...$params): ?array
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/TextVariable.php b/src/V3/TextVariable.php
index 839b976..63d8eaa 100644
--- a/src/V3/TextVariable.php
+++ b/src/V3/TextVariable.php
@@ -25,6 +25,8 @@ class TextVariable extends BaseVariable
      *                      - $params[0]: string $regex - Any valid PHP PCRE pattern syntax that needs to be matched for the field to be considered valid. If left empty validity will be checked only for required fields whether they are empty or not. If using this regex test it is advisable to enter a description for this field to warn the user what is expected, as the generated error message is quite generic and will not give any indication where the regex failed.
      *                      - $params[1]: int $size - The size of the input field.
      *                      - $params[2]: int|null $maxlength - The max number of characters.
+      *
+      * @api
      */
     public function init(...$params)
     {
@@ -63,6 +65,8 @@ public function getMaxLength()
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/TimeVariable.php b/src/V3/TimeVariable.php
index 58b9304..109e774 100644
--- a/src/V3/TimeVariable.php
+++ b/src/V3/TimeVariable.php
@@ -22,6 +22,8 @@ public function isValid(Horde_Variables $vars, $value): bool
 
     /**
      * Return info about field type.
+      *
+      * @api
      */
     public function about(): array
     {
diff --git a/src/V3/UpdatefieldAction.php b/src/V3/UpdatefieldAction.php
index 25838a4..d9bdffc 100644
--- a/src/V3/UpdatefieldAction.php
+++ b/src/V3/UpdatefieldAction.php
@@ -76,6 +76,8 @@ class UpdatefieldAction extends BaseAction
      * @param mixed $renderer  The form renderer
      * @param string $varname  Variable name this action applies to
      * @return string  JavaScript code
+      *
+      * @api
      */
     public function getActionScript(\Horde\Form\Form $form, $renderer, string $varname): string
     {
@@ -89,6 +91,8 @@ public function getActionScript(\Horde\Form\Form $form, $renderer, string $varna
      * @param mixed $sourceVal  The source value
      * @param int|null $index  Array index
      * @param bool $arrayVal  Whether dealing with array values
+      *
+      * @api
      */
     public function setValues(\Horde_Variables $vars, $sourceVal, ?int $index = null, bool $arrayVal = false): void
     {
@@ -99,6 +103,8 @@ public function setValues(\Horde_Variables $vars, $sourceVal, ?int $index = null
      * Print JavaScript code for this action.
      *
      * @return string  JavaScript code
+      *
+      * @api
      */
     public function printJavaScript(): string
     {

From f6109eace21489d50920c032afaaf98d44ffccc9 Mon Sep 17 00:00:00 2001
From: Ralf Lang <ralf.lang@ralf-lang.de>
Date: Sun, 8 Mar 2026 10:15:07 +0100
Subject: [PATCH 4/5] feat(api): create distinct migration and V3-native
 interfaces

Split existing interfaces into separate migration and V3-native interfaces
to clearly distinguish lib/ compatibility methods from V3-specific additions.

- Clear documentation of which methods existed in lib/ vs new in V3
- Easier migration path - developers can see exactly what's supposed to be compatible and what isn't
- No changes to implementing classes (BaseVariable, BaseForm, BaseAction)
- Interfaces use extends, so existing code using Variable/Form/Action continues to work
- Foundation for development of V3 without disturbing migration support

No breaking changes to public API.
---
 src/V3/Action.php                     |  68 +-----
 src/V3/ActionMigrationInterface.php   |  73 ++++++
 src/V3/ActionV3Interface.php          |  38 +++
 src/V3/Form.php                       |  26 +-
 src/V3/FormMigrationInterface.php     | 337 ++++++++++++++++++++++++++
 src/V3/FormV3Interface.php            |  37 +++
 src/V3/Variable.php                   |  62 ++---
 src/V3/VariableMigrationInterface.php | 230 ++++++++++++++++++
 src/V3/VariableV3Interface.php        |  73 ++++++
 9 files changed, 837 insertions(+), 107 deletions(-)
 create mode 100644 src/V3/ActionMigrationInterface.php
 create mode 100644 src/V3/ActionV3Interface.php
 create mode 100644 src/V3/FormMigrationInterface.php
 create mode 100644 src/V3/FormV3Interface.php
 create mode 100644 src/V3/VariableMigrationInterface.php
 create mode 100644 src/V3/VariableV3Interface.php

diff --git a/src/V3/Action.php b/src/V3/Action.php
index 8742a2d..f5891b7 100644
--- a/src/V3/Action.php
+++ b/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,65 +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
-      *
-      * @api
-     */
-    public function getTrigger(): ?array;
-
-    /**
-     * Get action ID.
-     *
-     * @return string  Unique action identifier
-      *
-      * @api
-     */
-    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
-      *
-      * @api
-     */
-    public function getActionScript(Form $form, $renderer, string $varname): string;
-
-    /**
-     * Print JavaScript for this action.
-     *
-     * Some actions may need to output JavaScript directly.
-      *
-      * @api
-     */
-    public function printJavaScript(): void;
-
-    /**
-     * Get target field name for this action.
-     *
-     * @return string|null  Target field name or null
-      *
-      * @api
-     */
-    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
-      *
-      * @api
-     */
-    public function setValues($vars, $sourceVal, ?int $index = null, bool $arrayVal = false): void;
 }
diff --git a/src/V3/ActionMigrationInterface.php b/src/V3/ActionMigrationInterface.php
new file mode 100644
index 0000000..41cde12
--- /dev/null
+++ b/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;
+}
diff --git a/src/V3/ActionV3Interface.php b/src/V3/ActionV3Interface.php
new file mode 100644
index 0000000..6630b5c
--- /dev/null
+++ b/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;
+}
diff --git a/src/V3/Form.php b/src/V3/Form.php
index 092fe3f..149c77a 100644
--- a/src/V3/Form.php
+++ b/src/V3/Form.php
@@ -1,6 +1,30 @@
 <?php
+/**
+ * Copyright 2001-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.
+ *
+ * @category Horde
+ * @license  http://www.horde.org/licenses/lgpl21 LGPL
+ * @package  Form
+ */
+
 namespace Horde\Form\V3;
 
-interface Form
+/**
+ * Combined interface for forms.
+ *
+ * Extends both FormMigrationInterface (lib/ compatibility methods)
+ * and FormV3Interface (V3-native methods) to provide the complete
+ * Form API.
+ *
+ * Implementations of this interface support both migrated code from lib/
+ * and new V3-specific functionality.
+ *
+ * @category Horde
+ * @package  Form
+ */
+interface Form extends FormMigrationInterface, FormV3Interface
 {
 }
diff --git a/src/V3/FormMigrationInterface.php b/src/V3/FormMigrationInterface.php
new file mode 100644
index 0000000..a25617f
--- /dev/null
+++ b/src/V3/FormMigrationInterface.php
@@ -0,0 +1,337 @@
+<?php
+/**
+ * Copyright 2001-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.
+ *
+ * @category Horde
+ * @license  http://www.horde.org/licenses/lgpl21 LGPL
+ * @package  Form
+ */
+
+namespace Horde\Form\V3;
+
+use Horde_Variables;
+use Psr\Http\Message\ServerRequestInterface;
+
+/**
+ * Migration interface for Form methods that existed in lib/ (Horde_Form).
+ *
+ * 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 FormMigrationInterface
+{
+    /**
+     * Returns the form variables as an array.
+     *
+     * @return array  Form variables
+     */
+    public function getVars(): array;
+
+    /**
+     * Sets form variables.
+     *
+     * @param Horde_Variables|ServerRequestInterface|array $vars  Variables to set
+     */
+    public function setVars(Horde_Variables|ServerRequestInterface|array $vars): void;
+
+    /**
+     * Gets a single variable value.
+     *
+     * @param string $name     Variable name
+     * @param mixed $default   Default value if not set
+     *
+     * @return mixed  Variable value
+     */
+    public function getVar(string $name, mixed $default = null): mixed;
+
+    /**
+     * Sets a single variable value.
+     *
+     * @param string $name   Variable name
+     * @param mixed $value   Variable value
+     */
+    public function setVar(string $name, mixed $value): void;
+
+    /**
+     * Returns the form title.
+     *
+     * @return string  Form title
+     */
+    public function getTitle(): string;
+
+    /**
+     * Sets the form title.
+     *
+     * @param string $title  Form title
+     */
+    public function setTitle(string $title): void;
+
+    /**
+     * Returns the extra form content.
+     *
+     * @return string  Extra content
+     */
+    public function getExtra(): string;
+
+    /**
+     * Sets extra form content.
+     *
+     * @param string $extra  Extra content
+     */
+    public function setExtra(string $extra): void;
+
+    /**
+     * Returns the form name.
+     *
+     * @return string  Form name
+     */
+    public function getName(): string;
+
+    /**
+     * Gets or sets token usage.
+     *
+     * @param bool|null $token  Set token usage, or null to get current state
+     *
+     * @return bool  Token usage state
+     */
+    public function useToken(?bool $token = null): bool;
+
+    /**
+     * Sets the currently open form section.
+     *
+     * @param string $section      Section name
+     * @param string $desc         Section description
+     * @param string $image        Section image path
+     * @param bool $expanded       Whether section is expanded
+     */
+    public function setSection(
+        string $section,
+        string $desc = '',
+        string $image = '',
+        bool $expanded = true
+    ): void;
+
+    /**
+     * Gets section description.
+     *
+     * @param string|int $section  Section identifier
+     *
+     * @return string  Section description
+     */
+    public function getSectionDesc(string|int $section): string;
+
+    /**
+     * Gets section image path.
+     *
+     * @param string|int $section  Section identifier
+     *
+     * @return string  Section image path
+     */
+    public function getSectionImage(string|int $section): string;
+
+    /**
+     * Sets the open section.
+     *
+     * @param string|int $section  Section identifier
+     */
+    public function setOpenSection(string|int $section): void;
+
+    /**
+     * Gets the currently open section.
+     *
+     * @return string|int|null  Open section identifier
+     */
+    public function getOpenSection(): string|int|null;
+
+    /**
+     * Gets section expanded state.
+     *
+     * @param string|int $section  Section identifier
+     * @param bool $boolean        Return as boolean vs string
+     *
+     * @return bool|string  Expanded state
+     */
+    public function getSectionExpandedState(string|int $section, bool $boolean = false): bool|string;
+
+    /**
+     * Adds a variable to the form.
+     *
+     * @param string $humanName         Human-readable name
+     * @param string $varName           Internal variable name
+     * @param string|Variable $type     Variable type or instance
+     * @param bool $required            Whether required
+     * @param bool $readonly            Whether readonly
+     * @param string|null $description  Long description
+     * @param mixed $params             Type-specific parameters
+     *
+     * @return Variable  The created variable
+     */
+    public function addVariable(
+        string $humanName,
+        string $varName,
+        string|Variable $type,
+        bool $required,
+        bool $readonly = false,
+        ?string $description = null,
+        mixed $params = []
+    ): Variable;
+
+    /**
+     * Inserts a variable before another variable.
+     *
+     * @param string $before            Variable to insert before
+     * @param string $humanName         Human-readable name
+     * @param string $varName           Internal variable name
+     * @param string|Variable $type     Variable type or instance
+     * @param bool $required            Whether required
+     * @param bool $readonly            Whether readonly
+     * @param string|null $description  Long description
+     * @param mixed $params             Type-specific parameters
+     *
+     * @return Variable  The created variable
+     */
+    public function insertVariableBefore(
+        string $before,
+        string $humanName,
+        string $varName,
+        string|Variable $type,
+        bool $required,
+        bool $readonly = false,
+        ?string $description = null,
+        mixed $params = []
+    ): Variable;
+
+    /**
+     * Removes a variable from the form.
+     *
+     * @param Variable|string $var  Variable instance or name
+     *
+     * @return bool  True if removed, false if not found
+     */
+    public function removeVariable(Variable|string $var): bool;
+
+    /**
+     * Adds a hidden variable.
+     *
+     * @param string $humanName         Human-readable name
+     * @param string $varName           Internal variable name
+     * @param string|Variable $type     Variable type or instance
+     * @param bool $required            Whether required
+     * @param bool $readonly            Whether readonly
+     * @param string|null $description  Long description
+     * @param mixed $params             Type-specific parameters
+     *
+     * @return Variable  The created variable
+     */
+    public function addHidden(
+        string $humanName,
+        string $varName,
+        string|Variable $type,
+        bool $required,
+        bool $readonly = false,
+        ?string $description = null,
+        mixed $params = []
+    ): Variable;
+
+    /**
+     * Gets form variables.
+     *
+     * @param bool $flat          Return flat array vs nested by section
+     * @param bool $withHidden    Include hidden variables
+     *
+     * @return array  Form variables
+     */
+    public function getVariables(bool $flat = true, bool $withHidden = false): array;
+
+    /**
+     * Sets form buttons.
+     *
+     * @param array|string|bool $submit  Submit button configuration
+     * @param string|bool $reset         Reset button configuration
+     */
+    public function setButtons(array|string|bool $submit, string|bool $reset = false): void;
+
+    /**
+     * Appends buttons to existing buttons.
+     *
+     * @param array|string $submit  Submit button configuration
+     */
+    public function appendButtons(array|string $submit): void;
+
+    /**
+     * Validates the form.
+     *
+     * @param Horde_Variables|array|null $vars  Variables to validate
+     *
+     * @return bool  True if valid
+     */
+    public function validate($vars = null): bool;
+
+    /**
+     * Returns whether form is valid.
+     *
+     * @return bool  True if valid
+     */
+    public function isValid(): bool;
+
+    /**
+     * Gets all validation errors.
+     *
+     * @return array  Errors indexed by variable name
+     */
+    public function getErrors(): array;
+
+    /**
+     * Gets error for specific variable.
+     *
+     * @param string $varName  Variable name
+     *
+     * @return string|null  Error message or null
+     */
+    public function getError(string $varName): ?string;
+
+    /**
+     * Sets an error for a variable.
+     *
+     * @param string $varName   Variable name
+     * @param string $message   Error message
+     */
+    public function setError(string $varName, string $message): void;
+
+    /**
+     * Clears errors.
+     *
+     * @param string|null $varName  Variable name, or null for all
+     */
+    public function clearError(?string $varName = null): void;
+
+    /**
+     * Extracts form data.
+     *
+     * @param Horde_Variables|array|null $vars  Variables to extract from
+     *
+     * @return array  Extracted form data
+     */
+    public function getInfo($vars = null): array;
+
+    /**
+     * Returns whether form was submitted.
+     *
+     * @return bool  True if submitted
+     */
+    public function isSubmitted(): bool;
+
+    /**
+     * Gets form encoding type.
+     *
+     * @return string|null  Encoding type or null
+     */
+    public function getEnctype(): ?string;
+}
diff --git a/src/V3/FormV3Interface.php b/src/V3/FormV3Interface.php
new file mode 100644
index 0000000..4855f67
--- /dev/null
+++ b/src/V3/FormV3Interface.php
@@ -0,0 +1,37 @@
+<?php
+/**
+ * Copyright 2001-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.
+ *
+ * @category Horde
+ * @license  http://www.horde.org/licenses/lgpl21 LGPL
+ * @package  Form
+ */
+
+namespace Horde\Form\V3;
+
+/**
+ * V3-native interface for Form methods introduced in the V3 implementation.
+ *
+ * These methods are new to V3 and provide modernized functionality
+ * not present in lib/ (Horde_Form).
+ *
+ * Note: Most Form functionality is migration-based. V3 improvements are
+ * primarily internal (PSR-7 support, type hints, private helper methods).
+ * This interface is included for completeness but currently empty as all
+ * public methods existed in lib/.
+ *
+ * @category Horde
+ * @package  Form
+ */
+interface FormV3Interface
+{
+    // Currently no V3-specific public methods.
+    // Internal improvements include:
+    // - normalizeVars() - private method for PSR-7/array/Horde_Variables normalization
+    // - getInfoFromVariables() - private extraction method
+    // - createVariable() - private factory method
+    // - Enhanced type hints on all methods (PHP 8+ features)
+}
diff --git a/src/V3/Variable.php b/src/V3/Variable.php
index 18eaa35..22d7d30 100644
--- a/src/V3/Variable.php
+++ b/src/V3/Variable.php
@@ -1,57 +1,31 @@
 <?php
 /**
- * Copyright 2001-2025 Horde LLC (http://www.horde.org/)
+ * Copyright 2001-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   Robert E. Coyle <robertecoyle@hotmail.com>
+ * @category Horde
+ * @license  http://www.horde.org/licenses/lgpl21 LGPL
+ * @package  Form
  */
 
 namespace Horde\Form\V3;
-use Horde_Variables;
 
-interface Variable
+/**
+ * Combined interface for form variables.
+ *
+ * Extends both VariableMigrationInterface (lib/ compatibility methods)
+ * and VariableV3Interface (V3-native methods) to provide the complete
+ * Variable API.
+ *
+ * Implementations of this interface support both migrated code from lib/
+ * and new V3-specific functionality.
+ *
+ * @category Horde
+ * @package  Form
+ */
+interface Variable extends VariableMigrationInterface, VariableV3Interface
 {
-    public function getMessage();
-    public function setFormOb($form);
-    public function setDefault($value);
-    public function getDefault();
-    public function setAction($action);
-    public function hasAction();
-    public function hide();
-    public function isHidden();
-    public function disable();
-    public function isDisabled();
-    public function getHumanName();
-    public function getTypeName(): string;
-    public function getVarName();
-//    public function getType();
-//    public function isRequired();
-//    public function isReadonly();
-    public function hasDescription(): bool;
-    public function getDescription();
-    public function isArrayVal();
-    public function isUpload();
-    public function setHelp($help);
-    public function hasHelp();
-    public function getHelp();
-    public function setOption($option, $val);
-    public function getOption($option);
-
-    public function getInfo($vars, ...$args);
-
-    public function wasChanged($vars);
-    public function validate($vars, $message);
-    public function getValue($vars, $index = null);
-    public function invalid(string $message): bool;
-
-    // Former type methods
-    public function getProperty($property);
-    public function setProperty($property, $value);
-    public function init(...$params);
-    public function onSubmit($vars);
-    //public function isValid(Horde_Variables $vars, $value): bool;
-    public function getValues(...$params);
-    public function about(): array;
 }
diff --git a/src/V3/VariableMigrationInterface.php b/src/V3/VariableMigrationInterface.php
new file mode 100644
index 0000000..939a07a
--- /dev/null
+++ b/src/V3/VariableMigrationInterface.php
@@ -0,0 +1,230 @@
+<?php
+/**
+ * Copyright 2001-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   Robert E. Coyle <robertecoyle@hotmail.com>
+ * @category Horde
+ * @license  http://www.horde.org/licenses/lgpl21 LGPL
+ * @package  Form
+ */
+
+namespace Horde\Form\V3;
+
+use Horde_Variables;
+
+/**
+ * Migration interface for Variable methods that existed in lib/ (Horde_Form_Variable).
+ *
+ * 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 VariableMigrationInterface
+{
+    /**
+     * Assign this variable to a form.
+     *
+     * @param \Horde\Form\Form $form  The form instance
+     */
+    public function setFormOb($form);
+
+    /**
+     * Sets a default value for this variable.
+     *
+     * @param mixed $value  A variable value
+     */
+    public function setDefault($value);
+
+    /**
+     * Returns this variable's default value.
+     *
+     * @return mixed  This variable's default value
+     */
+    public function getDefault();
+
+    /**
+     * Assigns an action to this variable.
+     *
+     * @param Action $action  An Action instance
+     */
+    public function setAction($action);
+
+    /**
+     * Returns whether this variable has an attached action.
+     *
+     * @return bool  True if this variable has an attached action
+     */
+    public function hasAction();
+
+    /**
+     * Makes this a hidden variable.
+     */
+    public function hide();
+
+    /**
+     * Returns whether this is a hidden variable.
+     *
+     * @return bool  True if this a hidden variable
+     */
+    public function isHidden();
+
+    /**
+     * Disables this variable.
+     */
+    public function disable();
+
+    /**
+     * Returns whether this variable is disabled.
+     *
+     * @return bool  True if this variable is disabled
+     */
+    public function isDisabled();
+
+    /**
+     * Return the short description of this variable.
+     *
+     * @return string  A short description
+     */
+    public function getHumanName();
+
+    /**
+     * Returns the internally used variable name.
+     *
+     * @return string  This variable's internal name
+     */
+    public function getVarName();
+
+    /**
+     * Returns the name of this variable's type.
+     *
+     * @return string  This variable's type name
+     */
+    public function getTypeName(): string;
+
+    /**
+     * Returns whether this variable has a long description.
+     *
+     * @return bool  True if this variable has a long description
+     */
+    public function hasDescription(): bool;
+
+    /**
+     * Returns this variable's long description.
+     *
+     * @return string  This variable's long description
+     */
+    public function getDescription();
+
+    /**
+     * Returns whether this is an array variable.
+     *
+     * @return bool  True if this an array variable
+     */
+    public function isArrayVal();
+
+    /**
+     * Returns whether this variable is to upload a file.
+     *
+     * @return bool  True if variable is to upload a file
+     */
+    public function isUpload();
+
+    /**
+     * Assigns a help text to this variable.
+     *
+     * @param string $help  The variable help text
+     */
+    public function setHelp($help);
+
+    /**
+     * Returns whether this variable has some help text assigned.
+     *
+     * @return bool  True if this variable has a help text
+     */
+    public function hasHelp();
+
+    /**
+     * Returns the help text of this variable.
+     *
+     * @return string  This variable's help text
+     */
+    public function getHelp();
+
+    /**
+     * Sets a variable option.
+     *
+     * @param string $option  The option name
+     * @param mixed $val      The option's value
+     */
+    public function setOption($option, $val);
+
+    /**
+     * Returns a variable option's value.
+     *
+     * @param string $option  The option name
+     *
+     * @return mixed  The option's value
+     */
+    public function getOption($option);
+
+    /**
+     * Processes the submitted value of this variable.
+     *
+     * @param Horde_Variables $vars  The submitted form variables
+     * @param mixed ...$args         Additional arguments (deprecated)
+     *
+     * @return mixed  Processed value of the variable
+     */
+    public function getInfo($vars, ...$args);
+
+    /**
+     * Returns whether this variable has been changed.
+     *
+     * @param Horde_Variables $vars  The submitted form variables
+     *
+     * @return ?bool  Null if trackchange not set, boolean otherwise
+     */
+    public function wasChanged($vars);
+
+    /**
+     * Validates this variable.
+     *
+     * @param Horde_Variables $vars  The submitted form variables
+     * @param mixed ...$args         Additional arguments (deprecated)
+     *
+     * @return bool  True if the variable validated
+     */
+    public function validate($vars, ...$args);
+
+    /**
+     * Returns the submitted or default value of this variable.
+     *
+     * @param Horde_Variables $vars  The submitted form variables
+     * @param int|null $index        Array element index if array variable
+     *
+     * @return mixed  The variable or element value
+     */
+    public function getValue($vars, $index = null);
+
+    /**
+     * Returns the possible values of this variable.
+     *
+     * @param mixed ...$params  Type-specific parameters
+     *
+     * @return array|null  The possible values or null
+     */
+    public function getValues(...$params);
+
+    /**
+     * Hook called on form submission.
+     *
+     * @param Horde_Variables $vars  Submitted form variables
+     */
+    public function onSubmit($vars);
+}
diff --git a/src/V3/VariableV3Interface.php b/src/V3/VariableV3Interface.php
new file mode 100644
index 0000000..5ee1e96
--- /dev/null
+++ b/src/V3/VariableV3Interface.php
@@ -0,0 +1,73 @@
+<?php
+/**
+ * Copyright 2001-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   Robert E. Coyle <robertecoyle@hotmail.com>
+ * @category Horde
+ * @license  http://www.horde.org/licenses/lgpl21 LGPL
+ * @package  Form
+ */
+
+namespace Horde\Form\V3;
+
+/**
+ * V3-native interface for Variable methods introduced in the V3 implementation.
+ *
+ * These methods are new to V3 and don't exist in lib/ (Horde_Form_Variable).
+ * They support the modernized PHP 8+ architecture and provide new functionality.
+ *
+ * @category Horde
+ * @package  Form
+ */
+interface VariableV3Interface
+{
+    /**
+     * Returns the validation error message.
+     *
+     * @return string  The validation error message
+     */
+    public function getMessage();
+
+    /**
+     * Gets internal property value by name.
+     *
+     * @param string $property  Property name (without underscore prefix)
+     *
+     * @return mixed  Property value, or null if not set
+     */
+    public function getProperty($property);
+
+    /**
+     * Sets internal property value by name.
+     *
+     * @param string $property  Property name (without underscore prefix)
+     * @param mixed $value      Value to set
+     */
+    public function setProperty($property, $value);
+
+    /**
+     * Initialize variable with type-specific parameters.
+     *
+     * @param mixed ...$params  Variable arguments specific to variable type
+     */
+    public function init(...$params);
+
+    /**
+     * Mark variable as invalid with error message.
+     *
+     * @param string $message  The error message
+     *
+     * @return bool  Always returns false
+     */
+    public function invalid(string $message): bool;
+
+    /**
+     * Return info about field type (metadata).
+     *
+     * @return array  Type metadata including name and parameters
+     */
+    public function about(): array;
+}

From be47b785e95ba570d07a8c6e90e2f0e3e2a26017 Mon Sep 17 00:00:00 2001
From: Ralf Lang <ralf.lang@ralf-lang.de>
Date: Sun, 8 Mar 2026 10:31:38 +0100
Subject: [PATCH 5/5] fix(test): fix global mocks and TextType init parameter
 order

Fix 2 PHP warnings in lib/ tests
Result: 6 tests that were triggering 2 PHP warnings now pass without warnings.
Avoided test dependency on horde/injector through a bit more mocking.
---
 test/unit/FormTest.php          | 38 +++++++++++++++++++++++++++++++++
 test/unit/Type/TextTypeTest.php |  4 ++--
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/test/unit/FormTest.php b/test/unit/FormTest.php
index 7720670..0f2c7a7 100644
--- a/test/unit/FormTest.php
+++ b/test/unit/FormTest.php
@@ -33,6 +33,44 @@
 #[CoversClass(Horde_Form::class)]
 class FormTest extends TestCase
 {
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        // Mock the global $injector for tests that use form tokens
+        if (!isset($GLOBALS['injector'])) {
+            $mockTokenSource = new class {
+                public function verify($token) {
+                    return true;
+                }
+            };
+
+            $GLOBALS['injector'] = new class($mockTokenSource) {
+                private $tokenSource;
+
+                public function __construct($tokenSource) {
+                    $this->tokenSource = $tokenSource;
+                }
+
+                public function getInstance($className) {
+                    if ($className === 'Horde_Token') {
+                        return $this->tokenSource;
+                    }
+                    return new \stdClass();
+                }
+            };
+        }
+
+        // Mock the global $session for tests that use form secrets
+        if (!isset($GLOBALS['session'])) {
+            $GLOBALS['session'] = new class {
+                public function get($app, $key) {
+                    return null;
+                }
+            };
+        }
+    }
+
     // ========================================================================
     // Constructor Tests
     // ========================================================================
diff --git a/test/unit/Type/TextTypeTest.php b/test/unit/Type/TextTypeTest.php
index 435b11f..6acf8e4 100644
--- a/test/unit/Type/TextTypeTest.php
+++ b/test/unit/Type/TextTypeTest.php
@@ -115,7 +115,7 @@ public function testIsValidAllowsZeroForRequiredField(): void
     public function testIsValidReturnsFalseWhenExceedsMaxLength(): void
     {
         $type = new Horde_Form_Type_text();
-        $type->init(40, 10);  // Max 10 characters
+        $type->init('', 40, 10);  // regex='', size=40, maxlength=10
 
         $var = $this->createMockVariable(false);
         $vars = new Horde_Variables();
@@ -128,7 +128,7 @@ public function testIsValidReturnsFalseWhenExceedsMaxLength(): void
     public function testIsValidReturnsTrueWhenWithinMaxLength(): void
     {
         $type = new Horde_Form_Type_text();
-        $type->init(40, 20);  // Max 20 characters
+        $type->init('', 40, 20);  // regex='', size=40, maxlength=20
 
         $var = $this->createMockVariable(false);
         $vars = new Horde_Variables();