Yii DataView version 1.3.0 was released. In this version:

• Add GridView::keepColumnAttributesInEmptyCell() to keep column body cell attributes on empty cells
• Add GridView::filterRowAttributes(), and filterAttributes and filterClass parameters to DataColumn to set HTML attributes and a CSS class for filter cells
• Add GridView methods sortableHeaderClass(), sortableHeaderAscClass(), sortableHeaderDescClass(), sortableLinkAscClass() and sortableLinkDescClass() to configure CSS classes for sortable column headers and links
• Add GridView::captionAttributes() method and $attributes parameter to GridView::caption() to set HTML attributes for the caption tag
• Add OffsetPagination::currentLinkAttributes() and disabledLinkAttributes(), and KeysetPagination::disabledLinkAttributes() to set HTML attributes for the current page link or a disabled control, layered on top of linkAttributes()
• Add BaseListView::accessibility() that opts into automatically added accessibility attributes: scope="col" and aria-sort on GridView header cells, scope="row" on row header cells, and aria-current, aria-disabled, aria-label and role="link" on pagination links — and a rowHeader parameter to DataColumn that renders the column's body cells as <th> row headers
• Add ariaLabelNav(), ariaLabelFirst(), ariaLabelPrevious(), ariaLabelNext(), ariaLabelLast() and ariaLabelPage() methods to OffsetPagination, and ariaLabelNav(), ariaLabelPrevious() and ariaLabelNext() to KeysetPagination, to set aria-label on the nav container and page links
• Add $accessibility, $translator and $translationCategory parameters to the PaginationContext constructor and to OffsetPagination::create() and KeysetPagination::create(), and a PaginationContext::translate() method
• Make dependency container in GridView constructor optional
• Render disabled KeysetPagination controls ("previous" on the first page, "next" on the last page) as span elements instead of a elements without an href
• Render disabled OffsetPagination controls ("first"/"previous" on the first page, "next"/"last" on the last page) as span elements instead of clickable a elements
• Keep GridView and column header cell attributes when a column renders no header

Yii2 Gii Datasource Generator ¶

1. Features
2. Requirements
3. Installation
4. How it works
5. Comparison to yii2-giiant
6. License

Generate Yii2 models, search models, controllers and CRUD views for an entire database schema in one step — with connection management, live schema preview, and an ER diagram — instead of running Gii's Model and CRUD generators one table at a time.

Features ¶

• Connection registry — save multiple named database connections; each is tested live before it's stored, and persists automatically with zero manual edits to your app's config/web.php.
• Schema preview with ER diagram — see every table and view in a connection's schema, with a live entity-relationship diagram rendered from real foreign key metadata.
• Generate-all-at-once — pick the tables you want, review a single combined diff/preview screen covering every model, search model, controller, and CRUD view, then confirm once to write them all.
• Collision-safe multi-connection support — every generated class and file is prefixed with the connection's name (e.g. inventory_db → InventoryDbOrder), so two connections that both have an order table never collide, and each model is pinned to its own database connection.
• Correct relations — foreign-key-based relations between generated models point at the correct connection-prefixed class name in both directions, even across a full batch generation run.

Requirements ¶

• PHP >= 8.1
• Yii2 (yiisoft/yii2 ~2.0.45)
• yiisoft/yii2-gii ~2.2.0 (installed automatically as a dependency)
• A relational database with a yii\db\Schema driver: MySQL/MariaDB, PostgreSQL, SQL Server, SQLite, Oracle, or CUBRID. Non-relational sources are not supported in this release.

Installation ¶

Add the package with Composer:

composer require josemodi97/yii2-gii-datasource-generator

No further configuration is required — the extension registers itself into your application via Composer's extra.bootstrap mechanism on every request (the same pattern used by other zero-config Yii2 extensions), so config/web.php and config/console.php never need to be edited.

Once installed, visit /gii-datasource-generator/connection/index in your dev-environment application (access is restricted to 127.0.0.1/::1 by default, same as Gii itself — configure allowedIPs on the module if you need broader access).

How it works ¶

1. Add a connection — pick a driver, enter connection details, and it's tested live before being saved to config/gii-datasources.php (add this file to your .gitignore — it holds plaintext credentials, same trust boundary as Gii itself).
2. Preview the schema — see every table/view, with an ER diagram for relational sources.
3. Generate All — select the objects you want, review the combined file list (grouped into Models / Search Models / Controllers / Views, with inline diff/preview), then confirm.

Everything generated is placed in your app's normal models/, controllers/, and views/ folders, using the connection's name as a class/file prefix — so it's safe to run this against several databases in the same project.

Comparison to yii2-giiant ¶

yii2-giiant is the established tool for batch-generating CRUD from a schema, using the db component your app already has configured. This package targets a different scenario: managing several independent database connections in one project through a UI (rather than one connection already wired into your app config), with a schema/ER preview step before generation, and connection-prefixed naming so multiple databases' generated code can never collide.

License ¶

MIT — see LICENSE.

Yii DataView version 1.2.0 was released. In this version:

• Add prepareDataReader() to reuse filtered data reader
• Add UseInlineJsInterface::useInlineJs() to DropdownFilter, SelectPageSize and InputPageSize, and BaseListView::useInlineJs() to override it for every rendered widget, so their onChange/onchange handler can be replaced with the shipped no-inline-js.js script
• Pass DataContext to callable buttons in ActionColumn

Yii2 Rector

1. Support
2. Installation
3. Usage
4. Rules at a glance
5. Rule reference

A set of Rector rules for Yii2 projects that I put together for my own day-to-day work. They make refactoring a Yii2 codebase easier and help keep it cleaner, automating the framework-specific patterns — magic properties, ActiveRecord/Query calls, accumulated deprecations — that a generic Rector set has no way to know about.

Support ¶

If you like this project, give it a ⭐ on GitHub — it helps others discover it.

Installation ¶

[!IMPORTANT]

It works better with the latest versions of PHP, Yii2, and Rector. The more up‑to‑date the versions, the better the refactoring.

composer require --dev mspirkov/yii2-rector

Usage ¶

use MSpirkov\Yii2\Rector\Yii2SetList;
use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths(...)
    ->withSets([
        Yii2SetList::MAIN,
    ]);

Enabling individual rules ¶

Individual rules can be enabled on their own via ->withRules([...]) instead of ->withSets([...]):

use MSpirkov\Yii2\Rector\Rules\ReplaceClassnameWithClassRector;
use MSpirkov\Yii2\Rector\Rules\ReplaceExistenceCheckWithExistsRector;
use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths(...)
    ->withRules([
        ReplaceClassnameWithClassRector::class,
        ReplaceExistenceCheckWithExistsRector::class,
    ]);

Skipping rules ¶

Any rule — whether pulled in through Yii2SetList::MAIN or added individually — can be turned off entirely via ->withSkip([...]):

use MSpirkov\Yii2\Rector\Rules\MergeModelRulesRector;
use MSpirkov\Yii2\Rector\Yii2SetList;
use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths(...)
    ->withSets([
        Yii2SetList::MAIN,
    ])
    ->withSkip([
        MergeModelRulesRector::class,
    ]);

Mapping a rule to a list of paths/patterns instead skips it only there, leaving it active everywhere else — handy for legacy code that isn't ready for a particular rule yet:

    ->withSkip([
        MergeModelRulesRector::class => [
            __DIR__ . '/src/Legacy/*',
        ],
    ]);

A plain path/pattern (no rule class key) skips those files from every rule, Yii2-specific or not.

Configuring a rule ¶

AddPropertyTagsRector and RemoveRedundantPropertyTagsRector accept a skippedClasses option — see the rule reference below for the exact shape of each — and AddPropertyTagsRector additionally accepts insertBeforeTags. Configure them via ->withConfiguredRule(), using the rule's own constants as keys:

use MSpirkov\Yii2\Rector\Rules\AddPropertyTagsRector;
use MSpirkov\Yii2\Rector\Yii2SetList;
use Rector\Config\RectorConfig;

return RectorConfig::configure()
    ->withPaths(...)
    ->withSets([
        Yii2SetList::MAIN,
    ])
    ->withConfiguredRule(AddPropertyTagsRector::class, [
        'skippedClasses' => [
            'App\Models\LegacyModel',
            'App\Models\Product' => ['internalNotes'],
        ],
        'insertBeforeTags' => ['@author', '@since'],
    ]);

App\Models\LegacyModel above is skipped entirely (a plain array value), while only the internalNotes property is skipped on App\Models\Product (a class-name key mapped to a list of property names) — every other property on it is still processed normally.

Rules at a glance ¶

Rule reference ¶

AddPropertyTagsRector ¶

Add (or correct) @property/@property-read/@property-write tags on a yii\base\BaseObject subclass, based on its own getXxx()/setXxx() method pairs and ActiveRecord relation getters (hasOne()/hasMany()). A class whose __get()/__set() is overridden by something other than yii\base\BaseObject, yii\base\Component, yii\db\BaseActiveRecord, or yii\base\DynamicModel is skipped entirely, since such magic properties may not correspond to getXxx()/setXxx() methods. Configurable via skippedClasses — a plain array value (e.g. 'App\Foo') fully skips a class, while a string key mapped to a list of property names (e.g. 'App\Bar' => ['name']) skips only those properties — and insertBeforeTags, a list of PHPDoc tag names (defaulting to ['@author', '@since', '@mixin']) before which newly added @property* tags are inserted

+/**
+ * @property string $name The product name.
+ * @property-read int $price
+ * @property-write float $discount
+ */
 class Product extends BaseObject
 {
     private string $_name;

     private int $_price;

     private float $_discount;

     /**
      * @return string The product name.
      */
     public function getName(): string
     {
         return $this->_name;
     }

     /**
      * @param string $name The product name.
      */
     public function setName(string $name): void
     {
         $this->_name = $name;
     }

     public function getPrice(): int
     {
         return $this->_price;
     }

     public function setDiscount(float $discount): void
     {
         $this->_discount = $discount;
     }
 }

+/**
+ * @property-read Customer|null $customer
+ * @property-read OrderItem[] $items
+ */
 class Order extends ActiveRecord
 {
     public function getCustomer(): ActiveQuery
     {
         return $this->hasOne(Customer::class, ['id' => 'customer_id']);
     }

     public function getItems(): ActiveQuery
     {
         return $this->hasMany(OrderItem::class, ['order_id' => 'id']);
     }
 }

MergeModelRulesRector ¶

Merge yii\base\Model::rules() entries that configure the same validator with the same options but a different attribute into one entry, combining their attributes into a single array (an attribute already present in another merged entry is not duplicated). Two entries only merge when everything after the attribute(s) — the validator and any options — is identical; a rules() body that isn't a single return [...] of literal rule arrays is left untouched

 class LoginForm extends Model
 {
     public function rules(): array
     {
         return [
-            ['login', 'required'],
-            ['password', 'required'],
+            [['login', 'password'], 'required'],
         ];
     }
 }

RemoveRedundantHtmlEncodeRector ¶

Remove a yii\helpers\Html::encode() call whose $content argument PHPStan proves is a numeric string — digits only can't contain a character htmlspecialchars() would touch, so the call is replaced by its bare $content argument (dropping a trailing $doubleEncode argument, if present, too). Any other $content is left untouched

 <?php
 /**
  * @var numeric-string $id
  * @var string $name
  */
 ?>
-<?= Html::encode($id) ?>
+<?= $id ?>
 <?= Html::encode($name) ?>

RemoveRedundantPropertyTagsRector ¶

Remove a @property/@property-read/@property-write tag from a yii\base\BaseObject subclass when neither a matching public getXxx() nor setXxx() method exists (own or inherited) — typically left behind after the accessor it documented was renamed or removed. A tag backed by at least one accessor is left untouched even if it names the wrong direction (e.g. @property-read with only a setter) — correcting it to match the accessor that does exist is AddPropertyTagsRector's job, not this rule's, so the two never touch the same tag. A class whose __get()/__set() isn't the one inherited from yii\base\BaseObject or yii\base\Component — own override or inherited from some other ancestor, including yii\db\BaseActiveRecord and yii\base\DynamicModel — is skipped entirely, since its magic properties aren't necessarily backed by getter/setter methods. Configurable via skippedClasses — a plain array value (e.g. 'App\Foo') fully skips a class, while a string key mapped to a list of property names (e.g. 'App\Bar' => ['name']) skips only those properties

 /**
  * @property string $name
- * @property-read int $legacyCount
  */
 class Product extends BaseObject
 {
     private string $_name;

     public function getName(): string
     {
         return $this->_name;
     }

     public function setName(string $name): void
     {
         $this->_name = $name;
     }
 }

ReplaceClassnameWithClassRector ¶

Replace the deprecated yii\base\BaseObject::className() call with the native ::class constant. self::className() and parent::className() are left untouched, since both are late-static-binding forwarding calls not generally equivalent to self::class/parent::class once the class is subclassed — only static::className() and an explicit class name are rewritten

-$class = SomeClass::className();
-$class = static::className();
+$class = SomeClass::class;
+$class = static::class;

ReplaceExistenceCheckWithExistsRector ¶

Replace an existence check on a yii\db\QueryInterface result with the cheaper ->exists() call. Recognises a ->count() comparison against the boundary literals 0/1 (in either operand order) and a strict ->one() !== null / ->one() === null check. A check that means "no rows" (e.g. count() < 1, one() === null) is rewritten to the negated !exists(), not exists(). Only the boundary comparisons that map unambiguously onto a presence/absence question are recognised — count() > 1, for instance, is left untouched

 public function emailIsTaken(string $email): bool
 {
-    return User::find()->where(['email' => $email])->one() !== null;
+    return User::find()->where(['email' => $email])->exists();
 }

 public function emailIsAvailable(string $email): bool
 {
-    return User::find()->where(['email' => $email])->count() < 1;
+    return !User::find()->where(['email' => $email])->exists();
 }

ReplaceFindWhereAllWithFindAllRector ¶

Replace find()->where([...])->all() on an ActiveRecord class with the equivalent findAll([...]). Only fires when the where() condition is a literal array keyed entirely by string literals: findAll() treats any other condition shape (scalar, list, Expression) as a primary key lookup instead of forwarding it to where() unchanged, so those shapes are intentionally left untouched.

-$customers = Customer::find()->where(['status' => 1])->all();
+$customers = Customer::findAll(['status' => 1]);

ReplaceFindWhereOneWithFindOneRector ¶

Replace find()->where([...])->one() on an ActiveRecord class with the equivalent findOne([...]). Only fires when the where() condition is a literal array keyed entirely by string literals: findOne() treats any other condition shape (scalar, list, Expression) as a primary key lookup instead of forwarding it to where() unchanged, so those shapes are intentionally left untouched.

-$customer = Customer::find()->where(['status' => 1])->one();
+$customer = Customer::findOne(['status' => 1]);

ReplaceGetterWithPropertyRector ¶

Replace a yii\base\BaseObject getter call with the equivalent magic-property access, when the property is documented via a class-level @property or @property-read tag whose type matches the getter's return type, and there is no public native property of the same name (which would bypass the getter entirely)

 /**
  * @property-read string $prop
  */
 class Example extends BaseObject
 {
     private string $_prop;

     public function getProp(): string
     {
         return $this->_prop;
     }
 }

-$value = (new Example())->getProp();
+$value = (new Example())->prop;

ReplaceSetterWithPropertyRector ¶

Replace a yii\base\BaseObject setter call with the equivalent magic-property assignment, when the property is documented via a class-level @property or @property-write tag whose type matches the setter's parameter type, and there is no public native property of the same name (which would bypass the setter entirely)

 /**
  * @property-write string $prop
  */
 class Example extends \yii\base\BaseObject
 {
     private string $_prop;

     public function setProp(string $value): void
     {
         $this->_prop = $value;
     }
 }

-(new Example())->setProp('value');
+(new Example())->prop = 'value';

ReplaceWhereEqualityConditionWithArrayRector ¶

Replace a single-column string where()/andWhere()/orWhere() condition (interpolated or concatenated) with the safer array condition format

-$query->where("column = $value");
-$query->andWhere('column = ' . $value);
+$query->where(['column' => $value]);
+$query->andWhere(['column' => $value]);

We are very pleased to announce the release of the ApiDoc extension version 4.0.1.

This release enhances the generation:

• Recoverable HTML parsing errors in API link titles are now suppressed.
• Removed the bold formatting from the method names for better readability.
• Added <wbr> to namespaces so line breaks are made on \ if possible.

See the CHANGELOG for a full list of changes.

Twitter Bootstrap 5 Extension for Yii 2

1. Installation
2. Translations
3. Usage
4. Documentation
5. Support the project
6. Follow updates

This is the Twitter Bootstrap extension for Yii framework 2.0. It encapsulates Bootstrap 5 components and plugins in terms of Yii widgets, and thus makes using Bootstrap components/plugins in Yii applications extremely easy.

For license information check the LICENSE-file.

Documentation is at docs/guide/README.md.

Installation ¶

[!IMPORTANT]

• The minimum required PHP version is PHP 7.4.
• It works best with PHP 8.

The preferred way to install this extension is through composer.

Either run

php composer.phar require --prefer-dist yiisoft/yii2-bootstrap5

or add

"yiisoft/yii2-bootstrap5": "*"

to the require section of your composer.json file.

Translations ¶

The i18n configuration will be automatically added to your application configuration via bootstrapping process.

Usage ¶

For example, the following single line of code in a view file would render a Bootstrap Progress plugin:

<?= yii\bootstrap5\Progress::widget(['percent' => 60, 'label' => 'test']) ?>

Documentation ¶

• Internals

Support the project ¶

Follow updates ¶

Yii HTTP Middleware version 1.3.0 was released.

In this version:

• Add ETag value normalization in HttpCacheMiddleware via ETagValueNormalizerInterface with NoopETagValueNormalizer and SuffixETagValueNormalizer implementations
• Add $keepHeadersOnStatusCode and $removedHeaders constructor parameters to RemoveBodyMiddleware
• Add $removeOnStatusCode constructor parameter to ContentLengthMiddleware
• Remove Content-Length and Transfer-Encoding headers in RemoveBodyMiddleware when the body is removed
• Remove already present Content-Length header in ContentLengthMiddleware for status codes that must not carry one
• Add missing 103 Early Hints status code to default status code lists in RemoveBodyMiddleware and ContentLengthMiddleware

Yii2 Multi-Tenant Auth: How to Support Concurrent Multi-User Sessions in the Same Browser ¶

1. 1. Introduction & The Engineering Challenge
2. 2. Architecture Overview: Real-Time Dynamic Context Switching
3. 3. Step 1: The Custom User Component (common\components\User.php)
4. 4. Step 2: The Custom Session Component (common\components\Session.php)
5. 5. Step 3: Application Configuration (config/main.php)
6. 6. Key Benefits & Takeaways

A Comprehensive Guide to Multi-Context Authentication, Real-Time Context Switching, and Session Isolation in Yii2 Framework.

1. Introduction & The Engineering Challenge ¶

In modern web applications built on Yii2 Advanced Framework—such as E-Commerce platforms with a Main Admin Panel and a Merchant/Seller Portal—developers often face a critical requirement:

How can a user log into the Main Admin panel AND a Merchant portal concurrently using two different accounts in the exact same browser without session collisions?

The Core Problem: ¶

Web browsers attach the same session cookie (PHP Session ID) to every HTTP request sent to the same domain. Out of the box, Yii2 relies on a single session key ($_SESSION['__id']) to track the authenticated identity.

When a user logs into the Merchant portal in Tab 2, PHP overwrites $_SESSION['__id'] with the Merchant User ID. The moment the user refreshes Tab 1 (Admin Panel), Yii2 loads the Merchant User identity instead of the Admin, leading to broken authorization, UI glitches, or unexpected logouts.

2. Architecture Overview: Real-Time Dynamic Context Switching ¶

Rather than attempting to hack runtime session names or creating fragile beforeRequest event hooks, the optimal solution introduces a Zero Code Mutation Architecture.

