Allow optional jQuery in Validators and Widgets. #20528

terabytesoftw · 2025-09-15T21:36:00Z

Q	A
Is bugfix?	❌
New feature?	✔️
Breaks BC?	❌

This solution implements a way to make jQuery optional, while trying to keep BC as low as possible:

useJquery property is added to yii\base\Application, this allows you to control whether jQuery is used or not.
Gridview.
Validators.
ActiveForm.
ActiveField.
Add CDN all assets.
Add 100% test coverage.

I also think it would be a good idea to add the assets with CDN, and thus not depend on any package manager, if YII_DEBUG is true, it will be used without minification.

Minimum BC:

CheckboxColum => protected function getHeaderCheckBoxName() => public function getHeaderCheckBoxName()
ActiveField => protected function isClientValidationEnabled() => public function isClientValidationEnabled()
ActiveField => protected function isAjaxValidationEnabled() => public function isAjaxValidationEnabled()
private function buildMimeTypeRegexp($mask) => public function buildMimeTypeRegexp($mask)
private function getIpParsePattern() => public function getIpParsePattern()

// Application configuration
return [
    'useJquery' => false, // Disable jQuery globally
];

// Or dynamically
Yii::$app->useJquery = false;

// With jQuery default behavior
$form = ActiveForm::begin([]);

// Without jQuery custom client script
$form = ActiveForm::begin(['clientScript' => ActiveFormClientScript::class]);

Two interfaces have been added to add the clientScript to validators, widgets, components, etc.

<?php

declare(strict_types=1);

namespace yii\validators\client;

use yii\base\Model;
use yii\validators\Validator;
use yii\web\View;

interface ClientValidatorScriptInterface
{
    public function getClientOptions(Validator $validator, Model $model, string $attribute): array;
    public function register(Validator $validator, Model $model, string $attribute, View $view): string;
}

<?php


declare(strict_types=1);

namespace yii\web\client;

use yii\base\BaseObject;
use yii\web\View;

interface ClientScriptInterface
{
    public function getClientOptions(BaseObject $object): array;
    public function register(BaseObject $object, View $view): void;
}

Fixed generation of labels, whether custom or not, when enclosedByLabel === false, for both checkbox() and radio().

Example:

    public function testCheckboxEnclosedByLabelFalseWithCustomLabel(): void
    {
        $this->activeField->checkbox(
            [
                'label' => 'Custom Label',
                'labelOptions' => [
                    'class' => 'custom-label-class',
                    'data-test' => 'custom-label-data',
                ],
            ],
            false,
        );

        $this->assertEqualsWithoutLE(
            <<<HTML
            <div class="form-group field-activefieldtestmodel-attributename">
            <label class="custom-label-class" data-test="custom-label-data" for="activefieldtestmodel-attributename">Custom Label</label>
            <input type="hidden" name="ActiveFieldTestModel[attributeName]" value="0"><input type="checkbox" id="activefieldtestmodel-attributename" name="ActiveFieldTestModel[attributeName]" value="1">
            <div class="hint-block">Hint for attributeName attribute</div>
            <div class="help-block"></div>
            </div>
            HTML,
            $this->activeField->render(),
            'Failed asserting that checkbox renders correctly.',
        );
    }

    public function testCheckboxEnclosedByLabelFalseWithCustomLabelTag(): void
    {
        $this->activeField->checkbox(
            [
                'label' => 'Custom Label',
                'labelOptions' => [
                    'class' => 'custom-label-class',
                    'data-test' => 'custom-label-data',
                    'tag' => 'span',
                ],
            ],
            false,
        );

        $this->assertEqualsWithoutLE(
            <<<HTML
            <div class="form-group field-activefieldtestmodel-attributename">
            <span class="custom-label-class" data-test="custom-label-data">Custom Label</span>
            <input type="hidden" name="ActiveFieldTestModel[attributeName]" value="0"><input type="checkbox" id="activefieldtestmodel-attributename" name="ActiveFieldTestModel[attributeName]" value="1">
            <div class="hint-block">Hint for attributeName attribute</div>
            <div class="help-block"></div>
            </div>
            HTML,
            $this->activeField->render(),
            'Failed asserting that checkbox renders correctly.',
        );
    }

    public function testCheckboxEnclosedByLabelFalseWithCustomLabelTagFalse(): void
    {
        $this->activeField->checkbox(
            [
                'label' => 'Custom Label',
                'labelOptions' => [
                    'tag' => false,
                ],
            ],
            false,
        );

        $this->assertEqualsWithoutLE(
            <<<HTML
            <div class="form-group field-activefieldtestmodel-attributename">
            Custom Label
            <input type="hidden" name="ActiveFieldTestModel[attributeName]" value="0"><input type="checkbox" id="activefieldtestmodel-attributename" name="ActiveFieldTestModel[attributeName]" value="1">
            <div class="hint-block">Hint for attributeName attribute</div>
            <div class="help-block"></div>
            </div>
            HTML,
            $this->activeField->render(),
            'Failed asserting that checkbox renders correctly.',
        );
    }

