DateControl supports configuration of the bootstrap library version so that you can use this either with any Bootstrap version 3.x and above. For setting up the bootstrap version for your extension, you can configure the DateControl::bsVersion property to one of the following.

• To use with bootstrap 3 library - you can set DateControl::bsVersion property to any string starting with 3 (e.g. 3 or 3.3.7 or 3.x)

• To use with bootstrap 4 library - you can set DateControl::bsVersion property to any string starting with 4 (e.g. 4 or 4.6.0 or 4.x)

• To use with bootstrap 5 library - you can set DateControl::bsVersion property to any string starting with 5 (e.g. 5 or 5.1.0 or 5.x)

'params' => [
    'bsVersion' => '5.x', // this will set globally `bsVersion` to Bootstrap 5.x for all Krajee Extensions
    // other settings
    // 'adminEmail' => 'admin@example.com'
]

"yiisoft/yii2-bootstrap5": "@dev"

"yiisoft/yii2-bootstrap4": "@dev"

"yiisoft/yii2-bootstrap": "@dev"

The yii2-datecontrol extension can be installed automatically or manually using one of these options:

$ php composer.phar require kartik-v/yii2-datecontrol "dev-master"

"kartik-v/yii2-datecontrol": "dev-master"

When working with the great Yii Framework, one of the most common observations I had was the need to have a proper control on the date settings. The date settings for each Yii application, are unique to each application and region. Most Yii developers or users almost always need an option of displaying date and time in ONE specific format, but save them to database in ANOTHER format. So to summarize, the problem statement was:

• Lack of a single configuration method to display date & times to user (or VIEW) in ONE format
• Lack of a configuration method to save date & times in database (or MODEL) in ANOTHER format

Most existing Yii solutions try to overcome the above by setting the format in model->afterFind, present in view, then unformat it in model->setAttribues or model->beforeValidate. This was still an issue when had one many models and views in the application and changes in development cycle, had to be replicated in many places (more complex scenarios being multi-regional formats).

This module helps overcome this large gap by addressing all of these at the presentational level. The module enables one to configure the date and time settings separately for DISPLAY and SAVE. This can be setup either globally or individually at each DateControl widget level. And if this is not useful enough, it automatically enables any date/time picker widgets to be used in conjunction with this.

How this magic works, is that the extension just alters this at the presentational layer (VIEW). It automatically sets the base model input to hidden and displays a mirror input in the display format one has set. Then on each edit of the display input, the extension traps the change event, and overrwrites the hidden base model input as per the desired save format. The other good thing is, that the extension automatically triggers the javascript change event for the base model input as well. Thus all client model validations and other jquery events needed by Picker widgets are automatically triggered.

The rules for deriving the display format for each type (date, datetime, or time) is validated in the following sequence:

1. if displayFormat is set in DateControl widget, it will be first used

2. else if Yii::$app->params['dateControlDisplay'] is set, it will be next used

3. else, the format as set in Module::displaySettings will be used from the DateControl Module

4. else, the format as set in Yii::$app->formatter will be used

The rules for deriving the save format for each type (date, datetime, or time) is validated in the following sequence:

1. if saveFormat is set in DateControl widget, it will be first used

2. else if Yii::$app->params['dateControlSave'] is set, it will be next used

3. else, the format as set in Module::saveSettings will be used from the DateControl Module

4. else, the format as set in Yii::$app->formatter will be used

use kartik\datecontrol\Module;
// other settings
'params' => [
    // format settings for displaying each date attribute (ICU format example)
    'dateControlDisplay' => [
        Module::FORMAT_DATE => 'dd-MM-yyyy',
        Module::FORMAT_TIME => 'hh:mm:ss a',
        Module::FORMAT_DATETIME => 'dd-MM-yyyy hh:mm:ss a', 
    ],
    
    // format settings for saving each date attribute (PHP format example)
    'dateControlSave' => [
        Module::FORMAT_DATE => 'php:U', // saves as unix timestamp
        Module::FORMAT_TIME => 'php:H:i:s',
        Module::FORMAT_DATETIME => 'php:Y-m-d H:i:s',
    ]
]

