1.0.1 2022-06-17 13:19 UTC

This package is auto-updated.

Last update: 2022-07-30 05:13:16 UTC



Yii Widget

Latest Stable Version Total Downloads Build status Scrutinizer Code Quality Code Coverage Mutation testing badge static analysis type-coverage

Widgets are reusable building blocks used to create complex and configurable user interface elements in an object-oriented fashion.

This package provides an abstract class and a factory for creating widgets, ready-made widgets are provided in the yiisoft/yii-widgets package.


The package could be installed via composer:

composer require yiisoft/widget --prefer-dist

General usage

In order to implement your own widget, you need to create a class that extends the abstract class Yiisoft\Widget\Widget. In most cases it is enough to implement run() method.

final class MyWidget extends \Yiisoft\Widget\Widget
    protected function run(): string
        return 'My first widget.'.

To get the string "My first widget." in the view, call the widget() method. Inside which the Yiisoft\Widget\WidgetFactory will create an instance of the MyWidget, and when converting the object to a string, the declared run() method will be called.

<?= MyWidget::widget() ?>

The Yiisoft\Widget\WidgetFactory factory uses a Factory instance to create widget objects, so you can require dependencies by listing them in your widget's constructor and set default values when initializing the factory. To initialize the widget factory call WidgetFactory::initialize() once before using widgets:

 * @var \Psr\Container\ContainerInterface $container
$widgetDefaults = [
    MyWidget::class => [
        'withNumber()' => [42],

\Yiisoft\Widget\WidgetFactory::initialize($container, $widgetDefaults);

It is a good idea to do that for the whole application. See Yii example in the configuration file of this package config/bootstrap.php.

Configuring the widget

You can configure the widget when creating its instance, for example, the widget class must accept some ID when initializing the object.

final class MyWidget extends \Yiisoft\Widget\Widget
    private string $id;

    public function __construct(string $id)
        $this->id = $id;

    protected function run(): string
        return $this->id;

To set a value for the ID, you can pass it in the configuration array to the widget() method:

<?= MyWidget::widget([
    '__construct()' => [
        'id' => 'value',
]) ?>

For a description of the configuration syntax, see the yiisoft/factory package documentation.

Widget for capturing content

Some widgets can take a block of content which should be enclosed between the invocation of begin() and end() methods. These are wrapping widgets that mimic opening and closing HTML tags that wrap some content. They are used a bit differently:

<?= MyWidget::widget()->begin() ?>
<?= MyWidget::end() ?>

For your widget to do this, you need override the parent begin() method and don't forget to call parent::begin():

final class MyWidget extends \Yiisoft\Widget\Widget
    public function begin(): ?string
        return null;

    protected function run(): string
        return (string) ob_get_clean();

The package ensures that all widgets are properly opened, closed and nested.

Additional methods for customizing the run

In addition to the run() method, you can override two other methods, beforeRun() and afterRun().

The beforeRun() method is called right before running the widget. The return value of the method will determine whether the widget should continue to run. When overriding this method, make sure you call the parent implementation like the following:

protected function beforeRun(): bool
    if (!parent::beforeRun()) {
       return false;

    // your custom code here

    return true; // or false to not run the widget

The afterRun() method is called right after running the widget. The return value of the method will be used as the widget return value. If you override this method, your code should look like the following:

protected function afterRun(string $result): string
    $result = parent::afterRun($result);
    // your custom code here
    return $result;


Unit testing

The package is tested with PHPUnit. To run tests:

./vendor/bin/phpunit --testdox --no-interaction

Mutation testing

The package tests are checked with Infection mutation framework with Infection Static Analysis Plugin. To run it:


Static analysis

The code is statically analyzed with Psalm. To run static analysis:



The Yii Widget is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

Support the project

Open Collective

Follow updates

Official website Twitter Telegram Facebook Slack