README

Yii Widget

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.

Requirements

PHP 8.0 - 8.5.

Installation

The package could be installed with Composer:

composer require yiisoft/widget

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 render() method.

final class MyWidget extends \Yiisoft\Widget\Widget
{
    public function render(): 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 render() 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);