By subclassing yii\web\User and yii\web\Session, we intercept authentication and session access points to perform Real-Time Dynamic Context Switching based on the request URI:

                  ┌──────────────────────────────────────────────┐
                  │                HTTP Request                  │
                  └──────────────────────┬───────────────────────┘
                                         │
                         ┌───────────────┴───────────────┐
                         │   URL Routing Context Check   │
                         └───────────────┬───────────────┘
                                         │
              ┌──────────────────────────┴──────────────────────────┐
              ▼                                                     ▼
   [ Main Admin Route ]                                   [ Merchant Module Route ]
   Context = 'admin'                                      Context = 'merchant'
   ------------------                                     ---------------------
   idParam = '__id'                                       idParam = '__id_merchant'
   Cookie  = '_identity_admin'                            Cookie  = '_identity_merchant'
   Session = $_SESSION['key']                             Session = $_SESSION['merchant_key']
   Flashes = $_SESSION['__flash']                         Flashes = $_SESSION['merchant___flash']

3. Step 1: The Custom User Component (common\components\User.php) ¶

We extend yii\web\User to dynamically evaluate the active URL route. Depending on the route context, the component updates $idParam and $identityCookie on the fly and invalidates cached identity objects when switching between tabs.

<?php

namespace common\components;

use Yii;
use yii\web\User as BaseUser;

class User extends BaseUser
{
    private $_lastContext = null;

    public function init()
    {
        $this->applyContext();
        parent::init();
    }

    /**
     * Determines the active application context based on URL path.
     */
    protected function getCurrentContext()
    {
        try {
            if (Yii::$app->has('request')) {
                $path = Yii::$app->request->getPathInfo();
                $merchantPrefix = 'merchant'; // Prefix for merchant routes

                if ($path === $merchantPrefix || strpos($path, $merchantPrefix . '/') === 0) {
                    return 'merchant';
                }
            }
        } catch (\Exception $e) {
        }
        return 'admin';
    }

    /**
     * Applies context-specific idParam and identityCookie configurations.
     */
    public function applyContext()
    {
        $context = $this->getCurrentContext();
        
        if ($this->_lastContext !== $context) {
            $env = defined('YII_ENV') ? '_' . YII_ENV : '';

            if ($context === 'merchant') {
                $this->idParam = '__id_merchant';
                $this->identityCookie = [
                    'name' => '_identity_merchant' . $env,
                    'httpOnly' => true,
                ];
            } else {
                $this->idParam = '__id';
                $this->identityCookie = [
                    'name' => '_identity_admin' . $env,
                    'httpOnly' => true,
                ];
            }

            // Invalidate identity cache when switching context
            if ($this->_lastContext !== null) {
                $this->setIdentity(null);
            }

            $this->_lastContext = $context;
        }
    }

    // Intercept entry points to ensure context is applied before execution
    public function getIdentity($autoRenew = true)
    {
        $this->applyContext();
        return parent::getIdentity($autoRenew);
    }

    public function login(\yii\web\IdentityInterface $identity, $duration = 0)
    {
        $this->applyContext();
        return parent::login($identity, $duration);
    }

    public function logout($destroySession = true)
    {
        $this->applyContext();
        return parent::logout($destroySession);
    }

    protected function renewAuthStatus()
    {
        $this->applyContext();
        parent::renewAuthStatus();
    }
}

4. Step 2: The Custom Session Component (common\components\Session.php) ¶

To prevent generic session data collisions (Yii::$app->session->set('key', $val)) and flash alert mismatches (setFlash), we subclass yii\web\Session.

This component automatically prefixes session keys and isolates flash arrays based on the active context:

<?php

namespace common\components;

use Yii;
use yii\web\Session as BaseSession;

class Session extends BaseSession
{
    /**
     * Returns key prefix based on current route context.
     */
    protected function getContextPrefix()
    {
        try {
            if (Yii::$app->has('request')) {
                $path = Yii::$app->request->getPathInfo();
                $merchantPrefix = 'merchant';

                if ($path === $merchantPrefix || strpos($path, $merchantPrefix . '/') === 0) {
                    return 'merchant_';
                }
            }
        } catch (\Exception $e) {
        }
        return '';
    }

    /**
     * Ensures session status is active before reading/writing.
     */
    protected function ensureSessionActive()
    {
        if (session_status() !== PHP_SESSION_ACTIVE) {
            @session_start();
        }
    }

    // --- Session Key Getters & Setters ---

    public function get($key, $defaultValue = null)
    {
        $this->ensureSessionActive();
        return parent::get($this->getContextPrefix() . $key, $defaultValue);
    }

    public function set($key, $value)
    {
        $this->ensureSessionActive();
        parent::set($this->getContextPrefix() . $key, $value);
    }

    public function remove($key)
    {
        $this->ensureSessionActive();
        return parent::remove($this->getContextPrefix() . $key);
    }

    public function has($key)
    {
        $this->ensureSessionActive();
        return parent::has($this->getContextPrefix() . $key);
    }

    // --- Flash Messages Isolation ---

    public function setFlash($key, $value = true, $removeAfterAccess = true)
    {
        $this->ensureSessionActive();
        $param = $this->getContextPrefix() . $this->flashParam;

        $counters = isset($_SESSION[$param]) && is_array($_SESSION[$param]) ? $_SESSION[$param] : [];
        $counters[$key] = $removeAfterAccess ? -1 : 0;
        $_SESSION[$param] = $counters;
        $_SESSION[$param][$key] = $value;
    }

    public function getFlash($key, $defaultValue = null, $delete = false)
    {
        $this->ensureSessionActive();
        $param = $this->getContextPrefix() . $this->flashParam;

        $counters = isset($_SESSION[$param]) && is_array($_SESSION[$param]) ? $_SESSION[$param] : [];
        if (!isset($counters[$key])) {
            return $defaultValue;
        }

        $value = isset($_SESSION[$param][$key]) ? $_SESSION[$param][$key] : $defaultValue;
        if ($delete) {
            $this->removeFlash($key);
        }

        return $value;
    }

    public function getAllFlashes($delete = false)
    {
        $this->ensureSessionActive();
        $param = $this->getContextPrefix() . $this->flashParam;

        $counters = isset($_SESSION[$param]) && is_array($_SESSION[$param]) ? $_SESSION[$param] : [];
        $flashes = [];
        foreach ($counters as $key => $count) {
            if (isset($_SESSION[$param][$key])) {
                $flashes[$key] = $_SESSION[$param][$key];
                if ($delete) {
                    unset($counters[$key], $_SESSION[$param][$key]);
                }
            }
        }
        if ($delete) {
            $_SESSION[$param] = $counters;
        }

        return $flashes;
    }

    public function removeFlash($key)
    {
        $this->ensureSessionActive();
        $param = $this->getContextPrefix() . $this->flashParam;

        $counters = isset($_SESSION[$param]) && is_array($_SESSION[$param]) ? $_SESSION[$param] : [];
        $value = isset($_SESSION[$param][$key]) ? $_SESSION[$param][$key] : null;
        unset($counters[$key], $_SESSION[$param][$key]);
        $_SESSION[$param] = $counters;

        return $value;
    }

    public function hasFlash($key)
    {
        return $this->getFlash($key) !== null;
    }
}

5. Step 3: Application Configuration (config/main.php) ¶

Configure your custom components in backend/config/main.php (or your relevant configuration file):

return [
    'components' => [
        // 1. Custom Session Component
        'session' => [
            'class' => 'common\components\Session',
            'timeout' => 86400 * 30,
            'name' => 'advanced_backend_session',
            'cookieParams' => [
                'httpOnly' => true,
                'secure' => false,
                'lifetime' => 3600 * 24 * 30,
            ],
        ],

        // 2. Custom User Component
        'user' => [
            'class' => 'common\components\User',
            'identityClass' => 'common\models\User',
            'enableAutoLogin' => true,
            'identityCookie' => [
                'name' => '_identity_admin',
                'httpOnly' => true,
            ],
        ],
        
        // ... rest of your application components
    ],
];

6. Key Benefits & Takeaways ¶

1. Zero Code Mutation Across Existing Project Code:
   • Developers continue calling Yii::$app->user->identity, Yii::$app->user->id, Yii::$app->session->set(), and Yii::$app->session->setFlash() standardly without modifying views, controllers, or widgets.
2. True Concurrent Multi-User Authentication:
   • Users can be signed into an Admin account in Tab 1 and a Merchant account in Tab 2 simultaneously within the same browser.
3. 100% RBAC & Cache Compatibility:
   • Standard RBAC managers (yii\rbac\DbManager or custom cached managers) key permission queries by $userId (userAccessCheck:userId:permission), preserving full isolation.

Conclusion ¶

By leveraging object-oriented extension points in Yii2's core architecture (yii\web\User and yii\web\Session), you achieve robust multi-tenant authentication and session isolation elegantly. Happy coding!

yii2-ecitizen-gateway ¶

1. Compatibility
2. Installation
3. Quickstart: Laravel
4. Quickstart: Yii2
5. Quickstart: Standalone PHP (No Framework)
6. Core Features & Usage Details
7. File & Class Structure
8. Security
9. License

A beginner-friendly Kenya eCitizen / PesaFlow payment gateway for Laravel, Yii2, and Standalone PHP. Build signed checkout payloads, render payment buttons, and verify webhook callbacks with plain-English fields.

• Framework Agnostic: Pure PHP with zero forced dependencies (php: >=7.4). Works seamlessly in Laravel, Yii2, Yii3, WordPress, or vanilla PHP.
• Laravel Auto-Discovery: Includes native EcitizenServiceProvider and Ecitizen Facade with php artisan vendor:publish support.
• Yii2 Gii Tools: Includes eCitizen Client Generator and eCitizen Controller Generator in Gii with zero view-template dependencies.
• Zero Database Obligation: Accepts and verifies payments out of the box without requiring any database tables or migrations. Bring your own database models when ready.
• Instant Payment Button: Render ready-to-use, HMAC-signed payment forms in one line of code (payButton()).
• Safaricom M-Pesa STK Push: Automatic Kenyan phone normalization (PhoneHelper) to trigger instant PIN prompts on customer phones.
• Cryptographic Signature Verification: Validate server-to-server IPN notifications with HMAC-SHA256 (verify(), isPaid()).

Compatibility ¶

• Requires PHP 7.4 or newer (fully tested on PHP 8.0, 8.1, 8.2, 8.3, and 8.4+).
• Laravel: Fully compatible with Laravel 6.x, 7.x, 8.x, 9.x, 10.x, and 11.x+.
• Yii2: Fully compatible with Yii 2.0.x and Gii code generation.
• Standalone PHP: Core classes (EcitizenClient, EcitizenGateway, PhoneHelper) have zero third-party dependencies.

Installation ¶

Install via Composer:

composer require josemodi97/yii2-ecitizen-gateway

Quickstart: Laravel ¶

The package registers its Service Provider and Ecitizen Facade automatically via Laravel Package Discovery.

1. Publish Configuration ¶

Run the Artisan publish command to create config/ecitizen.php:

php artisan vendor:publish --tag=ecitizen-config

2. Configure Environment Variables ¶

Add your merchant credentials to your .env file:

ECITIZEN_CLIENT_ID=your_api_client_id
ECITIZEN_API_KEY=your_api_key
ECITIZEN_SECRET=your_merchant_secret
ECITIZEN_SERVICE_ID=your_service_id
ECITIZEN_GATEWAY_URL=https://payments.ecitizen.go.ke/PaymentAPI/iframev2.1.php
ECITIZEN_CURRENCY=KES

3. Create a Payment Controller ¶

Use the Ecitizen Facade in your controller:

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Ecitizen; // or: use odhis\ecitizen\adapters\laravel\Facades\Ecitizen;

class PaymentController extends Controller
{
    /**
     * Display the payment summary card and pay button.
     */
    public function pay()
    {
        $payButtonHtml = Ecitizen::payButton([
            'amount'      => 1500,
            'reference'   => 'INV-1002',
            'description' => 'Land Rates Clearance',
            'name'        => 'John Doe',
            'idNumber'    => '28374619',
            'phone'       => '0712345678', // Automatically triggers Safaricom M-Pesa STK push!
            'callbackUrl' => route('payment.success'),
            'notifyUrl'   => route('payment.notify'),
        ], 'Proceed to eCitizen', ['class' => 'btn btn-success btn-lg']);

        return view('payment.pay', compact('payButtonHtml'));
    }

    /**
     * Webhook endpoint: receives server-to-server IPN from eCitizen.
     */
    public function notify(Request $request)
    {
        $result = Ecitizen::verify($request->all());

        if ($result['success']) {
            // Payment verified and settled!
            $reference  = $result['reference'];
            $amountPaid = $result['amountPaid'];

            // Optional: update your database record here
            // Order::where('reference', $reference)->update(['status' => 'paid']);

            return response()->json(['status' => 'ok']);
        }

        return response()->json(['status' => 'error', 'message' => 'Invalid signature'], 400);
    }

    /**
     * Browser redirect landing page after payment.
     */
    public function success()
    {
        return view('payment.success');
    }
}

4. Configure Routes & Exempt CSRF ¶

Because eCitizen servers send webhook notifications via POST, you must exempt the notification route from CSRF verification.

Routes (routes/web.php): ¶

use App\Http\Controllers\PaymentController;

Route::get('/payment/pay', [PaymentController::class, 'pay'])->name('payment.pay');
Route::post('/payment/notify', [PaymentController::class, 'notify'])->name('payment.notify');
Route::get('/payment/success', [PaymentController::class, 'success'])->name('payment.success');

CSRF Exemption: ¶

• Laravel 11+ (bootstrap/app.php): `php ->withMiddleware(function (Middleware $middleware) {

  $middleware->validateCsrfTokens(except: [
      'payment/notify',
  ]);
  

  }) `

• Laravel 6.x – 10.x (app/Http/Middleware/VerifyCsrfToken.php): `php protected $except = [

  'payment/notify',
  

  ]; `

5. Render in Blade View (resources/views/payment/pay.blade.php) ¶

<div class="card p-4 shadow-sm text-center">
    <h2>Invoice #INV-1002</h2>
    <p class="lead">Amount: <strong>KES 1,500</strong></p>
    <div class="mt-3">
        {!! $payButtonHtml !!}
    </div>
</div>

Quickstart: Yii2 ¶

Yii2 provides dedicated visual code generators in Gii with zero view-template dependencies.

Step 1: Client Generator (ecitizen-client) ¶