'modules' => [
   'datecontrol' =>  [
        'class' => '\kartik\datecontrol\Module'
    ]
];

• displaySettings: array, the format settings for displaying each date attribute (in the view). An associative array that need to be setup as $type => $format, where:

  • type: string, one of the following formats:

    • Module::FORMAT_DATE or 'date'.

    • Module::FORMAT_TIME or 'time'.

    • Module::FORMAT_DATETIME or 'datetime'.

  • format: string the PHP date format string

  The Yii::$app->params['dateControlDisplay'] setting will override this. If this is not set, the display settings will automatically be derived from Yii::$app->formatter based on the type setting in the DateControl widget.

• saveSettings: array, the format settings for saving each date attribute (to the model). An associative array that need to be setup as $type => $format, where:

  • type: string, one of the following formats:

    • Module::FORMAT_DATE or 'date'.

    • Module::FORMAT_TIME or 'time'.

    • Module::FORMAT_DATETIME or 'datetime'.

  • format: string the PHP date format string. Set this to 'php:U' to save it as Unix timestamp.

  The Yii::$app->params['dateControlSave'] setting will override this. If this is not set, the display settings will automatically be derived from Yii::$app->formatter based on the type setting in the DateControl widget.

• displayTimezone: string,the timezone for the displayed date. Must be one of the PHP DateTimeZone formats. If not set, no timezone setting will be applied for formatting. Note: Timezones will work only if ajaxConversion is set to true.

• saveTimezone: string,the timezone for the saved date. Must be one of the PHP DateTimeZone formats. If not set, no timezone setting will be applied for formatting. Note: Timezones will work only if ajaxConversion is set to true.

• autoWidget: boolean, whether to automatically use a preset widget from \kartik\widgets based on $type. The following widgets will be automatically set for the formats:

  • \kartik\widgets\DatePicker for Module::FORMAT_DATE

  • \kartik\widgets\TimePicker for Module::FORMAT_TIME

  • \kartik\widgets\DateTimePicker for Module::FORMAT_DATETIME

  If this is not set, it will default to true.

• widgetSettings: array, the widget settings that will be used to render the date input. NOTE: If autoWidget is true, this will be auto-generated, as explained above. An associative array that need to be setup as $type => $settings, where:

  • type: string, one of the following formats:

    • Module::FORMAT_DATE or 'date'.

    • Module::FORMAT_TIME or 'time'.

    • Module::FORMAT_DATETIME or 'datetime'.

  • settings: array which consists of these keys:

    • class: string the widget class name for the input widget that will render the date input.

    • options: array the HTML attributes for the input widget

• convertAction: string, the route/action to convert the date as per the saveFormat in DateControl widget. Defaults to '/datecontrol/parse/convert'

• ajaxConversion: boolean, whether to use ajax based date conversion from display to save formats. If set to false, the plugin will use php-date-formatter.js to convert to the set formats using client side validation. Defaults to true.

Usage

