DynamicFormModelInterface.php

<?php

/**
 * @author: Jens Giessmann <jg@handcode.de>
 *
 * @copyright: 2025, Jens Giessmann
 */

namespace handcode\dynamicFormModel;

use yii\widgets\ActiveForm;

/**
 * This interface define methods and constants which are required for DynamicFormModel instances
 * The constants are used e.g. in DynamicFormModelStruct to validate the struct and therefor are part of the interface.
 * Interface constants can be overwritten in concrete classes with PHP > 8.1
 */
interface DynamicFormModelInterface
{
    /**
     * key for the formName of the model
     * - can be used at top level of the struct
     */
    public const KEY_NAME = 'formName';

    /**
     * key of the struct array where the properties are defined
     * - can be used at top level of the struct
     */
    public const KEY_PROPERTIES = 'properties';

    /**
     * key for properties where property type can be defined
     * if not set, type 'attribute' will be used as default
     */
    public const KEY_PROPERTY_TYPE = 'type';

    /**
     * property type 'attribute' is the default type for a 'simple'
     * property which is initialized as scalar attribute inside this object
     */
    public const PROPERTY_TYPE_ATTRIBUTE = 'attribute';

    /**
     * property type 'object' can be used to define (you guessed it...) child objects
     *
     * - child objects will be static::class instances on their own, so in theory you can nest
     *   as many objects as you like.
     * - If not explicitly specified in the object, defaults such as rules and input definitions
     *   are inherited from this base model to the child model(s).
     * - formFields of the child object(s) will be grouped and assigned to fieldsets
     *   with the property name.
     */
    public const PROPERTY_TYPE_OBJECT = 'object';

    /**
     * key of the rules defined in the struct.
     * - can be used at top level of the struct to define default rules
     * - or as key in the subarray within one property definition.
     */
    public const KEY_RULES = 'rules';

    /**
     * key for the (init) value within one property definition
     */
    public const KEY_VALUE = 'value';

    /**
     * key for the attributeLabel within one property definition
     * - will be used in activeFormFields
     */
    public const KEY_LABEL = 'label';

    /**
     * key for the attributeHint within one property definition
     * - will be used in activeFormFields
     */
    public const KEY_HINT = 'hint';

    /**
     * field input type definition for the generated form
     * - can be used at top level of the struct to define default input type
     * - or as key in the subarray within on property definition
     */
    public const KEY_INPUT = 'input';

    /**
     * inputCallback definition for the generated form input
     * will be called with inputCallback(ActiveForm $form, Model $model, string $attribute, array $options) and should return the
     * ActiveForm Input.
     * - if defined, type, widget, etc. will be ignored and "the rest of the input config will be
     *   used as callback $options param
     * - can be used at top level of the struct to define default input type
     * - or as key in the subarray within on property definition
     */
    public const KEY_INPUT_CALLBACK = 'inputCallback';

    /**
     * can be used inside a self::KEY_INPUT config array to define a widgetClass name that
     * should be used as inputWidget
     * - if set, self::KEY_INPUT_TYPE will be ignored
     */
    public const KEY_INPUT_WIDGET = 'widget';

    /**
     * can be used inside a self::KEY_INPUT config array to define type for the ActiveField that
     * should be used
     * - if self::KEY_INPUT_WIDGET is defined, it will be ignored
     */
    public const KEY_INPUT_TYPE = 'type';

    /**
     * can be used inside a self::KEY_INPUT config array to define an options array that
     * should be used when initializing the input as widget or ActiveField
     */
    public const KEY_INPUT_OPTIONS = 'options';

    /**
     * can be used inside a self::KEY_INPUT config array to define the items array that
     * should be used as items param when initializing a list input like dropDownList, checkBoxList,...
     * The array is used "as is" so you have to define proper key => value pairs
     *
     * as the items array will be used as items param before options, it should only be declared IF a
     * list input defined as type!
     */
    public const KEY_INPUT_LIST_ITEMS = 'items';

    /**
     * same as KEY_INPUT_LIST_ITEMS
     * difference:
     * the given values are mapped as key => value pairs, so you can define simple arrays as items
     */
    public const KEY_INPUT_LIST_ITEM_VALUES = 'itemValues';

    /**
     * can be used
     * - at top level of the struct to define default fieldSet
     * - within property definition to group properties in different fieldSets
     * value will be the legend/name of the fieldset
     * each name will define a new fieldset when first found
     *
     * if min. one fieldset is defined, all properties without defined fieldset are ordered in a 'default' set.
     */
    public const KEY_FIELD_SET = 'fieldset';

    /**
     * can be used inside a self::KEY_INPUT config array to define a callback which will be called
     * to get the items array that should be used as items param when initializing a list input
     * like dropDownList, checkBoxList,...
     * as the items array will be used as items param before options, it should only be declared IF a
     * list input defined as type!
     */
    public const KEY_INPUT_LIST_ITEMS_CALLBACK = 'itemsCallback';

    /**
     * return the formName that is used in ActiveForms for this model
     *
     * @return string
     */
    public function formName();

    /**
     * we need a way to explicitly set the formName to control it independently of the struct
     * e.g. if one create multiple models from the same struct in one form
     *
     * @param $name
     */
    public function setFormName($name);

    /**
     * sets the struct for the model
     *
     * struct can be a php config array or a json string that can be encoded to the php config
     *
     * @param array|string $struct
     *
     * @return bool
     */
    public function setStruct(array|string $struct);

    /**
     * return the defined struct for this model
     *
     * @return null|array|string
     */
    public function getStruct();

    /**
     * ensure an array from given struct
     * - struct can be a php array -> nothing is done
     * - a json string that can be decoded to the struct array
     *
     * @param array|string $struct
     *
     * @return array|false struct array or false if not valid
     */
    public function structToArray(array|string $struct);

    /**
     * validate struct against struct specs
     * if no struct is provided as argument, struct from self::getStruct()
     * should be validated.
     *
     * if errors are found, they should be accessible via
     * self::getStructErrors()
     *
     * @param null|array|string $struct
     *
     * @return bool
     */
    public function validateStruct(array|string|null $struct = null);

    /**
     * if errors where found while validating struct with self::validateStruct(),
     * the errors (if any) will be returned as array, else (no errors or not validated) `null`
     *
     * @return null|array
     */
    public function getStructErrors();

    /**
     * get the defaultRule for each attribute that has no rule defined in struct
     *
     * @return array
     */
    public function getDefaultRules();

    /**
     * get the defaultInput config for each attribute that has no input defined in struct
     *
     * @return array
     */
    public function getDefaultInput();

    /**
     * return the ActiveForm fields for the attributes defined
     * in the struct of this model
     *
     * @param ActiveForm $form
     *
     * @return string
     */
    public function formFields(ActiveForm $form);

    /**
     * get object attributes as json from Serializer
     *
     * @return string
     */
    public function toJson();

    /**
     * default should be $this->toJson()
     */
    public function __toString();

    /**
     * return a list of valid property types
     *
     * @return string[]
     */
    public static function validPropertyTypes();
}