Open Gii in your browser (http://localhost/index.php?r=gii), select eCitizen Client Generator, fill in your credentials, and click Generate:

This writes @app/config/ecitizen.php:

use odhis\ecitizen\EcitizenClient;

$ecitizen = new EcitizenClient([
    'apiClientID' => 'YOUR_API_CLIENT_ID',
    'apiKey'      => 'YOUR_API_KEY',
    'secret'      => 'YOUR_SECRET',
    'serviceID'   => 'YOUR_SERVICE_ID',
]);

return $ecitizen;

Step 2: Controller Generator (ecitizen-controller) ¶

Select eCitizen Controller Generator and click Generate:

This creates @app/controllers/PaymentController.php with self-contained rendering (no separate view files needed):

• actionPay() — Displays payment summary and payment button.
• actionNotify() — Receives and cryptographically verifies server-to-server webhook notifications.
• actionSuccess() — Customer confirmation landing page.

Step 3: Making Payments in Yii2 ¶

Visit http://localhost/index.php?r=payment/pay:

Customize parameters on the fly via query parameters: http://localhost/index.php?r=payment/pay&amount=1200&description=Permit+Renewal&phone=0712345678

When payment completes, eCitizen redirects to your confirmation page:

Quickstart: Standalone PHP (No Framework) ¶

You can use the gateway directly in any vanilla PHP script or microframework:

1. Initialize Client & Render Payment Button ¶

require_once __DIR__ . '/vendor/autoload.php';

use odhis\ecitizen\EcitizenClient;

$ecitizen = new EcitizenClient([
    'apiClientID' => 'YOUR_API_CLIENT_ID',
    'apiKey'      => 'YOUR_API_KEY',
    'secret'      => 'YOUR_SECRET',
    'serviceID'   => 'YOUR_SERVICE_ID',
]);

echo $ecitizen->payButton([
    'amount'      => 500,
    'reference'   => 'INV-0001',
    'description' => 'School fees',
    'name'        => 'Jane Doe',
    'idNumber'    => '12345678',
    'phone'       => '0712345678', // Automatically formatted for M-Pesa STK push
    'callbackUrl' => 'https://example.com/payment/success',
    'notifyUrl'   => 'https://example.com/payment/notify',
]);

2. Verify Incoming Webhook (notify.php) ¶

require_once __DIR__ . '/vendor/autoload.php';

use odhis\ecitizen\EcitizenClient;

$ecitizen = new EcitizenClient([
    'apiClientID' => 'YOUR_API_CLIENT_ID',
    'apiKey'      => 'YOUR_API_KEY',
    'secret'      => 'YOUR_SECRET',
    'serviceID'   => 'YOUR_SERVICE_ID',
]);

$result = $ecitizen->verify($_POST);

header('Content-Type: application/json');

if ($result['success']) {
    $ref    = $result['reference'];   // e.g. 'INV-0001'
    $paid   = $result['amountPaid'];  // e.g. 500.00
    $status = $result['status'];      // e.g. 'Settled'

    // Update your database / log settlement...

    echo json_encode(['status' => 'ok']);
    exit;
}

http_response_code(400);
echo json_encode(['status' => 'error', 'message' => 'Signature verification failed']);

Core Features & Usage Details ¶

1. Safaricom M-Pesa STK Push ¶

When the customer provides a phone number in any common Kenyan format (0712345678, +254712345678, or 254712345678), the built-in PhoneHelper automatically normalizes it to international standard 2547XXXXXXXX and sets sendStkPush => true.

This causes eCitizen to immediately initiate an M-Pesa STK push PIN prompt on the customer's phone upon reaching the gateway.

2. Custom Checkout Form or Embedded iFrame (checkout()) ¶

If you want to render an embedded <iframe> on your page or submit via custom JavaScript instead of using payButton(), use checkout():

$checkout = $ecitizen->checkout([
    'amount'      => 2500,
    'reference'   => 'APP-4401',
    'description' => 'Building Permit',
    'name'        => 'Grace Mwangi',
    'idNumber'    => '19283746',
    'callbackUrl' => 'https://example.com/payment/success',
    'notifyUrl'   => 'https://example.com/payment/notify',
]);

// Returns:
// [
//     'url' => 'https://payments.ecitizen.go.ke/PaymentAPI/iframev2.1.php',
//     'payload' => [
//         'apiClientID'    => '...',
//         'serviceID'      => '...',
//         'billRefNumber'  => 'APP-4401',
//         'amountExpected' => '2500.00',
//         'currency'       => 'KES',
//         'secureHash'     => '...',
//         ...
//     ]
// ]

Embedded iFrame HTML Example: ¶

<iframe
    src="<?= htmlspecialchars($checkout['url'] . '?' . http_build_query($checkout['payload'])) ?>"
    width="100%"
    height="700px"
    frameborder="0"
    allow="payment">
</iframe>

3. URLs Explained: Browser Redirect vs Server Webhook ¶

eCitizen handles communication through two separate channels:

4. Bring Your Own Database (BYOD) ¶

The library does not mandate any database tables, migrations, or schema definitions. You are free to persist transactions however your project requires:

// In your notification webhook handler:
if ($result['success']) {
    // Example with Eloquent (Laravel):
    Order::where('reference', $result['reference'])->update([
        'status'      => 'paid',
        'amount_paid' => $result['amountPaid'],
    ]);

    // Example with ActiveRecord (Yii2):
    // $order = Order::findOne(['reference' => $result['reference']]);
    // if ($order) { $order->status = 'paid'; $order->save(false); }

    // Example with PDO (Vanilla PHP):
    // $stmt = $pdo->prepare("UPDATE orders SET status = 'paid' WHERE reference = ?");
    // $stmt->execute([$result['reference']]);
}

File & Class Structure ¶

Security ¶

• Sensitive credentials (API Keys, Secrets, Passwords) should always be stored in environment variables (.env).
• Never skip HMAC signature verification on inbound webhooks. Always use $ecitizen->verify($postData).
• Always exempt the notification webhook URL from CSRF middleware so eCitizen's server can deliver payment updates.

License ¶

MIT License. See LICENSE for details.

Yii Sentry version 3.0.0 was released. In this version:

• Chg #40, 41, #43: Change PHP version constraint to 8.1 - 8.5
• Bump sentry/sentry version to ^4.0
• Add support for Sentry cron monitoring via check-ins
• Add support for symfony/console version ^7.0
• Explicitly import ErrorException in "use" section of config/params.php
• Remove unused yiisoft/di dependency

The Yii website has a fresh new look!

We’ve redesigned it for clearer navigation, better readability, improved mobile support, and consistent dark mode—all while keeping the familiar Yii spirit.

Take a look and let us know what you think!

Yii auth version 3.3.0 was released. In this version:

• Split AuthenticationMethodInterface into focused authentication and challenge interfaces
• Bump minimal PHP version to 8.1
• Explicitly mark readonly properties
• Explicitly import classes and functions in "use" section
• Remove unnecessary files from Composer package
• Fix authentication scheme in HttpBearer challenge according to RFC 6750
• Fix HttpHeader authentication to correctly handle header value "0"

Yii DB Migration version 2.1.0 was released. In this version:

• Add MigrationBuilder::insertBatch() method, deprecate batchInsert()
• Explicitly import classes, functions, and constants in "use" section
• Remove unnecessary files from Composer package
• Remove confirmation prompt from migrate:create command as creating a migration is non-destructive
• Improve styling of confirmations
• Improve output of migrate:up, migrate:down, migrate:redo, migrate:new, migrate:history, and migrate:create commands: remove redundant messages, replace >>> with cleaner output, and move "Database connection" info to the top
• Use newMigrationPath and newMigrationNamespace as source
• Fix migration namespaces and paths
• Fix getNamespacePath() matching a sibling namespace as a parent

Yii-Permission ¶

1. Installation
2. Usage
3. Define your own model.conf
4. Learning Casbin
5. License

An authorization library for the Yii 3.0 PHP Framework, based on Casbin.

• Installation
  • Getting Composer package
  • Configuring application
  • Database Migration
• Usage
  • Quick start
  • Using Enforcer Api
  • Using a middleware
    • Basic Enforcer Middleware
    • HTTP Request Middleware (RESTful is also supported)
  • Using Yii3 AccessChecker ($user->can())
• Define your own model.conf
• Learning Casbin

Installation ¶

Getting Composer package ¶

Require this package in the composer.json of your Yii 3.0 project.

Note: This package requires a database driver implementation for yiisoft/db (such as yiisoft/db-mysql, yiisoft/db-sqlite, yiisoft/db-pgsql, etc.) in your application. Make sure your project has installed a database driver.

If your project doesn't have a database driver yet, install one first (for example, SQLite or MySQL): `bash composer require yiisoft/db-mysql # or yiisoft/db-sqlite or yiisoft/db-pgsql `

composer require casbin/yii-permission

Configuring application ¶

Yii-Permission automatically registers its parameters and DI container definitions via yiisoft/config.

You can customize parameters in your project's config/params.php:

return [
    'casbin/yii-permission' => [
        'model' => [
            // Available Settings: "file", "text"
            'config_type' => 'file',
            'config_file_path' => dirname(__DIR__) . '/config/casbin-basic-model.conf',
            'config_text' => '',
        ],
        'database' => [
            // Connection service ID in DI container, defaults to Yiisoft\Db\Connection\ConnectionInterface::class
            'connection' => null,
            'casbin_rules_table' => 'casbin_rule',
        ],
        'log' => [
            'enabled' => false,
            'logger' => null,
        ],
        'adapter' => \Yii\Permission\Adapter::class,
    ],
];

Database Migration ¶

casbin/yii-permission automatically registers its database migration path (src/migrations) via yiisoft/config under "db-migration".

Run the Yii 3.0 database migration command to create the casbin_rule table (requires yiisoft/db-migration in your application):

composer require yiisoft/db-migration # if not installed yet
./yii migrate:up

Troubleshooting: ConnectionInterface Not Found

If running ./yii migrate:up throws an exception: No definition or class found or resolvable for "Yiisoft\Db\Connection\ConnectionInterface"

It means your Yii 3 application has not registered a default ConnectionInterface in the DI container yet. Ensure your application's DI container (e.g. config/common/di/db.php) defines Yiisoft\Db\Connection\ConnectionInterface::class.

Alternatively, if your database connection service has a custom ID in your container, set it in config/params.php: `php 'casbin/yii-permission' => [

'database' => [
    'connection' => 'your_custom_db_service_id',
],

], `

For more details, see the Yii Database Documentation.

For custom or manual database setups, see the Migration Class File for the detailed casbin_rule table schema.

Usage ¶

Quick start ¶

In Yii 3.0, you can directly inject native \Casbin\Enforcer into your actions, controllers or services to get 100% IDE auto-completion and full type safety:

use Casbin\Enforcer;
use Psr\Http\Message\ResponseFactoryInterface;
use Psr\Http\Message\ResponseInterface;

final readonly class Action
{
    public function __construct(
        private Enforcer $enforcer,
        private ResponseFactoryInterface $responseFactory
    ) {}

    public function __invoke(): ResponseInterface
    {
        // adds permissions to a user with full IDE autocomplete
        $this->enforcer->addPermissionForUser('eve', 'articles', 'read');

        // adds a role for a user
        $this->enforcer->addRoleForUser('eve', 'writer');

        // adds permissions to a policy
        $this->enforcer->addPolicy('writer', 'articles', 'edit');

        // checks permission
        if ($this->enforcer->enforce('eve', 'articles', 'edit')) {
            // permit eve to edit articles
            $response = $this->responseFactory->createResponse();
            $response->getBody()->write('<div>permit is: true</div>');
            return $response;
        } else {
            // deny the request
            $response = $this->responseFactory->createResponse();
            $response->getBody()->write('<div>permit is: false</div>');
            return $response;
        }
    }
}

Using Enforcer Api ¶

It provides a very rich API to facilitate various operations on the Policy:

Gets all roles:

$enforcer->getAllRoles(); // ['writer', 'reader']

Gets all the authorization rules in the policy:

$enforcer->getPolicy();

Gets the roles that a user has:

$enforcer->getRolesForUser('eve'); // ['writer']

Gets the users that have a role:

$enforcer->getUsersForRole('writer'); // ['eve']

Determines whether a user has a role:

$enforcer->hasRoleForUser('eve', 'writer'); // true or false

Adds a role for a user:

$enforcer->addRoleForUser('eve', 'writer');

Adds a permission for a user or role:

// to user
$enforcer->addPermissionForUser('eve', 'articles', 'read');
// to role
$enforcer->addPermissionForUser('writer', 'articles', 'edit');

Deletes a role for a user:

$enforcer->deleteRoleForUser('eve', 'writer');

Deletes all roles for a user:

$enforcer->deleteRolesForUser('eve');

Deletes a role:

$enforcer->deleteRole('writer');

Deletes a permission:

$enforcer->deletePermission('articles', 'read'); // returns false if the permission does not exist (aka not affected).

Deletes a permission for a user or role:

$enforcer->deletePermissionForUser('eve', 'articles', 'read');

Deletes permissions for a user or role:

// to user
$enforcer->deletePermissionsForUser('eve');
// to role
$enforcer->deletePermissionsForUser('writer');

Gets permissions for a user or role:

$enforcer->getPermissionsForUser('eve'); // return array

Determines whether a user has a permission:

$enforcer->hasPermissionForUser('eve', 'articles', 'read');  // true or false

See Casbin API for more APIs.

Using a middleware ¶

casbin/yii-permission provides two PSR-15 middlewares for HTTP route access control in Yii 3.0 applications.

Basic Enforcer Middleware ¶

\Yii\Permission\Middleware\EnforcerMiddleware is used to check explicit permission parameters (e.g. resource and action). It provides an immutable withParams(array $params) method returning a cloned instance for safe route-level parameter binding.

use Yii\Permission\Middleware\EnforcerMiddleware;
use Yiisoft\Router\Route;

// Checks if current user has permission on 'articles' resource with 'read' action
Route::get('/articles')
    ->action([ArticleController::class, 'index'])
    ->middleware(
        fn (EnforcerMiddleware $middleware) => $middleware->withParams(['articles', 'read'])
    );

HTTP Request Middleware ( RESTful is also supported ) ¶

\Yii\Permission\Middleware\RequestMiddleware automatically extracts the request Path as the resource and HTTP Method as the action ($enforcer->enforce($userId, $path, $method)).

use Yii\Permission\Middleware\RequestMiddleware;
use Yiisoft\Router\Group;
use Yiisoft\Router\Route;

// Automatically checks permission based on Request Path & HTTP Method
Group::create('/api')
    ->middleware(RequestMiddleware::class)
    ->routes(
        Route::get('/posts')->action([PostController::class, 'index']),
        Route::post('/posts')->action([PostController::class, 'create'])
    );

Note: Both middlewares automatically fetch the current logged-in user ID via Yiisoft\User\CurrentUser::getId(). If your project needs automatic logged-in user resolution, you can install the yiisoft/user package: `bash composer require yiisoft/user ` If CurrentUser is not available or the user is a guest, it falls back to the user_id request attribute or 'guest'.

Using Yii3 AccessChecker ($user->can()) ¶

casbin/yii-permission provides \Yii\Permission\AccessChecker implementing Yiisoft\Access\AccessCheckerInterface.

1. Register as AccessCheckerInterface in DI Container (config/common/di/auth.php) ¶

Bind AccessCheckerInterface to AccessChecker so that Yiisoft\User\CurrentUser uses Casbin under the hood:

use Yiisoft\Access\AccessCheckerInterface;
use Yii\Permission\AccessChecker;

return [
    AccessCheckerInterface::class => AccessChecker::class,
];

2. Check Permission via $user->can() in Controllers ¶

Once registered, you can use Yii 3.0's native $user->can() method directly:

use Yiisoft\User\CurrentUser;

final readonly class PostController
{
    public function __construct(
        private CurrentUser $user
    ) {}

    public function update(): ResponseInterface
    {
        // 1. Passing resource and action as separate arguments (Recommended for Casbin)
        if ($this->user->can('articles', ['write'])) {
            // Permission granted
        }

        // 2. Or using comma-separated string format
        if ($this->user->can('articles,write')) {
            // Permission granted
        }

        // 3. Or checking a single permission string
        if ($this->user->can('updatePost')) {
            // Permission granted
        }
    }
}

Define your own model.conf ¶

You can customize your own model configuration file (e.g. casbin-basic-model.conf). For full syntax and pre-defined model examples, see Casbin Supported Models and PHP-Casbin Models.

Learning Casbin ¶

You can find the full documentation of Casbin on the website.

License ¶

This project is licensed under the Apache-2.0 License.

Yii2 eCitizen Payment Extension ¶

1. What This Package Does
2. What This Package Does Not Do
3. Compatibility
4. Installation
5. Yii2 Configuration
6. Environment Variables
7. Yii2 MVC Pattern
8. Basic Checkout Usage
9. Callback URL Building
10. Example Model: Payment Form
11. Example Controller: Checkout
12. Example View: Checkout Iframe
13. Optional Built-In Notification Controller
14. Example Callback Action In Your App
15. Notification Data
16. Query Payment Status
17. Localhost and Public Callback URLs
18. Security Notes
19. Suggested Database Fields
20. Publishing To Packagist
21. Adding To Yii Framework Extensions
22. Troubleshooting
23. Development Checks

Yii2 Composer extension for eCitizen iframe payments.

This package wraps the reusable eCitizen payment gateway parts in Yii2 components so you can call them from normal Yii2 MVC code: models/forms validate user input, controllers call Yii::$app->payments->gateway('ecitizen'), and callback actions receive eCitizen asynchronous notifications.

It is intentionally not tied to a particular housing, school, fee, banking-slip, or invoice table. Your Yii application owns the order records, customer records, payment records, and reconciliation workflow.

What This Package Does ¶

• Builds eCitizen iframe checkout payloads
• Generates the eCitizen secureHash
• Validates eCitizen notification signatures
• Extracts normalized notification data
• Queries eCitizen payment status by invoice/reference
• Builds callback URLs from the hosting Yii application
• Provides an optional notification controller
• Provides a small iframe helper view

What This Package Does Not Do ¶

• It does not create your application's invoices or orders.
• It does not update your housing, student, rent, fee, or banking tables.
• It does not decide whether a payment should be accepted.
• It does not store callbacks automatically.
• It does not reconcile paid invoices into your own accounting records.

The expected pattern is: this extension handles eCitizen communication; your application handles business logic and persistence.

Compatibility ¶

• PHP 8.0+
• Yii2 2.0.45+
• Composer package name: josemodi97/yii2-ecitizen-payment
• Yii namespace: josemodi97\ecitizen

Installation ¶

All paths in this guide are relative to the root of the Yii2 application that will use this package. For a basic Yii2 app, that is the folder that contains composer.json, config/, controllers/, models/, and views/.

After publishing to Packagist:

composer require josemodi97/yii2-ecitizen-payment

If the package is kept in a local folder, edit the consuming Yii2 app's composer.json:

Path from Yii2 app root: composer.json

{
  "repositories": [
    {
      "type": "path",
      "url": "../yii2-ecitizen-payment"
    }
  ],
  "require": {
    "josemodi97/yii2-ecitizen-payment": "*"
  }
}

Then run:

composer update josemodi97/yii2-ecitizen-payment

Yii2 Configuration ¶

Add the payment component to the Yii2 application config.

Basic Yii2 Template ¶

Add the component in:

• App config: config/web.php

Advanced Yii2 Template ¶

Add the component in each application config that needs eCitizen access:

• Frontend: frontend/config/main.php
• Backend: backend/config/main.php
• Console: console/config/main.php

'components' => [
    'payments' => [
        'class' => josemodi97\ecitizen\Payment::class,
        'gateways' => [
            'ecitizen' => [
                'class' => josemodi97\ecitizen\gateways\EcitizenGateway::class,
                'apiClientID' => getenv('ECITIZEN_API_CLIENT_ID'),
                'apiKey' => getenv('ECITIZEN_API_KEY'),
                'secret' => getenv('ECITIZEN_SECRET'),
                'serviceID' => getenv('ECITIZEN_SERVICE_ID'),
                'callbackBaseUrl' => getenv('ECITIZEN_CALLBACK_BASE_URL') ?: null,
            ],
        ],
    ],
],

callbackBaseUrl is optional in normal web requests. If it is not set, the gateway tries to derive the base URL from the current Yii request, for example https://housing.example.com. Set it explicitly for console jobs, queue workers, reverse-proxy deployments, or local development through a public HTTPS tunnel.

Full Gateway Options ¶

'ecitizen' => [
    'class' => josemodi97\ecitizen\gateways\EcitizenGateway::class,
    'apiClientID' => getenv('ECITIZEN_API_CLIENT_ID'),
    'apiKey' => getenv('ECITIZEN_API_KEY'),
    'secret' => getenv('ECITIZEN_SECRET'),
    'serviceID' => getenv('ECITIZEN_SERVICE_ID'),
    'currency' => 'KES',
    'url' => 'https://payments.ecitizen.go.ke/PaymentAPI/iframev2.1.php',
    'statusUrl' => 'https://payments.ecitizen.go.ke/api/invoice/payment/status',
    'callbackBaseUrl' => getenv('ECITIZEN_CALLBACK_BASE_URL') ?: null,
    'allowedGatewayHosts' => ['payments.ecitizen.go.ke'],
    'pictureURL' => '',
    'sendSTK' => false,
    'caBundlePath' => null,
    'timeout' => 30,
],

Environment Variables ¶

Create a .env file in the Yii2 application root if your app uses dotenv-style environment loading.

Path from Yii2 basic app root: .env

Path from Yii2 advanced project root: .env

ECITIZEN_API_CLIENT_ID=your_api_client_id
ECITIZEN_API_KEY=your_api_key
ECITIZEN_SECRET=your_secret
ECITIZEN_SERVICE_ID=your_service_id
ECITIZEN_CALLBACK_BASE_URL=https://your-domain.example

Yii2 does not load .env files by default in every template. If your application already loads .env, getenv('ECITIZEN_API_CLIENT_ID') will work as shown above. If it does not, install and bootstrap a dotenv loader in the Yii2 application, or set these variables in your server environment.

If you choose the dotenv approach, install the loader in the Yii2 application:

composer require vlucas/phpdotenv

Example using vlucas/phpdotenv in a Yii2 basic app:

Path from Yii2 app root: web/index.php

require __DIR__ . '/../vendor/autoload.php';

if (class_exists('Dotenv\\Dotenv')) {
    $dotenv = Dotenv\Dotenv::createImmutable(dirname(__DIR__));
    $dotenv->safeLoad();
}

require __DIR__ . '/../vendor/yiisoft/yii2/Yii.php';

Example using vlucas/phpdotenv in a Yii2 advanced app:

Common entry files from project root:

• Frontend: frontend/web/index.php
• Backend: backend/web/index.php
• Console: yii

Load .env before requiring common/config/bootstrap.php or before reading config files:

require __DIR__ . '/../../vendor/autoload.php';

if (class_exists('Dotenv\\Dotenv')) {
    $dotenv = Dotenv\Dotenv::createImmutable(dirname(__DIR__, 2));
    $dotenv->safeLoad();
}

Do not hard-code real eCitizen keys, secrets, service IDs, or callback URLs in code. Move all secrets to environment variables.

Yii2 MVC Pattern ¶

A clean Yii2 integration usually looks like this:

• Model or form: validates amount, invoice reference, customer name, phone, and email.
• Controller: receives the user request, creates a local pending payment record, builds the eCitizen payload, and renders the checkout.
• Callback controller action: receives eCitizen notifications and stores the raw payload.
• Service or ActiveRecord layer: marks the local order paid only after signature validation and status checks.
• Reconciliation job: rechecks pending or suspicious payments using queryPaymentStatus().

Basic Checkout Usage ¶

Place these calls inside your own controller action, service class, console command, or model method.

$gateway = Yii::$app->payments->gateway('ecitizen');

$payload = $gateway->createCheckoutPayload([
    'amount' => 1000,
    'reference' => 'INV-1001',
    'description' => 'Application fee',
    'clientName' => 'Jane Doe',
    'clientEmail' => 'jane@example.com',
    'clientPhone' => '0712345678',
]);

$gatewayUrl = $gateway->gatewayUrl();

The payload includes eCitizen fields such as:

apiClientID
amountExpected
serviceID
billRefNumber
billDesc
currency
clientMSISDN
clientName
clientEmail
callBackURLOnSuccess
notificationURL
secureHash

Post the returned payload to $gatewayUrl using a normal form or an iframe.

Callback URL Building ¶

The gateway can build callback URLs from the hosting Yii application:

$notificationUrl = Yii::$app->payments
    ->gateway('ecitizen')
    ->buildCallbackUrl('/ecitizen-payment/ecitizen-notify');

You may override the base URL for one call:

$notificationUrl = Yii::$app->payments
    ->gateway('ecitizen')
    ->buildCallbackUrl('/ecitizen-payment/ecitizen-notify', 'https://tunnel.example.com');

If you do not pass notificationURL or callBackURLOnSuccess to createCheckoutPayload(), the gateway will build defaults:

'notificationURL' => '/ecitizen-payment/ecitizen-notify'
'callBackURLOnSuccess' => '/payment/success'

The final URLs are absolute URLs based on the host Yii application.

Example Model: Payment Form ¶

Path from Yii2 app root: models/EcitizenPaymentForm.php

<?php

namespace app\models;

use yii\base\Model;

class EcitizenPaymentForm extends Model
{
    public $amount;
    public $reference;
    public $description;
    public $clientName;
    public $clientEmail;
    public $clientPhone;

    public function rules()
    {
        return [
            [['amount', 'reference', 'description', 'clientName'], 'required'],
            ['amount', 'number', 'min' => 1],
            [['reference', 'description', 'clientName', 'clientEmail', 'clientPhone'], 'trim'],
            ['reference', 'string', 'max' => 50],
            ['description', 'string', 'max' => 100],
            ['clientEmail', 'email'],
            ['clientPhone', 'string', 'max' => 20],
        ];
    }
}

Example Controller: Checkout ¶

Path from Yii2 app root: controllers/EcitizenController.php

<?php

namespace app\controllers;

use app\models\EcitizenPaymentForm;
use Yii;
use yii\web\Controller;
use yii\web\Response;

class EcitizenController extends Controller
{
    public function actionCreate()
    {
        $model = new EcitizenPaymentForm();

        if ($model->load(Yii::$app->request->post()) && $model->validate()) {
            /*
             * Save your local pending payment record before redirecting/rendering
             * checkout. The extension does not do database writes for you.
             */
            $gateway = Yii::$app->payments->gateway('ecitizen');
            $payload = $gateway->createCheckoutPayload([
                'amount' => $model->amount,
                'reference' => $model->reference,
                'description' => $model->description,
                'clientName' => $model->clientName,
                'clientEmail' => $model->clientEmail,
                'clientPhone' => $model->clientPhone,
                'notificationURL' => $gateway->buildCallbackUrl('/ecitizen-payment/ecitizen-notify'),
                'callBackURLOnSuccess' => $gateway->buildCallbackUrl('/ecitizen/success'),
            ]);

            return $this->render('checkout', [
                'gatewayUrl' => $gateway->gatewayUrl(),
                'payload' => $payload,
            ]);
        }

        return $this->render('create', [
            'model' => $model,
        ]);
    }

    public function actionSuccess()
    {
        return $this->render('success');
    }
}

Example View: Checkout Iframe ¶

Path from Yii2 app root: views/ecitizen/checkout.php

<?php

use yii\helpers\Html;

/** @var string $gatewayUrl */
/** @var array $payload */

$this->title = 'Continue to eCitizen';
?>

<h1><?= Html::encode($this->title) ?></h1>

<form id="ecitizen-checkout-form" method="post" action="<?= Html::encode($gatewayUrl) ?>" target="ecitizen-checkout-frame" autocomplete="off">
    <?php foreach ($payload as $name => $value): ?>
        <?= Html::hiddenInput((string) $name, (string) $value) ?>
    <?php endforeach; ?>
</form>

<iframe name="ecitizen-checkout-frame" title="eCitizen checkout" style="width:100%;min-height:640px;border:0"></iframe>

<?php
$this->registerJs("document.getElementById('ecitizen-checkout-form').submit();");

The package also includes a small reusable partial:

echo $this->render('@vendor/josemodi97/yii2-ecitizen-payment/views/payment/_iframe', [
    'gatewayUrl' => $gatewayUrl,
    'payload' => $payload,
    'frameName' => 'ecitizen-checkout-frame',
]);

Optional Built-In Notification Controller ¶

The package includes a lightweight controller for receiving eCitizen notifications.

Add it to your app config:

'controllerMap' => [
    'ecitizen-payment' => josemodi97\ecitizen\controllers\PaymentController::class,
],

Notification endpoint:

/ecitizen-payment/ecitizen-notify

The built-in action:

• reads POST data
• falls back to raw JSON body
• validates the eCitizen secure hash
• extracts normalized notification data
• returns JSON

It does not save to your database. For production systems, create your own callback action or extend the controller so you can store the raw payload and update your payment records.

Example Callback Action In Your App ¶

Path from Yii2 app root: controllers/EcitizenCallbackController.php

<?php

namespace app\controllers;

use Yii;
use yii\web\Controller;
use yii\web\Response;

class EcitizenCallbackController extends Controller
{
    public $enableCsrfValidation = false;

    public function actionNotify()
    {
        Yii::$app->response->format = Response::FORMAT_JSON;

        $payload = Yii::$app->request->post();
        if ($payload === []) {
            $decoded = json_decode(Yii::$app->request->rawBody, true);
            $payload = is_array($decoded) ? $decoded : [];
        }

        $gateway = Yii::$app->payments->gateway('ecitizen');
        if (!$gateway->validateNotificationHash($payload)) {
            Yii::$app->response->statusCode = 400;
            return ['success' => false, 'message' => 'Invalid eCitizen notification signature.'];
        }

        $notification = $gateway->extractNotification($payload);

        /*
         * Store the raw payload first.
         * Then find your local payment using $notification['reference'].
         * Mark it paid only if the status and amount are acceptable.
         */

        return [
            'success' => true,
            'reference' => $notification['reference'],
        ];
    }
}

Notification Data ¶

extractNotification() returns a normalized array:

[
    'provider' => 'ecitizen',
    'reference' => 'INV-1001',
    'gatewayReference' => 'ECITIZEN-INVOICE-NO',
    'amount' => 1000.00,
    'paymentDate' => '2026-07-18 12:30:00',
    'status' => 'PAID',
    'raw' => [],
]

Use:

josemodi97\ecitizen\gateways\EcitizenGateway::notificationStatusIsPaid($notification['status'])

to check common settled statuses:

PAID
SUCCESS
COMPLETED
SETTLED

Query Payment Status ¶

Use status queries for reconciliation, manual refresh buttons, cron jobs, or when a callback was missed.

$status = Yii::$app->payments
    ->gateway('ecitizen')
    ->queryPaymentStatus('INV-1001');

The extension signs the status query using:

api_client_id
client_invoice_ref
secure_hash

Your application should inspect the response and decide whether the local payment can be marked as paid.

Localhost and Public Callback URLs ¶

Callback actions belong in a web controller because eCitizen calls them over HTTPS.

localhost cannot receive eCitizen callbacks directly because it is only reachable from your own machine. For local development, expose the Yii app through a secure public HTTPS tunnel, then set:

ECITIZEN_CALLBACK_BASE_URL=https://your-tunnel-url.example

For a deployed housing application, you can omit callbackBaseUrl when Yii sees the correct public host. If the app runs behind a proxy or a queue/console command builds the payload, configure it explicitly:

ECITIZEN_CALLBACK_BASE_URL=https://your-public-url.example

Always store the raw callback payload before transforming it. This makes reconciliation much easier when eCitizen sends unexpected fields.

Security Notes ¶

• Keep callback actions CSRF-exempt because eCitizen will not send a Yii CSRF token.
• Validate the eCitizen secure hash before trusting a callback.
• Do not rely only on the user returning to the success URL.
• Treat the notification URL as the source of asynchronous payment updates.
• Re-query eCitizen before force-marking old pending payments as paid.
• Keep credentials out of Git.
• Use HTTPS for all callback URLs.
• Keep allowedGatewayHosts restricted to eCitizen hosts.
• Log failed validation attempts without logging secrets.

Suggested Database Fields ¶

Your host application can use any schema, but these fields are useful:

id
reference
amount
currency
description
customer_name
customer_email
customer_phone
gateway
gateway_reference
status
raw_checkout_payload
raw_callback_payload
created_at
paid_at
last_status_checked_at

Suggested statuses:

pending
paid
failed
cancelled
expired
review_required

Publishing To Packagist ¶

Recommended package name:

josemodi97/yii2-ecitizen-payment

Recommended Yii extension title:

Yii2 eCitizen Payment

Recommended short description:

Yii2 component for eCitizen iframe checkout, notification validation, and payment status queries.

Submit this public repository URL to Packagist:

https://github.com/JoseModi97/yii2-ecitizen-payment

Adding To Yii Framework Extensions ¶

Yii2 extensions are Composer packages. To appear correctly as a Yii extension, the package should:

• be hosted in a public VCS repository such as GitHub
• contain a valid composer.json at the repository root
• use a Yii-style package name such as josemodi97/yii2-ecitizen-payment
• set Composer package type to yii2-extension
• require yiisoft/yii2
• be registered on Packagist

This package already uses:

{
  "name": "josemodi97/yii2-ecitizen-payment",
  "type": "yii2-extension",
  "require": {
    "yiisoft/yii2": "^2.0.45"
  }
}

After the GitHub repository is pushed and Packagist has imported it, open Yii Framework Extensions:

https://www.yiiframework.com/extensions

Search for:

josemodi97/yii2-ecitizen-payment

If it does not appear immediately, wait for Packagist/Yii indexing to refresh. Yii extension discovery depends on public Composer metadata, so the Packagist package must exist first.

Recommended Yii extension title:

Yii2 eCitizen Payment

Recommended Yii extension description:

Yii2 component for eCitizen iframe checkout, notification validation, callback URL generation, and payment status queries.

Troubleshooting ¶

callbackBaseUrl is not configured ¶

This means the gateway could not derive a URL from the current Yii request. Set:

ECITIZEN_CALLBACK_BASE_URL=https://your-public-url.example

eCitizen rejects the checkout payload ¶

Check:

• apiClientID
• apiKey
• secret
• serviceID
• amount
• currency
• billRefNumber
• secureHash

Also confirm that the service ID belongs to the configured eCitizen client account.

Notification validation fails ¶

Check that the eCitizen account sending the callback uses the same apiKey and secret configured in the Yii app. Store the raw payload temporarily during testing so you can compare the received fields.

Local callbacks do not arrive ¶

Use a public HTTPS tunnel and configure:

ECITIZEN_CALLBACK_BASE_URL=https://your-tunnel-url.example

Do not use plain http://localhost for real gateway callbacks.

Development Checks ¶

Run PHP syntax checks:

php -l src/gateways/EcitizenGateway.php

Validate Composer metadata:

composer validate --no-check-publish

Yii Bulma version 1.1.0 was released. In this version:

• Bump yiisoft/html version to ^4.2.0
• Adapt configuration to changes in yiisoft/form
• Change PHP constraint in composer.json to 8.1 - 8.5
• Adopt last change yiisoft/widget
• Refactor yiisoft/html classes usage
• Explicitly import constants in "use" section
• Explicitly add transitive dependency yiisoft/files
• Add support for yiisoft/assets version ^3.0 || ^4.0 || ^5.0
• Allow yiisoft/arrays ^3.0
• Fixed publish options in assets

yii2-safaricom-daraja ¶

1. Compatibility
2. Installation
3. Quickstart: Yii2 (Dedicated Modular Gii Tools)
4. Quickstart: Laravel
5. Quickstart: Standalone PHP
6. Environment Variables
7. Basic Usage
8. Yii2 MVC Pattern
9. Example Model: STK Push Form
10. Example Controller
11. STK Push and Query
12. C2B URL Registration and Simulation
13. B2C, B2B, and B2Pochi
14. Reversal, Transaction Status, and Account Balance
15. M-Pesa Ratiba Standing Orders
16. Lipa na Bonga
17. IMSI and SWAP CheckATI
18. Pull Transactions API
19. IoT SIM Portal APIs
20. All Tools and Endpoints from the Collection
21. Endpoint Paths
22. Callback and Result URL Notes
23. Error Handling
24. Testing
25. Notes

A beginner-friendly Safaricom Daraja M-Pesa payment gateway for Yii2, Laravel, and Standalone PHP. Configure credentials directly via Gii, trigger STK Push PIN prompts on customer phones, and verify webhook callbacks with plain-English fields.

• Direct Gii Credentials Setup: Configure your Safaricom Consumer Key, Secret, Passkey, and ShortCode directly through Gii (daraja-client) — zero manual config file editing required.
• Instant Payment Controller in Gii: Generate a ready-to-use MpesaController (daraja-controller) with a built-in checkout card, webhook receiver with automatic CSRF exemption, and status querying.
• Zero Database Obligation: Trigger STK push and receive verified callbacks out of the box without requiring database migrations or tables. Bring your own database models when ready.
• Automatic Phone Normalization: Automatically converts Kenyan phone numbers (07..., 01..., +254..., 7...) into standard 254... format via PhoneHelper.
• Laravel Auto-Discovery: Includes native DarajaServiceProvider and Daraja Facade with php artisan vendor:publish support.
• Framework Agnostic & Standalone Core: Pure PHP (php: >=7.4) with zero forced framework dependencies. Works in Yii2, Laravel, WordPress, or vanilla PHP.
• Complete Safaricom API Coverage: Full support for STK Push, STK Query, C2B, B2C, B2B, Ratiba, Lipa na Bonga, Pull Transactions, IMSI/SWAP, and IoT SIM Portal APIs.

Compatibility ¶

• Requires PHP 7.4 or newer (fully tested on PHP 7.4, 8.0, 8.1, 8.2, 8.3, and 8.4+).
• Yii2: Fully compatible with Yii 2.0.x and Gii code generation.
• Laravel: Fully compatible with Laravel 6.x, 7.x, 8.x, 9.x, 10.x, and 11.x+.
• Standalone PHP: Core classes (DarajaClient, Daraja, PhoneHelper) have zero mandatory third-party dependencies.

Installation ¶

Install via Composer:

composer require josemodi97/yii2-safaricom-daraja

Quickstart: Yii2 (Dedicated Modular Gii Tools) ¶

Instead of a cluttered monolithic configuration, each Safaricom Daraja feature has its own dedicated Gii generator with its bare minimum required credentials.

Unified File Architecture: All Gii tools write into the same configuration file (@app/config/daraja.php by default). When you run any tool, it automatically pre-populates existing credentials and merges newly entered settings so previously configured keys are never overwritten or lost!

Live Gii Setup Demonstration with Blurred Credentials ¶

Here is a step-by-step walkthrough demonstrating how to configure the extension in Gii using your credentials (visually blurred in the screenshots for security):

DARAJA_CONSUMER_KEY=GKMPa04A74Wy****************************pseu
DARAJA_CONSUMER_SECRET=aUEAoECfvtKW****************************iRn
DARAJA_SHORTCODE=174379
DARAJA_PASSKEY=bfb279f9aa9b****************************c919

Step 1: Access Gii Code Generator ¶

Open http://localhost:8080/index.php?r=gii (or http://localhost/index.php?r=gii). You will see the 7 dedicated Safaricom Daraja generators ready to use:

Step 2: Configure Core API Credentials (daraja-client) ¶

Click 1. Safaricom Daraja Core API Credentials (daraja-client). Enter your Consumer Key and Consumer Secret, select your environment (Sandbox or Production), preview the generated file, and click Generate:

Your credentials are saved to @app/config/daraja.php.

Step 3: Configure M-Pesa STK Push (daraja-stk) ¶

Click 2. Safaricom M-Pesa STK Push (Express) (daraja-stk). Notice that your Core API Credentials (consumerKey and consumerSecret) are automatically pre-populated from @app/config/daraja.php!

Enter your ShortCode (174379) and Passkey, check Generate STK Payment Controller, and click Preview:

Scrolling down reveals the optional controller generator settings and the code file preview table:

Step 4: Live Generation Result & Automatic Route Setup ¶

Upon clicking Generate, Gii creates the files and displays the success alert, controller endpoints, and ready-to-use snippet:

The STK Push credentials are automatically merged into @app/config/daraja.php, and a ready-to-use controller (app\controllers\MpesaStkController) is created with checkout (/mpesa-stk/pay), webhook receiver (/mpesa-stk/callback), and query (/mpesa-stk/query) routes.

Step 5: Unified Configuration Output (@app/config/daraja.php) ¶

Both Core authentication and STK Push settings now live cleanly together in @app/config/daraja.php:

Yii::$app->daraja is automatically loaded and ready to trigger payments anywhere in your application!

Additional Feature Generators (Transactions & Balance, C2B, B2C) ¶

Why were Steps 1–5 presented first? The quickstart above deliberately spotlights the fundamental onboarding path (Authentication + STK Push) so developers can accept their first mobile money payment in under 5 minutes without wading through a massive wall of images.

However, Safaricom Daraja is modular. Each of the following specialized Gii tools automatically inherits your core credentials and writes cleanly to your unified @app/config/daraja.php:

1. Safaricom M-Pesa Transactions & Balance (daraja-transaction) ¶

Click 5. Safaricom M-Pesa Transactions & Balance to manage account balance inquiries, transaction status queries, and payment reversals. Supply your shortcode, initiator name, security credential, and optional result/timeout webhooks:

Code Usage: ¶

// Query Account Balance
$balance = Yii::$app->daraja->checkBalance([
    'remarks' => 'Daily balance check',
]);

// Query Status of Any Transaction
$status = Yii::$app->daraja->queryTransaction([
    'transactionId' => 'NLJ7RT61SV',
    'remarks'       => 'Check transaction status',
]);

// Reverse a Transaction
$reversal = Yii::$app->daraja->reverseTransaction([
    'transactionId' => 'NLJ7RT61SV',
    'amount'        => 500,
    'remarks'       => 'Refund customer overpayment',
]);

2. Safaricom M-Pesa C2B Paybill / Buy Goods Till (daraja-c2b) ¶

Click 3. Safaricom M-Pesa C2B (Paybill / Till) to register your validation and confirmation URLs, configure fallback behavior (Completed vs Cancelled), and optionally generate a dedicated MpesaC2bController:

Code Usage: ¶

// Register Validation & Confirmation URLs with Safaricom
$response = Yii::$app->daraja->c2bRegister([
    'shortCode'       => '600981',
    'responseType'    => 'Completed', // or 'Cancelled'
    'confirmationUrl' => 'https://yourdomain.com/mpesa-c2b/confirmation',
    'validationUrl'   => 'https://yourdomain.com/mpesa-c2b/validation',
]);

// Simulate C2B Payment (Sandbox only)
$sim = Yii::$app->daraja->c2bSimulate([
    'phone'     => '0708374149',
    'amount'    => 100,
    'reference' => 'INV-001',
]);

3. Safaricom M-Pesa B2C Disbursements (daraja-b2c) ¶

Click 4. Safaricom M-Pesa B2C (Disbursements) to configure automated business payouts (salaries, merchant payments, and promotional disbursements):

Code Usage: ¶

$response = Yii::$app->daraja->b2c([
    'phone'     => '0712345678',
    'amount'    => 1500,
    'commandId' => 'SalaryPayment', // Options: SalaryPayment, BusinessPayment, PromotionPayment
    'remarks'   => 'Monthly salary payout',
]);

Using Daraja in Your Code ¶

1. M-Pesa STK Push (Express) ¶

use Safaricom\Daraja\DarajaClient;

// Through the auto-registered application component:
$daraja = Yii::$app->daraja;
// or directly loading the unified config:
$daraja = require Yii::getAlias('@app/config/daraja.php');

// Trigger STK Push (Lipa Na M-Pesa Online):
$response = $daraja->stkPush([
    'phone'       => '0712345678', // Auto-normalized to 254712345678!
    'amount'      => 100,
    'reference'   => 'INV-001',
    'description' => 'Service payment',
]);

2. Verify Webhook Callbacks ¶

In your controller action (e.g. MpesaStkController::actionCallback):

public function actionCallback()
{
    Yii::$app->response->format = \yii\web\Response::FORMAT_JSON;
    $daraja = Yii::$app->daraja;

    $result = $daraja->verifyCallback(Yii::$app->request->bodyParams);

    if ($result['success']) {
        $receipt = $result['mpesaReceiptNumber']; // e.g. NLJ7RT61SV
        $amount  = $result['amount'];             // e.g. 100.00
        $phone   = $result['phone'];              // e.g. 254712345678
        // Update your order/database here...
    }

    return ['ResultCode' => 0, 'ResultDesc' => 'Accepted'];
}

3. B2C Disbursements ¶

$response = Yii::$app->daraja->b2c([
    'phone'     => '0712345678',
    'amount'    => 500,
    'commandId' => 'SalaryPayment', // or BusinessPayment, PromotionPayment
    'remarks'   => 'September salary',
]);

4. Query STK Push Transaction Status ¶

$status = Yii::$app->daraja->stkQuery('ws_CO_060920261234567890');

Quickstart: Laravel ¶

The package automatically registers its Service Provider and Daraja Facade via Laravel Package Discovery.

1. Publish Configuration ¶

php artisan vendor:publish --tag=daraja-config

2. Configure .env ¶

DARAJA_ENV=sandbox
DARAJA_CONSUMER_KEY=your_consumer_key
DARAJA_CONSUMER_SECRET=your_consumer_secret
DARAJA_PASSKEY=bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919
DARAJA_SHORTCODE=174379
DARAJA_CALLBACK_BASE_URL=https://yourdomain.com

3. Trigger STK Push & Handle Callbacks ¶

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Daraja; // or use Safaricom\Daraja\adapters\laravel\Facades\Daraja;

class PaymentController extends Controller
{
    public function pay()
    {
        $response = Daraja::stkPush([
            'phone'       => '0712345678',
            'amount'      => 100,
            'reference'   => 'INV-001',
            'description' => 'Service payment',
            'callbackUrl' => route('mpesa.callback'),
        ]);

        return response()->json($response);
    }

    public function callback(Request $request)
    {
        $result = Daraja::verifyCallback($request->all());

        if ($result['success']) {
            $receipt = $result['mpesaReceiptNumber'];
            $amount  = $result['amount'];
            // Update order status in your database...
        }

        return response()->json(['ResultCode' => 0, 'ResultDesc' => 'Accepted']);
    }
}

CSRF Exemption in Laravel: Exclude your webhook route from CSRF protection:

• Laravel 11+: Add ->validateCsrfTokens(except: ['mpesa/callback']) in bootstrap/app.php.
• Laravel 6–10: Add 'mpesa/callback' to $except in app/Http/Middleware/VerifyCsrfToken.php.

Quickstart: Standalone PHP ¶

require_once __DIR__ . '/vendor/autoload.php';

use Safaricom\Daraja\DarajaClient;

$daraja = new DarajaClient([
    'consumerKey'    => 'your_consumer_key',
    'consumerSecret' => 'your_consumer_secret',
    'passkey'        => 'your_passkey',
    'shortCode'      => '174379',
    'environment'    => 'sandbox',
]);

// 1. Trigger STK Push:
$response = $daraja->stkPush([
    'phone'       => '0712345678',
    'amount'      => 100,
    'reference'   => 'INV-001',
    'description' => 'Service payment',
    'callbackUrl' => 'https://example.com/callback.php',
]);

// 2. In callback.php:
$data = json_decode(file_get_contents('php://input'), true);
$result = $daraja->verifyCallback($data);

if ($result['success']) {
    echo "Paid! Receipt: " . $result['mpesaReceiptNumber'];
}

Environment Variables ¶

Create a .env file in the Yii2 application root if your app uses dotenv-style environment loading.

Path from Yii2 basic app root: .env

Path from Yii2 advanced project root: .env

DARAJA_ENVIRONMENT=sandbox
DARAJA_CONSUMER_KEY=your_consumer_key
DARAJA_CONSUMER_SECRET=your_consumer_secret
DARAJA_SHORT_CODE=174379
DARAJA_PASSKEY=your_lipa_na_mpesa_passkey
DARAJA_INITIATOR_NAME=your_initiator_name
DARAJA_INITIATOR_PASSWORD=your_initiator_password
DARAJA_CALLBACK_BASE_URL=https://your-domain.example
DARAJA_IOT_API_KEY=your_iot_api_key
DARAJA_IOT_MSISDN=254700000000

Yii2 does not load .env files by default in every template. If your application already loads .env, getenv('DARAJA_CONSUMER_KEY') will work as shown above. If it does not, install and bootstrap a dotenv loader in the Yii2 application, or set these variables in your server environment.

If you choose the dotenv approach, install the loader in the Yii2 application:

composer require vlucas/phpdotenv

Example using vlucas/phpdotenv in a Yii2 basic app:

Path from Yii2 app root: web/index.php

require __DIR__ . '/../vendor/autoload.php';

if (class_exists('Dotenv\\Dotenv')) {
    $dotenv = Dotenv\Dotenv::createImmutable(dirname(__DIR__));
    $dotenv->safeLoad();
}

require __DIR__ . '/../vendor/yiisoft/yii2/Yii.php';

Example using vlucas/phpdotenv in a Yii2 advanced app:

Common entry files from project root:

• Frontend: frontend/web/index.php
• Backend: backend/web/index.php
• Console: yii

Load .env before requiring common/config/bootstrap.php or before reading config files:

require __DIR__ . '/../../vendor/autoload.php';

if (class_exists('Dotenv\\Dotenv')) {
    $dotenv = Dotenv\Dotenv::createImmutable(dirname(__DIR__, 2));
    $dotenv->safeLoad();
}

Do not hard-code real consumer keys, secrets, passkeys, initiator passwords, or API keys in code. The Postman collection may contain sample values; move all secrets to environment variables.

Basic Usage ¶

Place these calls inside your own controller action, service class, console command, or model method. The MVC example below uses these paths:

• Form model: models/StkPushForm.php
• Controller: controllers/DarajaController.php
• Optional payment view: views/daraja/stk-push.php

Generate an OAuth access token:

$tokenResponse = Yii::$app->daraja->generateAccessToken();
$accessToken = $tokenResponse['access_token'];

Most API calls do not need you to pass the token manually. The component automatically generates and refreshes the bearer token when consumerKey and consumerSecret are configured.

Use named helper methods where available:

$response = Yii::$app->daraja->stkPush($payload);
$response = Yii::$app->daraja->c2bRegisterUrl($payload);
$response = Yii::$app->daraja->accountBalance($payload);

Use the generic endpoint catalog for any endpoint:

use Safaricom\Daraja\EndpointCatalog;

$response = Yii::$app->daraja->request(EndpointCatalog::PULL_QUERY, [
    'ShortCode' => Yii::$app->params['daraja.shortCode'],
    'StartDate' => '2026-07-01 00:00:00',
    'EndDate' => '2026-07-16 23:59:59',
    'OffSetValue' => '0',
]);

Yii2 MVC Pattern ¶

A clean Yii2 integration usually looks like this:

• Model or form: validates phone numbers, amount, account reference, date ranges, and required business fields.
• Controller: receives the user request, builds the Daraja payload, calls the component, and returns a Yii response.
• Callback controller action: receives Safaricom result/confirmation/validation callbacks and stores them.
• Service or ActiveRecord layer: saves payment requests, checkout request IDs, transaction IDs, and callback result codes.

Example Model: STK Push Form ¶

Create the form model.

Path from Yii2 app root: models/StkPushForm.php

<?php

namespace app\models;

use Yii;
use yii\base\Model;

class StkPushForm extends Model
{
    public $phoneNumber;
    public $amount;
    public $accountReference;
    public $transactionDesc;

    public function rules()
    {
        return [
            [['phoneNumber', 'amount', 'accountReference'], 'required'],
            ['amount', 'number', 'min' => 1],
            [['accountReference', 'transactionDesc'], 'string', 'max' => 100],
            ['phoneNumber', 'match', 'pattern' => '/^2547[0-9]{8}$/', 'message' => 'Use format 2547XXXXXXXX.'],
        ];
    }

    public function send()
    {
        if (!$this->validate()) {
            return false;
        }

        $shortCode = Yii::$app->params['daraja.shortCode'];
        $passkey = Yii::$app->params['daraja.passkey'];
        $timestamp = date('YmdHis');

        return Yii::$app->daraja->stkPush([
            'BusinessShortCode' => $shortCode,
            'Password' => Yii::$app->daraja->generateStkPassword($shortCode, $passkey, $timestamp),
            'Timestamp' => $timestamp,
            'TransactionType' => 'CustomerPayBillOnline',
            'Amount' => $this->amount,
            'PartyA' => $this->phoneNumber,
            'PartyB' => $shortCode,
            'PhoneNumber' => $this->phoneNumber,
            'CallBackURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/stk-callback'),
            'AccountReference' => $this->accountReference,
            'TransactionDesc' => $this->transactionDesc ? $this->transactionDesc : 'Payment',
        ]);
    }
}