use \kartik\datecontrol\Module;
// other settings
'modules' => [
   'datecontrol' =>  [
        'class' => 'kartik\datecontrol\Module',

        // format settings for displaying each date attribute (ICU format example)
        'displaySettings' => [
            Module::FORMAT_DATE => 'dd-MM-yyyy',
            Module::FORMAT_TIME => 'hh:mm:ss a',
            Module::FORMAT_DATETIME => 'dd-MM-yyyy hh:mm:ss a', 
        ],
        
        // format settings for saving each date attribute (PHP format example)
        'saveSettings' => [
            Module::FORMAT_DATE => 'php:U', // saves as unix timestamp
            Module::FORMAT_TIME => 'php:H:i:s',
            Module::FORMAT_DATETIME => 'php:Y-m-d H:i:s',
        ],

        // set your display timezone
        'displayTimezone' => 'Asia/Kolkata',

        // set your timezone for date saved to db
        'saveTimezone' => 'UTC',
        
        // automatically use kartik\widgets for each of the above formats
        'autoWidget' => true,

        // default settings for each widget from kartik\widgets used when autoWidget is true
        'autoWidgetSettings' => [
            Module::FORMAT_DATE => ['type'=>2, 'pluginOptions'=>['autoclose'=>true]], // example
            Module::FORMAT_DATETIME => [], // setup if needed
            Module::FORMAT_TIME => [], // setup if needed
        ],
        
        // custom widget settings that will be used to render the date input instead of kartik\widgets,
        // this will be used when autoWidget is set to false at module or widget level.
        'widgetSettings' => [
            Module::FORMAT_DATE => [
                'class' => 'yii\jui\DatePicker', // example
                'options' => [
                    'dateFormat' => 'php:d-M-Y',
                    'options' => ['class'=>'form-control'],
                ]
            ]
        ]
        // other settings
    ]
]

• dateControlDisplay: array, the format settings for displaying each date attribute (in the view). An associative array that need to be setup as $type => $format, where:

  • type: string, one of the following formats:

    • Module::FORMAT_DATE or 'date'.

    • Module::FORMAT_TIME or 'time'.

    • Module::FORMAT_DATETIME or 'datetime'.

  • format: string the PHP date format string

• dateControlSave: array, the format settings for saving each date attribute (to the model). An associative array that need to be setup as $type => $format, where:

  • type: string, one of the following formats:

    • Module::FORMAT_DATE or 'date'.

    • Module::FORMAT_TIME or 'time'.

    • Module::FORMAT_DATETIME or 'datetime'.

  • format: string the PHP date format string. Set this to 'php:U' to save it as Unix timestamp.

• dateControlDisplayTimezone: string,the timezone for the displayed date. Must be one of the PHP DateTimeZone formats. If not set, no timezone setting will be applied for formatting. Note: Timezones will work only if ajaxConversion is set to true.

• dateControlSaveTimezone: string,the timezone for the saved date. Must be one of the PHP DateTimeZone formats. If not set, no timezone setting will be applied for formatting. Note: Timezones will work only if ajaxConversion is set to true.

• bsVersion: string | int, the bootstrap library version to be used for the extension. Refer the Bootstrap Info section for details and pre-requisites on setting this property.

  • To use with Bootstrap library - you can set this to any string starting with 3 (e.g. 3 or 3.3.7 or 4.x / 3.x)

  • To use with bootstrap 4 - you can set this to any string starting with 4 (e.g. 4 or 4.6.0 or 4.x)

  • To use with bootstrap 5 - you can set this to any string starting with 4 (e.g. 5 or 5.1.0 or 5.x)

• bsColCssPrefixes: array, the bootstrap grid column css prefixes mapping, the key is the bootstrap versions, and the value is an array containing the sizes and their corresponding grid column css prefixes. The class using this trait, must implement kartik\base\BootstrapInterface. If not set will default to:.

  [
     3 => [
        self::SIZE_X_SMALL => 'col-xs-',
        self::SIZE_SMALL => 'col-sm-',
        self::SIZE_MEDIUM => 'col-md-',
        self::SIZE_LARGE => 'col-lg-',
        self::SIZE_X_LARGE => 'col-lg-',
        self::SIZE_XX_LARGE => 'col-lg-',
     ],
     4 => [
        self::SIZE_X_SMALL => 'col-',
        self::SIZE_SMALL => 'col-sm-',
        self::SIZE_MEDIUM => 'col-md-',
        self::SIZE_LARGE => 'col-lg-',
        self::SIZE_X_LARGE => 'col-xl-',
        self::SIZE_XX_LARGE => 'col-xl-',
     ],
     5 => [
        self::SIZE_X_SMALL => 'col-',
        self::SIZE_SMALL => 'col-sm-',
        self::SIZE_MEDIUM => 'col-md-',
        self::SIZE_LARGE => 'col-lg-',
        self::SIZE_X_LARGE => 'col-xl-',
        self::SIZE_XX_LARGE => 'col-xxl-',
     ],
  ];
  