To install the assets, i added php-forge/foxy, which i maintain and allows you to install assets easily using the composer installer. i think it would be great to use CDN to manage the assets, so we don't depend on anything external.

Issues related:

codecov · 2025-09-15T21:37:44Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 66.74%. Comparing base (9f5b6ee) to head (68e1499).
⚠️ Report is 18 commits behind head on 22.0.

Additional details and impacted files

@@             Coverage Diff              @@
##               22.0   #20528      +/-   ##
============================================
+ Coverage     65.42%   66.74%   +1.31%     
- Complexity    11266    11372     +106     
============================================
  Files           428      445      +17     
  Lines         37064    37364     +300     
============================================
+ Hits          24250    24937     +687     
+ Misses        12814    12427     -387

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…ield`, `ActiveForm`, fix customLabel for `checkbox` and `radio` methods.

…FormTest`.

…migration directories.

…implify `getClientOptions()` method.

…asset manager hash callback assignments.

…JqueryClientScript`.

…ptTest` and `ActiveFormTest` for clarity.

…ryClientScriptTest` for stricter comparison.

…ooleanValidatorJqueryClientScriptTest` for clarity.

…JqueryClientScript`.

…ryClientScript`.

… message assertions.

…age assertions and improve clarity in validation checks.

…interface implementation.

…ipt`.

samdark · 2025-09-27T10:17:59Z

framework/console/Application.php

+     *
+     * @since 2.2.0
+     */
+    public bool $useJquery = false;


I don't think it is needed. Anything breaks if it's removed?

composer.json

samdark · 2025-09-27T10:21:29Z

framework/base/Application.php

+     *
+     * @since 2.2.0
+     */
+    public bool $useJquery = true;


Should it be for web application only?

samdark · 2025-09-27T10:24:28Z

framework/validators/Validator.php

     * @return string
     */
-    protected function formatMessage($message, $params)
+    public function formatMessage($message, $params)


Why changing it to public?

framework/web/View.php

samdark · 2025-09-27T10:30:36Z

framework/widgets/ActiveField.php

     * @since 2.0.11
     */
-    protected function isClientValidationEnabled()
+    public function isClientValidationEnabled()


Why is it public now?

samdark · 2025-09-27T10:30:40Z

framework/widgets/ActiveField.php

     * @since 2.0.11
     */
-    protected function isAjaxValidationEnabled()
+    public function isAjaxValidationEnabled()


Why is it public now?

samdark · 2025-09-27T10:30:44Z

framework/widgets/ActiveField.php

     * @since 2.0.7
     */
-    protected function getInputId()
+    public function getInputId()


Why is it public now?

Copilot

Pull Request Overview

This PR introduces optional jQuery functionality for Yii2 validators and widgets, allowing developers to disable jQuery while maintaining backward compatibility. The implementation adds a useJquery property to yii\base\Application and provides alternative client script implementations that work without jQuery.

Main feature: Optional jQuery support controlled by Yii::$app->useJquery setting
Enhanced widgets: ActiveForm, ActiveField, and GridView components now support jQuery-free operation
Comprehensive validation: All core validators can function without jQuery through new client script interfaces

Reviewed Changes

Copilot reviewed 83 out of 84 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
framework/widgets/ActiveForm.php	Adds client script interface and conditional jQuery dependency
framework/widgets/ActiveField.php	Implements jQuery-optional validation and enhanced label rendering
framework/web/View.php	Updates jQuery usage to reference global application setting
framework/validators/*.php	Adds client script interfaces to all validators for jQuery independence
framework/jquery/validators/*.php	New jQuery-specific client script implementations
tests/framework/*/.php	Comprehensive test coverage for new functionality

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Allow optional jQuery in Validators, widgets and components.

8b4ca6e

terabytesoftw added 2 commits September 15, 2025 18:38

Fix tests lint.

21ee13e

Fix tests lint.

5ea9707

terabytesoftw changed the title ~~Allow optional jQuery in Validators, widgets and components.~~ Allow optional jQuery in Validators and Widgets. Sep 15, 2025

terabytesoftw added 25 commits September 15, 2025 19:04

Fix phpdoc.

921b089

Add jQuery integration flag for console application compatibility.

e0d40e7

Add code coverage 100% for ActiveFormJqueryClientScript, `ActiveF…

8748789

…ield`, `ActiveForm`, fix customLabel for `checkbox` and `radio` methods.

Update asset manager hash callback and adjust script paths in `Active…