Example Controller ¶

Create the controller.

Path from Yii2 app root: controllers/DarajaController.php

<?php

namespace app\controllers;

use Yii;
use yii\web\Controller;
use yii\web\Response;
use app\models\StkPushForm;

class DarajaController extends Controller
{
    public $enableCsrfValidation = false;

    public function actionStkPush()
    {
        Yii::$app->response->format = Response::FORMAT_JSON;

        $model = new StkPushForm();
        $model->load(Yii::$app->request->post(), '');

        if (!$model->validate()) {
            return ['ok' => false, 'errors' => $model->getErrors()];
        }

        try {
            return ['ok' => true, 'data' => $model->send()];
        } catch (\Exception $e) {
            Yii::error($e->getMessage(), __METHOD__);
            return ['ok' => false, 'message' => $e->getMessage()];
        }
    }

    public function actionStkCallback()
    {
        Yii::$app->response->format = Response::FORMAT_JSON;

        $raw = Yii::$app->request->getRawBody();
        $payload = json_decode($raw, true);

        Yii::info($payload, 'daraja.stk.callback');

        /*
         * Save the callback to your database here.
         * Common fields:
         * $payload['Body']['stkCallback']['MerchantRequestID']
         * $payload['Body']['stkCallback']['CheckoutRequestID']
         * $payload['Body']['stkCallback']['ResultCode']
         * $payload['Body']['stkCallback']['ResultDesc']
         */

        return ['ResultCode' => 0, 'ResultDesc' => 'Accepted'];
    }
}