• language: string, the language code used for rendering the dates. This will use the language relatedconfiguration date setting formats, from the configuration in the locales folder of this extension. When autoWidget is true, this will automatically set the languages for DatePicker, DateTimePicker, or TimePicker widgets.

• type: string, data type to use for the displayed date control. Should be one of the following values:

  • DateControl::FORMAT_DATE or 'date'.

  • DateControl::FORMAT_TIME or 'time'.

  • DateControl::FORMAT_DATETIME or 'datetime'.

• displayFormat: string,the format string for displaying the date (in the view). If not set, will automatically derive this based on displaySettings in the Module based on the type setting. Note the format can be passed as a ICU format OR a PHP datetime format, exactly as in yii\i18n\Formatter. If you are passing a PHP format, prefix the format with the pattern php:.

• saveFormat: string, the format string for saving the date (to the model). If not set, will automatically derive this based on saveSettings in the Module based on the type setting. Note the format can be passed as a ICU format OR a PHP datetime format, exactly as in yii\i18n\Formatter. If you are passing a PHP format, prefix the format with the pattern php:.

• displayTimezone: string,the timezone for the displayed date. Must be one of the PHP DateTimeZone formats. If not set, no timezone setting will be applied for formatting. Note: Timezones will work only if ajaxConversion is set to true.

• saveTimezone: string,the timezone for the saved date. Must be one of the PHP DateTimeZone formats. If not set, no timezone setting will be applied for formatting. Note: Timezones will work only if ajaxConversion is set to true.

• autoWidget: boolean, whether to automatically use a preset widget from \kartik\widgets based on $type. This will override the setting at the Module level. The following widgets will be automatically set for the formats:

  • \kartik\widgets\DatePicker for Module::FORMAT_DATE

  • \kartik\widgets\TimePicker for Module::FORMAT_TIME

  • \kartik\widgets\DateTimePicker for Module::FORMAT_DATETIME

• widgetClass: string, any custom widget class to use. Will only be used if autoWidget is set to false. NOTE: A normal text input will be generated, if this is not set and autoWidget is false

• widgetOptions: string, the configuration options for the widget which will be parsed only in one of the following cases:

  • when autoWidget is true and this corresponds to widget settings for DatePicker, TimePicker, or DateTimePicker based on the type setting, OR

  • when autoWidget is false and widgetClass is set and this allows to set the configuration options for the particular widget class.

• options: string, the HTML attributes for the display input. This property is applicable and parsed only if autoWidget is false and widgetClass is NOT set or empty.

• disabled: boolean whether the input widget is to be entirely disabled. Defaults to false. Note this will disable properly if you use normal HTML inputs OR have autoWidget property set to true. For other custom widgets, this will be applied only if the widget has a disabled property.

• readonly: boolean whether the input widget is to be entirely readonly. Defaults to false. Note this will set to readonly properly if you use normal HTML inputs OR have autoWidget property set to true. For other custom widgets, this will be applied only if the widget has a readonly property.

• saveOptions: string, the HTML attributes for the base model input that will be saved typically to database. The following special options are recognized:

  • type: string whether to generate a hidden or text input. Defaults to hidden.

  • label: string any label to be placed before the input. Will be only displayed if type is set to text.

• ajaxConversion: boolean, whether to use ajax based date conversion from display to save formats. If set to false, the plugin will use php-date-formatter.js to convert to the set formats using client side validation. Defaults to true and is overridden by the value set at Module level.