1d6ddb9

…FormTest`.

Update composer.lock.

dbd7760

Update PHPCS configuration to exclude additional false positives and …

8a9c70a

…migration directories.

Refactor validators to return null instead of an empty string and s…

bf198b9

…implify `getClientOptions()` method.

Refactor ActiveFormTest to remove redundant server request URI and …

514f1b1

…asset manager hash callback assignments.

Add code coverage 100% for BooleanValidator and `BooleanValidator…

ddf36bf

…JqueryClientScript`.

Enhance error message assertions in `BooleanValidatorJqueryClientScri…

a43c983

…ptTest` and `ActiveFormTest` for clarity.

Replace assertEquals() with assertSame() in `BooleanValidatorJque…

16830a1

…ryClientScriptTest` for stricter comparison.

Replace variable assignment with inline instantiation of View in `B…

30d0e32

…ooleanValidatorJqueryClientScriptTest` for clarity.

Add code coverage 100% for CompareValidator and `CompareValidator…

5b8aff9

…JqueryClientScript`.

Fix PHPCs issues.

8335d95

Add code coverage 100% for EmailValidator and `EmailValidatorJque…

693eb43

…ryClientScript`.

Add coverage 100% to CompareValidator.

342e715

Refactor validation tests to improve clarity and consistency in error…

7e159cf

… message assertions.

Refactor EmailValidatorJqueryClientScriptTest to enhance error mess…

fabb1e9

…age assertions and improve clarity in validation checks.

Add code coverage 100% for FileValidatorJqueryClientScript.

67ad445

Add code coverage 100% for FilterValidatorJqueryClientScript.

5ed8f23

Refactor client script initialization in validators to ensure proper …

1b930df

…interface implementation.

Add code coverage 100% for ImageValidatorJqueryClientScript.

c4cbbb3

Fix minor corrections.

b2cda69

Fix style ci.

0175983

Add code coverage 100% for IpValidatorJqueryClientScript.

1657033

terabytesoftw added 14 commits September 20, 2025 13:27

Add code coverage 100% for NumberValidatorJqueryClientScript.

4a366ef

fix style ci.

538918f

Add code coverage 100% for RangeValidatorJqueryClientScript.

7d9bc31

Add code coverage 100% for RegularValidatorJqueryClientScriptTest.

6afa219

Add code coverage 100% for RequireValidatorJqueryClientScript.

b160cda

Add code coverage 100% for StringValidatorJqueryClientScript.

a2187a2

Add code coverage 100% for TrimValidatorJqueryClientScript.

faceade

Add code coverage 100% for UrlValidatorJqueryClientScript.

da4625e

Add code coverage 100% for GridViewJqueryClientScript.

b42e3ce

Fix minor corrections.

d8a8761

Add tests for 'getClientOptions()' method in `GridViewJqueryClientScr…

1ff3c56

…ipt`.

Add code coverage 100% for CheckboxColumnJqueryClientScript.

abab38b

Captcha widget support for vanillaJS should be added in another PR.

ca13ed9

More cleanup.

68e1499

terabytesoftw marked this pull request as ready for review September 24, 2025 14:00

samdark requested changes Sep 27, 2025

View reviewed changes

terabytesoftw added 22 Yii 2.2 type:feature labels Sep 29, 2025

samdark approved these changes Sep 29, 2025

View reviewed changes

samdark requested a review from Copilot September 29, 2025 22:34

Copilot AI reviewed Sep 29, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Allow optional jQuery in Validators and Widgets. #20528

Allow optional jQuery in Validators and Widgets. #20528

Uh oh!

terabytesoftw commented Sep 15, 2025 •

edited

Loading

Uh oh!

codecov bot commented Sep 15, 2025 •

edited

Loading

Uh oh!

samdark Sep 27, 2025

Uh oh!

Uh oh!

samdark Sep 27, 2025

Uh oh!

samdark Sep 27, 2025

Uh oh!

Uh oh!

samdark Sep 27, 2025

Uh oh!

samdark Sep 27, 2025

Uh oh!

samdark Sep 27, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Allow optional jQuery in Validators and Widgets. #20528

Are you sure you want to change the base?

Allow optional jQuery in Validators and Widgets. #20528

Uh oh!

Conversation

terabytesoftw commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

samdark Sep 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

samdark Sep 27, 2025

Choose a reason for hiding this comment

Uh oh!

samdark Sep 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

samdark Sep 27, 2025

Choose a reason for hiding this comment

Uh oh!

samdark Sep 27, 2025

Choose a reason for hiding this comment

Uh oh!

samdark Sep 27, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

terabytesoftw commented Sep 15, 2025 •

edited

Loading

codecov bot commented Sep 15, 2025 •

edited

Loading