STK Push and Query ¶

Start a Lipa na M-Pesa Online payment:

$timestamp = date('YmdHis');
$shortCode = Yii::$app->params['daraja.shortCode'];
$password = Yii::$app->daraja->generateStkPassword($shortCode, Yii::$app->params['daraja.passkey'], $timestamp);

$response = Yii::$app->daraja->stkPush([
    'BusinessShortCode' => $shortCode,
    'Password' => $password,
    'Timestamp' => $timestamp,
    'TransactionType' => 'CustomerPayBillOnline',
    'Amount' => 1,
    'PartyA' => '254700000000',
    'PartyB' => $shortCode,
    'PhoneNumber' => '254700000000',
    'CallBackURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/stk-callback'),
    'AccountReference' => 'INV-1001',
    'TransactionDesc' => 'Invoice payment',
]);

Query an STK payment using the CheckoutRequestID returned by Safaricom:

$response = Yii::$app->daraja->stkQuery([
    'BusinessShortCode' => $shortCode,
    'Password' => $password,
    'Timestamp' => $timestamp,
    'CheckoutRequestID' => 'ws_CO_...',
]);

C2B URL Registration and Simulation ¶

Put the registration/simulation calls in a controller action, console command, or service class. For example:

• Controller path from Yii2 app root: controllers/DarajaController.php
• Console command path from Yii2 app root: commands/DarajaController.php

Register confirmation and validation URLs:

$response = Yii::$app->daraja->c2bRegisterUrl([
    'ShortCode' => Yii::$app->params['daraja.shortCode'],
    'ResponseType' => 'Completed',
    'ConfirmationURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/c2b-confirmation'),
    'ValidationURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/c2b-validation'),
]);

Sandbox C2B simulation:

$response = Yii::$app->daraja->c2bSimulate([
    'ShortCode' => Yii::$app->params['daraja.shortCode'],
    'CommandID' => 'CustomerPayBillOnline',
    'Amount' => '10',
    'Msisdn' => '254700000000',
    'BillRefNumber' => 'INV-1001',
]);

Callback examples can be added as methods inside the same web controller.

Path from Yii2 app root: controllers/DarajaController.php

public function actionC2bValidation()
{
    Yii::$app->response->format = \yii\web\Response::FORMAT_JSON;
    Yii::info(json_decode(Yii::$app->request->getRawBody(), true), 'daraja.c2b.validation');

    return ['ResultCode' => 0, 'ResultDesc' => 'Accepted'];
}

public function actionC2bConfirmation()
{
    Yii::$app->response->format = \yii\web\Response::FORMAT_JSON;
    Yii::info(json_decode(Yii::$app->request->getRawBody(), true), 'daraja.c2b.confirmation');

    return ['ResultCode' => 0, 'ResultDesc' => 'Accepted'];
}

B2C, B2B, and B2Pochi ¶

Put these payout/request examples in your own service class, console command, or controller action.

Suggested paths from Yii2 app root:

• Service class: components/DarajaService.php
• Console command: commands/DarajaController.php
• Web controller: controllers/DarajaController.php

Generate a security credential from your initiator password and Safaricom public certificate:

$credential = Yii::$app->daraja->generateSecurityCredential(
    Yii::$app->params['daraja.initiatorPassword'],
    Yii::getAlias(Yii::$app->params['daraja.certificatePath'])
);

B2C payment request:

$response = Yii::$app->daraja->b2cPayment([
    'InitiatorName' => Yii::$app->params['daraja.initiatorName'],
    'SecurityCredential' => $credential,
    'CommandID' => 'BusinessPayment',
    'Amount' => '100',
    'PartyA' => Yii::$app->params['daraja.shortCode'],
    'PartyB' => '254700000000',
    'Remarks' => 'Payout',
    'QueueTimeOutURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/timeout'),
    'ResultURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/result'),
    'Occasion' => 'Refund',
]);

B2B payment request:

$response = Yii::$app->daraja->b2bPayment([
    'Initiator' => Yii::$app->params['daraja.initiatorName'],
    'SecurityCredential' => $credential,
    'CommandID' => 'BusinessPayBill',
    'SenderIdentifierType' => '4',
    'RecieverIdentifierType' => '4',
    'Amount' => '100',
    'PartyA' => Yii::$app->params['daraja.shortCode'],
    'PartyB' => '600000',
    'AccountReference' => 'INV-1001',
    'Remarks' => 'Supplier payment',
    'QueueTimeOutURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/timeout'),
    'ResultURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/result'),
]);

B2Pochi payment request:

$response = Yii::$app->daraja->b2PochiPayment([
    'OriginatorConversationID' => uniqid('b2pochi-', true),
    'InitiatorName' => Yii::$app->params['daraja.initiatorName'],
    'SecurityCredential' => $credential,
    'CommandID' => 'BusinessPayment',
    'Amount' => '100',
    'PartyA' => Yii::$app->params['daraja.shortCode'],
    'PartyB' => '254700000000',
    'Remarks' => 'B2Pochi payment',
    'QueueTimeOutURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/timeout'),
    'ResultURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/result'),
    'Occasion' => 'Payment',
]);

Reversal, Transaction Status, and Account Balance ¶

Put these examples in your own service class, console command, or controller action.

Suggested paths from Yii2 app root:

• Service class: components/DarajaService.php
• Console command: commands/DarajaController.php
• Web controller: controllers/DarajaController.php

Reverse a transaction:

$response = Yii::$app->daraja->reversal([
    'Initiator' => Yii::$app->params['daraja.initiatorName'],
    'SecurityCredential' => $credential,
    'CommandID' => 'TransactionReversal',
    'TransactionID' => 'ABC123XYZ',
    'Amount' => '100',
    'ReceiverParty' => Yii::$app->params['daraja.shortCode'],
    'RecieverIdentifierType' => '4',
    'ResultURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/result'),
    'QueueTimeOutURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/timeout'),
    'Remarks' => 'Customer refund',
    'Occasion' => 'Refund',
]);

Query transaction status:

$response = Yii::$app->daraja->transactionStatus([
    'Initiator' => Yii::$app->params['daraja.initiatorName'],
    'SecurityCredential' => $credential,
    'CommandID' => 'TransactionStatusQuery',
    'TransactionID' => 'ABC123XYZ',
    'PartyA' => Yii::$app->params['daraja.shortCode'],
    'IdentifierType' => '4',
    'ResultURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/result'),
    'QueueTimeOutURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/timeout'),
    'Remarks' => 'Status query',
    'Occasion' => 'Status',
]);

Query account balance:

$response = Yii::$app->daraja->accountBalance([
    'Initiator' => Yii::$app->params['daraja.initiatorName'],
    'SecurityCredential' => $credential,
    'CommandID' => 'AccountBalance',
    'PartyA' => Yii::$app->params['daraja.shortCode'],
    'IdentifierType' => '4',
    'Remarks' => 'Balance query',
    'QueueTimeOutURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/timeout'),
    'ResultURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/result'),
]);

M-Pesa Ratiba Standing Orders ¶

Put these examples in your own service class, console command, or controller action.

Suggested paths from Yii2 app root:

• Service class: components/DarajaService.php
• Console command: commands/DarajaController.php
• Web controller: controllers/DarajaController.php

Create a standing order for Paybill:

$response = Yii::$app->daraja->ratibaCreatePaybill([
    'StandingOrderName' => 'Monthly fee',
    'BusinessShortCode' => '174379',
    'TransactionType' => 'Standing Order Customer Pay Bill',
    'Amount' => '100',
    'PartyA' => '254700000000',
    'ReceiverPartyIdentifierType' => '4',
    'CallBackURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/ratiba-callback'),
    'AccountReference' => 'ACC-1001',
    'TransactionDesc' => 'Monthly payment',
    'Frequency' => '1',
    'StartDate' => '20260716',
    'EndDate' => '20270716',
]);

Create a standing order for Buy Goods:

$response = Yii::$app->daraja->ratibaCreateBuyGoods([
    'StandingOrderName' => 'Merchant subscription',
    'BusinessShortCode' => '300584',
    'TransactionType' => 'Standing Order Customer Pay Merchant',
    'Amount' => '100',
    'PartyA' => '254700000000',
    'ReceiverPartyIdentifierType' => '2',
    'CallBackURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/ratiba-callback'),
    'AccountReference' => 'ACC-1001',
    'TransactionDesc' => 'Merchant payment',
    'Frequency' => '1',
    'StartDate' => '20260716',
    'EndDate' => '20270716',
]);

Lipa na Bonga ¶

Put these examples in your own service class, console command, or controller action.

Suggested paths from Yii2 app root:

• Service class: components/DarajaService.php
• Console command: commands/DarajaController.php
• Web controller: controllers/DarajaController.php

Redeem Bonga points to Paybill:

$response = Yii::$app->daraja->lipaNaBongaRedeemPaybill([
    'msisdn' => '254700000000',
    'amount' => 100,
    'bongaPoints' => 500,
    'conversionRate' => 0.2,
    'shortCode' => Yii::$app->params['daraja.shortCode'],
    'accountNumber' => 'ACC-1001',
]);

Calculate points:

$response = Yii::$app->daraja->lipaNaBongaCalculatePoints([
    'points' => '500',
]);

IMSI and SWAP CheckATI ¶

Put this example in your own service class, console command, or controller action.

Suggested paths from Yii2 app root:

• Service class: components/DarajaService.php
• Console command: commands/DarajaController.php
• Web controller: controllers/DarajaController.php

$response = Yii::$app->daraja->imsiCheckAti([
    'customerNumber' => '254700000000',
]);

$response = Yii::$app->daraja->swapCheckAti([
    'customerNumber' => '254700000000',
]);

Pull Transactions API ¶

Put these examples in your own service class, console command, or controller action.

Suggested paths from Yii2 app root:

• Service class: components/DarajaService.php
• Console command: commands/DarajaController.php
• Web controller: controllers/DarajaController.php

Register a callback URL:

$response = Yii::$app->daraja->pullRegister([
    'ShortCode' => Yii::$app->params['daraja.shortCode'],
    'RequestType' => 'Pull',
    'NominatedNumber' => '254700000000',
    'CallBackURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/pull-callback'),
]);

Query transactions:

$response = Yii::$app->daraja->pullQuery([
    'ShortCode' => Yii::$app->params['daraja.shortCode'],
    'StartDate' => '2026-07-01 00:00:00',
    'EndDate' => '2026-07-16 23:59:59',
    'OffSetValue' => '0',
]);

IoT SIM Portal APIs ¶

Put these examples in your own service class, console command, or controller action.

Suggested paths from Yii2 app root:

• Service class: components/DarajaService.php
• Console command: commands/DarajaController.php
• Web controller: controllers/DarajaController.php

The IoT SIM portal endpoints from the collection use the same request() engine, but they commonly need additional headers such as x-api-key, x-source-system, X-MSISDN, X-App, and X-MessageID. Use Daraja::iot($endpointKey, $data, $headers, $query).

use Safaricom\Daraja\EndpointCatalog;

$headers = [
    'x-correlation-conversationid' => uniqid('', true),
    'x-source-system' => 'web-portal',
    'x-api-key' => getenv('DARAJA_IOT_API_KEY'),
    'Accept-Language' => 'EN',
    'X-MSISDN' => getenv('DARAJA_IOT_MSISDN'),
    'X-App' => 'web-portal',
    'X-MessageID' => uniqid('msg-', true),
];

$response = Yii::$app->daraja->iot(
    EndpointCatalog::IOT_GET_ALL_MESSAGES,
    ['vpnGroup' => 'MY-GROUP'],
    $headers,
    ['pageNo' => 1, 'pageSize' => 10]
);

The package also exposes named IoT helpers such as iotSearchMessages(), iotSendSingleMessage(), iotAllSims(), and iotSuspendUnsuspendSub(). These helpers call the same endpoints as iot() and accept the same payload/header/query style where paging is needed.

Search messages:

$response = Yii::$app->daraja->iot(
    EndpointCatalog::IOT_SEARCH_MESSAGES,
    ['searchValue' => 'hello', 'vpnGroup' => 'MY-GROUP', 'username' => 'admin'],
    $headers,
    ['pageNo' => 1, 'pageSize' => 5]
);

Send one message:

$response = Yii::$app->daraja->iot(
    EndpointCatalog::IOT_SEND_SINGLE_MESSAGE,
    [
        'msisdn' => '254700000000',
        'message' => 'Test message',
        'vpnGroup' => 'MY-GROUP',
        'username' => 'admin',
    ],
    $headers
);

SIM activation:

$response = Yii::$app->daraja->iot(
    EndpointCatalog::IOT_SIM_ACTIVATION,
    ['msisdn' => '254700000000', 'vpnGroup' => 'MY-GROUP', 'username' => 'admin'],
    $headers
);

All Tools and Endpoints from the Collection ¶

Import the constant class where you need generic access:

use Safaricom\Daraja\EndpointCatalog;

Endpoint Paths ¶

All paths use the configured base URL:

• Sandbox: https://sandbox.safaricom.co.ke
• Production: https://api.safaricom.co.ke

Callback and Result URL Notes ¶

Callback actions belong in a web controller because Safaricom calls them over HTTPS.

Suggested path from Yii2 app root: controllers/DarajaController.php

Safaricom sends many responses asynchronously. Any payload with ResultURL, QueueTimeOutURL, CallBackURL, ConfirmationURL, or ValidationURL must point to a publicly reachable HTTPS URL.

Use the component helper when building callback payload fields:

'CallBackURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/stk-callback'),
'ResultURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/result'),
'QueueTimeOutURL' => Yii::$app->daraja->buildCallbackUrl('/daraja/timeout'),

For a deployed housing application, you can omit callbackBaseUrl when Yii sees the correct public host. If the app runs behind a proxy or a queue/console command builds the payload, configure it explicitly:

DARAJA_CALLBACK_BASE_URL=https://your-public-url.example

localhost cannot receive Safaricom callbacks directly because it is only reachable from your own machine. For local development, expose the Yii app through a secure public HTTPS tunnel, then use that tunnel URL as DARAJA_CALLBACK_BASE_URL.

Always store the raw callback JSON before transforming it. This makes reconciliation much easier when Safaricom sends unexpected fields.

Error Handling ¶

Failed HTTP responses throw Safaricom\Daraja\DarajaException.

try {
    $response = Yii::$app->daraja->accountBalance($payload);
} catch (\Safaricom\Daraja\DarajaException $e) {
    Yii::error($e->getMessage(), 'daraja');
    throw $e;
}

Testing ¶

Run the package tests:

vendor/bin/phpunit

The included tests check the endpoint catalog and component behavior. Real API calls require valid Safaricom credentials and publicly reachable callback URLs.

Notes ¶

• The extension does not hard-code credentials from the Postman collection.
• Put credentials in environment variables or Yii application params.
• Keep callback actions CSRF-exempt because Safaricom will not send a Yii CSRF token.
• Keep your production and sandbox credentials separate.
• Store IDs returned by Safaricom, especially MerchantRequestID, CheckoutRequestID, ConversationID, OriginatorConversationID, and transaction IDs.

Yii2 PHPStan rules

1. Support
2. Installation
3. Configuration
4. Rules at a glance
5. Rule reference

A set of PHPStan rules for Yii2 projects that I put together for my own day-to-day work. Yii2 leans heavily on loosely-typed config arrays and magic properties/methods that PHPStan can't see through on its own, and on conventions — like keeping business logic and database access out of controllers and views — that are easy to drift from without anyone noticing. These rules catch both: they validate Yii2-specific config and structure statically, and they enforce the architectural boundaries and other code-quality checks I try to keep in a codebase. In my experience they help keep a Yii2 codebase a bit cleaner and more maintainable, but they're just my opinions turned into checks, not a universal standard — use what's useful, ignore or disable the rest.

Support ¶

If you like this project, give it a ⭐ on GitHub — it helps others discover it.

Installation ¶

[!IMPORTANT]

It works better with the latest versions of PHP, Yii2, and PHPStan. The more up-to-date the versions are, the more accurate the analysis is.

php composer.phar require --dev mspirkov/yii2-phpstan-rules

If your project uses phpstan/extension-installer, the rules are picked up automatically — nothing else to do.

Otherwise, include them manually in your phpstan.neon:

includes:
    - vendor/mspirkov/yii2-phpstan-rules/rules.neon

Configuration ¶

All rules are on by default. Turn the whole set off, turn off just one of the two rule groups, or tune individual rules, under parameters.mspirkovYii2Rules:

parameters:
    mspirkovYii2Rules:
        # Master switch — false disables every rule below
        enableAllRules: false

        # Covers just the `*Validation` rules (config/shape checks like modelRulesValidation,
        # componentBehaviorsValidation, activeQueryWithValidation, ...) — defaults to
        # enableAllRules, so setting it only makes sense when it should differ. Here it keeps
        # static config validation on while the `no*` code-quality rules stay off.
        enableValidationRules: true

        # Component IDs treated as "the database" by the DB-access rules
        yiiAppDbProperties:
            - db

        # Classes to skip in config-array validation (unknown option / wrong option type
        # checks) — shared by every rule that validates a class against a config array:
        # baseObjectInstantiationValidation, yiiCreateObjectValidation,
        # componentBehaviorsValidation, controllerActionsValidation,
        # widgetPropertiesValidation, and modelRulesValidation. Useful when a class's
        # constructor consumes some config keys itself instead of leaving them for
        # Yii::configure() to apply to a public, checkable property.
        # Omit "attributes" to skip the class entirely; list them to skip only those options.
        baseObjectConfigValidation:
            skippedClasses:
                -
                    class: app\payment\PaymentGateway
                    attributes:
                        - retryPolicy
                -
                    class: app\sdk\ThirdPartySdkClient

        # Thresholds for the complexity rules — exceeding any one flags the method
        actionComplexity:
            ifCount: 3
            foreachCount: 0
            forCount: 0
            whileCount: 0
            doWhileCount: 0
            switchCount: 0
            matchCount: 0
            ternaryCount: 1
            tryCatchCount: 1

        # Yii application properties allowed to be read anywhere (e.g. request-agnostic settings)
        noForbiddenYiiAppProperties:
            allowedProperties:
                - id
                - name
                - charset
                - language
                - timeZone

        # Project-specific model validator aliases
        modelRulesValidation:
            customValidators:
                slug: app\validators\SlugValidator

        # Disable a single rule without touching the rest
        noDynamicQueryWhere:
            enabled: false

Rules at a glance ¶

Validation rules ¶

Statically validate Yii2's loosely-typed config arrays and array-driven conventions — shapes PHPStan can't check on its own because they only take effect at runtime. Toggle all of them at once with enableValidationRules.

Code quality rules ¶

Catch architectural drift, complexity, and other code-quality issues that are easy to miss without anyone noticing — business logic and database access staying out of controllers and views, actions calling other actions directly, superglobals, dynamic SQL, an Application object that anything can read from or write to, and calls that are provably redundant.

Rule reference ¶

Validation rules ¶

Active Form field validation ¶

ActiveForm::field($model, $attribute) binds an editable input to the attribute: it reads the current value to render the input, and writes the submitted value back to the model on load(). This rule checks that the attribute is both readable and writable — a declared (non-readonly) property, a PHPDoc @property, or a matching getter/setter pair — and reports it whether it's missing entirely or only exists as read-only or write-only. yii\base\DynamicModel instances (and subclasses) are skipped entirely, since their attributes are defined at runtime via defineAttribute() and can't be resolved statically.

/**
 * @property string $email
 * @property-read string $fullName
 */
final class ContactModel extends Model
{
    public $name;

    public function getPhone(): string { /* ... */ }

    public function setPhone(string $phone): void { /* ... */ }
}

/** @var ContactModel $model */

$form = ActiveForm::begin();

echo $form->field($model, 'name');     // ✓ declared property
echo $form->field($model, 'email');    // ✓ declared via @property
echo $form->field($model, 'phone');    // ✓ has both getPhone() and setPhone()
echo $form->field($model, 'fullName'); // ✗ read-only — declared via @property-read, nothing to write the submitted value back to
echo $form->field($model, 'nickname'); // ✗ typo — "nickname" is not a property on ContactModel

ActiveForm::end();

ActiveQuery with() validation ¶

with(), joinWith(), and innerJoinWith() take relation names as plain strings, so a typo (or a relation that got renamed) silently returns no related data instead of failing. This rule checks that every relation name passed to these methods — including a joinWith()/innerJoinWith() alias ('orders o' or 'orders AS o') and a dotted sub-relation path ('orders.items') — resolves to an actual relation (a getXxx() method returning something compatible with yii\db\ActiveQueryInterface) on the queried model.

Validating a sub-relation requires knowing which model the parent relation points to. This rule can work that out two ways: from the relation getter's own @return ActiveQuery<T> PHPDoc, or from a @property-read T / @property-read T[] PHPDoc property of the same name on the model (the same resolution activeFormFieldValidation and friends already rely on). A relation whose target model can't be determined either way is still checked for existence at its own level, but any further sub-relation path past it is left unchecked rather than guessed at.

/**
 * @property-read Address $address
 */
class Customer extends ActiveRecord
{
    /** @return ActiveQuery<Order> */
    public function getOrders()
    {
        return $this->hasMany(Order::class, ['customer_id' => 'id']);
    }

    public function getAddress()
    {
        return $this->hasOne(Address::class, ['id' => 'address_id']);
    }
}

class Order extends ActiveRecord
{
    /** @return ActiveQuery<Item> */
    public function getItems()
    {
        return $this->hasMany(Item::class, ['order_id' => 'id']);
    }
}

class Address extends ActiveRecord
{
    /** @return ActiveQuery<Country> */
    public function getCountry()
    {
        return $this->hasOne(Country::class, ['id' => 'country_id']);
    }
}

class Item extends ActiveRecord { /* ... */ }
class Country extends ActiveRecord  { /* ... */ }

Customer::find()->with('orders')->all();           // ✓
Customer::find()->with('orders.items')->all();     // ✓ Order declares its own "items" relation
Customer::find()->with('address.country')->all();  // ✓ related model resolved via @property-read
Customer::find()->joinWith('orders o')->all();     // ✓ alias is stripped before the relation is checked
Customer::find()->with('oders')->all();             // ✗ typo — no such relation on Customer
Customer::find()->with('orders.oops')->all();       // ✗ typo — no such relation on Order

Active Record condition validation ¶

findOne(), findAll(), and deleteAll() take a plain array condition (['attribute' => value], with an array value matched as an IN (...) condition) — and so does the second, condition argument of updateAll() / updateAllCounters(). Like attributeLabels() and scenarios(), this is never checked against the model until the query actually runs. This rule checks that every attribute name in a condition array exists on the queried ActiveRecord model (the same @property-aware resolution as activeRecordRelationValidation) and that its value's type is compatible with the attribute's declared type. Only array literals with a resolvable string key are checked; primary-key-only lookups (findOne(1), findOne([1, 2])) and dynamically-built condition arrays are left alone. A value implementing yii\db\ExpressionInterface (e.g. new Expression('NOW()')) is accepted for any attribute regardless of its declared type — yii\db\conditions\HashConditionBuilder builds it as raw SQL instead of type-casting it, and does so per-value inside an IN (...) array too.

/**
 * @property int $id
 * @property int $status
 * @property string $updated_at
 */
final class Customer extends ActiveRecord { /* ... */ }

Customer::findOne(1);                                         // ✓ primary key lookup, not a condition hash
Customer::findOne(['status' => 1]);                           // ✓
Customer::findOne(['status' => [1, 2]]);                      // ✓ IN (1, 2)
Customer::findOne(['updated_at' => new Expression('NOW()')]); // ✓ raw SQL, not type-checked
Customer::findOne(['statuss' => 1]);                          // ✗ typo — unknown attribute
Customer::findOne(['status' => '1']);                         // ✗ wrong type — int expected
Customer::deleteAll(['statuss' => 1]);                        // ✗ typo — unknown attribute
Customer::updateAll(['status' => 1], ['idd' => 5]);           // ✗ typo — unknown attribute in the condition

Active Record relations validation ¶

hasOne() and hasMany() relation links are plain string arrays: the array keys belong to the related AR class, and the values belong to the current AR class. This rule checks that those properties exist, including properties declared through PHPDoc @property.

/**
 * @property int $id
 * @property int $customer_id
 * @property int $shipping_address_id
 */
final class Order extends ActiveRecord
{
    public function getShippingAddress(): ActiveQuery
    {
        // ✗ missing property "uuid" on Address
        return $this->hasOne(Address::class, ['uuid' => 'shipping_address_id']);
    }

    public function getItems(): ActiveQuery
    {
        // ✗ missing property "order_uuid" on Order
        return $this->hasMany(OrderItem::class, ['order_id' => 'order_uuid']);
    }

    public function getCustomer(): ActiveQuery
    {
        // ✓
        return $this->hasOne(Customer::class, ['id' => 'customer_id']);
    }
}

/**
 * @property int $id
 */
final class Customer extends ActiveRecord { /* ... */ }

/**
 * @property int $id
 */
final class Address extends ActiveRecord { /* ... */ }

/**
 * @property int $id
 * @property int $order_id
 */
final class OrderItem extends ActiveRecord { /* ... */ }

Active Record update values validation ¶

updateAll()'s attribute values and updateAllCounters()'s counter values are the other plain array these two methods take — the values written into the row, as opposed to the WHERE condition activeRecordConditionValidation checks. This rule checks that every attribute name exists on the ActiveRecord model and that its value's type is compatible with the attribute's declared type; unlike a condition, these values are written as-is, so (unlike activeRecordConditionValidation) an array value is not treated as an IN (...) shorthand and is always a type mismatch. As with a condition, a value implementing yii\db\ExpressionInterface is accepted for any attribute regardless of its declared type — yii\db\QueryBuilder::prepareUpdateSets() builds it as raw SQL instead of type-casting it.

/**
 * @property int $id
 * @property int $status
 * @property int $age
 * @property string $updated_at
 */
final class Customer extends ActiveRecord { /* ... */ }

Customer::updateAll(['status' => 1], ['id' => 5]);              // ✓
Customer::updateAll(['updated_at' => new Expression('NOW()')]); // ✓ raw SQL, not type-checked
Customer::updateAll(['statuss' => 1]);                          // ✗ typo — unknown attribute
Customer::updateAll(['status' => 'active']);                    // ✗ wrong type — int expected
Customer::updateAllCounters(['age' => 1]);                      // ✓
Customer::updateAllCounters(['agee' => 1]);                     // ✗ typo — unknown attribute

BaseObject instantiation validation ¶

yii\base\BaseObject::__construct($config = []) applies $config via Yii::configure($this, $config), the same mechanism Yii::createObject() uses to apply its own config array — so a typo'd key or wrong-typed value in a plain new SomeObject([...]) call is just as invisible to PHPStan as it is in a createObject() config array. This rule checks a new call the same way yiiCreateObjectValidation checks Yii::createObject(): config keys against the target class's writable properties, and literal values against their declared types. It only looks at classes extending yii\base\BaseObject, and only at a literal array passed as the constructor's last argument when that argument is exactly the one named $config — the Yii2 convention for opting into array-config construction. A subclass whose last parameter isn't named config (or is variadic) doesn't follow that convention, so its last argument is left alone.

$countQuery = Article::find()->where(['status' => 1]);

new Pagination(['totalCount' => $countQuery->count()]);  // ✓
new Pagination(['totalCoutn' => 100]);                   // ✗ typo — unknown option "totalCoutn"
new Pagination(['defaultPageSize' => '20']);             // ✗ wrong type — int expected

Behavior attributes validation ¶

TimestampBehavior, BlameableBehavior, SluggableBehavior, AttributeTypecastBehavior, and mspirkov/yii2-db's DateTimeBehavior all fill in specific model attributes on their own — createdAtAttribute/updatedAtAttribute, createdByAttribute/updatedByAttribute, attribute/slugAttribute, attributeTypes, and the attributes event map every AttributeBehavior subclass inherits — and none of that is checked against the model until the behavior actually runs. This rule checks that every attribute name these options reference (a literal string, or an array of them) actually exists on the model declaring behaviors(), the same @property-aware resolution modelRulesValidation and modelAttributeLabelsValidation use. yii\base\DynamicModel instances are skipped, since their attributes are defined at runtime via defineAttribute() and can't be resolved statically.

/**
 * @property string $title
 * @property string $slug
 * @property string $created_at
 */
final class Post extends ActiveRecord
{
    public function behaviors(): array
    {
        return [
            [
                'class' => TimestampBehavior::class,
                'createdAtAttribute' => 'created_at',   // ✓
                'updatedAtAttribute' => 'udpated_at',   // ✗ typo — unknown attribute
            ],
            [
                'class' => SluggableBehavior::class,
                'attribute' => 'titel',                 // ✗ typo — unknown attribute
                'slugAttribute' => 'slug',              // ✓
            ],
            [
                'class' => AttributeTypecastBehavior::class,
                'attributeTypes' => [
                    'created_at' => AttributeTypecastBehavior::TYPE_STRING, // ✓
                ],
            ],
        ];
    }
}

TimestampBehavior, BlameableBehavior, SluggableBehavior, and DateTimeBehavior all extend yii\behaviors\AttributeBehavior, so instead of (or alongside) their own shorthand options, any of them can be configured directly through the inherited attributes event map — and this rule checks that map's attribute names the same way, on whichever of the four (or a custom AttributeBehavior subclass) it appears on:

/**
 * @property string $created_at
 * @property string|null $updated_at
 */
final class Article extends ActiveRecord
{
    public function behaviors(): array
    {
        return [
            [
                'class' => TimestampBehavior::class,
                'attributes' => [
                    self::EVENT_BEFORE_INSERT => ['created_at', 'updated_at'], // ✓
                ],
            ],
            [
                'class' => BlameableBehavior::class,
                'attributes' => [
                    self::EVENT_BEFORE_INSERT => ['created_by', 'updated_by'], // ✗ neither attribute exists
                ],
            ],
            [
                'class' => SluggableBehavior::class,
                'attributes' => [
                    self::EVENT_BEFORE_VALIDATE => 'slug',     // ✗ unknown attribute
                ],
            ],
            [
                'class' => DateTimeBehavior::class,
                'attributes' => [
                    self::EVENT_BEFORE_UPDATE => 'updated_at', // ✓
                ],
            ],
        ];
    }
}

Component behaviors validation ¶

Component::behaviors() uses Yii object configs, so typos usually wait until runtime. This rule checks statically visible behavior definitions on yii\base\Component subclasses, including models: classes that do not extend yii\base\Behavior, bad config keys, unknown config options, and option value types inferred from public properties or setters.

public function behaviors(): array
{
    return [
        'timestamp' => [
            'class' => TimestampBehavior::class,
            'createdAtAtribute' => 'created_at',     // ✗ typo — unknown option
        ],
        'typecast' => [
            'class' => AttributeTypecastBehavior::class,
            'attributeTypes' => [
                'views_count' => AttributeTypecastBehavior::TYPE_INTEGER,
                'is_published' => AttributeTypecastBehavior::TYPE_BOOLEAN,
            ],
            'typecastAfterValidate' => 1,            // ✗ bool expected
        ],
        'invalid' => stdClass::class,                // ✗ not a yii\base\Behavior

        'slug' => [
            'class' => SluggableBehavior::class,
            'attribute' => 'title',                  // ✓
        ],
    ];
}

Controller actions validation ¶

Controller::actions() shares the same object-config shape as Component::behaviors() — this rule checks statically visible action definitions on yii\base\Controller subclasses: classes that do not extend yii\base\Action, an empty action ID, bad config keys, unknown config options, and option value types inferred from public properties or setters.

public function actions(): array
{
    return [
        'error' => [
            'class' => ErrorAction::class,
            'vieww' => 'error',            // ✗ typo — unknown option
        ],
        'captcha' => [
            'class' => CaptchaAction::class,
            'fixedVerifyCode' => 1,        // ✗ string expected
        ],
        'invalid' => stdClass::class,      // ✗ not a yii\base\Action

        'download' => [
            'class' => DownloadAction::class,
            'path' => '@app/uploads',      // ✓
        ],
    ];
}

Html active attribute validation ¶

Html::activeInput(), activeTextInput(), and the rest of the active*() family (activeHiddenInput, activePasswordInput, activeFileInput, activeTextarea, activeRadio, activeCheckbox, activeDropDownList, activeListBox, activeCheckboxList, activeRadioList, activeLabel, activeHint) all take a model and a plain attribute-name string, the same as ActiveForm::field(). This rule checks that the attribute exists on the given model, the same @property-aware resolution used by activeFormFieldValidation and uploadedFileInstanceValidation. yii\base\DynamicModel instances are skipped, since their attributes are defined at runtime via defineAttribute() and can't be resolved statically.