• asyncRequest: boolean, whether to fire an asynchronous ajax request (applicable when ajaxConversion is set to true). Defaults to true. You can set this to false for cases, where you need this to be fired synchronously. For example, when using this widget as a filter in \kartik\grid\GridView, with a PJAX enabled grid.

• pluginOptions: array, the jQuery plugin options for the datecontrol plugin. The following options can be setup:

  • dateSettings: array, This property allows you to configure the terms used for short/long days and months, and the meridiem. This is defaulted to:

    {
        longDays: ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
        shortDays: ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
        shortMonths: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
        longMonths: ['January', 'February', 'March', 'April', 'May', 'June',
            'July', 'August', 'September', 'October', 'November', 'December'],
        meridiem: ['AM', 'PM']
    }
    

    This property will be autogenerated from the locales configuration based on the language setting. You can override this at runtime.

For the examples below, the displaySettings and saveSettings are set to the following at the module configuration level :

 // format settings for displaying each date attribute (ICU format example)
'displaySettings' => [
    Module::FORMAT_DATE => 'dd-MM-yyyy',
    Module::FORMAT_TIME => 'hh:mm:ss a',
    Module::FORMAT_DATETIME => 'dd-MM-yyyy hh:mm:ss a', 
],

// format settings for saving each date attribute (PHP format example)
'saveSettings' => [
    Module::FORMAT_DATE => 'php:U', // saves as unix timestamp
    Module::FORMAT_TIME => 'php:H:i:s',
    Module::FORMAT_DATETIME => 'php:Y-m-d H:i:s',
],

use kartik\datecontrol\DateControl;

// Use DatePicker input with ActiveForm and model validation enabled (without ajax conversion). 
echo $form->field($model, 'test_date')->widget(DateControl::classname(), [
    'type'=>DateControl::FORMAT_DATE,
    'ajaxConversion'=>false,
    'widgetOptions' => [
        'pluginOptions' => [
            'autoclose' => true
        ]
    ]
]);

// Use a DateTimePicker input with ActiveForm and model validation enabled. 
echo $form->field($model, 'datetime_1')->widget(DateControl::classname(), [
    'type'=>DateControl::FORMAT_DATETIME
]);

// Use a TimePicker input with ActiveForm and model validation enabled. 
echo $form->field($model, 'datetime_2')->widget(DateControl::classname(), [
    'type'=>DateControl::FORMAT_TIME
]);

// Use a plain text input with no model, no ActiveField validation with both custom display and save formats.
echo DateControl::widget([
    'name'=>'kartik-date', 
    'value'=>time(),
    'type'=>DateControl::FORMAT_TIME,
    'autoWidget'=>false,
    'displayFormat' => 'php:D, d-M-Y H:i:s A'
    'saveFormat' => 'php:U'
]);

//  Use a custom widget, with custom format (ICU notation), and widget options - for example the yii\widgets\MaskedInput.
echo $form->field($model, 'to_date')->widget(DateControl::classname(), [
    'displayFormat' => 'dd/MM/yyyy',
    'autoWidget' => false,
    'widgetClass' => 'yii\widgets\MaskedInput',
    'widgetOptions' => [
        'mask' => '99/99/9999'
    ],
]);

// Use different timezones for display (Pacific/Chatham) and save (UTC)
echo DateControl::widget([
    'name'=>'kartik-date-3', 
    'value'=>time(),
    'type'=>DateControl::FORMAT_DATETIME,
    'displayTimezone'=>'Pacific/Chatham',
    'saveTimezone'=>'UTC'
]);

// A disabled DateControl widget setup for time format using `kartik\widgets\TimePicker`.
echo DateControl::widget([
    'name'=>'kartik-date-3', 
    'value'=>date('H:i:s'),
    'type'=>DateControl::FORMAT_TIME,
    'disabled'=>true
]);

yii2-datecontrol is released under the BSD-3-Clause License. See the bundled LICENSE.md for details.