/**
 * @property string $email
 */
final class ContactModel extends Model
{
    public $name;
}

/** @var ContactModel $model */

echo Html::activeLabel($model, 'name');    // ✓ declared property
echo Html::activeInput('text', $model, 'email');  // ✓ declared via @property
echo Html::activeTextInput($model, 'nema');       // ✗ typo — "nema" is not a property on ContactModel
echo Html::activeHint($model, 'nickname');        // ✗ typo — "nickname" is not a property on ContactModel

Model attribute hints validation ¶

Model::attributeHints() is just as easy to get wrong as attributeLabels() — a typo'd key silently means the hint is never shown for the intended attribute. This rule checks that every key is an existing property on the model (as a declared property or a PHPDoc @property, same resolution as modelRulesValidation) and isn't left empty — though the existence check alone is skipped for yii\base\DynamicModel subclasses, since their attributes are defined at runtime via defineAttribute() and can't be resolved statically:

/**
 * @property string $email
 */
final class ContactModel extends Model
{
    public $name;

    public function attributeHints(): array
    {
        return [
            'name' => 'Your full name',
            'emial' => 'We will reply here',   // ✗ typo — "emial" is not a property on ContactModel
            'email' => 'We will reply here',   // ✓ declared via @property
        ];
    }
}

Model attribute labels validation ¶

Model::attributeLabels() is just as easy to get wrong as rules() — a typo'd key silently falls back to the default humanized attribute name instead of showing your label. This rule checks that every key is an existing property on the model (as a declared property or a PHPDoc @property, same resolution as modelRulesValidation) and isn't left empty — though the existence check alone is skipped for yii\base\DynamicModel subclasses, since their attributes are defined at runtime via defineAttribute() and can't be resolved statically:

/**
 * @property string $email
 */
final class ContactModel extends Model
{
    public $name;

    public function attributeLabels(): array
    {
        return [
            'name' => 'Name',
            'emial' => 'E-mail',   // ✗ typo — "emial" is not a property on ContactModel
            'email' => 'E-mail',   // ✓ declared via @property
        ];
    }
}

Model validation rules validation ¶

Model::rules() is just a plain array — PHP will never tell you that you forgot a validator's required option, wrote an invalid regex, misconfigured one of its options, or targeted an attribute that doesn't even exist. For every rule entry the validator type resolves to (a built-in alias like required/string/number/compare/date/match/in/unique/exist/file/image/ip/url, a custom Validator subclass, a configured project alias, or an inline closure/method), this rule statically checks the option array against what that validator actually accepts and requires. A validator name it can't resolve is reported as an error; add project-specific aliases under modelRulesValidation.customValidators:

public function rules(): array
{
    return [
        ['email', 'string', 'lenght' => 255],             // ✗ typo — unknown option "lenght" for StringValidator
        ['code', 'match', 'pattern' => '/[/'],            // ✗ invalid regular expression
        ['ip', 'ip', 'ipv4' => false, 'ipv6' => false],   // ✗ disables both protocols
        ['message', 'string', 'max' => 'invalid'],        // ✗ 'max' must be int|null
        ['status', 'someUnregisteredAlias'],              // ✗ unknown validator

        ['name', 'string', 'max' => 255],                 // ✓
    ];
}

This rule also checks that the attribute names at index 0 of each rule (including array lists of attributes) actually exist on the model, the same way activeRecordRelationValidation checks relation links — as a declared property or a PHPDoc @property. It only reports on attribute names it can resolve to a literal or constant string; anything built dynamically at runtime is left alone. This check alone is skipped for yii\base\DynamicModel subclasses, since their attributes are defined at runtime via defineAttribute() and can't be resolved statically.

/**
 * @property string $email
 */
final class ContactModel extends Model
{
    public $name;

    public function rules(): array
    {
        return [
            ['name', 'required'],
            ['emial', 'required'],   // ✗ typo — "emial" is not a property on ContactModel
            ['email', 'string'],     // ✓ declared via @property
        ];
    }
}

Model scenarios validation ¶

Model::scenarios() maps scenario names to the attributes active in them, and PHP won't tell you that a scenario name is empty, an attribute list isn't actually an array, or an attribute doesn't exist on the model — the same way modelAttributeLabelsValidation checks attributeLabels(). An attribute prefixed with ! (Yii's "unsafe" marker) is checked under its unprefixed name. The attribute-existence check alone is skipped for yii\base\DynamicModel subclasses, since their attributes are defined at runtime via defineAttribute() and can't be resolved statically.

final class ContactModel extends Model
{
    public $name;
    public $email;

    public function scenarios(): array
    {
        return [
            'create' => ['name', 'email'],
            'update' => ['name', '!emial'],  // ✗ typo — "emial" is not a property on ContactModel
            '' => ['name'],                  // ✗ empty scenario name
            'delete' => 'name',              // ✗ must be an array of attribute names
        ];
    }
}

Query condition validation ¶

Query::where() / andWhere() / orWhere() accept an "operator format" array ([operator, operand1, operand2, ...]), and Yii only discovers a missing operand at query-build time — each yii\db\conditions\*Condition::fromArrayDefinition() throws an InvalidArgumentException if its required operands aren't present. This rule checks the operand count against those same rules: not, between / not between, in / not in, like and its variants, and exists / not exists each need a specific minimum (or, for not, an exact) number of operands, and the standard comparison operators (=, !=, <>, >, >=, <, <=) need exactly 2, Yii's documented "arbitrary operator" case. and / or operands are recursed into, since they typically wrap further operator-format sub-conditions; yii\db\conditions\ConjunctionCondition itself never validates their count, but a zero-operand and/or can never produce a meaningful condition, so this rule still requires at least one. Any other operator string — a genuinely custom one registered via QueryBuilder::setConditionClasses() — is left unchecked rather than guessed at, and so is anything built dynamically or in hash format (['status' => 1], never operator-format to begin with).

$query->where(['in', 'status']);                                    // ✗ missing the values operand — needs 2
$query->andWhere(['between', 'age', 18]);                           // ✗ missing the upper bound — needs 3
$query->orWhere(['not', ['in', 'status']]);                         // ✗ same as above, nested inside "not"
$query->where(['>=', 'age', 18, 30]);                               // ✗ arbitrary operator, extra operand — needs exactly 2
$query->where(['and']);                                             // ✗ empty "and" — needs at least 1 operand

$query->where(['in', 'status', [1, 2]]);                            // ✓
$query->andWhere(['between', 'age', 18, 65]);                       // ✓
$query->orWhere(['and', ['status' => 1], ['in', 'type', [1, 2]]]);  // ✓

UploadedFile instance validation ¶

UploadedFile::getInstance($model, $attribute) and getInstances($model, $attribute) build the file input's name from $model and a plain attribute-name string, the same way ActiveForm::field() does — so a typo silently returns null (or an empty array) instead of the uploaded file. This rule checks that the attribute exists on the given model, the same @property-aware resolution used elsewhere (e.g. activeFormFieldValidation, modelAttributeLabelsValidation). yii\base\DynamicModel instances are skipped, since their attributes are defined at runtime via defineAttribute() and can't be resolved statically.

final class UploadForm extends Model
{
    public $imageFile;
    public $imageFiles;

    public function rules(): array
    {
        return [[['imageFile', 'imageFiles'], 'file']];
    }
}

/** @var UploadForm $model */

$model->imageFile = UploadedFile::getInstance($model, 'imageFile');    // ✓
$model->imageFiles = UploadedFile::getInstances($model, 'imageFiles'); // ✓
$model->imageFile = UploadedFile::getInstance($model, 'imagefile');    // ✗ typo — "imagefile" is not a property on UploadForm
$files = UploadedFile::getInstances($model, 'imagefiles');             // ✗ typo — "imagefiles" is not a property on UploadForm

Widget properties validation ¶

Widget::begin($config) / Widget::widget($config) configs are just arrays, like behaviors(), so a typo'd key or a wrong-typed value only fails once the widget renders. This rule checks config keys against the called widget's writable properties and literal values against their declared types.

ActiveForm::begin([
    'method' => 'get',             // ✓ declared property
    'metod' => 'get',              // ✗ typo — unknown option "metod"
    'encodeErrorSummary' => 'yes', // ✗ wrong type — bool expected, string given
]);

ActiveForm::end();

Yii::createObject() validation ¶

Yii::createObject()'s class / __class config array is declared as an open, all-optional PHPStan array shape (array{class?: class-string<T>, __class?: class-string<T>, ...}), so PHPStan itself already flags an unknown or wrong-typed class value — but it stays silent about a missing class/__class key entirely (just an unhelpful "unable to resolve the template type" note) and about every other key in the array, since ... accepts anything. This rule fills exactly those two gaps on calls to createObject() on Yii (or any class extending yii\BaseYii): a clear "must specify class or __class" message, plus config keys checked against the resolved class's writable properties and value types, the same way componentBehaviorsValidation checks behaviors. Callables (a Closure, or a [$target, 'method'] array) are left alone, since they are not object configs.

Yii::createObject([
    'traceLevel' => 3,        // ✗ missing "class" or "__class"
]);

Yii::createObject([
    'class' => Logger::class,
    'traceLevel' => '3',      // ✗ wrong type — int expected
    'flushInteval' => 1000,   // ✗ typo — unknown option (should be "flushInterval")
]);

Yii::createObject([
    'class' => Logger::class,
    'traceLevel' => 3,        // ✓
]);

Code quality rules ¶

Complexity limits ¶

noComplexActionClasses and noComplexControllerActions count if, foreach, for, while, do-while, switch, match, ternaries, and try/catch blocks inside a controller action or Action::run(). Cross any configured threshold and the rule fires, pointing at the exact construct that pushed it over:

// ✗ flagged: 4 `if` statements against a default limit of 3
public function actionCheckout(): string
{
    if ($this->cart->isEmpty()) { /* ... */ }
    if (!$this->cart->hasPaymentMethod()) { /* ... */ }
    if ($this->cart->hasOutOfStockItems()) { /* ... */ }
    if ($this->cart->hasExpiredCoupon()) { /* ... */ }

    return $this->render('checkout', ['cart' => $this->cart]);
}

// ✓ the decision tree moves to a service, the action just orchestrates
public function actionCheckout(): string
{
    return $this->render('checkout', $this->checkoutService->process($this->cart));
}

No calling actions via $this ¶

// ✗ flagged: bypasses the action-resolution pipeline (filters, events, results)
public function actionEdit(int $id): Response
{
    return $this->actionView($id);
}

// ✓ redirect, or extract the shared part into a private method / service
public function actionEdit(int $id): Response
{
    return $this->redirect(['view', 'id' => $id]);
}

No database access outside repositories ¶

Fires on self::find()/findOne()/save(), Yii::$app->db, Yii::$app->db->createCommand(), creating or configuring a Query, transactions, and friends — wherever they turn up in a controller, an Action, or a view file.

// ✗ flagged in a view: queries the database instead of just rendering data
<?php foreach (Post::find()->where(['status' => 1])->all() as $post): ?>

// ✓ the controller/action fetches the data, the view only renders it
<?php foreach ($posts as $post): ?>

noDbQueriesInActions / noDbQueriesInControllers push the same query building into a repository or service instead. Query builder setup counts too: new Query(), $query->where(), and dynamic calls on a Query object are all treated as direct database access in these layers.

No raw superglobals ¶

Covers $_GET, $_POST, $_REQUEST, $_SESSION, $_COOKIE, $_FILES, and $_SERVER, each pointing at the matching yii\web\Request / Session / UploadedFile API.

// ✗ flagged, with the fix suggested in the error message
$id = $_GET['id'];

// ✓ read through the injected yii\web\Request instead
$id = $this->request->get('id');

No dynamic SQL strings ¶

Applies to where(), andWhere(), and orWhere() alike. The check is purely structural — it flags any interpolated or concatenated string passed as the condition, regardless of what the string contains (an IN (...) list is just as flagged as a plain = comparison) — and leaves the array condition syntax, including its ['in', 'column', $values] operator form, untouched.

// ✗ flagged: string-built condition, one step from SQL injection
$query->where("status = $status");
$query->andWhere('status = ' . $status);
$query->orWhere("id IN ($ids)");

// ✓ array condition syntax — parameterized, and PHPStan can see the shape
$query->where(['status' => $status]);
$query->andWhere(['in', 'id', $ids]);

No forbidden Yii::$app properties ¶

Checks any expression typed as yii\base\Application, not just Yii::$app directly. A short allowlist (id, name, charset, language, timeZone by default) stays available everywhere since those are effectively static configuration, not injectable services.

// ✗ arbitrary component access
$cache = Yii::$app->cache;

// ✓ inject the component instead
public function __construct(private CacheInterface $cache) {}

No redundant existence check ¶

Query::exists() runs a lighter SELECT EXISTS(...) query instead of fetching a row (one()) or counting every matching row (count()). This rule catches the common ways a record-existence check like this ends up written as one of those instead, on any expression typed as yii\db\QueryInterface / yii\db\ActiveQueryInterface — the comparison can be written with the query call on either side, and count() > 0 / count() !== 0 (or, negated, count() < 1 / count() === 0) are flagged the same way as one() !== null / one() === null:

// ✗ flagged: fetches a full row just to test whether one is there
public function emailIsTaken(string $email): bool
{
    return User::find()->where(['email' => $email])->one() !== null;
}

// ✗ flagged: counts every matching row just to test whether one is there
public function emailIsAvailable(string $email): bool
{
    return User::find()->where(['email' => $email])->count() < 1;
}

// ✓ exists() only asks the database whether a row is there
public function emailIsTaken(string $email): bool
{
    return User::find()->where(['email' => $email])->exists();
}

// ✓ same, negated
public function emailIsAvailable(string $email): bool
{
    return !User::find()->where(['email' => $email])->exists();
}

No redundant Html::encode() ¶

PHPStan already flags most nonsensical Html::encode() calls on its own (wrong argument types and the like). The one gap it doesn't cover is a numeric-string argument: a value PHPStan can already prove only ever holds digits, so escaping it can't do anything — htmlspecialchars() never touches a plain number. This rule fires only in that narrow case, on yii\helpers\Html / BaseHtml and their subclasses:

/**
 * @var numeric-string $id
 * @var string $name
 */

echo Html::encode($id);   // ✗ flagged — $id can only ever be a numeric-string
echo Html::encode($name); // ✓ a plain string may still contain special characters

No Yii::$app property mutation ¶

Checks the same yii\base\Application-typed expressions as noForbiddenYiiAppProperties, on the write side.

// ✗ mutation of properties
Yii::$app->params = [...];
Yii::$app->setComponents([...]);

Yii2 Sentry ¶

1. Features
2. Installation
3. Configuration
4. Built-in Collectors
5. Usage
6. How Collectors Work
7. Creating a Custom Collector
8. License

Read this in other languages: English, Русский

Complete Sentry integration for Yii2 framework: logging, tracing and profiling.

Features ¶

• Tracking errors and exceptions through Yii2 logs
• Database performance monitoring (slow queries, transactions)
• HTTP request tracing (incoming and outgoing)
• Manual spans for tracking performance of critical operations
• Flexible data collection configuration through collector system
• Sanitization of sensitive data (passwords, tokens, API keys)

Installation ¶

Install the package via composer:

composer require tzabzlat/yii2-sentry

For using performance profiling features, you need to install the PHP Excimer extension.

Configuration ¶

Basic Configuration ¶

Add to your application configuration (not common):

'bootstrap' => ['sentry'],
'log'          => [
    'logger'  => 'tzabzlat\yii2sentry\Logger',
]
'components' => [
    'sentry' => [
        'class' => 'tzabzlat\yii2sentry\SentryComponent',
        'dsn' => 'https://your-sentry-dsn@sentry.io/project',
        'environment' => YII_ENV,
        // Sampling rate (percentage of requests for performance metrics collection)
        'tracesSampleRatePercent' => YII_ENV_PROD ? 5 : 100,
        // Additional tags for all events
        'tags' => [
            'application' => 'app-api',
            'app_version' => '1.0.0',
        ],
    ],
]

Built-in Collectors ¶

The package includes four main collectors, each responsible for its own monitoring area:

1. LogCollector ¶

Collects and sends Yii2 logs with error and warning levels to Sentry. Allows configuring which logs should be sent and which should be ignored.

2. DbCollector ¶

Tracks SQL queries, measures their performance, and creates spans in Sentry for analysis. Automatically marks slow queries. Also tracks database transactions.

3. HttpClientCollector ¶

Tracks outgoing HTTP requests made through Yii2 HttpClient. Measures response time, records response status, and creates spans for visualizing HTTP dependencies.

4. RequestCollector ¶

Tracks incoming HTTP requests to your application. Creates the main transaction for each request and collects information about the controller, action, processing time, and response status.

Usage ¶

Manual Spans for Custom Operations ¶

To create spans manually, use the trace method:

// Simple span
Yii::$app->sentry->trace('Operation name', function() {
    // Your code here
    heavyOperation();
});

// With additional data
Yii::$app->sentry->trace(
    'Data import', 
    function() {
        // Import data
        return $result;
    }, 
    'custom.import', // Operation type
    [
        'source' => 'api',
        'records_count' => $count
    ]
);

// Span with exception handling
try {
    Yii::$app->sentry->trace('Critical operation', function() {
        // In case of an exception, the span will be marked as failed
        throw new \Exception('Error!');
    });
} catch (\Exception $e) {
    // The exception will be caught here
    // The span is already marked as failed in Sentry
}

Collector Configuration ¶

You can configure each collector separately through the collectorsConfig parameter:

'sentry' => [
    'class' => 'tzabzlat\yii2sentry\SentryComponent',
    'dsn' => env('SENTRY_DSN', ''),
    'environment' => YII_ENV,
    'tracesSampleRatePercent' => YII_ENV_PROD ? 20 : 100,
    'collectorsConfig' => [
        // LogCollector configuration
        'logCollector' => [
            'targetOptions' => [
                'levels' => ['error', 'warning'], // Log levels to send
                'except' => ['yii\web\HttpException:404'], // Exceptions
                'exceptMessages' => [
                    '/^Informational message/' => true, // Exclude by pattern
                ],
            ],
        ],
        
        // DbCollector configuration
        'dbCollector' => [
            'slowQueryThreshold' => 100, // Threshold in ms for slow queries
        ],
        
        // HttpClientCollector with sensitive URL masking
        'httpClientCollector' => [
            'urlMaskPatterns' => [
                '|https://api\.telegram\.org/bot([^/]+)/|' => 'https://api.telegram.org/bot[HIDDEN]/',
            ],
        ],
        
        // RequestCollector configuration
        'requestCollector' => [
            'captureUser' => true, // Capture user ID
        ],
    ],
]

Disabling Collectors ¶

To disable a specific collector, set its configuration to false:

'collectorsConfig' => [
    'dbCollector' => false, // Disables the database collector
    'httpClientCollector' => false, // Disables the HTTP client collector
],

How Collectors Work ¶

LogCollector ¶

Connects a special LogTarget that intercepts logs with specified levels and sends them to Sentry. Processes exceptions as a separate type of event. Also supports filtering by categories and message patterns.

DbCollector ¶

Overrides the standard Yii2 DbCommand and connects to query profiling events. Measures the execution time of each SQL query, determines the query type (SELECT, INSERT, etc.), and creates spans for visualization in Sentry. Tracks transactions through Connection events.

HttpClientCollector ¶

Subscribes to request sending events through HttpClient. For each request, it creates a span with details of URL, method, headers, and request body (with sanitization of sensitive data). Measures response time and adds information about the response status.

RequestCollector ¶

Creates the main transaction for each incoming HTTP request. Collects information about the route, controller, action, request parameters, and response. Measures the total request processing time and peak memory usage.

Creating a Custom Collector ¶

You can create your own collector by implementing the CollectorInterface or extending the BaseCollector class:

namespace app\components\sentry;

use tzabzlat\yii2sentry\collectors\BaseCollector;
use tzabzlat\yii2sentry\SentryComponent;
use Sentry\Breadcrumb;
use Sentry\State\Scope;
use Yii;

class MyCustomCollector extends BaseCollector
{
    // Collector configuration
    public $someOption = 'default';
    
    /**
     * Attaches the collector to Sentry
     */
    public function attach(SentryComponent $sentryComponent): bool
    {
        parent::attach($sentryComponent);
        
        // Connect to Yii2 events
        \yii\base\Event::on(SomeClass::class, SomeClass::EVENT_NAME, function($event) {
            $this->handleEvent($event);
        });
        
        return true;
    }
    
    /**
     * Sets additional tags
     */
    public function setTags(Scope $scope): void
    {
        $scope->setTag('custom_tag', 'value');
    }
    
    /**
     * Handles a custom event
     */
    protected function handleEvent($event)
    {
        // Create a span for tracking
        $span = $this->sentryComponent->startSpan(
            'My Custom Operation',
            'custom.operation',
            [
                'key' => 'value',
                'event_type' => get_class($event)
            ]
        );
        
        // Add a breadcrumb to the timeline
        $this->addBreadcrumb(
            'My Event Happened',
            ['data' => 'value'],
            Breadcrumb::LEVEL_INFO,
            'custom'
        );
        
        // Finish the span
        if ($span) {
            $this->sentryComponent->finishSpan($span, [
                'result' => 'success',
                'additional_data' => $someValue
            ]);
        }
    }
}

Then add your collector to the configuration:

'sentry' => [
    // ...
    'collectorsConfig' => [
        'myCustomCollector' => [
            'class' => 'app\components\sentry\MyCustomCollector',
            'someOption' => 'custom value',
        ],
    ],
],

Contributing ¶

If you found a bug or have suggestions for improvement, feel free to:

• Create an issue with a description of the problem or suggestion
• Propose pull requests with fixes or new features

License ¶

MIT

Yii Bootstrap 5 version 1.2.0 was released.

In this version:

• Add tabIndex() method to Button widget
• Raise yiisoft/html version to ^3.13 || ^4.0
• Fix Collapse re-encoding content already managed by Toggler

darktoolz/yii2-rexfilter ¶

composer require darktoolz/yii2-rexfilter "@dev"

Yii3 reCAPTCHA ¶

1. Features
2. Requirements
3. Installation
4. Documentation

Google reCAPTCHA v2 and v3 form field + server-side validator for Yii3.

Stats for Nerds

Features ¶

• reCAPTCHA v2 — checkbox/invisible widget field with theme, size, and type options
• reCAPTCHA v3 — score-based field that fetches its token on form submit (not page load), avoiding surprise challenge popups
• Server-side validation — PHP attribute rules (RecaptchaV2Rule / RecaptchaV3Rule) verified against Google's siteverify endpoint
• Score threshold + action matching — v3 rules can enforce a minimum score and an expected action name
• Zero-config ergonomics — once site keys are set, fields and rules work out of the box via a static registry
• i18n — validation and legal-notice messages are translated through Yii Translator

Requirements ¶

• PHP 8.3+
• PSR-17 request + stream factories
• PSR-18 HTTP client

Installation ¶

composer require yiirocks/recaptcha

Documentation ¶

The complete reference guide is available at Yii.Rocks.

Voyti — Yii3 User Management Extension ¶

1. Features
2. Requirements
3. Views Implementation
4. Installation
5. Documentation

войти
/vɐjˈtʲi/
verb

"to enter" or "to log in"

Highly customizable and extensible user management, authentication, and authorization extension for Yii3.

Originally ported from Usuario, Voyti has since been rebuilt around modern PSR standards and Yiisoft components. It has been extensively redesigned to provide a flexible, modular foundation that adapts to a wide range of authentication and authorization requirements.

Stats for Nerds

Features ¶

• User Management — Registration, email confirmation, login/logout with remember-me, password recovery, password expiration
• Profile Management — User profiles with gravatar, timezone, bio, and a personal website link
• Social Authentication — OAuth2 login via Google, GitHub, Facebook, and more
• Two-Factor Authentication — Email codes, TOTP (authenticator app) with QR provisioning, or WebAuthn/passkeys, with enforced-per-permission support and one-time backup codes for account recovery
• RBAC Management — Full admin UI for roles, permissions, and rules with parent-child hierarchy, assignment management, and filtering
• Identity Switching — Admins can temporarily switch into another user's identity for support or debugging, then restore their own session with one click
• Session Management — Session tracking and termination
• GDPR Data Handling — Data export and account anonymization
• Password Policies — Minimum complexity requirements, max age enforcement via middleware
• Email Change Confirmation — Three modes: immediate, confirm new address, confirm both old and new
• REST API: User Management — JSON user CRUD (Bearer-token auth), with optional per-user request throttling (429 responses, X-Rate-Limit-* headers)
• REST API: Client Login & Self-Service — Credential login, account/session self-service, admin RBAC/audit-log, and dynamic 2FA/social-login/GDPR bridges over JSON, for a browser-based single-page application (SPA) or any other stateless client
• Bot Protection — Google reCAPTCHA v2/v3 for registration and login forms
• Brute-Force Protection — Exponential backoff delays for failed login and registration attempts, tracked per IP address
• i18n — Built-in translations for multiple languages
• Pluggable Views — View-agnostic core with Bootstrap 5 views available; alternative UI frameworks can implement the standard interface
• Email Customization — Mail templates are independently overridable for complete control over transactional email content and styling
• Toast Notifications — Native Bootstrap toast support with automatic fallback to flash messages

Requirements ¶

• PHP 8.3+
• ext-intl
• Various yiisoft packages (automatic installation via composer)

Views Implementation ¶

Voyti's core is view-agnostic; you need a views implementation package to render any pages. yiirocks/voyti-views-bootstrap5 is the reference implementation using Bootstrap 5. You can substitute an alternative views package if you prefer a different UI framework, as long as it implements the yiirocks/voyti-views interface.

Installation ¶

composer require yiirocks/voyti yiirocks/voyti-views-bootstrap5

Documentation ¶

The complete reference guide is available at Yii.Rocks.

We’ve added a new Yii3 demo application:

https://github.com/yiisoft/demo-summarizer

It started as a practical way to test yiisoft/queue together with AMQP and Redis/Valkey drivers in Yii3 application, but it turned into a useful demo on its own.

The app lets you upload documents, extract readable markdown, summarize content with a local OpenAI-compatible llama.cpp service, and track processing progress through Yii Queue workers. It supports multiple queue drivers, background workers, S3-compatible storage via Garage, retries, deletion, and clearing all stored data and pending jobs.

By default, it runs with AMQP protocol, two RabbitMQ workers, Kreuzberg extraction, Garage storage, and a small CPU-friendly Gemma model through llama.cpp.

It is useful if you want to see:

• Yii3 app structure in practice.
• Native yiisoft/queue worker usage.
• AMQP and Redis/Valkey queue drivers.
• Docker-based local development.
• File upload validation and processing.
• S3-compatible storage integration.
• Local LLM integration through an OpenAI-compatible API.

Try it with:

make build
make up
make -- yii migrate:up -y

Then open http://127.0.0.1/

Feedback and improvements are welcome.

Yii HTML version 4.2.0 was released. In this version:

• Add beforeInput() and afterInput() methods to abstract BooleanInputTag, extended by Radio and Checkbox
• Add beforeCheckbox() and afterCheckbox() methods to CheckboxList, and beforeRadio() and afterRadio() methods to RadioList

Yii Runner RoadRunner version 3.2.0 was released. In this version:

• Add PHP 8.5 support
• Add spiral/roadrunner-http version ^v4.0.0 support

1. File validator
2. SplFileInfo support in Image validator
3. Other changes

Yii Validator version 2.6.0 was released.

This release adds a new File validator, extends Image validator input support, and includes translation, documentation, and internal code quality improvements.

File validator ¶

The new File rule validates that a value is a file. It supports:

• string file paths;
• SplFileInfo instances;
• PSR-7 UploadedFileInterface instances.

It can also check allowed extensions, MIME types, and file size.

use Yiisoft\Validator\Rule\File;
use Yiisoft\Validator\Validator;

$result = (new Validator())->validate(
    ['avatar' => $request->getUploadedFiles()['avatar'] ?? null],
    [
        'avatar' => new File(
            extensions: ['jpg', 'png', 'webp'],
            mimeTypes: ['image/jpeg', 'image/png', 'image/webp'],
            maxSize: 2_000_000,
        ),
    ],
);

For multiple files, use it together with Each:

use Yiisoft\Validator\Rule\Each;
use Yiisoft\Validator\Rule\File;

$rules = [
    'attachments' => new Each(
        new File(
            extensions: ['pdf', 'txt'],
            maxSize: 5_000_000,
        ),
    ),
];

Optional upload fields can use skipOnEmpty:

use Yiisoft\Validator\Rule\File;

$rule = new File(skipOnEmpty: true);

SplFileInfo support in Image validator ¶

Image validator now accepts SplFileInfo values directly. This is useful when your application already works with filesystem objects instead of plain paths.

use SplFileInfo;
use Yiisoft\Validator\Rule\Image\Image;
use Yiisoft\Validator\Validator;

$result = (new Validator())->validate(
    new SplFileInfo(__DIR__ . '/avatar.jpg'),
    new Image(
        minWidth: 128,
        minHeight: 128,
        maxWidth: 2048,
        maxHeight: 2048,
	),
);

The Image validator was also fixed to handle unreadable streams correctly.

Other changes ¶

• Updated Polish translations.
• Explicitly imported classes, functions, and constants in use sections.
• Fixed translations, documentation grammar, incorrect imports, and a broken contributing guide link.

We are very pleased to announce the release of the ApiDoc extension version 4.0.0.

This is a major release that modernizes ApiDoc for current PHP projects. The minimum PHP version is now 8.2, and dependency requirements were raised for nikic/php-parser, phpdocumentor/reflection, and phpdocumentor/type-resolver.

Version 4.0.0 adds support for intersection and nullable types, PHPStan/Psalm syntax, constants in interfaces and traits, inherited descriptions, improved method signatures, better inline @see and @link handling, and links to built-in PHP functions. It also includes a new template for custom projects.

A brief overview of major changes:

• PHP 8.2 is now required.
• Deprecated code was removed.
• nikic/php-parser 5.0+ is now required.
• phpdocumentor/reflection 7.0+ and phpdocumentor/type-resolver 2.0+ are now required.
• FQSEN support in inline @link tags was removed.
• Type extraction and rendering were significantly improved.
• Constants, inheritance, and PHPDoc handling are more complete.

Most of this release is handled by Maksim Spirkov, with the new custom project template also based on work by jcherniak and cebe.

See the CHANGELOG for a full list of changes.

Yii2 HTTP Client version 2.0.17 was released. In this version:

• Fixed TypeError: stream_get_contents(): Argument #1 ($stream) must be of type resource, bool given when PHP error reporting is turned off.
• Fixed the PHP 8.5 deprecation for the predefined locally scoped $http_response_header variable.
• Fixed curl_close() and curl_multi_close() deprecations in PHP 8.5.
• Fixed PHPDoc annotations for Response::$statusCode and Response::getStatusCode().
• Added additional keys to Message::getHeaders() to expose full HTTP status line details through Client::getHeaders().
• Applied Yii2 coding standards.
• Raised the minimum PHP version to 7.4.

Yii HTML version 4.1.0 was released. In this version:

• Add test helper functions for controlling HTML ID generation

Yii Active Record version 1.1.0 was released. In this version:

• Clarify $relations parameter type in JoinWith::__construct() from array<string|Closure> to array<string|callable(ActiveQueryInterface):void>
• Optimize performance of ActiveRecord::get() method
• Remove check for empty string in AbstractActiveRecord::markPropertyChanged() method
• Add default config for yiisoft/config plugin
• Relation query should be created by related class, not primary model class
• Fix SoftDelete with initiated custom date
• Fix ActiveRecordInterface::upsert() with $updateProperties = false
• Fix ActiveRecordInterface::upsert() to prioritize passed associative values during updates
• Fix properties with hooks

Yii RBAC PHP File Storage version 2.1.0 was released. In this version:

• Change PHP constraint in composer.json to 8.1 - 8.5
• Bump yiisoft/rbac version to ^2.1
• Apply code style fixes
• Explicitly import functions and constants in "use" section

We are pleased to announce the release of Yii Framework version 2.0.55.

Please refer to the instructions at https://www.yiiframework.com/download/ to install or upgrade to this version.

In this release:

• Security fix for CVE-2026-39850: internal variables in View::renderPhpFile() and ErrorHandler::renderFile() are now isolated to prevent parameter collisions from overriding included file paths.
• Continued PHPStan/Psalm and PHPDoc annotation improvements, including generics, conditional types, and more accurate return and parameter types.
• yii\grid\GridView's default filterSelector can now be overridden and may use Closures.
• Better compatibility with newer PHP versions, including PHP 8.6-related test adjustments.
• Removal of obsolete code paths for PHP versions older than the current Yii 2 minimum.
• Bug fixes.

The Yii 2 basic and advanced application templates received refreshed CI, Docker, static analysis, documentation, and project template updates. Note that the framework itself still supports PHP 7.4+, while the updated application templates target newer PHP versions.

Thanks to all Yii community members who contribute to the framework, translators who keep documentation translations up to date, and community members who answer questions at forums.

Special thanks goes to Maksim Spirkov who continued taking care of the majority of annotation-related changes.

There are many active Yii communities, so if you need help or want to share your experience, feel free to join them.

A complete list of changes can be found in the CHANGELOG.

Hey everyone,

I’m working on a Yii 1.x–based ERP/POS system and recently implemented Redis caching for performance optimization. Thought I’d share my setup and a few lessons learned in case it helps someone still maintaining Yii 1.x apps.

My Setup ¶

'components'=>array(
    'cache'=>array(
        'class'=>'CRedisCache',
        'hostname'=>'127.0.0.1',
        'port'=>6379,
        'database'=>1,
        'keyPrefix'=>'database',
    ),
),

Why Redis Instead of FileCache? ¶

• Much faster read/write (RAM-based)
• Great for high-traffic POS/ERP environments
• Reduces DB load significantly
• Works well for session + query caching

✅ Where I’m Using Cache ¶

• Product listing queries (heavy joins)
• Dashboard stats (sales, stock, reports)
• API responses for branch sync
• Session handling (planning to shift fully to Redis)

Things to Watch Out For ¶

1. Key Prefix is Important If you’re running multiple apps on same Redis instance, always use keyPrefix to avoid conflicts.

2. Cache Invalidation Yii 1.x doesn’t auto-handle this well. You need to manually clear cache when:

   • product updates
   • stock changes
   • price updates

3. Persistence Redis is in-memory. Make sure:

   • RDB or AOF is enabled (depending on your setup)
   • Otherwise you risk data loss on restart

4. Production Deployment Don’t keep Redis on default config:

   • bind to private IP
   • use password (requirepass)
   • firewall the port

Example Usage ¶

$key = 'product_list';

$data = Yii::app()->cache->get($key);

if ($data === false) {
    $data = Product::model()->findAll();
    Yii::app()->cache->set($key, $data, 300); // cache for 5 minutes
}

Question for Community ¶

For those still on Yii 1.x:

• Are you using Redis for sessions as well?
• Any best practices for automatic cache invalidation?

Would love to hear how others are optimizing legacy Yii apps in production.

Thanks!

bestyii/yii2-tabler ¶

1. 产品定位
2. 当前交付面
3. 适合什么项目
4. 和应用的边界
5. 安装
6. 快速开始
7. 组件契约
8. 资源策略
9. 产品目标
10. 稳定性与兼容原则
11. 质量与可维护性
12. 文档入口
13. 选型结论

bestyii/yii2-tabler 是一个面向 Yii2 后台、运营平台和数据管理界面的 Tabler 组件包。 它不是单纯的 CSS 主题封装，而是把 Tabler 的视觉语言、常见后台部件和前端插件整合成可复用的 Yii2 Widget 与 Asset Bundle。 从产品目标上，它不应只是一个“Tabler 版补充包”，而应逐步成为 yiisoft/yii2-bootstrap5 的上位替代：既覆盖 Bootstrap 常用能力，也提供更丰富的后台组件和更优的视觉表达。

产品定位 ¶

这个包解决的是 Yii2 后台项目里最常见的三个问题：

1. 设计系统已经选定 Tabler，但团队不希望在视图里手写大量碎片化 HTML。
2. 项目需要的不只是按钮、弹窗、导航，还包括图表、地图、富文本、拖拽上传、分段导航、状态指示、时间线、运营型表格等后台高频组件。
3. 团队希望把前端插件接入、资源发布、组件文档和测试门禁，统一收敛在包级别，而不是散落在每个业务应用里。

因此，bestyii/yii2-tabler 的目标不是替代 Yii2 本身，而是为 Yii2 提供一层偏产品化、偏后台场景的 Tabler 组件基座，并逐步补齐 yii2-bootstrap5 已有的核心能力。

当前交付面 ¶

基于当前仓库快照，这个包已经提供：

• 62 个顶层类，覆盖 Bootstrap 常用组件、Tabler 后台组件和表单基座。
• 31 个 Asset Bundle，用于统一管理 Tabler 及其配套前端依赖。
• 59 篇组件文档，位于 docs/components。
• 包级 phpunit、phpstan、ecs 三条质量门禁。

代表性组件包括：

• Bootstrap 核心层：ActiveForm、ActiveField、Breadcrumbs、ButtonDropdown、ButtonToolbar、LinkPager、NavBar、Popover、ToggleButtonGroup
• 基础界面：Button、Alert、Badge、Card、Modal、Offcanvas、Tabs、Toast
• 导航与页头：Nav、Dropdown、DropdownMenu、PageHeader、Pagination、NavSegmented
• 状态与运营表达：Status、StatusDot、StatusIndicator、Ribbon、Steps、Timeline、Tracking、Trending
• 内容与后台块：Avatar、AvatarList、EmptyState、Payment、Tag
• 数据与交互：Table、AdvancedTable、Range、Rating
• 插件型组件：Chart、Datepicker、Dropzone、Fullcalendar、Select、Signature、Typed、VectorMap、Wysiwyg

适合什么项目 ¶

适合：

• SaaS 后台
• CRM / ERP / OA
• 数据分析与运营平台
• 需要较强视觉完成度的内部管理系统
• 已经采用 Tabler 作为统一视觉系统的 Yii2 项目

不适合：

• 只需要最基础 Bootstrap 组件的轻量页面
• 主要面向营销落地页而非后台工作台的项目
• 必须严格沿用 yiisoft/yii2-bootstrap5 既有命名、示例和资源层约定，不接受迁移适配的项目

和应用的边界 ¶

这个包当前聚焦在“组件层”和“资源层”：

• 提供 Widget、Asset Bundle、组件文档和测试
• 不内置应用级模块、站点路由或布局系统
• 不伪装成完整后台脚手架

也就是说，它更像一个可持续维护的 UI 组件包，而不是一个整站模板。

安装 ¶

composer require bestyii/yii2-tabler

当前要求：

• PHP 8.2 - 8.4
• Yii2 ~2.0.32

官方支持策略和兼容承诺见 docs/support-policy.md。

快速开始 ¶

1. 渲染一个按钮 ¶

use bestyii\tabler\Button;

echo Button::primary(
    'Open Preview',
    icon: 'eye',
    url: ['/preview'],
);

2. 渲染一个标准页头 ¶

use bestyii\tabler\Badge;
use bestyii\tabler\PageHeader;

echo PageHeader::widget([
    'preTitle' => 'Operations',
    'title' => 'Hybrid Validation Board',
    'content' => Badge::green('Ready', lite: true),
]);

对于高频场景，组件现在提供了更易写的静态 helper，例如 Badge::secondary('Draft')、Button::primary('Save')、Alert::success('Done')、Progress::success(72, label: '72%')。底层的 ::widget([...]) API 仍然保留，适合更完整的配置数组。

如果颜色或类型是在业务代码里动态算出来的，可以进一步使用类型化的 make()：

use bestyii\tabler\Badge;
use bestyii\tabler\Button;

echo Badge::make(color: 'orange', text: 'Review queue', lite: true);
echo Button::make(color: 'danger', label: 'Delete', outline: true, icon: 'trash');

当前已支持语法糖的组件和预设范围如下：

• Badge：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• Button：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• Alert：primary、secondary、success、info、warning、danger
• Progress：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• Tag：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• Status：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• StatusDot：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• StatusIndicator：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• Ribbon：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• Spinner：border、grow
• ButtonDropdown：primary、secondary、success、info、warning、danger、blue、azure、indigo、purple、pink、red、orange、yellow、lime、green、teal、cyan、dark
• Offcanvas：left、right、top、bottom
• Popover：auto、top、bottom、left、right