Yii Framework Twig Extension 3.0.0

Yii View Twig Renderer version 3.0.0 was released. In this version:

• Rename ViewRenderer to more understandable TwigTemplateRenderer
• Remove YiiTwigExtension
• Update version of yiisoft/view to ^11|^12
• Change PHP constraint in composer.json to 8.1 - 8.5
• Raise the minimum PHP version to ^8.1

HaloBCA melalui 628131500646 WhatsApp dapat diakses 24 jam, memungkinkan Anda mendapatkan bantuan dan informasi... ¶

Version 2.3.8 of Queue extension for Yii 2 was released.

This release fixes problems with SQS and Redis, prevents multiple execution of aborted jobs, and adds PHP 8.4 compatibility. Environment variables are now passed to sub-processes.

See the CHANGELOG for details.

It happened! Yii3 is officially released after years of intensive development and polishing.

Yii was always following the same principles of being performant, flexible but with good defaults, practice-oriented, simple, explicit, and consistent. Yii3 is not an exception.

While Yii 1.1 and Yii 2.0 are good frameworks, Yii3 was born to improve things even more, addressing the following drawbacks:

1. Yii 2.0 had a closed ecosystem with difficulties configuring general PHP packages.
2. Some magic and implicitness. Non-standard PHP behavior for objects introduced in Yii 2.0.
3. PHP standards compatibility and modern PHP usage were not in place due to backwards compatibility constraints.
4. Some anti-patterns, such as the service locator being available out of the box. That was affecting overall projects' testability and maintainability in the long run.

In the following we will summarize some of the highlights of this long-awaited release. You may check out the Getting Started section if you want to rush to try it out first.

Independent packages ¶

Compared to Yii 1.1 and Yii 2.0 which were monolithic frameworks, Yii3 is a package ecosystem with more than 130 official packages. These packages could be used in any PHP code or as a whole framework relatively similar to Yii 2.0 or Yii 1.1. Application templates help a lot in this case.

Application templates ¶

There are three application templates available out of the box:

• Web — for classic server-rendered applications.
• API — for APIs.
• Console — for console-only tools and background workers.

Unlike Yii 2.0, these are very minimalistic, so you start with basic things such as routing, configuration, DI container, or environment already wired together for you. But, at the same time, additional functionality, such as connecting to a database, isn't in templates by default. Install only what you need—no bloat, just solutions.

Ability to use any packages ¶

Instead of focusing on Yii-specific extensions, as it was with Yii 2.0, we've made the framework to work well with any PHP packages available at Packagist, be they PSR-compatible ones, Symfony packages, or generic PHP code. The container is able to configure any of these.

Yii3 embraces the entire PHP ecosystem instead of reinventing the wheel. It integrates seamlessly with any PHP library. No vendor lock-in. No proprietary APIs. Just modern PHP standards enabling you to leverage the entire ecosystem's innovation.

First-class DI container ¶

The central part of the framework is its dependency injection container. It brings all the individual packages together, automatically resolving dependencies and helping to obtain classes requested. Usual usage is very simple and explicit:

return [
   // Interface to class mapping
   EngineInterface::class => EngineMarkOne::class,
   
   // Detailed configuration
   MyServiceInterface::class => [
       'class' => MyService::class,
       '__construct()' => [42],
       'setDiscount()' => [10],
   ],

   // Factory closures
   'api' => static fn(ApiConfig $config) => new ApiClient($config),
];

// Dependencies are automatically injected based on type hints
final readonly class MyController
{
   public function __construct(
       private CacheInterface $cache
   ) {}
}

Another advantage of the container is that it is very fast and works at runtime. Your configuration is what is actually executed, so there is no magic, and you can even step-debug it with XDebug if needed.

Configuration ¶

Following the traditional way of configuring things with Yii 2.0, we've extracted what was included into an advanced application supporting multiple environments, config overrides, etc. The configuration in Yii3 is very powerful and could be configured to follow basically any layout of the project if needed. By default, application templates are supplying configuration that is divided into web (or API) and console, also having some common shared configs. The configuration is divided into two main parts there: DI container configuration, which maps configured classes to interfaces, and parameters, which are used for configuring these classes.

'yiisoft/view' => [
    'basePath' => null,
    'parameters' => [
        'assetManager' => Reference::to(AssetManager::class),
        'applicationParams' => Reference::to(ApplicationParams::class),
        'aliases' => Reference::to(Aliases::class),
        'urlGenerator' => Reference::to(UrlGeneratorInterface::class),
        'currentRoute' => Reference::to(CurrentRoute::class),
    ],
],

'yiisoft/yii-view-renderer' => [
    'viewPath' => null,
    'layout' => '@src/Web/Shared/Layout/Main/layout.php',
    'injections' => [
        Reference::to(CsrfViewInjection::class),
    ],
],

Security ¶

Similar to Yii 1.1 and Yii 2.0, we take security seriously. It was considered when implementing every package, such as the presentation layer and database abstraction.

As for features:

• Access control abstraction
• RBAC implementation for access control
• JWT authentication
• User abstraction for applications
• Middleware for handling proxy chains and headers
• Third-party authentication client.

There are also helpers for common security-related actions, such as the CSRF-protection package.

Documentation contains a dedicated guide page with established security response processes.

Databases ¶

Yii 2.0 had an exceptional database abstraction layer. At first, we extracted it into a separate package and then reimagined and improved it. It resulted in yiisoft/db, which is database access, schema management, and a powerful query builder. Extra tools and storage, such as migrations, database caching, etc., were built on top of DB as well as a more explicit but still rapid Active Record implementation.

$posts = $connection
   ->select(['id', 'title', 'created_at'])
   ->from('{{%posts}}')
   ->where(['status' => 'published'])
   ->andWhere(['>', 'views', 1000])
   ->orderBy(['created_at' => SORT_DESC])
   ->limit(10)
   ->all();

Other than our own database layer, you can use Cycle ORM or Doctrine, make queries using PDO or native drivers. Whatever you prefer. Yii3 does not force you to stick to a single implementation.

Data abstraction ¶

Powerful data abstraction yiisoft/data, and widgets for it, such as grid view, are there and are perfect for creating powerful universal admin panels. The abstraction includes data formatting, pagination, sorting, and an ability to use any data source with any action/presentation and vice versa.

Caching  ¶

Caching got even more advanced than in Yii 2.0. First of all, out of the box there's a cache stampede protection. Second, cache drivers are PSR-16 compatible. That means you can use any PSR-16 implementation for a very specific storage, and it will work right away.

The following backends were implemented by our team already:

• APCu
• DB
• Files
• Memcached
• Redis

Standards first ¶

Similar to caching, the framework leverages PSR interfaces for more:

• Logging so you can either stick to Yii's logger or replace it with Monolog if you prefer it.
• Middleware so you can bring endless solutions from Packagist, such as CORS handling, and use these without any changes to the code.
• Request-response abstraction that allows optimal testing and worker mode.
• Even a DI container could be either replaced or combined with another PSR-compliant one.

Standards-first architecture ensures your code stays portable and future-proof while maintaining full access to modern PHP tooling.

Worker mode ¶

In traditional PHP servers, framework initialization and database connection are done for every request, which is not great for performance. Yii3 may run in worker mode together with RoadRunner, Swoole, or FrankenPHP. In this mode it initializes once and then serves many request-response cycles, which results in drastically lower response times.

While this mode is great, the state is largely shared between multiple request-response processing, so developers should take care of isolating the state (or not storing it at all) and potential memory leaks. Yii3 helps with it a lot: all the packages were designed either to not use any state or to reset it properly on every start of the request.

Everything for classic web applications ¶

Not every project should be an API with a client so everything for classic server-rendered web applications is available: Widgets, Views with template engines support such as Twig, Forms, asset management, HTML helpers, etc.

Additionally, there are ready-to-use widgets for Bootstrap 5 and Bulma.

A toolset for building APIs ¶

Yii3 provides many tools that help build APIs:

• Data response that takes care of data presentation.
• Swagger support.

We plan to add more in the future but the current set is already enough for building powerful APIs.

HTTP layer and networking ¶

Yii3 works with the HTTP layer on a more precise level than previous versions of the framework and follows PSR interfaces. On top of these relatively low-level interfaces, there are handy abstractions:

• HTTP helpers that define response codes and more
• Cookies
• Download Response Factory  to allow sending files from an application

Additionally, network utilities are there to help with the IP protocol. 

User input and validator ¶

Yii3 has a powerful validator powered by attributes, the ability to fill forms with data from HTTP (input-http) or elsewhere, tools to work with forms, and more.

<?php

declare(strict_types=1);

namespace App\Web\Echo;

use Yiisoft\FormModel\FormModel;
use Yiisoft\Validator\Label;
use Yiisoft\Validator\Rule\Length;

final class Form extends FormModel
{
    #[Label('The message to be echoed')]
    #[Length(min: 2)]
    public string $message = '';
}

Helpers ¶

There are various helpers available to simplify common programming tasks.

• Arrays
• Files
• JSON
• Strings
• VarDumper

Internationalization ¶

Since the Yii framework community and the team members are from all over the world, we take internationalization seriously and understand it very well.

Out of the box, Yii3 has:

• Message translation with intl-powered ICU formatting.
• Support in a view layer.
• Support in the router.

Testing ¶

Proper dependency Inversion makes it easy to unit test the code created with Yii3. Following PSR for request and response allows you to perform API testing without actually running an HTTP server.

To ease testing even more, a set of test-specific PSR implementations are provided by yiisoft/test-support.

Error handling ¶

We value developers' time. That's why we pay attention to error messages and the error page. All these are exceptionally useful. Messages provide context. We'll never use "Error" as a message. Additionally, we took it to the next level with "friendly exceptions." In development mode these are rendered with the information block that explains why the error happened and how to likely fix it. In the future we'll try to provide a button that will automatically try to apply the fix.

The error page contains the error. For each stack trace level, it displays the source code. The line where the error happened is highlighted. Stacktrace items that are part of the framework packages are collapsed by default because these are tested so much that it's unlikely that the error is there.

The handler itself, yiisoft/error-handler, is even more interesting than the one of Yii2. It handles out-of-memory errors and fatals, can maps certain exception types to custom exceptions, respond in different formats, etc.

Additionally, there is a package to integrate Sentry for error collection.

Documentation ¶

There are the following resources available:

• The definitive guide — the main source about using the framework as a whole.
• Community cookbook — how to do X with Yii3.
• API docs for all packages — all the public API rendered nicely for browsing
• Individual package readme and docs — explains how to use each individual package

Exceptional quality standards ¶

Yii3 maintains exceptional code quality standards across all packages. Every line undergoes rigorous verification through multiple layers of automated testing and analysis. 

For all the packages, we have nearly 100% coverage with tests, strict Psalm/PhpStan types, and a close to 100% mutation score. Every code change is reviewed publicly. All these measures give an exceptionally stable and predictable foundation for your projects.

Predictable releases ¶

The release policy is SemVer. Each package is versioned independently. Patch versions never break anything while fixing bugs. The minor version introduces enhancements and features but is still compatible. The major version introduces backwards incompatible changes requiring code updates.

And more ¶

There are many additional features that are less exciting but are very important:

• Aliases
• Events
• Profiler
• Requirements checker
• Mailer
• Console
• Mutex locks with various backends

Likely we forgot to mention some parts of the framework, so go ahead and explore.

Useful resources ¶

Below are some useful links about Yii3:

• Check out the nice landing page here.
• The guide is here. We recommend the "getting started" first.
• API docs are available as well.
• Yii3 packages. Don't forget to star these!
• Telegram group.
• Yii project site
• Yii Facebook group
• Yii X feeds
• Yii LinkedIn group

Thank you! ¶

Thank you for your support and patience! We did it together. All the core team members, community contributors, and backers.

We're pretty sure the Yii3 codebase will serve us well in at least the next 10 years or even more.

Future plans are:

1. Guide improvements and missing pieces.
2. More package releases to enrich the ecosystem and tooling. Queue, the debug panel, and Gii already work well, but we're still polishing these.
3. Checking feedback, fixing, and improving things.
4. Website improvements.

Merry Christmas and Happy New Year! Enjoy!

We are very pleased to announce the release of Redis extension version 2.1.0.

This version fixes one PHP 8.4 compatibility issue that was found since last release, adds support for predis, changes yii\redis\Cache::$forceClusterMode to false, and makes yii\redis\Connection implement yii\redis\ConnectionInterface.

See the CHANGELOG for details.

We are very pleased to announce that Yii Framework version 1.1.32 is released. You can download it at yiiframework.com/download/.

Yii 1.1.32 adds support for PHP 8.4 and improves compatibility with PHP 8.

This release is a release of Yii 1.1, which has reached maintenance mode and will only receive security and compatibility fixes. For the complete list of changes in this release, please see the change log. For upgrading, always make sure to read the upgrade instructions.

We would like to express our gratitude to all contributors who have spent their precious time helping improve Yii and made this release possible.

Yii Form Model version 1.1.0 was released. In this version:

• Add populateFromGet() and populateFromGetAndValidate() to FormHydrator
• Add PHP 8.5 support

Yii3 API project template version 1.1.0 was released. In this version:

• Add Makefile stop goal for stopping Docker containers (@samdark,
• Prune unused container and do not detach on make prod-deploy
• Add PHP 8.5 support
• Update composer dependencies

Cycle ORM query adapter for yiisoft/data version 1.0.0 was released.

There package provides Cycle ORM query adapter and writer for Yii Data.

See package documentation for usage.

Yii3 web application template version 1.1.0 was released. In this version:

• Add Makefile stop goal for stopping Docker containers
• Update structure in src/ directory
• Improve message for missing or invalid APP_ENV
• Remove <meta http-equiv="X-UA-Compatible" content="IE=edge"> from layout
• Update composer dependencies
• Use relative path for Psalm cache directory
• Prune unused container and do not detach on make prod-deploy
• Add PHP 8.5 support
• Always use only one goal in Makefile
• Add DI container delegates configuration
• Fix fake goals in Makefile

Yii RBAC Database storage 2.1.0

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

• Adapt to Yii DB 2
• Change PHP constraint in composer.json to 8.1 - 8.5
• Refactor AssignmentStorage::filterUserItemNames() method
• Bump yiisoft/rbac version to ^2.1
• Mark internal class ItemTreeTraversalFactory as final

Yii Event version 2.2.0 was released. In this version:

• Change PHP constraint in composer.json to 8.1 - 8.5
• Minor refactoring of CallableFactory and ListenerCollectionFactory
• Raise minimum PHP version to ^8.1 and refactor code

Yii Cache DB Handler version 1.1.0 was released. In this version:

• Bump supported version of yiisoft/db to ^2.0
• Change supported PHP versions to 8.1 - 8.5
• Mark DbSchemaManager::$db property as readonly

Yii Logging Library version 2.2.0 was released. In this version:

• Add optional $levels parameter to Target constructor allowing log level filtering at instantiation
• Add ext-psr to conflict section in composer.json

All targets were updated as well to allow $levels in constructor. Additionally:

• File Target 3.1.0 added categories, except and exportInterval setters to default config and replaced rotate by rename to rotate by copy.
• Syslog Target 2.1.0 removed dead code that checked case when syslog() returned false.
• DB Target 1.1.0 bumped minimal required PHP version to 8.1.

The first stable release of a powerful set of data displaying widgets is now available.

Yii DataView provides three flexible widgets for presenting data in web applications:

• ListView — display data as a customizable list.

• GridView — present data in a feature-rich grid with sorting, filtering, and pagination.

• DetailView — show detailed information about a single record.

Data Source Independence. Works seamlessly with database, CSV, REST API, or any data source through the Yii Data package.

Built-in Pagination. Handle large datasets efficiently with integrated pagination controls.

Internationalization. Full translation support for multilingual applications.

Theming Support. Customize appearance to match your application design.

Flexible Column Types. DataColumn with custom value presenters, ActionColumn, etc.

Modern PHP. Built for PHP 8.1 - 8.5 with type safety and modern best practices.

Yii Data DB, a database query adapter for Yii Data, is now available.

This package provides a data reader implementation that bridges Yii DB with the Yii Data reading interface, making it easy to work with database queries in a flexible and consistent way.

• QueryDataReader. Wraps database queries to provide pagination, sorting, and filtering capabilities.

• Field Mapping. Map data reader field names to database columns for clean API design.

• Batch Processing. Process large datasets efficiently with configurable batch sizes.

• Multi-Database Support. Tested with SQLite, MySQL, PostgreSQL, Microsoft SQL Server, and Oracle.

Yii Data 2 is now available, bringing major improvements and modernization to this package that provides generic data abstractions for reading, writing, and processing.

• PHP 8.1+ required: modernized codebase with readonly properties and improved type safety.

• Enhanced filtering: added Stringable support, nested value filtering, case-sensitive Like filter with matching modes, and new All/None filters.

• Improved pagination: new LimitableDataInterface, nextPage()/previousPage() methods, PageToken class, and better limit handling in paginators.

• Better developer experience: comprehensive Psalm annotations, PageNotFoundException for clearer error handling, and OrderHelper for low-level order operations.

For a complete list of changes, see the CHANGELOG.md.

Yii Middleware Dispatcher version 5.4.0 was released. In this version:

• Add support for using middlewares from container-registered identifier
• Add PHP 8.5 support

Yii HTML version 3.12.0 was released. In this version:

• Add Tag::addStyle() and Tag::removeStyle() methods
• Add Color class, Html::color() and Input::color() methods
• Add PHP 8.5 support
• Minor refactor RadioList::renderUncheckInput() and CheckboxList::renderUncheckInput() methods

Yii Caching Library version 3.2.0 was released. In this version:

• Add Ttl value object for working with time-to-live duration
• Add PHP 8.5 support

yii2-recurring-date ¶

1. Main Features
2. Installation
3. Usage
4. JSON Format (persisted)
5. Calculation of the Next Expiration Date
6. Configuration and Customization
7. Validations and UX Behavior
8. Internationalization (i18n)
9. Tests
10. Best Practices and Notes
11. Contributing
12. License

A Yii2 extension/widget that provides a simple and intuitive interface to define and manage recurring date patterns. It is designed to simplify the configuration of renewals, expirations, and periodic events, with clean integration into Yii2 forms and internationalization support.

Main Features ¶

• Visual interface to configure recurring periods: no expiration, interval (days/months/years), monthly (day of the month), yearly (day + month), and specific date.
• Handling of edge cases (e.g., days 29/30/31 and February 29) with configurable adjustment policy (previous | next).
• Persistence of the recurrence scheme in a hidden field as JSON ready to be sent to the server.
• Backend function to calculate the next expiration date based on a base date and the configuration.
• Localization (i18n) with translations in English and Spanish.

Installation ¶

Install the extension with Composer:

composer require davidrnk/yii2-recurring-date

Register the asset (if the widget does not do it automatically) and add the widget to your views/forms according to the usage examples.

Usage ¶

The extension can be used with Yii2 models (ActiveForm) or independently.

Usage with model (ActiveForm):

use davidrnk\RecurringDate\Widget\RecurringDate;

echo $form->field($model, 'recurrence_config')->widget(RecurringDate::class, [
    // options
    'options' => ['class' => 'form-control my-custom-class'],
    'labels' => [
        'title_modal' => 'Configure recurrence',
        // you can override other labels
    ],
]);

Usage without model:

echo davidrnk\RecurringDate\Widget\RecurringDate::widget([
    'name' => 'recurrence',
    'value' => json_encode(['type' => 'monthly', 'day' => 1]),
    'options' => ['class' => 'form-control'],
]);

The widget renders a read-only text control with a button to open a modal where recurrence is configured. The resulting JSON is saved in a hidden field (input.hidden) and is the content you should store in the database.

JSON Format (persisted) ¶

The widget persists the configuration in JSON format with the following main structure (examples):

• No expiration

{"type": "no_expiration"}

• Interval

{ "type": "interval", "value": 10, "unit": "days" }

• Monthly (day of the month) + optional adjustment

{ "type": "monthly", "day": 31, "adjust": "previous" }

• Yearly (day + month) + optional adjustment

{ "type": "yearly", "day": 29, "month": 2, "adjust": "previous" }

• Specific date

{ "type": "specific_date", "date": "2025-12-31" }

Relevant keys:

• type: one of no_expiration, interval, monthly, yearly, specific_date.
• value, unit: used by interval (unit: days|months|years).
• day: day of the month (1-31).
• month: month (1-12).
• date: ISO date for specific_date.
• adjust: policy when the day does not exist in the period (values: previous — adjust to the last valid day of the month, or next — move to the next day).

Calculation of the Next Expiration Date ¶

In the backend, the library provides a function to calculate the resulting date based on a base date and the JSON configuration. In the code the function is called:

use davidrnk\RecurringDate\Core\RecurringDateEngine;

$nextDueDate = RecurringDateEngine::calculateExpiration($startDate, $configArray);
// returns DateTime instance or null if configuration is invalid

In the documentation and examples of this README, we refer to this date as nextDueDate. If calculateExpiration returns null, the combination of parameters is invalid or could not be calculated.

Quick example:

$start = new \DateTime('2025-01-31');
$cfg = ['type' => 'monthly', 'day' => 31, 'adjust' => 'previous'];
$next = RecurringDateEngine::calculateExpiration($start, $cfg);
echo $next ? $next->format('Y-m-d') : 'invalid';

Configuration and Customization ¶

The widget exposes several ways to adjust its visual and textual behavior:

• options (array): HTML attributes for the visible text field (e.g., class, style, placeholder).
• labels (array): you can override texts and labels used in the modal. Examples of keys you can customize:
  • title_modal, type, configure, preview, save, cancel, quantity, unit, month_day, adjust, adjust_previous, adjust_next, etc.
• Translations: the extension includes files in src/messages/en and src/messages/es. The displayed texts are also sent to JavaScript for preview.

Example of label customization:

echo $form->field($model, 'recurrence_config')->widget(RecurringDate::class, [
    'labels' => [
        'title_modal' => 'Schedule repetition',
        'adjust_previous' => 'Adjust to the last day of the month',
    ],
]);

Validations and UX Behavior ¶

• The widget validates on the client side combinations that are clearly invalid (e.g., 31 in months with 30 days, February 31) and blocks saving when the selection is fatal.
• For non-fatal cases (e.g., day >= 29 in monthly or February 29 in yearly), it shows a warning and allows the user to select the adjust policy.
• The adjust value is persisted in JSON and is considered by RecurringDateEngine::calculateExpiration.

Internationalization (i18n) ¶

The default language of the extension is English. Translations are included in src/messages/en and src/messages/es. Strings used in views and JavaScript translations are defined and loaded from RecurringDate::getJSTranslations().

If you need to add another language, add a file in src/messages/XX/davidrnk.recurring.php with the required keys.

Tests ¶

Unit tests for PHP are included for the calculation logic (tests/RecurringDateEngineTest.php) and should be executed with:

vendor/bin/phpunit tests/RecurringDateEngineTest.php

Best Practices and Notes ¶

• Save the persisted JSON directly in a text field in the database (e.g., recurrence_config), and use RecurringDateEngine::calculateExpiration to obtain the next expiration date when needed.
• Decide and document the default adjust policy for your domain (by default the extension uses previous — clamp to the last valid day). This avoids surprises when calculating next dates.
• Review the locale configuration (Yii::$app->language) to ensure the UI displays the desired translations.

Contributing ¶

Pull requests and issues are welcome. For major changes, first open an issue describing the proposed change.

License ¶

BSD-3-Clause — see LICENSE file.

Yii2 - Modern Starter Kit

1. Screenshots
2. Requirements
3. Installation
4. Production Build
5. Configuration
6. Directory Structure
7. Testing

Yii2 - Modern Starter Kit is a modern, full-featured Yii 2 application template with React frontend powered by Inertia.js.

The template includes a beautiful UI built with Shadcn UI components, dark/light theme support, user authentication, CRUD operations, and all the modern features you need to rapidly build web applications.

Screenshots ¶

Light Theme ¶

Dark Theme ¶

Requirements ¶

Before you begin, ensure you have the following installed on your system:

• PHP >= 7.4.0 (PHP 8.0+ recommended)
• Composer - PHP dependency manager (Install Composer)
• Node.js >= 18.0.0 and npm (or yarn)
• MySQL >= 5.7 or MariaDB >= 10.3
• Web Server (Apache/Nginx) or PHP built-in server

Installation ¶

Step 1: Clone the Repository ¶

git clone [email protected]:crenspire/yii2-react-starter.git
cd yii2-react-starter

Or download and extract the project archive to your desired directory.

Step 2: Install PHP Dependencies ¶

Install all PHP dependencies using Composer:

composer install

This will install all required PHP packages including Yii2 framework and Inertia.js adapter.

Step 3: Install Node.js Dependencies ¶

Install all frontend dependencies:

npm install

This will install React, Inertia.js, Shadcn UI components, Tailwind CSS, and all other frontend dependencies.

Step 4: Configure Database ¶

1. Create a MySQL database for your application:

CREATE DATABASE yii2basic CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

1. Update the database configuration in config/db.php:

return [
    'class' => 'yii\db\Connection',
    'dsn' => 'mysql:host=localhost;dbname=yii2basic',
    'username' => 'root',
    'password' => 'your_password',
    'charset' => 'utf8mb4',
];

Replace your_password with your MySQL root password (or your database user credentials).

Step 5: Run Database Migrations ¶

Run the migrations to create all necessary database tables:

php yii migrate

This will create the following tables:

• users - User accounts with soft deletes
• password_reset_tokens - Password reset functionality
• And other required tables

Step 6: Seed Admin User (Optional) ¶

Create an admin user for testing:

php yii seed/admin

This creates an admin user with:

• Email: [email protected]
• Password: admin123

Step 7: Configure Cookie Validation Key ¶

The cookie validation key should be automatically generated during composer install. If it wasn't, you can generate it manually:

1. Open config/web.php
2. Find the cookieValidationKey in the request component
3. Set it to a random string (32 characters recommended):

'request' => [
    'cookieValidationKey' => 'your-random-32-character-string-here',
],

You can generate a random string using:

php -r "echo bin2hex(random_bytes(16));"

Step 8: Start Development Servers ¶

You need to run two servers simultaneously:

1. PHP Development Server (Backend): `bash php yii serve `

2. Vite Development Server (Frontend): `bash npm run dev `

Or use concurrently to run both at once (if installed):

npx concurrently "php yii serve" "npm run dev"

Step 9: Access the Application ¶

Open your browser and navigate to:

http://localhost:8080

You should see the home page. You can now:

• Sign Up: Create a new account at /auth/register
• Sign In: Login at /auth/login (or use admin credentials if you seeded)
• Dashboard: Access the dashboard at /dashboard (requires login)

Production Build ¶

For production deployment, build the frontend assets:

npm run build

This will compile and optimize all React components and assets into the web/dist directory.

Configuration ¶

Environment Configuration ¶

The application uses Yii2's environment configuration. You can set the environment by:

1. Copying config/params.php and modifying as needed
2. Setting YII_ENV constant in web/index.php:
   • YII_ENV_DEV - Development mode
   • YII_ENV_PROD - Production mode

Additional Configuration Files ¶

• config/web.php - Web application configuration
• config/console.php - Console application configuration
• config/db.php - Database configuration
• config/params.php - Application parameters

NOTES:

• Make sure the runtime/ and web/assets/ directories are writable by the web server
• For production, disable debug mode and enable schema caching in config/web.php
• Configure your web server to point to the web/ directory as the document root

Directory Structure ¶

assets/             contains assets definition
commands/           contains console commands (controllers)
config/             contains application configurations
controllers/        contains Web controller classes
mail/               contains view files for e-mails
models/             contains model classes
migrations/         contains database migrations
resources/          contains frontend resources (React, CSS, JS)
  js/               React components and pages
  css/              Stylesheets
runtime/            contains files generated during runtime
tests/              contains various tests for the basic application
vendor/             contains dependent 3rd-party packages
views/              contains view files for the Web application
web/                contains the entry script and Web resources
  images/           contains screenshots and images
  dist/             contains built frontend assets (production)

Testing ¶

Tests are located in tests directory. They are developed with Codeception PHP Testing Framework. By default, there are 3 test suites:

• unit
• functional
• acceptance

Tests can be executed by running

vendor/bin/codecept run

The command above will execute unit and functional tests. Unit tests are testing the system components, while functional tests are for testing user interaction. Acceptance tests are disabled by default as they require additional setup since they perform testing in real browser.

Running acceptance tests ¶

To execute acceptance tests do the following:

1. Rename tests/acceptance.suite.yml.example to tests/acceptance.suite.yml to enable suite configuration

2. Replace codeception/base package in composer.json with codeception/codeception to install full-featured version of Codeception

3. Update dependencies with Composer

   composer update

4. Download Selenium Server and launch it:

   java -jar ~/selenium-server-standalone-x.xx.x.jar

   In case of using Selenium Server 3.0 with Firefox browser since v48 or Google Chrome since v53 you must download GeckoDriver or ChromeDriver and launch Selenium with it:

   ` # for Firefox java -jar -Dwebdriver.gecko.driver=~/geckodriver ~/selenium-server-standalone-3.xx.x.jar

   # for Google Chrome java -jar -Dwebdriver.chrome.driver=~/chromedriver ~/selenium-server-standalone-3.xx.x.jar `

   As an alternative way you can use already configured Docker container with older versions of Selenium and Firefox:

   docker run --net=host selenium/standalone-firefox:2.53.0

5. (Optional) Create yii2basic_test database and update it by applying migrations if you have them.

   tests/bin/yii migrate
   

   The database configuration can be found at config/test_db.php.

1. Start web server:

   tests/bin/yii serve

2. Now you can run all available tests

   # run all available tests
   vendor/bin/codecept run
   
   # run acceptance tests
   vendor/bin/codecept run acceptance
   
   # run only unit and functional tests
   vendor/bin/codecept run unit,functional
   

Code coverage support ¶

By default, code coverage is disabled in codeception.yml configuration file, you should uncomment needed rows to be able to collect code coverage. You can run your tests and collect coverage with the following command:

#collect coverage for all tests
vendor/bin/codecept run --coverage --coverage-html --coverage-xml

#collect coverage only for unit tests
vendor/bin/codecept run unit --coverage --coverage-html --coverage-xml

#collect coverage for unit and functional tests
vendor/bin/codecept run functional,unit --coverage --coverage-html --coverage-xml

You can see code coverage output under the tests/_output directory.

1. Introduction
2. Installation
3. Quick Setup
4. Core Features
5. Best Practices
6. Common Patterns
7. Troubleshooting
8. Additional Resources
9. Conclusion

Introduction ¶

Inertia.js is a modern approach to building single-page applications (SPAs) without the complexity of building an API. It allows you to use modern JavaScript frameworks like React, Vue, or Svelte while keeping your Yii2 controllers and routing intact.

Why Inertia.js?

• No need to build a separate API
• Keep your existing Yii2 controllers and models
• Server-side routing and validation
• Better SEO than traditional SPAs
• Simpler architecture than API + SPA

The crenspire/yii2-inertia package provides a seamless Inertia.js adapter for Yii2, matching the developer experience of popular frameworks like Laravel's Inertia adapter.

Installation ¶

Install via Composer:

composer require crenspire/yii2-inertia

Quick Setup ¶

1. Configure the View Renderer ¶

Add to your config/web.php:

'view' => [
    'renderers' => [
        'inertia' => \Crenspire\Yii2Inertia\ViewRenderer::class,
    ],
],

2. Create Root Template ¶

Create views/layouts/inertia.php:

<!DOCTYPE html>
<html lang="<?= Yii::$app->language ?>">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title><?= Html::encode($this->title) ?></title>
    <script type="module" src="/dist/assets/index.js"></script>
    <link rel="stylesheet" href="/dist/assets/index.css">
</head>
<body>
    <div id="app" data-page="<?= htmlspecialchars(json_encode($page), ENT_QUOTES, 'UTF-8') ?>"></div>
</body>
</html>

3. Use in Controllers ¶

use Crenspire\Yii2Inertia\Inertia;

class HomeController extends \yii\web\Controller
{
    public function actionIndex()
    {
        return Inertia::render('Home', [
            'title' => 'Welcome',
            'users' => User::find()->all(),
        ]);
    }
}

4. Setup Frontend ¶

Install Inertia.js and your framework:

# For React
npm install @inertiajs/inertia @inertiajs/inertia-react react react-dom

# For Vue
npm install @inertiajs/inertia @inertiajs/inertia-vue3 vue

# For Svelte
npm install @inertiajs/inertia @inertiajs/inertia-svelte svelte

Create src/main.jsx (React example):

import React from 'react';
import ReactDOM from 'react-dom/client';
import { createInertiaApp } from '@inertiajs/inertia-react';
import Home from './pages/Home';
import Dashboard from './pages/Dashboard';

createInertiaApp({
  resolve: (name) => {
    const pages = { Home, Dashboard };
    return pages[name];
  },
  setup({ el, App, props }) {
    ReactDOM.createRoot(el).render(<App {...props} />);
  },
});

Core Features ¶

Sharing Global Data ¶

Share data that should be available on every page:

// In config/bootstrap.php or base controller
use Crenspire\Yii2Inertia\Inertia;

// Share user data
Inertia::share('user', function () {
    return Yii::$app->user->identity;
});

// Share flash messages
Inertia::share('flash', function () {
    return [
        'success' => Yii::$app->session->getFlash('success'),
        'error' => Yii::$app->session->getFlash('error'),
    ];
});

// Share multiple values
Inertia::share([
    'appName' => 'My Application',
    'version' => '1.0.0',
]);

Tip: Use closures for dynamic data (like user or flash messages) to ensure fresh data on each request.

Handling Redirects ¶

For form submissions and other redirects, use Inertia::location():

public function actionStore()
{
    $model = new User();
    
    if ($model->load(Yii::$app->request->post()) && $model->save()) {
        Yii::$app->session->setFlash('success', 'User created!');
        return Inertia::location('/users');
    }
    
    return Inertia::render('Users/Create', [
        'errors' => $model->errors,
    ]);
}

The method automatically handles both Inertia requests (409 status) and regular requests (302 redirect).

Asset Versioning ¶

Set up versioning for cache busting:

// Automatic (uses manifest.json mtime if exists)
$version = Inertia::version();

// Manual string
Inertia::version('1.0.0');

// Callback (recommended)
Inertia::version(function () {
    return filemtime(Yii::getAlias('@webroot/dist/manifest.json'));
});

Partial Reloads ¶

Optimize performance by only reloading specific props:

// Client requests only 'users' and 'stats' props
return Inertia::render('Dashboard', [
    'users' => $users,      // Included
    'stats' => $stats,      // Included
    'other' => $other,      // Excluded
]);

In your frontend component:

import { router } from '@inertiajs/inertia-react';

const refreshStats = () => {
  router.reload({ only: ['stats'] });
};

Best Practices ¶

1. Organize Components by Route ¶

Structure your frontend to match backend routes:

src/pages/
  Home.jsx
  Dashboard.jsx
  Users/
    Index.jsx
    Show.jsx
    Edit.jsx

// Maps to src/pages/Users/Index.jsx
return Inertia::render('Users/Index', ['users' => $users]);

2. Handle Forms with Inertia ¶

Use Inertia's form helper for better UX:

import { useForm } from '@inertiajs/inertia-react';

export default function CreateUser() {
  const { data, setData, post, processing, errors } = useForm({
    name: '',
    email: '',
  });

  const submit = (e) => {
    e.preventDefault();
    post('/users');
  };

  return (
    <form onSubmit={submit}>
      <input
        value={data.name}
        onChange={(e) => setData('name', e.target.value)}
      />
      {errors.name && <div>{errors.name}</div>}
      <button disabled={processing}>Submit</button>
    </form>
  );
}

3. Error Handling ¶

Return validation errors from your controller:

public function actionStore()
{
    $model = new User();
    
    if ($model->load(Yii::$app->request->post()) && $model->save()) {
        return Inertia::location('/users');
    }
    
    // Return with errors
    return Inertia::render('Users/Create', [
        'errors' => $model->errors,
        'values' => $model->attributes,
    ]);
}

4. Flash Messages ¶

Create a reusable flash message component:

// Share flash messages globally
Inertia::share('flash', function () {
    return [
        'success' => Yii::$app->session->getFlash('success'),
        'error' => Yii::$app->session->getFlash('error'),
    ];
});

// FlashMessage.jsx
import { usePage } from '@inertiajs/inertia-react';

export default function FlashMessage() {
  const { flash } = usePage().props;
  
  if (!flash) return null;
  
  return (
    <div>
      {flash.success && <div className="alert-success">{flash.success}</div>}
      {flash.error && <div className="alert-error">{flash.error}</div>}
    </div>
  );
}

5. Pagination ¶

Handle pagination with Yii2's DataProvider:

use yii\data\ActiveDataProvider;

public function actionIndex()
{
    $dataProvider = new ActiveDataProvider([
        'query' => User::find(),
        'pagination' => ['pageSize' => 15],
    ]);
    
    return Inertia::render('Users/Index', [
        'users' => $dataProvider->getModels(),
        'pagination' => [
            'currentPage' => $dataProvider->pagination->page + 1,
            'lastPage' => $dataProvider->pagination->pageCount,
            'perPage' => $dataProvider->pagination->pageSize,
            'total' => $dataProvider->totalCount,
        ],
    ]);
}

6. Optimize Database Queries ¶

Use eager loading to prevent N+1 queries:

$users = User::find()
    ->with('posts', 'comments')
    ->all();

7. Minimize Prop Size ¶

Only send necessary data:

// Instead of full models
return Inertia::render('Users/Index', [
    'users' => User::find()
        ->select(['id', 'name', 'email'])
        ->asArray()
        ->all(),
]);

Common Patterns ¶

Base Controller ¶

Create a base controller for shared functionality:

namespace app\controllers;

use Crenspire\Yii2Inertia\Inertia;
use yii\web\Controller;

abstract class BaseController extends Controller
{
    public function init()
    {
        parent::init();
        
        Inertia::share('user', function () {
            return Yii::$app->user->identity;
        });
    }
    
    protected function inertiaRender($component, $props = [])
    {
        return Inertia::render($component, $props);
    }
}

Resource Controller ¶

class UsersController extends BaseController
{
    public function actionIndex()
    {
        $users = User::find()->all();
        return $this->inertiaRender('Users/Index', ['users' => $users]);
    }
    
    public function actionShow($id)
    {
        $user = User::findOne($id);
        if (!$user) {
            throw new NotFoundHttpException('User not found');
        }
        return $this->inertiaRender('Users/Show', ['user' => $user]);
    }
    
    public function actionStore()
    {
        $model = new User();
        if ($model->load(Yii::$app->request->post()) && $model->save()) {
            Yii::$app->session->setFlash('success', 'User created!');
            return Inertia::location(['users/show', 'id' => $model->id]);
        }
        return $this->inertiaRender('Users/Create', [
            'errors' => $model->errors,
        ]);
    }
}

Troubleshooting ¶

Version Mismatch Issues ¶

If you're experiencing frequent full page reloads:

1. Ensure your version callback returns a stable value
2. Check that manifest.json exists and is readable
3. Verify file permissions

Inertia::version(function () {
    $manifest = Yii::getAlias('@webroot/dist/manifest.json');
    return file_exists($manifest) ? (string)filemtime($manifest) : '1';
});

Redirects Not Working ¶

Always use Inertia::location() instead of Yii::$app->response->redirect() for Inertia requests.

Props Not Available in Frontend ¶

1. Verify props are passed as an array in PHP
2. Ensure props are JSON-serializable (no closures)
3. Use the usePage() hook correctly:

import { usePage } from '@inertiajs/inertia-react';

const { props } = usePage();
const { title, user } = props;

CSRF Token ¶

Share CSRF token globally:

Inertia::share('csrfToken', function () {
    return Yii::$app->request->csrfToken;
});

Use in forms:

<input type="hidden" name="_token" value={props.csrfToken} />

Additional Resources ¶

• Package Repository: GitHub - crenspire/yii2-inertia
• Inertia.js Documentation: https://inertiajs.com/
• Example Application: See the examples/basic directory in the repository

Conclusion ¶

Inertia.js with Yii2 provides a powerful way to build modern SPAs while keeping the simplicity and power of server-side routing and validation. The crenspire/yii2-inertia package makes it easy to integrate Inertia.js into your Yii2 applications with a familiar API.

Give it a try and let us know what you think! For issues, questions, or contributions, please visit the GitHub repository.

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

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

In this release:

• PHP 8.5 support. The minimum supported version was raised from 7.3 to 7.4.
• PHPStan/Psalm annotations revamped, adding better IDE support and static types.
• Fixture loader now throws exceptions instead of ignoring missing fixtures.
• ArrayDataProvider now supports paths as keys.
• BaseStringHelper::convertIniSizeToBytes().
• Bug fixes.

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 took 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.

yii2-scheduler ¶

1. Installation
2. Usage
3. Upgrade notes
4. Release checklist
5. Logging
6. Monitoring Events
7. Cleanup and safety
8. Compatibility
9. License

High-resolution cron-like job scheduler for Yii2 supporting:

• External cron mode (invoke the scheduler from system cron, typically every minute)
• Daemon mode (single long-running loop with microsecond timing and drift correction)
• Queue integration (yii2-queue) or synchronous execution
• Single-instance locks with max running time and stale lock reclamation
• Atomic distributed locks (cache add) with metadata: {pid, host, ts}
• Robust cron pattern parsing: wildcards, ranges, steps, lists

Installation ¶

1. Require the package (after you publish it to a VCS):

composer require ldkafka/yii2-scheduler

1. Configure in your Yii2 console app (e.g. console/config/main.php):

return [
    'bootstrap' => [
        // ensure the component can bootstrap its controller
        'scheduler',
    ],
    'components' => [
        'cache' => [ /* your cache config */ ],
        'queue_scheduler' => [ /* your yii2-queue config */ ],

        'scheduler' => [
            'class' => ldkafka\scheduler\Scheduler::class,
            'config' => [
                'cache' => 'cache',            // optional; default 'cache' (uses Yii::$app->cache)
                'queue' => 'queue_scheduler',  // optional; omit to run inline synchronously
            ],
            'jobs' => require __DIR__ . '/scheduler.php',
        ],
    ],
];

1. Create console/config/scheduler.php with your jobs:

<?php

use ldkafka\scheduler\ScheduledJob;

return [
    [
        'class' => \common\jobs\ExampleJob::class, // must extend ScheduledJob
        'run' => 'EVERY_MINUTE',
        'single_instance' => true,        // default true
        'max_running_time' => 300,        // seconds; 0 = unlimited
    ],
    [
        'class' => \common\jobs\NightlyJob::class,
        'run' => [
            'minutes' => 0,
            'hours' => 2,
            'wday' => '1-5',              // Mon-Fri
        ],
    ],
];

Usage ¶

• External cron mode:

php yii scheduler/run

• Daemon mode (long-running with drift correction):

php yii scheduler/daemon

Upgrade notes ¶

Upgrading from 1.0.3 or earlier ¶

• Lock format changed: Locks now store {pid, host, ts} instead of bare PID. No migration needed; old locks will expire naturally (1-hour TTL).
• Config cleanup: Remove obsolete staleLockTtl and maxJobsPerTick from your scheduler config (not implemented).
• Cron parsing improved: The day key is now normalized to mday. Update job configs using day to use mday instead for clarity.
• Log levels adjusted: Normal flow messages moved from warning→info. Review log filters if you relied on warning-level job execution logs.

Release checklist ¶

• Symbolic: EVERY_MINUTE, EVERY_HOUR, EVERY_DAY, EVERY_WEEK, EVERY_MONTH
• Cron-like array using getdate() keys: minutes, hours, mday (day of month), wday (weekday), mon, year
  • Patterns per key:
    • * - wildcard (matches any value)
    • 5 - exact match
    • */5 - step/interval (every 5th unit: 0, 5, 10...)
    • 1-5 - range (1 through 5 inclusive)
    • 10-20/2 - range with step (10, 12, 14, 16, 18, 20)
    • 1,3,5 - list (matches 1 or 3 or 5)
  • Multiple patterns can be combined with commas for OR semantics

Writing a job ¶

namespace common\jobs;

use ldkafka\scheduler\ScheduledJob;
use Yii;

class ExampleJob extends ScheduledJob
{
    public function execute($queue = null)
    {
        Yii::info('ExampleJob executed', 'scheduler');
        // do work
        return true; // success
    }
}

Notes:

• When using queue mode, jobs are pushed to the configured queue component and executed by a queue worker.
• Locks use metadata format {pid: int, host: string, ts: int} and are acquired atomically with cache->add().
• Stale lock reclamation: if the scheduler finds an existing lock with no running jobs in cache, it safely re-reads and deletes the lock before retrying (prevents race conditions).
• Stale jobs exceeding max_running_time are auto-removed from the run cache; if the queue driver supports remove(), the queued job is also removed.
• max_running_time is enforced during scheduler ticks; consider queueing long-running jobs for better concurrency.

Logging ¶

All logs use the scheduler category with production-appropriate levels:

• info: Normal operations (job selected, queued, executed, lock acquired/released)
• warning: Anomalies worth attention (stale lock removed, job exceeded max time, single-instance conflict, queue check failure)
• error: Failures requiring intervention (cache lock acquisition failed, job class not found, queue push failed, critical init errors)

Configure a log target in your console/config/main.php if needed:

'log' => [
    'targets' => [
        [
            'class' => 'yii\log\FileTarget',
            'levels' => ['error', 'warning', 'info'],
            'categories' => ['scheduler'],
            'logFile' => '@runtime/logs/scheduler.log',
            'maxFileSize' => 10240, // 10 MB
        ],
    ],
],

Monitoring Events ¶

The scheduler triggers events throughout job lifecycle for integration with monitoring systems. Attach event handlers in your scheduler configuration:

'scheduler' => [
    'class' => ldkafka\scheduler\Scheduler::class,
    'on jobBeforeRun' => function ($event) {
        // $event is SchedulerJobEvent with: job_class, job_config, start_time
        Yii::info("Starting job: {$event->job_class}", 'monitoring');
    },
    'on jobAfterRun' => function ($event) {
        // $event includes: result, start_time, end_time
        $duration = $event->end_time - $event->start_time;
        Yii::info("Job {$event->job_class} completed in {$duration}s", 'monitoring');
    },
    'on jobError' => function ($event) {
        // $event includes: error, exception, trace, error_time
        Yii::error("Job {$event->job_class} failed: {$event->error}", 'monitoring');
    },
    'on jobBlocked' => function ($event) {
        // $event->data includes: job_id, job_config, reason, running_time
        $data = $event->data;
        Yii::warning("Job {$data['job_config']['class']} blocked: {$data['reason']}", 'monitoring');
    },
    'config' => [ /* ... */ ],
    'jobs' => [ /* ... */ ],
],

Available Events ¶

• EVENT_JOB_BEFORE_RUN (jobBeforeRun): Job is about to execute
• EVENT_JOB_AFTER_RUN (jobAfterRun): Job completed successfully
• EVENT_JOB_ERROR (jobError): Job threw exception
• EVENT_JOB_BLOCKED (jobBlocked): Job prevented from running (e.g., single-instance lock)
• EVENT_JOB_TIMEOUT (jobTimeout): Reserved for future use

All events use SchedulerJobEvent class with typed properties for monitoring integration.

Cleanup and safety ¶

• All jobs are executed via a SafeJobWrapper that catches exceptions and prevents worker crashes.
• On completion (sync or async), the wrapper will call Scheduler::finalizeRuntimeJob() to remove the job entry from the persistent run cache.

Compatibility ¶

• Requires PHP >= 8.0, Yii2 ~2.0.14
• Optional pcntl for graceful signal handling (SIGINT/SIGTERM). On platforms without pcntl, the daemon stops when too many ticks are missed (configurable).

License ¶

BSD-3-Clause

Yii2 Google Gemini Component (v2.0.0) ¶

1. What’s New in 2.0.0
2. Feature Summary
3. Requirements
4. Installation
5. Quick Start
6. Usage Examples
7. Caching Modes Deep Dive
8. Console Commands
9. Configuration Options
10. Supported Models (Snapshot)
11. Canonical Response Format
12. Helper Methods
13. Cache Modes (Summary)
14. Error Handling Pattern
15. Advanced Usage
16. Testing
17. Troubleshooting
18. Production Notes
19. Links
20. License
21. Support / Contributing

Native, strongly-typed Yii2 component for the Google Gemini REST API. No external SDKs – only yii\\httpclient. Provides generation (text & multimodal), streaming, embeddings, Files API, token counting, and flexible caching strategies.

What’s New in 2.0.0 ¶

• Rebuilt on pure REST calls (no Gemini SDK)
• Added multimodal inline data handling
• Added SSE streaming helper
• Full embeddings single + batch support
• Files API wiring (simplified upload flow)
• Model discovery (list + get)
• Uniform response shape & error handling
• Client & server caching patterns
• Strict typing, final class, consistent helper methods

Feature Summary ¶

Requirements ¶

• PHP >= 8.0
• Yii2 >= 2.0.40
• yiisoft/yii2-httpclient

Installation ¶

composer require ldkafka/yii2-google-gemini

Quick Start ¶

Basic Configuration ¶

'components' => [
    'gemini' => [
        'class' => 'ldkafka\gemini\Gemini',
        'apiKey' => 'YOUR_GEMINI_API_KEY',
        'generationConfig' => [
            'temperature' => 0.7,
            'topP' => 0.95,
            'maxOutputTokens' => 2048,
        ],
    ],
],

Simple Text Generation ¶

$gemini = Yii::$app->gemini;
$resp = $gemini->generateContent('gemini-2.5-flash', 'Explain quantum computing');

if ($resp['ok']) {
    echo $gemini->extractText($resp['data']);
}

Usage Examples ¶

1. Basic Text Generation ¶

$resp = $gemini->generateContent('gemini-2.5-flash', 'What is PHP?');

if ($resp['ok']) {
    $text = $gemini->extractText($resp['data']);
    $usage = $gemini->getUsageMetadata($resp['data']);
    echo "Response: $text\n";
    echo "Tokens used: {$usage['totalTokenCount']}\n";
}

2. Streaming Responses ¶

$gemini->streamGenerateContent('gemini-2.5-flash', 'Write a short story', function($chunk) {
    if ($text = $chunk['candidates'][0]['content']['parts'][0]['text'] ?? null) {
        echo $text;
        flush();
    }
});

3. Multimodal (Text + Image) ¶

$content = [[
    'parts' => [
        ['text' => 'What is in this image?'],
        ['inline_data' => [
            'mime_type' => 'image/jpeg',
            'data' => base64_encode(file_get_contents('/path/to/image.jpg'))
        ]]
    ],
    'role' => 'user'
]];

$resp = $gemini->generateContent('gemini-2.5-flash', $content);

4. Client-side Conversation Caching ¶

$gemini->cacheType = 'client';
$gemini->cacheTtl = 3600;

// First message
$resp = $gemini->chat('gemini-2.5-flash', 'My name is Alice', 'user123');

// Follow-up (remembers context)
$resp = $gemini->chat('gemini-2.5-flash', 'What is my name?', 'user123');
// Response: "Your name is Alice."

5. Server-side Context Caching (Advanced) ¶

$gemini->cacheType = 'server';

// Create cache with system instruction (requires 32k+ tokens)
$cacheName = $gemini->createServerCache(
    'gemini-2.5-flash',
    'assistant-id',
    'You are a helpful travel assistant. [... long system instruction ...]',
    3600
);

// Use cached context
$resp = $gemini->chatServer('gemini-2.5-flash', 'Best beaches in Sydney?', 'assistant-id');

6. System Instructions ¶

$gemini->systemInstruction = [
    'parts' => [['text' => 'You are a helpful coding assistant who explains concepts simply.']]
];

$resp = $gemini->generateContent('gemini-2.5-flash', 'Explain recursion');

7. File Uploads ¶

// Upload a large video file
$resp = $gemini->uploadFile('/path/to/video.mp4', 'My Video', 'video/mp4');
$fileUri = $resp['data']['file']['uri'];

// Use in generation
$content = [[
    'parts' => [
        ['text' => 'Summarize this video'],
        ['file_data' => [
            'file_uri' => $fileUri,
            'mime_type' => 'video/mp4'
        ]]
    ]
]];
$resp = $gemini->generateContent('gemini-2.5-flash', $content);

// List uploaded files
$files = $gemini->listFiles();

// Delete file
$gemini->deleteFile('files/abc123');

8. Embeddings ¶

// Single embedding
$resp = $gemini->embedContent(
    'text-embedding-004',
    'Hello world',
    'RETRIEVAL_QUERY'
);
$embedding = $resp['data']['embedding']['values'];

// Batch embeddings
$requests = [
    [
        'content' => ['parts' => [['text' => 'Document 1']]],
        'taskType' => 'RETRIEVAL_DOCUMENT'
    ],
    [
        'content' => ['parts' => [['text' => 'Document 2']]],
        'taskType' => 'RETRIEVAL_DOCUMENT'
    ],
];
$resp = $gemini->batchEmbedContents('text-embedding-004', $requests);

9. Token Counting ¶

$tokens = $gemini->countTokens('gemini-2.5-flash', 'Your prompt text here');
echo "This prompt will use approximately $tokens tokens\n";

10. Model Discovery ¶

// List all available models
$models = $gemini->listModels();
foreach ($models['data']['models'] as $model) {
    echo "{$model['name']}: {$model['displayName']}\n";
}

// Get specific model details
$model = $gemini->getModel('gemini-2.5-flash');
echo "Context window: {$model['data']['inputTokenLimit']} tokens\n";

Caching Modes Deep Dive ¶

Server cache creation requires a very large system instruction document. Use countTokens() before attempting createServerCache().

Console Commands ¶

Example test commands in console/controllers/TestController.php:

# Stateless generation
php yii test/gemini-none "What is the capital of France?"

# Client-side caching (conversation)
php yii test/gemini-client

# Server-side caching
php yii test/gemini-server "Tell me about Sydney beaches"

# Clear cache
php yii test/gemini-client test-chat 1

Configuration Options ¶

Component Properties ¶

Generation Config Options ¶

'generationConfig' => [
    'temperature' => 0.7,          // 0.0-2.0, creativity level
    'topP' => 0.95,                // 0.0-1.0, nucleus sampling
    'topK' => 40,                  // Token selection limit
    'maxOutputTokens' => 2048,     // Max response length
    'stopSequences' => ['END'],    // Stop generation triggers
    'candidateCount' => 1,         // Number of responses
]

Supported Models (Snapshot) ¶

See Gemini Models Documentation for full list.

Canonical Response Format ¶

All methods return:

[
    'ok' => true|false,      // Success status
    'status' => 200,         // HTTP status code
    'data' => [...],         // Response data
    'error' => null|string   // Error message if failed
]

Helper Methods ¶

// Extract text from response
$text = $gemini->extractText($resp['data']);

// Get finish reason ('STOP', 'MAX_TOKENS', 'SAFETY', etc.)
$reason = $gemini->getFinishReason($resp['data']);

// Get usage metadata
$usage = $gemini->getUsageMetadata($resp['data']);
// ['promptTokenCount' => 10, 'candidatesTokenCount' => 50, 'totalTokenCount' => 60]

Helper Methods ¶

$text   = $gemini->extractText($resp['data']);
$reason = $gemini->getFinishReason($resp['data']);
$usage  = $gemini->getUsageMetadata($resp['data']);

Cache Modes (Summary) ¶

None (Stateless) ¶

$gemini->cacheType = 'none';
$resp = $gemini->generateContent('gemini-2.5-flash', 'Hello');
// Each request is independent

Client (Local Conversation History) ¶

$gemini->cacheType = 'client';
$resp = $gemini->chat('gemini-2.5-flash', 'My name is Bob', 'user123');
$resp = $gemini->chat('gemini-2.5-flash', 'What is my name?', 'user123');
// Conversation stored in Yii cache component

Server (Gemini Context Caching) ¶

$gemini->cacheType = 'server';
$cacheName = $gemini->createServerCache(
    'gemini-2.5-flash',
    'id',
    '[Large system instruction 32k+ tokens]',
    3600
);
$resp = $gemini->chatServer('gemini-2.5-flash', 'Question', 'id');
// System instruction cached on Google's servers

Note: Server caching requires minimum 32,000 tokens in cached content.

Error Handling Pattern ¶

$resp = $gemini->generateContent('gemini-2.5-flash', 'Hello');

if (!$resp['ok']) {
    Yii::error("Gemini API error: {$resp['error']} (HTTP {$resp['status']})");
    
    // Common error codes:
    // 400 - Bad request (invalid parameters)
    // 401 - Invalid API key
    // 429 - Rate limit exceeded
    // 500 - Server error
}

Advanced Usage ¶

Custom HTTP Configuration ¶

'gemini' => [
    'class' => 'ldkafka\gemini\Gemini',
    'apiKey' => 'YOUR_KEY',
    'httpConfig' => [
        'timeout' => 60,
        'transport' => 'yii\httpclient\CurlTransport',
    ],
],

Multimodal with Multiple Images ¶

$content = [[
    'parts' => [
        ['text' => 'Compare these images'],
        ['inline_data' => ['mime_type' => 'image/jpeg', 'data' => base64_encode($image1)]],
        ['inline_data' => ['mime_type' => 'image/jpeg', 'data' => base64_encode($image2)]],
    ]
]];

Custom Safety Settings ¶

$gemini->safetySettings = [
    ['category' => 'HARM_CATEGORY_HARASSMENT', 'threshold' => 'BLOCK_MEDIUM_AND_ABOVE'],
    ['category' => 'HARM_CATEGORY_HATE_SPEECH', 'threshold' => 'BLOCK_ONLY_HIGH'],
];

Safety Settings Explained ¶

safetySettings lets you tell Gemini which kinds of harmful content to filter and at what strictness. The value is an array of objects with a category and a threshold.

• Common categories: HARM_CATEGORY_HARASSMENT, HARM_CATEGORY_HATE_SPEECH, HARM_CATEGORY_SEXUALLY_EXPLICIT, HARM_CATEGORY_DANGEROUS_CONTENT, HARM_CATEGORY_VIOLENCE.
• Typical thresholds (in order of strictness): BLOCK_NONE, BLOCK_LOW_AND_ABOVE, BLOCK_MEDIUM_AND_ABOVE, BLOCK_ONLY_HIGH.

Example JSON payload as sent to the API:

[
    { "category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_MEDIUM_AND_ABOVE" },
    { "category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_ONLY_HIGH" }
]

Notes:

• If safetySettings is empty, no custom filters are applied (provider defaults may still apply).
• You can mix categories with different thresholds.
• Overly strict settings can block benign answers; adjust to your domain’s tolerance.

Testing ¶

The package includes comprehensive test actions:

1. actionGeminiNone - Test stateless generation
2. actionGeminiClient - Test client-side conversation caching
3. actionGeminiServer - Test server-side context caching

Troubleshooting ¶

"API key not configured" ¶

Ensure your API key is set in the component configuration or params.

"Failed to create server cache" ¶

Server caching requires:

• Minimum 32,000 tokens in the cached content
• Supported model (gemini-2.5-flash, gemini-2.5-pro)
• System instruction or large document

Use client-side caching for shorter conversations.

Streaming not working ¶

Ensure your HTTP client supports Server-Sent Events (SSE). The default Yii2 HTTP client may need custom transport configuration.

Production Notes ¶

• Implement backoff + retry for 429 & transient 5xx responses.
• Prune client cache histories when token counts get large (outside of scope for this base component).
• For server caching: build and store a domain knowledge base (e.g., large markdown/text corpus) and verify token count with countTokens().
• Log latency and token usage: Yii::info([...], 'gemini') for observability.

Links ¶

• Gemini API Documentation
• Get API Key
• API Reference
• Model Pricing

License ¶

BSD-3-Clause (matches class header).

Support / Contributing ¶

Open issues or PRs at: https://github.com/ldkafka/yii2-google-gemini

When reporting an issue, include:

1. PHP / Yii versions
2. Failing method and sample call
3. Full response array (mask secrets)
4. Expected vs actual behavior

Enjoy building with Gemini! Suggestions & improvements welcome.

Searchable & Dependent Dropdown Widget for Yii2 ¶

1. Features
2. Installation
3. Usage
4. Styling Features
5. Configuration Options
6. Recent Changes (v1.0.1)
7. License

A reusable Yii2 widget that provides a searchable dropdown list with support for dependent (cascading) dropdowns.
It is designed to work seamlessly within the wbraganca/yii2-dynamicform widget and has no dependency on any specific CSS framework like Bootstrap.

Note: This package uses the rft\searchabledepdrop\widgets namespace. Make sure to update your imports if you're upgrading from an older version.

Features ¶

• Searchable dropdown list.
• Support for dependent dropdowns (e.g., State -> City).
• Multiple selection support - Allow users to select multiple values.
• Works with wbraganca/yii2-dynamicform for creating dynamic forms.
• Framework-independent styling with modern, responsive design.
• Custom styling for multiple selection with removable tags.
• Compatible with PHP 5.6+ and modern Yii2 projects.

Installation ¶

Via Composer (Recommended) ¶

The preferred way to install this extension is through Composer.

composer require rft/yii2-searchable-depdrop

Yii2 will automatically load the widget via Composer’s autoloader.

Manual Installation (Alternative) ¶

If you don't want to use Composer, you can still install it manually:

1. Download the source files from the src/ directory
2. Place them in your project's widget directory (e.g., common/widgets/searchable_dep_drop/)
3. Ensure the namespace in the widget files matches the new location if you change it
4. Include the CSS and JS assets from the src/assets/ directory

Usage ¶

1. Controller Action for Dependent Data ¶

For dependent dropdowns, you need a controller action that returns data in JSON format.
The widget expects the parent value as a POST parameter (the name of the parameter is derived from the parent field's name).

The action should return a JSON object with an output key, which is an array of objects, each having an id and text property.

Example Controller Action:

public function actionListCities()
{
    \Yii::\$app->response->format = \yii\web\Response::FORMAT_JSON;
    $out = ['output' => [], 'selected' => ''];

    if (Yii::\$app->request->post('state')) {
        $state = Yii::\$app->request->post('state');
        if ($state) {
            $cities = AddressCity::find()
                ->where(['state' => $state])
                ->orderBy('name')
                ->all();

            $output = [];
            foreach ($cities as $city) {
                $output[] = ['id' => $city->id, 'text' => $city->name];
            }
            $out['output'] = $output;
        }
    }

    return $out;
}

2. View File Setup ¶

In your view file, you can use the widget like any other Yii2 input widget.

A. Standalone Searchable Dropdown

use rft\searchabledepdrop\widgets\SearchableDepDrop;

echo $form->field($model, 'state')->widget(SearchableDepDrop::class, [
    'data' => [
        'California' => 'California',
        'Texas' => 'Texas',
        // ... other states
    ],
    'placeholder' => 'Select a state...',
]);

B. Multiple Selection Dropdown

use rft\searchabledepdrop\widgets\SearchableDepDrop;

echo $form->field($model, 'tags')->widget(SearchableDepDrop::class, [
    'data' => [
        '1' => 'PHP',
        '2' => 'JavaScript',
        '3' => 'Python',
        '4' => 'Java',
        '5' => 'C#',
        // ... other options
    ],
    'allowMultiple' => true,
    'placeholder' => 'Select multiple technologies...',
]);

C. Dependent Dropdown

Example for a State → City dropdown setup:

use rft\searchabledepdrop\widgets\SearchableDepDrop;
use yii\helpers\ArrayHelper;
use yii\helpers\Url;
use common\models\AddressCity;

// State Dropdown (Parent)
echo $form->field($model, 'state')->widget(SearchableDepDrop::class, [
    'data' => ArrayHelper::map(
        AddressCity::find()->select('state')->distinct()->orderBy('state')->all(),
        'state',
        'state'
    ),
    'options' => [
        'id' => 'address-state',
    ],
    'placeholder' => 'Select a state...',
]);

// City Dropdown (Child)
echo $form->field($model, 'city_id')->widget(SearchableDepDrop::class, [
    'options' => [
        'id' => 'address-city',
    ],
    'placeholder' => 'Select City/Municipality',
    'pluginOptions' => [
        'depends' => ['address-state'],
        'url' => Url::to(['/site/list-cities']),
    ],
])->label('City/Municipality');

Styling Features ¶

The widget comes with built-in CSS that provides:

• Modern Design: Clean, professional appearance with subtle shadows and borders
• Responsive Layout: Adapts to different screen sizes and container widths
• Multiple Selection Tags: Selected items appear as removable tags with:
  • Black background with white text
  • Rounded corners (12px border-radius)
  • Remove button (×) with hover effects
  • Text truncation for long items
• Search Interface: Dedicated search input with clear visual separation
• Dropdown Styling:
  • Smooth hover effects
  • Scrollable list (max-height: 200px)
  • Active item highlighting
  • No results message styling
• Framework Independence: No dependency on Bootstrap or other CSS frameworks

Custom Styling ¶

You can override the default styles by targeting the CSS classes:

/* Main container */
.sdd-container {
  /* Your custom styles */
}

/* Display area */
.sdd-display {
  border: 2px solid #your-color;
  border-radius: 6px;
}

/* Selected items in multiple selection */
.sdd-selected-item {
  background-color: #your-color;
  border-radius: 8px;
}

.sdd-selected-item-container {
  max-width: 100px; /* Adjust tag width */
}

.sdd-item-text {
  font-size: 12px; /* Adjust text size */
}

.sdd-remove-btn {
  color: #your-remove-color;
}

/* Dropdown */
.sdd-dropdown {
  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
  border-radius: 4px;
}

/* Search input */
.sdd-search {
  padding: 10px 12px;
  font-size: 14px;
}

/* List items */
.sdd-list li {
  padding: 10px 15px;
}

.sdd-list li:hover {
  background-color: #your-hover-color;
}

Available CSS Classes ¶

Configuration Options ¶

The widget supports several configuration options:

3. Dynamic Form Integration ¶

The widget works seamlessly with wbraganca/yii2-dynamicform. Here's how to implement dependent dropdowns in dynamic forms:

Essential Widget Usage:

use rft\searchabledepdrop\widgets\SearchableDepDrop;

// State dropdown (parent)
echo $form->field($addresses[$i], "[{$i}]state")->widget(SearchableDepDrop::classname(), [
    'data' => ArrayHelper::map(
        AddressCity::find()->select('state')->distinct()->orderBy('state')->all(),
        'state', 'state'
    ),
    'placeholder' => 'Select State...',
    'options' => ['class' => 'form-control state-dropdown'],
]);

// City dropdown (child - depends on state)
echo $form->field($addresses[$i], "[{$i}]city_id")->widget(SearchableDepDrop::classname(), [
    'data' => [],
    'placeholder' => 'Select City...',
    'options' => ['class' => 'form-control city-dropdown'],
    'pluginOptions' => [
        'depends' => ['.state-dropdown'],
        'paramNames' => ['state'],
        'url' => Url::to(['/site/cities']),
    ]
]);

Required JavaScript for Dynamic Forms:

function initSearchableDepDrop(context) {
  $(context)
    .find(".sdd-container")
    .each(function () {
      var $container = $(this);
      if ($container.data("searchableDepDrop")) return;

      var optionsJson = $container.data("sdd-options");
      if (optionsJson) {
        var options = typeof optionsJson === "string" ? JSON.parse(optionsJson) : optionsJson;
        $container.searchableDepDrop(options);
      }
    });
}

// Initialize widgets on new form rows
$(".dynamicform_wrapper").on("afterInsert", function (e, item) {
  initSearchableDepDrop(item);
});

// Initialize existing widgets
initSearchableDepDrop(document.body);

Note: Replace .dynamicform_wrapper with your actual widgetContainer class from DynamicFormWidget::begin().

Multiple Selection Example ¶

To enable multiple selection in any dropdown, simply set allowMultiple => true:

// Multiple selection for skills/tags
echo $form->field($model, 'skills')->widget(SearchableDepDrop::classname(), [
    'data' => [
        '1' => 'PHP',
        '2' => 'JavaScript',
        '3' => 'Python',
        '4' => 'Java',
        '5' => 'C#',
        '6' => 'Ruby',
        '7' => 'Go',
        '8' => 'Swift',
    ],
    'allowMultiple' => true,
    'placeholder' => 'Select your skills...',
    'options' => ['class' => 'form-control skills-dropdown'],
]);

// Multiple selection for categories in dynamic form
echo $form->field($contact, "[{$i}]categories")->widget(SearchableDepDrop::classname(), [
    'data' => [
        '1' => 'Business',
        '2' => 'Personal',
        '3' => 'Emergency',
        '4' => 'Family',
        '5' => 'Friend',
    ],
    'allowMultiple' => true,
    'placeholder' => 'Select contact categories...',
    'options' => ['class' => 'form-control categories-dropdown'],
]);

Important Notes:

• For multiple selection, your model attribute should be an array or JSON field
• The widget automatically handles the serialization of multiple values
• Selected items appear as removable tags in the display area
• The paramNames option is crucial for dependent dropdowns to work properly

Recent Changes (v1.0.1) ¶

Fixed Issues ¶

• Fixed PSR-4 Autoloading: Reorganized file structure to match namespace requirements
  • Moved SearchableDepDrop.php to src/widgets/SearchableDepDrop.php
  • Moved SearchableDepDropAsset.php to src/widgets/SearchableDepDropAsset.php
  • Updated asset sourcePath to use vendor directory path
  • This resolves the "Class not found" error after composer install

Enhanced Features ¶

• Improved CSS Styling: Enhanced dropdown list items with text wrapping and visual separation
• Better Documentation: Added comprehensive styling documentation and usage examples
• Multiple Selection Support: Full support for selecting multiple values with removable tags

Package Structure ¶

src/
├── widgets/
│   ├── SearchableDepDrop.php
│   └── SearchableDepDropAsset.php
└── assets/
    ├── css/
    │   └── searchable-dep-drop.css
    └── js/
        └── searchable-dep-drop.js

Migration Guide ¶

If you're upgrading from a previous version:

1. Update your composer package: composer update rft/yii2-searchable-depdrop
2. The namespace remains the same: use rft\searchabledepdrop\widgets\SearchableDepDrop;
3. No code changes required in your existing implementations

License ¶

This project is licensed under the MIT License.

Yii2 WEB Extension

1. Installation
2. Components

A package of helper classes for working with web components in Yii2.

Installation ¶

Run

php composer.phar require mspirkov/yii2-web

or add

"mspirkov/yii2-web": "^0.1"

to the require section of your composer.json file.

Components ¶

• Request
• CookieManager

Request ¶

A wrapper for \yii\web\Request for easier handling of GET and POST parameters.

It contains the following methods:

• getGetInt - gets the value of a GET parameter by its name and tries to convert it to an integer.
• getGetFloat - gets the value of the GET parameter by its name and tries to convert it to a floating-point number.
• getGetBool - gets the value of the GET parameter by its name and tries to convert it to a boolean.
• getGetString - gets the value of the GET parameter by its name and tries to convert it to a string.
• getGetArray - gets the value of the GET parameter by its name and tries to convert it to an array.
• getPostInt - gets the value of a POST parameter by its name and tries to convert it to an integer.
• getPostFloat - gets the value of the POST parameter by its name and tries to convert it to a floating-point number.
• getPostBool - gets the value of the POST parameter by its name and tries to convert it to a boolean.
• getPostString - gets the value of the POST parameter by its name and tries to convert it to a string.
• getPostArray - gets the value of the POST parameter by its name and checks that the value is an array.

Configuration ¶

First, you need to replace the request component in the configuration:

<?php

use MSpirkov\Yii2\Web\Request;

return [
    ...
    'components' => [
        'request' => [
            'class' => Request::class,
            ...
        ],
        ...
    ],
];

IDE Autocomplete (Optional) ¶

You also need to specify this class in __autocomplete.php so that the IDE knows which class to use:

<?php

use yii\BaseYii;
use yii\web\Application;
use MSpirkov\Yii2\Web\Request;

class Yii extends BaseYii
{
    /** @var __Application */
    public static $app;
}

/**
 * @property-read Request $request
 */
class __Application extends Application {}

Basic Controller (Optional) ¶

I also recommend that you create your own basic controller and specify Request there:

use MSpirkov\Yii2\Web\Request;

/**
 * @property Request $request
 */
class Controller extends \yii\web\Controller
{
    public function init(): void
    {
        parent::init();

        $this->request = Instance::ensure($this->request, Request::class);
    }
}

Usage example: ¶

class ProductController extends Controller
{
    public function __construct(
        string $id,
        Module $module,
        private readonly ProductService $service,
        array $config = [],
    ) {
        parent::__construct($id, $module, $config);
    }

    public function actionDelete(): array
    {
        $this->response->format = Response::FORMAT_JSON;

        return $this->service->delete($this->request->getPostInt('id'));
    }
}

CookieManager ¶

A utility class for managing cookies.

This class encapsulates the logic for adding, removing, checking existence, and retrieving cookies, using the \yii\web\Request and \yii\web\Response objects. It simplifies working with cookies by abstracting implementation details and providing more convenient methods.

It contains the following methods:

• has - checks if a cookie with the specified name exists.
• get - returns the cookie with the specified name.
• add - adds a cookie to the response.
• remove - removes a cookie.
• removeAll - removes all cookies.

Usage example: ¶

class CookieManager extends \MSpirkov\Yii2\Web\CookieManager
{
    public function __construct()
    {
        parent::__construct(
            Instance::ensure('request', Request::class),
            Instance::ensure('response', Response::class),
        );
    }
}

class ExampleService
{
    public function __construct(
        private readonly CookieManager $cookieManager,
    ) {}

    public function addCookie(): void
    {
        $this->cookieManager->add([
            'name' => 'someCookieName',
            'value' => 'someCookieValue',
        ]);
    }
}

Yii2 DB Extension

1. Installation
2. Components

A package of helper classes for working with databases in Yii2.

Installation ¶

Run

php composer.phar require mspirkov/yii2-db

or add

"mspirkov/yii2-db": "^0.2"

to the require section of your composer.json file.

Components ¶

• AbstractRepository
• DateTimeBehavior
• TransactionManager

AbstractRepository ¶

An abstract class for creating repositories that interact with ActiveRecord models. Contains the most commonly used methods: findOne, findAll, save and others. It also has several additional methods: findOneWith, findAllWith.

This way, you can separate the logic of executing queries from the ActiveRecord models themselves. This will make your ActiveRecord models thinner and simpler. It will also make testing easier, as you can mock the methods for working with the database.

Usage example: ¶

/**
 * @extends AbstractRepository<Customer>
 */
class CustomerRepository extends AbstractRepository
{
    public function __construct()
    {
        parent::__construct(Customer::class);
    }
}

class CustomerService
{
    public function __construct(
        private readonly CustomerRepository $customerRepository,
    ) {}

    public function getCustomer(int $id): ?Customer
    {
        return $this->customerRepository->findOne($id);
    }
}

DateTimeBehavior ¶

Behavior for ActiveRecord models that automatically fills the specified attributes with the current date and time.

By default, this behavior uses the current date, time, and time zone. If necessary, you can specify your own attributes and time zone.

Usage example: ¶

/**
 * @property int $id
 * @property string $content
 * @property string $created_at
 * @property string|null $updated_at
 */
class Message extends ActiveRecord
{
    public static function tableName(): string
    {
        return '{{messages}}';
    }

    public function behaviors(): array
    {
        return [
            DateTimeBehavior::class,
        ];
    }
}

TransactionManager ¶

A utility class for managing database transactions with a consistent and safe approach.

This class simplifies the process of wrapping database operations within transactions, ensuring that changes are either fully committed or completely rolled back in case of errors.

It provides two main methods:

• safeWrap - executes a callable within a transaction, safely handling exceptions and logging them.
• wrap - executes a callable within a transaction.

Usage example: ¶

class TransactionManager extends \MSpirkov\Yii2\Db\TransactionManager
{
    public function __construct()
    {
        parent::__construct(Yii::$app->db);
    }
}

class ProductService
{
    public function __construct(
        private readonly TransactionManager $transactionManager,
        private readonly ProductFilesystem $productFilesystem,
        private readonly ProductRepository $productRepository,
    ) {}

    /**
     * @return array{success: bool, message?: string}
     */
    public function deleteProduct(int $id): array
    {
        $product = $this->productRepository->findOne($id);

        // There's some logic here. For example, checking for the existence of a product.

        $transactionResult = $this->transactionManager->safeWrap(function () use ($product) {
            $this->productRepository->delete($product);
            $this->productFilesystem->delete($product->preview_filename);

            return [
                'success' => true,
            ];
        });

        if ($transactionResult === false) {
            return [
                'success' => false,
                'message' => 'Something went wrong',
            ];
        }

        return $transactionResult;
    }
}

(draft - all will be retested later)

Intro ¶

1. PSR Standards by Framework Interoperability Group
2. Dependency injection + container
3. invoke()
4. Hash annotations for class attributes
5. Running the demo application
6. Adding DB into your project
7. Enabling MariaDB (MySQL) and migrations
8. Creating a migration
9. Running the migrations
10. Reading data from DB
11. Seeding the database
12. Using Repository and the Model class
13. API login + access token
14. JS client - Installable Vuejs3 PWA

In Yii3 it is not as easy to start as it was with Yii2. You have to install and configure basic things on your own. Yii3 uses the modern approach based on independent packages and dependency injection, but it makes it harder for newcomers. I am here to show all how I did it.

All the code is available in my new GitHub repository. I will be using it as a boiler-plate for my future projects so it should be always up-to-date and working.

Instead of installing local WAMP- or XAMPP-server I will be using Docker. Do not forget about a modern IDE like PhpStorm, which comes bundled with all you will ever need.

PSR Standards by Framework Interoperability Group ¶

First of all, learn what PHP Standards Recommendations by Framework Interoperability Group (FIG) are. It will help you understand why so many "weird" PSR imports are in the Yii3 code. In short: These interfaces help authors of different frameworks to write compatible classes so they can be reused in any other framework following these principles.

Dependency injection + container ¶

Check this YouTube video for explanation

invoke() ¶

The __invoke() public method is called when you call the instance as a method. (Therefore the constructor was already executed)

$obj = new MyObj(); // Now the __construct() is executed.
$obj(); // Now the __invoke() is executed (The instance is needed!)

I never used it, but prepared a following example that shows when invoking can be applied:

class MyUpper
{
    public function __invoke($a) { return $this->go($a); }
    public function go($a) { return strtoupper($a); }
}
$instance = new MyUpper();
$array = ['a', 'B', 1, '1'];

// __invoke is used:
var_dump($instance($array[0])); 
var_dump(array_map($instance, $array));

// These do the same without invoking:
var_dump(array_map('strtoupper', $array));
var_dump(array_map([$instance, 'go'], $array));
var_dump(array_map(function($a) use ($instance) { return $instance->go($a); }, ['a','B',1,'1']));

Hash annotations for class attributes ¶

PHP 8 introduces annotations like this (not only for class attributes):

• #[Column(type: 'primary')]
• #[Column(type: 'string(255)', nullable: true)]
• #[Entity(repository: UserRepository::class)]
• #[ManyToMany(target: Role::class, through: UserRole::class)]

They should replace the original DocBlock annotatinos and provide more new functionalities.

Learn what they mean and how they are used by Yii3. To me this is a brand new topic as well.

Yii3 - How to start ¶

Yii3 offers more basic applications: Web, Console, API. I will be using the API application:

• https://github.com/yiisoft/app-api
• Other apps are linked on the page

Clone it like this:

• git clone https://github.com/yiisoft/app-api.git yii3api

.. and follow the docker instructions in the documentation.

If you don't have Docker, I recommend installing the latest version of Docker Desktop:

• https://docs.docker.com/get-started/introduction/get-docker-desktop/

Running the demo application ¶

You may be surprised that docker-compose.yml is missing in the root. Instead the "make up" and "make down" commands are prepared. If you run both basic commands as mentioned in the documentation:

• make composer update
• make up

... then the web will be available on URL

• http://localhost:80
• If run via browser, XML is returned
• If run via Postman or Ajax, JSON is returned

If you want to modify the data that was returned by the endpoint, just open the action-class src/Api/IndexAction.php and add one more element to the returned array.

You may be missing 'docker compose stop' or 'make stop', because 'make down' removes your containers and drops your DB. In that case you can add it to the Makefile in the root (see below). If you then type 'make help' you will see the new command.

ifeq ($(PRIMARY_GOAL),stop)
stop: ## Stop the dev environment
	$(DOCKER_COMPOSE_DEV) stop
endif

Adding DB into your project ¶

Your project now does not contain any DB. Let's add MariaDB and Adminer (DB browser) into file docker/dev/compose.yml:

In my case the resulting file looks like this:

services:
  app:
    container_name: yii3api_php
    build:
      dockerfile: docker/Dockerfile
      context: ..
      target: dev
      args:
        USER_ID: ${UID}
        GROUP_ID: ${GID}
    env_file:
      - path: ./dev/.env
      - path: ./dev/override.env
        required: false
    restart: unless-stopped
    depends_on:
      - db
    ports:
      - "${DEV_PORT:-80}:80"
    volumes:
      - ../:/app
      - ../runtime:/app/runtime
      - caddy_data:/data
      - caddy_config:/config
    tty: true
  db:
    image: mariadb:12.0.2-noble
    container_name: yii3api_db
    environment:
      MARIADB_ROOT_PASSWORD: root
      MARIADB_DATABASE: db
      MARIADB_USER: db
      MARIADB_PASSWORD: db
  adminer:
    image: adminer:latest
    container_name: yii3api_adminer
    environment:
      ADMINER_DEFAULT_SERVER: db
    ports:
      - ${DEV_ADMINER_PORT}:8080
    depends_on:
      - db
volumes:
  mariadb_data:

Plus add/modify these variables in file docker/.env

• DEV_PORT=9080
• DEV_ADMINER_PORT=9081

Then run following commands:

• make down
• make build
• make up

Now you should see a DB browser on URL http://localhost:9081/?server=db&username=db&db=db

Login, server and pwd is defined in the snippet above.

If you type "docker ps" into your host console, you should see 3 running containers: yii3api_php, yii3api_adminer, yii3api_db.

The web will be, from now on, available on URL http://localhost:9080 which is more handy than just ":80" I think. (Later you may run 4 different projects at the same time and all cannot run on port 80)

Enabling MariaDB (MySQL) and migrations ¶

Now when your project contains MariaDB, you may wanna use it in the code ...

Installing composer packages ¶

After some time of searching you will discover you need to install these composer packages:

• https://github.com/yiisoft/db-mysql
• https://github.com/yiisoft/cache
• https://github.com/yiisoft/db-migration

So you need to run following commands:

composer require yiisoft/db-mysql
composer require yiisoft/cache
composer require yiisoft/db-migration

To run composer (or any other command inside your dockerized yii3 application) you have 4 options:

• Make: The best solution is to prepend the composer commands with "make".

Other solutions:

• If you have Composer running locally, you can call these commands directly on your computer. (I do not recommend)

• You can SSH into your docker container and call it there as Composer is installed inside. In that case:

  • Find the name of the PHP container by typing "docker ps"
  • Call "docker exec -it {containerName} /bin/bash"
  • Now you are in the console of your php server and you can run composer.

• If you are using PhpStorm, find the small icon "Services" in the left lower corner (looks ca like a cog wheel), find item "Docker-compose: app-api", inside click the "app" service, then "yii3api_php" container and then hit the button "terminal" on the righthand side.

Setting up composer packages ¶

Follow their documentations. Quick links:

• https://github.com/yiisoft/db/blob/master/docs/guide/en/connection/mysql.md (I did not need the snippet with "new DsnSocket()")
• https://github.com/yiisoft/db-migration/blob/master/docs/guide/en/README.md (I recommend "Yii Console" installation)

The documentations want you to create 2 files:

• config/common/di/db-mysql.php
• config/common/db.php
• But you actually need only one. I recommend db-mysql.php

Note: If you want to create a file using commandline, you can use command "touch". For example "touch config/common/di/db-mysql.php"

Note: In the documentation the PHP snippets do not contain tag and declaration. Prepend it:

<?php
declare(strict_types=1);

Create folder for migrations ¶

• src/Migration

When this is done, call "composer du" or "make composer du" and then try "make yii list". You should see the migration commands.

Creating a migration ¶

Run the command to create a migration:

• make yii migrate:create user

Open the file and paste following content to the up() method:

$b->createTable('user', [
'id' => $b->primaryKey(),
'name' => $b->string()->notNull(),
'surname' => $b->string()->notNull(),
'username' => $b->string(),
'email' => $b->string()->notNull()->unique(),
'phone' => $b->string(),
'admin_enabled' => $b->boolean()->notNull()->defaultValue(false)->comment('Can user access the administration?'),
'vuejs_enabled' => $b->boolean()->notNull()->defaultValue(false)->comment('Can user access the mobile application?'),
'auth_key' => $b->string(32)->notNull()->unique(),
'access_token' => $b->string(32)->unique()->comment('For API purposes'),
'password_hash' => $b->string(),
'password_default' => $b->string(),
'password_vuejs_default' => $b->string(),
'password_vuejs_hash' => $b->string(),
'password_reset_token' => $b->string()->unique(),
'verification_token' => $b->string()->unique(),
'verified_at' => $b->dateTime(),
'status' => $b->smallInteger()->notNull()->defaultValue(100),
'created_by' => $b->integer(),
'updated_by' => $b->integer(),
'deleted_by' => $b->integer(),
'created_at' => $b->dateTime()->notNull()->defaultExpression('CURRENT_TIMESTAMP'),
'updated_at' => $b->dateTime(),
'deleted_at' => $b->dateTime(),
]);

The down() method should contain this:

$b->dropTable('user');

Running the migrations ¶

Try to run "make yii migrate:up" and you will see error "could not find driver", because file "docker/Dockerfile" does not install the "pdo_mysql" extention. Add it to the place where "install-php-extensions" is called.

Then call:

• make down
• make build
• make up

Now you will see error "Connection refused" It means you have to update dns, user and password in file "config/common/params.php" based on what is written in "docker/dev/compose.yml".

If you run "make yii migrate:up" it should work now and your DB should contain the first table. Check it via adminer: http://localhost:9081/?server=db&username=db&db=db

Reading data from DB ¶

In Yii we were always using ActiveRecord and its models, but in Yii3 the package is not ready yet. The solution is to use existing class Yiisoft\Db\Query\Query.

Open class src/Api/IndexAction.php and modify it a little to return all users via your REST API. You have more options:

You can manually instantiate the Query object, but you need to provide the DB connection manually:

declare(strict_types=1);
namespace App\Api;
use App\Api\Shared\ResponseFactory;
use App\Shared\ApplicationParams;
use Psr\Http\Message\ResponseInterface;
use Yiisoft\Db\Connection\ConnectionInterface;
use Yiisoft\Db\Query\Query;

final class IndexAction
{
    public function __invoke(
        ResponseFactory     $responseFactory,
        ApplicationParams   $applicationParams,
        ConnectionInterface $db,
    ): ResponseInterface
    {
        $query = (new Query($db))
            ->select('*')
            ->from('user');
        return $responseFactory->success($query->all());
    }
}

Or you can use the DI container to provide you with the instance. I like this better as I can omit input parameters:

declare(strict_types=1);
namespace App\Api;
use App\Api\Shared\ResponseFactory;
use App\Shared\ApplicationParams;
use Psr\Container\ContainerInterface;
use Psr\Http\Message\ResponseInterface;
use Yiisoft\Db\Query\Query;

final class IndexAction
{
    public function __invoke(
        ResponseFactory    $responseFactory,
        ApplicationParams  $applicationParams,
        ContainerInterface $container,
    ): ResponseInterface
    {
        $query = $container->get(Query::class)
            ->select('*')
            ->from('user');
        return $responseFactory->success($query->all());
    }
}

Now you can call the URL and see all the users. (If you entered some) http://localhost:9080

Note: You can also use Injector (and method $injector->make()) instead of ContainerInterface (and method $container->get()). Injector seems to allow you to pass input arguments if needed.

PS: The input parameter of new Query(ConnectionInterface $db) is automatically provided as it is defined in DI. See the file you created earlier above: config/common/di/db-mysql.php

Seeding the database ¶

Seeding = inserting fake data.

You can technically create a migration or a command and insert random data manually. But you can also use the Faker. In that case I needed following dependencies:

composer require fakerphp/faker
composer require yiisoft/security (not only for generating random strings)

Now find the class HelloCommand.php, copy and rename it to SeedCommand.php

Inside you will need the instance of ConnectionInterface. It can be automatically provided by the DI (because you defined it in config/common/di/db-mysql.php), you only need to create a new constructor and then use the instance in method execute():

namespace App\Console;

use Faker\Factory;
use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Yiisoft\Db\Connection\ConnectionInterface;
use Yiisoft\Security\Random;
use Yiisoft\Yii\Console\ExitCode;

#[AsCommand(
    name: 'seed',
    description: 'Run to seed the DB',
)]
final class SeedCommand extends Command
{
    public function __construct(
        private readonly ConnectionInterface $db
    )
    {
        parent::__construct();
    }

    protected function execute(
        InputInterface  $input,
        OutputInterface $output
    ): int
    {

        $faker = Factory::create();

        for ($i = 0; $i < 10; $i++) {
            $this->db->createCommand()
                ->insert('user', [
                    'name' => $faker->firstName(),
                    'surname' => $faker->lastName(),
                    'username' => $faker->userName(),
                    'email' => $faker->email(),
                    'auth_key' => Random::string(32),
                ])
                ->execute();
        }

        $output->writeln('Seeding DONE.');

        return ExitCode::OK;
    }
}

Register the new command in file config/console/commands.php.

You can also obtain the ConnectionInterface in the same way as you did it in IndexAction with the Query object. Just use ContainerInterface $container in the constructor instead of ConnectionInterface $db. Then you can call $db = $this->container->get(ConnectionInterface::class);.

Using Repository and the Model class ¶

Each entity should have its Model class and Repository class if you are storing it in DB. Have a look at the demo application "blog-api": https://github.com/yiisoft/demo

In my case the User model (file src/Entity/User.php) will only contain private attributes, setters and getters. UserRepository (placed in the same folder) may look like this to enable CRUD (compressed code):

<?php
declare(strict_types=1);
namespace App\Entity;
use DateTimeImmutable;
use Yiisoft\Db\Connection\ConnectionInterface;
use Yiisoft\Db\Exception\Exception;
use Yiisoft\Db\Exception\InvalidConfigException;
use Yiisoft\Db\Query\Query;
final class UserRepository
{
    public const TABLE_NAME = 'user';
    public function __construct(private readonly ConnectionInterface $db){}
    public function findAll(array $orderBy = [], $asArray = false): array
    {
        $query = (new Query($this->db))->select('*')->from(self::TABLE_NAME)->orderBy($orderBy ?: ['created_at' => SORT_DESC]);
        if ($asArray) {
            return $query->all();
        }
        return array_map(
            fn(array $row) => $this->hydrate($row),
            $query->all()
        );
    }
    public function findBy(string $attr, mixed $value): ?User
    {
        $row = (new Query($this->db))->select('*')->from(self::TABLE_NAME)->where([$attr => $value])->one();
        return $row ? $this->hydrate($row) : null;
    }
    public function findByUsername(string $username): ?User
    {
        return $this->findBy('username', $username);
    }
    public function save(User $user): void
    {
        $data = ['name' => $user->getName(), 'surname' => $user->getSurname(), 'username' => $user->getUsername(), 'email' => $user->getEmail(), 'auth_key' => $user->getAuthKey()];
        if ($user->getId() === null) {
            $data['created_at'] = (new DateTimeImmutable())->format('Y-m-d H:i:s');
            $this->db->createCommand()->insert(self::TABLE_NAME, $data)->execute();
        } else {
            $this->db->createCommand()->update(self::TABLE_NAME, $data, ['id' => $user->getId()])->execute();
        }
    }
    public function delete(int $id): bool
    {
        try {
            $this->db->createCommand()->delete(self::TABLE_NAME, ['id' => $id])->execute();
        } catch (\Throwable $e) {
            return false;
        }
        return true;
    }
    private function hydrate(array $row): User
    {
        $user = new User();
        $reflection = new \ReflectionClass($user);
        $this->hydrateAttribute($reflection, $user, 'id', (int) $row['id']);
        $this->hydrateAttribute($reflection, $user, 'name', ($row['name']));
        $this->hydrateAttribute($reflection, $user, 'surname', $row['surname']);
        $this->hydrateAttribute($reflection, $user, 'username', $row['username']);
        $this->hydrateAttribute($reflection, $user, 'email', $row['email']);
        $this->hydrateAttribute($reflection, $user, 'created_at', new DateTimeImmutable($row['created_at']));
        $this->hydrateAttribute($reflection, $user, 'updated_at', new DateTimeImmutable($row['updated_at'] ?? ''));
        return $user;
    }
    private function hydrateAttribute(\ReflectionClass $reflection, object $obj, string $attribute, mixed $value)
    {
        $idProperty = $reflection->getProperty($attribute);
        $idProperty->setAccessible(true);
        $idProperty->setValue($obj, $value);
    }
}

Now you can modify IndexAction to contain this: (read above to understand details)

// use App\Entity\UserRepository;
$userRepository = $container->get(UserRepository::class);
return $responseFactory->success($userRepository->findAll([], true));

API login + access token ¶

Once user logs in you want to create an access-token. Why? Because in APIs the PHP session is not used, so users would have to send their login in every request, which would be a potential risk. So random strings with limited lifetime are generated and users send them in their requests intstead of the login. After a few minutes or hours the access token expires and a new one must be created. Each user can have more tokens for different situations. Details here: https://goteleport.com/learn/authentication-and-authorization/simple-random-tokens-secure-authentication/

Below I am indicating how to implement "Random Token Authentication". Other options would be:

• JWT (JSON Web Token) .. I see some disadvatages
• OAuth, OAuth2 - too complex for a simple API

Before you start, install dependency:

composer require yiisoft/security

Let's create a migration for storing the access tokens:

// method up():
$b->createTable('user_token', [
    'id' => $b->primaryKey(),
    'id_user' => $b->integer()->notNull(),
    'token' => $b->string()->notNull()->unique(),
    'expires_at' => $b->dateTime()->notNull(),
    'created_at' => $b->dateTime()->notNull()->defaultExpression('CURRENT_TIMESTAMP'),
    'updated_at' => $b->dateTime(),
    'deleted_at' => $b->dateTime(),
]);

Then create a model App\Entity\UserToken. It again contains only private properties, getters and setters. Plus I added __construct() and toArray():

// Uglified code:
#[Column(type: 'primary')]
private int $id;
#[Column(type: 'integer')]
private int $id_user;
#[Column(type: 'string(255)', default: '')]
private string $token = '';
#[Column(type: 'datetime')]
private DateTimeImmutable $expires_at;
#[Column(type: 'datetime', nullable: true)]
private ?DateTimeImmutable $created_at;
#[Column(type: 'datetime', nullable: true)]
private ?DateTimeImmutable $updated_at;
#[Column(type: 'datetime', nullable: true)]
private ?DateTimeImmutable $deleted_at;
public function __construct(int $userId, string $token, DateTimeImmutable $expiresAt = null)
{
    $this->id_user = $userId;
    $this->token = $token;
    $this->expires_at = $expiresAt;
}
public function toArray(): array
{
    return [
        'id' => $this->id,
        'id_user' => $this->id_user,
        'token' => $this->token,
        'expires_at' => $this->expires_at->format('Y-m-d H:i:s'),
    ];
}

Then you will also need class App\Entity\UserTokenRepository for DB manipulation. Copy and modify the UserRepository. These methods will be handy:

public function findByToken(string $token): ?UserToken
{
    $tokenEntity = $this->findBy('token', $token);
    if (!$tokenEntity) {
        return null;
    }
    if ($tokenEntity->getExpiresAt() < new DateTimeImmutable()) {
        // Optionally delete expired token
        $this->delete($tokenEntity->getId());
        return null;
    }
    return $tokenEntity;
}
public function create(int $userId, ?string $token = null, ?DateTimeImmutable $expiresAt = null, $lifespan = '+2 hours'): UserToken
{
    if (!$token) {
        $token = bin2hex(Random::string(32));
        // Example: 654367506342505647634a6f4c6945784d793447355048734b364a4e62483743
    }
    if (!$expiresAt) {
        $expiresAt = (new DateTimeImmutable())->modify($lifespan);
    }
    $entity = new UserToken($userId, $token, $expiresAt);
    $this->db->createCommand()
        ->insert(self::TABLE_NAME, $entity->toArray())
        ->execute();
    return $entity;
}

The User model will need one more method:

// use Yiisoft\Security\PasswordHasher;
public function validatePassword(string $password): bool
{
    return (new PasswordHasher())->validate($password, $this->password_vuejs_hash);
}

In the end you can create the login action. Register it again in config/common/routes.php.

<?php
declare(strict_types=1);
namespace App\Api;
use App\Api\Shared\ResponseFactory;
use App\Entity\UserRepository;
use App\Entity\UserTokenRepository;
use App\Shared\ApplicationParams;
use DateTimeImmutable;
use Psr\Container\ContainerInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Yiisoft\DataResponse\DataResponse;
use Yiisoft\Http\Status;
final class LoginAction
{
    public function __construct(
        private UserRepository      $userRepository,
        private UserTokenRepository $userTokenRepository,
    ){}
    public function __invoke(
        ResponseFactory        $responseFactory,
        ApplicationParams      $applicationParams,
        ContainerInterface     $container,
        ServerRequestInterface $request
    ): ResponseInterface
    {
        $data = json_decode((string) $request->getBody(), true);
        $username = $data['username'] ?? '';
        $password = $data['password'] ?? '';
        $user = $this->userRepository->findByUsername($username);
        if (!$user || !$user->validatePassword($password)) {
            return new DataResponse(['error' => 'Invalid credentials'], Status::UNAUTHORIZED);
        }
        $this->userTokenRepository->deleteByUserId($user->getId());
        $userToken = $this->userTokenRepository->create($user->getId());
        return $responseFactory->success([
            'token' => $userToken->getToken(),
            'expires_at' => $userToken->getExpiresAt()->format(DateTimeImmutable::ATOM),
        ]);
    }
}

Next we also need an algorithm that will enforce these tokens in each request, will validate and refresh them and will restrict access only to endpoints that the user can use. This is a bigger topic for later. It may be covered by the package https://github.com/yiisoft/auth/ which offers "HTTP bearer authentication".

JS client - Installable Vuejs3 PWA ¶

If you create a REST API you may be interested in a JS frontend that will communicate with it using Ajax. Below you can peek into my very simple VueJS3 attempt. It is an installable PWA application that works in offline mode (=1 data transfer per day, not on every mouse click) and is meant for situations when customer does not have wifi everywhere. See my Gitlab.

1. Installation
2. Usage

Yii 2 extension for render views using Fenom template engine.

Installation ¶

composer require ensostudio/yii2-fenom

Usage ¶

You can add a custom template engine by reconfiguring view component's behavior:

[
    'components' => [
        'view' => [
            'class' => yii\web\View::class,
            'renderers' => [
                'tpl' => [
                    'class' => ensostudio\yii2fenom\FenomViewRenderer::class,
                    // customize renderer options,
                ],
            ],
        ],
    ],
]

See https://www.yiiframework.com/doc/guide/2.0/en/tutorial-template-engines

Yii2 File Crafter

Yii2 File Crafter - library for generating a many templates with minimal differences

Content ¶

• Setup
• Config
• Using

Setup

Requirements

• php >=8.0
• Yii2

Composer

Add package to project ¶

Using console

(Recommended)

• Composer ( global setup )

  composer require andy87/yii2-file-crafter:dev-master --dev
  ````  
  

• Composer.phar ( local setup )

  php composer.phar require andy87/yii2-file-crafter:dev-master --dev
  

Using: file composer.json

Open file composer.json, in section with key require add line:
"andy87/yii2-file-crafter": "dev-master"

dont forget update composer `bash composer update `

- - - - -

Config

Config in the configuration file.

• basic:config/(web|web-local|local).php
• advanced:(frontend|backend)/config/main-local.php

Minimum config `php $config['modules']['gii'] = [

'class' => yii\gii\Module::class,
'generators' => [
    'fileCrafter' => [
        'class' => andy87\yii2\file_crafter\Crafter::class,
        'options' => [
            'templates' => [
                'group_name' => [
                    // 'template' => 'path/to/file.php',
                    'common/services/PascalCaseService' => '@app/common/services/items/{PascalCase}Service.php',
                    'template/test/unit/camelCaseService.tpl' => '@backend/test/unit/{{camelCase}}Service.php',
                    'templates/view/index.php' => 'custom/dir/{{snake_case}}/index.php',
                ]
            ]
        ]
    ]
],

]; `

Full Config with all options `php $config['modules']['gii'] = [

'class' => yii\gii\Module::class,
'generators' => [
    'fileCrafter' => [
        'class' => andy87\yii2\file_crafter\Crafter::class,
        'options' => [
            'cache' => [
                'dir' => '@runtime/yii2-file-crafter/cache',
                'ext' => '.tpl'
            ],
            'source' => [
                'dir' => '@runtime/yii2-file-crafter/templates/source',
                'ext' => '.tpl'
            ],
            'custom_fields' => [
                'singular' => 'label - one',
                'plural' => 'label - many',
           ],
            'commands' => [
                'php yii gii/model --tableName={{snake_case}} --modelClass={{PascalCase}} --ns="common\models" --interactive=0' //... 
            ],
            'eventHandler' => app\composents\behavior\FileCrafterBehavior::class,
            'autoCompleteStatus' => true,
            'autoCompleteList' => [
                'autocomplete name 1',
                'autocomplete name 2',
            ],
            'previewStatus' => true,
            'canDelete' => true,
            'parseDataBase' => ['autocomplete','fakeCache'],
            'templates' => [
                'common' => [
                    'common/services/PascalCaseService' => 'app/common/services/items/{[PascalCase]}Service.php',
                ],
                'backend' => [
                    'backend/test/unit/camelCaseService.tpl' => 'backend/test/unit/{{camelCase}}Service.php',
                ],
                'frontend' => [
                    'frontend/view/index.php' => 'app/frontend/view/{{snake_case}}/index.php',
                ],
                'all' => [
                    'common/services/PascalCaseService' => 'app/common/services/items/{PascalCase}Service.php',
                    'backend/test/unit/camelCaseService.tpl' => 'backend/test/unit/{{camelCase}}Service.php',
                    'frontend/view/index.php' => 'app/frontend/view/{{snake_case}}/index.php',
                ]
            ],
        ]
    ]
],

]; `

Using

• Marks
• Cache
• Source
• Custom Fields
• Autocomplete status
• Autocomplete list
• Preview status
• Can delete
• Parse data base
• Commands
• Events
• Templates

Marks

Module use marks for replace variables in templates.

• {{PascalCase}} - PascalCase by schema name
• {{camelCase}} - camelCase by schema name
• {{snake_case}} - snake_case by schema name
• {{kebab-case}} - kebab-case by schema name
• {{UPPERCASE}} - UPPERCASE by schema name
• {{lowercase}} - lowercase by schema name
• {{[key]}} - custom key from property custom_fields on config ( see Custom Fields )

Example ¶

for schema name Product Items replace marks:

• {{PascalCase}} - ProductItems
• {{camelCase}} - productItems
• {{snake_case}} - product_items
• {{kebab-case}} - product-items
• {{UPPERCASE}} - PRODUCT ITEMS
• {{lowercase}} - product items

Cache
<small style="color: #009; font-size:9px">(optional)</small>

Configuration for the cache folder with schema data.

• dir - path to the cache directory with schema data
• ext - extension of the cache file

Default configuration: `php $config['modules']['gii'] = [

'class' => Module::class,
    'generators' => [
        'fileCrafter' => [
        'options' => [
            // ... 
            'cache' => [
                'dir' => '@runtime/yii2-file-crafter/cache',
                'ext' => '.json'
            ],
            // ...
        ],
    ],
]

]; `

Source
<small style="color: #009; font-size:9px">(optional)</small>

Configuration for the source folder with templates files.

• dir - path to the directory with the templates files source for generation
• ext - extension of the templates file

Default configuration: `php $config['modules']['gii'] = [

'class' => Module::class,
    'generators' => [
        'fileCrafter' => [
        'options' => [
            // ... 
            'source' => [
                'dir' => '@runtime/yii2-file-crafter/templates/source',
                'ext' => '.tpl'
            ],
            // ...
        ],
    ],
]

]; `

Templates
<small style="color: #900; font-size:9px">(required)</small>

Array with groups of templates for use on generate files.
`php [

['group1'] => [
    'template1' => 'path/from/project/root/to/resultFile.tpl',
    'template2.tpl' => 'path/from/project/root/to/resultFile.php',
    // ...
],
['group2'] => [
    'template1.php' => '@path/alias/to/resultFile.tpl',
    '@alias/to/template' => 'path/from/project/root/to/resultFile.php',
    // ...
],

] ` The source path may contain:

• some @ alias ( source['dir'] - default container )
• ext for generate any file type ( .php default )
• some {{variable}} ( see Marks )

File source-template will be searched in the source folder.
Source folder path can be set in the configuration file. ( see Source )

The resultFile path may contain:

• some @ alias ( @app/ - default prefix )
• ext for generate any file type ( .php default )
• some {{variable}} ( see Marks )

Content of the templates file rendered with the View method renderFile
And prepared with the $replaceList array contains all marks. ( see Marks )
And also passed to the render method:

• $schema - schema object
• $generator - self generator object

$config['modules']['gii'] = [
    'class' => Module::class,
        'generators' => [
            'fileCrafter' => [
            'options' => [
                // ... 
                'templates' => [
                    'all' => [
                        '@backend/dir/by/alias/camelCaseService.tpl' => '@backend/generate/by/alias/{{camelCase}}Service.php',
                        'dir/on/source/dir/generate_file' => 'custom/dir/on/source/dir/{{snake_case}}/generate_file.tpl',
                    ],
                ],
                // ...
            ],
        ],
    ]
];

Custom Fields
<small style="color: #009; font-size:9px">(optional)</small>

Array with custom fields for use custom variables in templates.
Using on template key wrapped in square brackets: {{%key%}}
Example: {{key_one}}, {{key_two}}...

Example simple config
`php $config['modules']['gii'] = [

'class' => Module::class,
    'generators' => [
        'fileCrafter' => [
        'options' => [
            // ... 
            'custom_fields' => [
                'singular' => 'one',
                'plural' => 'many',
            ],
            // ...
        ],
    ],
]

]; with template:php Value - ONE = {{singular}} Value - MANY = ({{plural}}) `

___

Schema 1: Product Items
Field one = !!product!!
Field many = >>> products <<<

...generate...

Result: app/frontend/views/info--product_items.php `php Value - ONE = !!product!! Value - MANY = (>>> products <<<) `

___

Schema 2: Category Group
Field label one = --category--
Field label many = +++categories+++

...generate...

Result: app/frontend/views/info--category_group.php `php Value - ONE = --category-- Value - MANY = (+++categories+++) `

Autocomplete status

Key autoCompleteStatus contain status for autocomplete field Schema name in the form 200 populated values.

Variants: true or false(default)
`php $config['modules']['gii'] = [

'class' => Module::class,
    'generators' => [
        'fileCrafter' => [
        'options' => [
            // ... 
            'autoCompleteStatus' => true,
            // ...
        ],
    ],
],

]; `

Autocomplete list
<small style="color: #009; font-size:9px">(optional)</small>

Key autoCompleteList contain list of autocomplete field Schema name in the form self custom list.

Type: array
`php $config['modules']['gii'] = [

'class' => Module::class,
    'generators' => [
        'fileCrafter' => [
        'options' => [
            // ... 
            'autoCompleteList' => [
                'Product Items',
                'Category Group',
                'User Profile',
                // ...
            ],
            // ...
        ],
    ],
],

]; `

<h2 align="center">Preview status
<small style="color: #009; font-size:9px">(optional)</small> 

Key previewStatus contain status for preview file content on hover icon in the form.

Variants: true(default) or false
`php $config['modules']['gii'] = [

'class' => Module::class,
    'generators' => [
        'fileCrafter' => [
        'options' => [
            // ... 
            'previewStatus' => true,
            // ...
        ],
    ],
],

]; `

<h2 align="center">Can delete
<small style="color: #009; font-size:9px">(optional)</small> 

Key canDelete contain status for delete schema from the form.

Variants: true(default) or false `php $config['modules']['gii'] = [

'class' => Module::class,
    'generators' => [
        'fileCrafter' => [
        'options' => [
            // ... 
            'canDelete' => true,
            // ...
        ],
    ],
],

]; `

Parse data base
<small style="color: #009; font-size:9px">(optional)</small>

Key parseDataBase contain list of target for extend schema name list from database.

Variants: array with values:

• autocomplete
• fakeCache

Default empty; `php $config['modules']['gii'] = [

'class' => Module::class,
    'generators' => [
        'fileCrafter' => [
        'options' => [
            // ... 
            'parseDataBase' => ['autocomplete','fakeCache'],
            // ...
        ],
    ],
],

]; `

Commands
<small style="color: #009; font-size:9px">(optional)</small>

Key commands contain list cli command for call before generate any file.
command make use of the {{variable}} in the command string ( see Marks )

Example: generate gii model for table name from schema name before generate fileContent

Default empty; `php $config['modules']['gii'] = [

'class' => Module::class,
    'generators' => [
        'fileCrafter' => [
        'options' => [
            // ... 
            'commands' => [
                'php yii gii/model --tableName={{snake_case}} --modelClass={{PascalCase}} --ns="common\models"  --interactive=0 --overwrite=1' // ... 
            ],
            // ...
        ],
    ],
],

]; `

Events
<small style="color: #009; font-size:9px">(optional)</small>

Make use of the eventHandlers key to add a behavior to the module.

Example: add behavior FileCrafterBehavior to the module

Default null; `php $config['modules']['gii'] = [

'class' => Module::class,
    'generators' => [
    'options' => [
            // ... 
            'eventHandlers' => FileCrafterBehavior::class,
            // ...
        ],
    ],
],

]; `

Before init ¶

CrafterEvent::BEFORE_INIT before init module

After init ¶

CrafterEvent::AFTER_INIT after init module

Come events has special properties...

Before generate ¶

CrafterEventGenerate::BEFORE before generate all files

//class FileCrafterBehavior extends Behavior
public function beforeGenerate(CrafterEventGenerate $crafterEventGenerate): void {
    Yii::info([ 'Generated files', [
        $crafterEventGenerate->files // empty (call before generate)
    ]]); 
}

Before command ¶

CrafterEventCommand::BEFORE before run cli command

//class FileCrafterBehavior extends Behavior
public function beforeCommand(CrafterEventCommand $crafterEventCommand): void {
       Yii::error([ __METHOD__, [
        $crafterEventCommand->cmd->exec,
        $crafterEventCommand->cmd->output, // empty (call before exec command)
        $crafterEventCommand->cmd->replaceList
    ]]);
}

Cmd ¶

\andy87\yii2\file_crafter\components\models\Dto

• string $exec - exec command
• string $output - exec output
• array $replaceList - replace map

After command ¶

CrafterEventCommand::AFTER after run cli command

//class FileCrafterBehavior extends Behavior
public function afterCommand(CrafterEventCommand $crafterEventCommand): void {
    Yii::error([ __METHOD__, [
        $crafterEventCommand->cmd->exec,
        $crafterEventCommand->cmd->output, // output command
        $crafterEventCommand->cmd->replaceList
    ]]);
}

Before render ¶

CrafterEventRender::BEFORE before render file

//class FileCrafterBehavior extends Behavior
public function beforeRender(CrafterEventRender $crafterEventRender): void {
    Yii::error([ __METHOD__, [
        $crafterEventRender->schema,
        $crafterEventRender->sourcePath,
        $crafterEventRender->generatePath,
        $crafterEventRender->replaceList,
        $crafterEventRender->content // empty (call before render file)
    ]]);
}

After render ¶

CrafterEventRender::AFTER after render file

//class FileCrafterBehavior extends Behavior
public function afterRender(CrafterEventRender $crafterEventRender): void {
    Yii::error([ __METHOD__, [
        $crafterEventRender->schema,
        $crafterEventRender->sourcePath,
        $crafterEventRender->generatePath,
        $crafterEventRender->replaceList,
        $crafterEventRender->content // content file
    ]]);
}

After generate ¶

CrafterEventGenerate::AFTER after generate all files

public function afterGenerate(CrafterEventGenerate $crafterEventGenerate): void {
    Yii::info([ 'Generated files', [
        $crafterEventGenerate->files // CodeFile[]
    ]]); 
}

Packagist

Yii2 Material ¶

1. Instalación
2. Uso
3. Componentes
4. Donaciones
5. Licencia

Esta es una extensión primaria para Yii framework 2.0. Encapsula componentes de Material Design en términos de Widgets Yii.

NOTA: Material Web 3 no tiene los componentes Card, Snackbar, TopAppBar ni NavigationRail, así que se han creado desde 0 intentando seguir los lineamientos del diseño de Material 3.

Instalación ¶

La forma preferida de instalar esta extensión es a través de composer.

Luego ejecute

php composer.phar require --prefer-dist neoacevedo/yii2-material

o agregue

"neoacevedo/yii2-material": "*"

a la sección require de su archivo composer.json.

Uso ¶

Incluya antes del cierre de la etiqueta 'body' de su plantilla principal lo siguiente:

<?= MaterialAsset::publishMaterialScripts() ?>

Los data-* atributos programados no funcionan en Material Design Components para la web, por lo que se tendrán que programar los elementos que tengan estos atributos de manera separada.

Componentes ¶

• ActiveForm y ActiveField
• Button
• Card
• Checkbox
• Dialog
• Floating Action Button
• Icon Button
• ListTile
• Menu
• NavigationDrawer
• NavigationRail
• ProgressIndicator
• Radio
• Select
• SnackBar

Donaciones ¶

Si este proyecto te es útil, considera hacer una donación:

Licencia ¶

Este proyecto está licenciado bajo la Licencia GPL-3.0+ - ver el archivo LICENSE.md para más detalles.

Additional span with error class for ActiveField ¶

1. What is it about?
2. Installing
3. How to use

What is it about? ¶

Bootstrap 4 and 5 are expecting `html` like this to decorate validation error:

<input type="text" id="eventform-datetime" class="form-control is-invalid" name="EventForm[datetime]" aria-required="true">
<div class="invalid-feedback">Error message</div>

Element with `div.invalid-feedbackis supposed to be on the same level with yourinput.is-invalid`.

But sometimes when we are using any widgets or custom template we get html like this:

<div class="some-plugin-wrapper">
  <input type="text" id="eventform-datetime" class="form-control is-invalid" name="EventForm[datetime]" aria-required="true">
</div>  
<div class="invalid-feedback">Error message</div>

, so our error message is not shown.

Of cource you can make `div.invalid-feedback` visible by css for this page.

But if that does not suit you, this library propose another solution.

We are adding special `to a field template right before{error}part. And we **synchronize** thiswith the **input field** so it gets.is-invalid` class when input does

Installing ¶

Installing through composer:: ¶

The preferred way to install this library is through composer.

Either run composer require --prefer-dist mgrechanik/yii2-activefield-additional-error

or add "mgrechanik/yii2-activefield-additional-error " : "~1.0.0" to the require section of your composer.json.

How to use ¶

in your `viewfile, say it is_form.php`

use mgrechanik\additionalerror\AdditionalErrorBehavior;

<div class="event-form-form">

    <?php $form = ActiveForm::begin([
            'id' => 'event-create-form',
            // Adding behavior
            'as adderror' => [
                'class' => AdditionalErrorBehavior::class,
            ]
    ]); ?>

    <?= $form->field($model, 'datetime', [
            // Adding this hidden span before error block 
            'template' => "{label}\n{input}\n{hint}\n" . $form->getAdditionalErrorSpan($model, 'datetime') . "\n{error}"
    ])->hint('Some hint')
      ->widget(/* Some complicated widget creates a wrapper for the {input} part... */)

It will work for both server and client side.

Fix for Yii2 GridView filter functionality to work properly with Bootstrap 4 and Bootstrap 5 ¶

1. What is it about?
2. Installing
3. How to use
4. Similar problems with Forms or GridView and Bootstrap 4 / 5

What is it about? ¶

When you are using Yii2 default GridView you might meet a problem that validation errors for filter model are not displayed properly, like this:

Installing ¶

Installing through composer:: ¶

The preferred way to install this library is through composer.

Either run composer require --prefer-dist mgrechanik/gridviewfilterfix

or add "mgrechanik/gridviewfilterfix" : "~1.0.0" to the require section of your composer.json.

How to use ¶

Add the following lines of code to your main configuration file: 1) For Bootstrap 4 `php

'container' => [
    'definitions' => [
        \yii\grid\GridView::class => [
            'dataColumnClass' => \mgrechanik\gridviewfilterfix\Bs4DataColumn::class
        ]
    ]
],

2) For Bootstrap 5
```php
    'container' => [
        'definitions' => [
            \yii\grid\GridView::class => [
                'dataColumnClass' => \mgrechanik\gridviewfilterfix\Bs5DataColumn::class
            ]
        ]
    ],

Similar problems with Forms or GridView and Bootstrap 4 / 5 ¶

Paginator does not look good ¶

Solution:

    'container' => [
        'definitions' => [
            \yii\widgets\LinkPager::class => \yii\bootstrap5\LinkPager::class,
        ],
    ],

Error block under field is now shown, after failed validation, since this block is not at the same level with input.is-invalid ¶

There is a library to solve this problem

yii2-donate ¶

1. Basic functionality
2. Prerequisites
3. Installation
4. The Donate widget
5. Module options
6. Internationalization
7. Module ID

Donation widget for Yii2 ¶

Yii2-donate is a module for the Yii 2.0 PHP Framework to handle donations. It makes use of the payment service provider Mollie, which is mainly active in Western European countries.

Yii2-donate sports a widget, which can be placed on any page (or even all pages).

Basic functionality ¶

If a visitor selects an amount and presses the 'Donate'-button, she is transfered to a Mollie payment page. If she successfully completes the payment, she is redirected to the site's donate/thanks page, where she is rewarded with a joyful shower of confetti. If the visitor did supply an email address, she receives a 'Thank you' mail. The 'thanks' page also sports a button to resume her visit to the site.

If the visitor cancels the payment, she is redirected to the site's donate/cancel page, from where she can resume her surfing.

At any time, the site's administrator can get an overview of granted donations on the donate page.

Prerequisites ¶

You'll need a Mollie account. It's free, but depending on your country, you may need a valid registration as a (small) business. You'll get two API keys, one for testing purposes and one for the real work. One of the API keys is used tot initialize the module.

It is strongly advised that the app uses Pretty URLs.

Because Yii2-donate may send emails, the mailer component of the application has to be up and running. Be sure that the 'adminEmail' parameter of the application has a sensible value. If you prefer, you may set the 'supportEmail' parameter as well; if set, Yii2-donate will use this.

Installation ¶

Install Yii2-donate in the usual way with Composer. Add the following to the require section of your composer.json file:

"sjaakp/yii2-donate": "*"

or run:

composer require sjaakp/yii2-donate

You can manually install yii2-comus by downloading the source in ZIP-format.

Module ¶

Yii2-donate is a module in the Yii2 framework. It has to be configured in the main configuration file, usually called web.php or main.php in the config directory. Add the following to the configuration array:

<?php
// ...
'modules' => [
    'donate' => [
        'class' => sjaakp\donate\Module::class,
        // several options
    ],
],
// ...

The module has to be bootstrapped. Do this by adding the following to the application configuration array:

<php
// ...
'bootstrap' => [
    'donate',
]
// ...

There probably already is a bootstrap property in your configuration file; just add 'donate' to it.

Important: the module should also be set up in the same way in the console configuration (usually called console.php).

Console command ¶

To complete the installation, a console command have to be run. This will create a database table for the donations:

yii migrate

The migration applied is called sjaakp\donate\migrations\m000000_000000_init.

The Donate widget ¶

Placing the Donate widget in any view is trivial:

<?php
use sjaakp\donate\DonateWidget;
?>
...
<?= DonateWidget::widget() ?>
...

The small, collapsed variant is obtained by:

<?php
use sjaakp\donate\DonateWidget;
?>
...
<?= DonateWidget::widget([
    'small' => true
]) ?>
...

Module options ¶

The Donate module has a range of options. They are set in the application configuration like so:

 <?php
 // ...
 'modules' => [
     'donate' => [
         'class' => sjaakp\donate\Module::class,
         'description' => 'Please, buy me a drink!',
         // ...
         // ... more options ...
     ],
 ],
 // ...

The options (most are optional) are:

• mollieApiKey string One of the API keys obtained from Mollie. Not optional, must be set.
• choices array Amounts to select from. Keys are integers representing the amounts in cents, values are textual representations. Example: [ ..., 250 => '€2,50', 500 => '€5', ... ]. Defaults: amounts of 5, 10, 25, 50, and 100.
• header string|null Text header appearing in the donate-widget. If null (default) no header is rendered.
• includeMessage bool Whether a 'friendly message' field is included in the widget. Default: true.
• confetti bool Whether confetti is shown on the 'thanks' page. Default: true.
• description string|null The textual description displayed on Mollie's payment page. If null (default), defaults to 'Donation for <site name>'.
• locale string|null The locale sent to the payment site. If null, defaults to site's language property.
• mailOptions array Options for the app mailer. Default: see source.
• localTest bool|null If true, performs a dummy-payment on the local system, useful for debugging and testing. If null (default), localTest is set to true if YII_ENV === 'dev', in other words if the site is in the development environment.
• indexAccess array The access rule for the donations overview (donate page). Default: only accessible to authenticated visitors ([ 'allow' => true, 'roles' => ['@'] ]). For most sites, you'll want to refine this.

Internationalization ¶

All of Yii2-donate's utterances are translatable. The translations are in the 'sjaakp\donate\messages' directory.

You can override Yii2-donate's translations by setting the application's message source in the main configuration, like so:

 <?php
 // ...
 'components' => [
     // ... other components ...     
     'i18n' => [
          'translations' => [
               // ... other translations ...
              'donate' => [    // override donate's standard messages
                  'class' => yii\i18n\PhpMessageSource::class,
                  'basePath' => '@app/messages',  // this is a default
                  'sourceLanguage' => 'en-US',    // this as well
              ],
          ],
     ],
     // ... still more components ...
 ]

The translations should be in a file called 'donate.php'.

If you want a single or only a few messages translated and use Yii2-donate's translations for the main part, the trick is to set up 'i18n' like above and write your translation file something like:

  <?php
  // app/messages/nl/donate.php
  
  $donateMessages = Yii::getAlias('@sjaakp/donate/messages/nl/donate.php');
  
  return array_merge (require($donateMessages), [
     'Amount' => 'Bedrag in euro',   // your preferred translation
  ]);

At the moment, the only language implemented is Dutch. Agreed, it's only the world's 52th language, but it happens to be my native tongue. Please, feel invited to translate Yii2-donate in other languages. I'll be more than glad to include them into Yii2-donate's next release.

Module ID ¶

By default, the Module ID is 'donate'. It is set in the module configuration. If necessary (for instance if there is a conflict with another module or application component), you may set the Module ID to something different. Important: in that case, the moduleId property of the Donate widget must be set to this new value as well.

FAQ ¶

Can I change the layout for the Yii2-donate views?

• Use the EVENT_BEFORE_ACTION event. One easy way is to incorporate it in the module setup, like so:

  <?php
  // ...
  'modules' => [
     'donate' => [
         'class' => sjaakp\donate\Module::class,
         'description' => 'Please, buy me a drink!',
         'on beforeAction' => function ($event) {
             $event->sender->layout = '@app/views/layouts/one_column';
         },
         // ... more options ...
     ],
  ],
  // ...
  

There are multiple blog that shows how to use seperate login for yii2 application but in this article i will show you how to use a single login screen for all your YII2 Advanced, YII2 Basic, Application, It will also work when your domain on diffrent server or the same server.

Here are few Steps you need to follow ot achive this.

1. For Advanced Templates

Step 1 : Add this into your component inside

/path/common/config/main.php

  'components' => [
        'user' => [
            'identityClass' => 'common\models\User',
            'enableAutoLogin' => true,
            'identityCookie' => ['name' => '_identity', 'httpOnly' => true],
        ],
        'request' => [
            'csrfParam' => '_csrf',
        ],
    ],

Step 2: Add Session and Request into main-local.php

/path/common/config/main-local.php

   'components' => [
        'session' => [
            'cookieParams' => [
                'path' => '/',
                'domain' => ".example.com",
            ],
        ],
        'user' => [
            'identityCookie' => [
                'name' => '_identity',
                'path' => '/',
                'domain' => ".example.com",
            ],
        ],
        'request' => [
            'csrfCookie' => [
                'name' => '_csrf',
                'path' => '/',
                'domain' => ".example.com",
            ],
        ],
    ],

Note: example.com is the main domain. All other domain should be sub domain of this.

Step 3: Now Update the Same Validation Key for all the applications

/path/frontend/config/main-local.php

/path/backend/config/main-local.php

 'components' => [
        'request' => [
            // !!! insert a secret key in the following (if it is empty) - this is required by cookie validation
            'cookieValidationKey' => 'fFUeb5HDj2P-1a1FTIqya8qOE',
        ],
    ],

Note : Remove the Session and request keys from your main.php of Both frontend and backend application.

Step 4: Note Somethign that you also have and console application so update session, user,and request into the main-local.php of your console application

/path/console/config/main-local.php

 'components' => [
        'session' => null,
        'user' => null,
        'request' => null,
    ]

2. For Basic Templates

Additionaly If you have an basic templates installed for another project and you want to use same login for that templates. To Achive this follow the given steps

Step 1: Update You main-local.php of basic template

/path/basic-app/config/main-local.php

 'components' => [
        'session' => [
            'cookieParams' => [
                'path' => '/',
                'domain' => ".example.com",
            ],
        ],
        'user' => [
            'identityCookie' => [
                'name' => '_identity',
                'path' => '/',
                'domain' => ".example.com",
            ],
        ],
        'request' => [
            'csrfCookie' => [
                'name' => '_csrf',
                'path' => '/',
                'domain' => ".example.com",
            ],
        ],

    ],

I Hope you understand well how to use a single login for all of your domain and subdomain or repository.

:) Thanks for Reading

1. Source code available
2. Goal
3. Approach
4. Conclusion

I was recently assigned with the task of integrating several extensive forms into a WordPress website. These forms comprised numerous fields, intricate validation rules, dynamic fields (one to many relationships) and even interdependencies, where employing PHP inheritance could mitigate code duplication.

Upon initial exploration, it became evident that the conventional approach for handling forms in WordPress typically involves either installing a plugin or manually embedding markup using the editor or custom page templates. Subsequently, one largely relies on the plugin's functionality to manage form submissions or resorts to custom coding.

Given that part of my task entailed logging data, interfacing with API endpoints, sending emails, and more, I opted to develop the functionality myself, rather than verifying if existing plugins supported these requirements.

Furthermore, considering the current landscape (as of March 2024) where most Yii 3 packages are deemed production-ready according to official sources, and being a long-time user of the Yii framework, I deemed it an opportune moment to explore and acquaint myself with these updates.

Source code available ¶

You can explore the entire project and review the code by accessing it on Github.

Additionally, you can deploy it effortlessly using Docker by simply executing docker-compose up from the project's root directory. Check the Dockerfile for the WordPress setup and content generation which is done automatically.

Goal ¶

My objective was to render and manage forms within a WordPress framework utilizing Yii3 packages. For demonstration purposes, I chose to implement a basic Rating Form, where the focus is solely on validating the data without executing further actions.

Approach ¶

To proceed, let's start with a minimalistic classic theme as an example. I created a WordPress page named "The Rating Form" within the dashboard. Then, a file named page-the-rating-form.php is to be created within the theme's root folder to display this specific page.

This designated file serves as the blueprint for defining our form's markup.

Adding Yii3 Packages to the Project: ¶

To harness Yii3's functionalities, we'll incorporate the following packages:

• yiisoft/form-model: For defining a model class representing the form's fields and facilitating field rendering.
• yiisoft/form: To handle markup-related tasks.
• yiisoft/validator: For input validation.

To begin, let's initialize a Composer project in the root of our theme by executing composer init. This process will generate a composer.json file. Subsequently, we'll proceed to include the Yii3 packages in our project.

composer require yiisoft/form-model:dev-master yiisoft/validator yiisoft/form:dev-master

and instruct the theme to load the composer autoload by adding the following line to the functions.php file:

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

Create the form model ¶

Following the execution of the composer init command, a src directory has been created in the root directory of the theme. We will now proceed to add our form model class within this directory.

Anticipating the expansion of the project, it's imperative to maintain organization. Thus, we shall create the directory src/Forms and place the RatingForm class inside it.

<?php

namespace Glpzzz\Yii3press\Forms;

use Yiisoft\FormModel\FormModel;

class RatingForm extends FormModel
{

	private ?string $name = null;
	private ?string $email = null;
	private ?int $rating = null;
	private ?string $comment = null;
	private string $action = 'the_rating_form';

	public function getPropertyLabels(): array
	{
		return [
			'name' => 'Name',
			'email' => 'Email',
			'rating' => 'Rating',
			'comment' => 'Comment',
		];
	}

}

Beyond the requisite fields for our rating use case, it's crucial to observe the action class attribute. This attribute is significant as it instructs WordPress on which theme hook should manage the form submission. Further elaboration on this will follow.

Adding Validation Rules to the Model: ¶

Now, let's incorporate some validation rules into the model to ensure input integrity. Initially, we'll configure the class to implement the RulesProviderInterface. This enables the form package to access these rules and augment the HTML markup with native validation attributes.

class RatingForm extends FormModel implements RulesProviderInterface

Now we need to implement the getRules() method on the class.

public function getRules(): iterable
{
	return [
		'name' => [
			new Required(),
		],
		'email' => [
			new Required(),
			new Email(),
		],
		'rating' => [
			new Required(),
			new Integer(min: 0, max: 5),
		],
		'comment' => [
			new Length(min: 100),
		],
	];
}

Create the form markup ¶

To generate the form markup, we require an instance of RatingForm to be passed to the template. In WordPress, the approach I've adopted involves creating a global variable (admittedly not the most elegant solution) prior to rendering the page.

$hydrator = new Hydrator(
	new CompositeTypeCaster(
		new NullTypeCaster(emptyString: true),
		new PhpNativeTypeCaster(),
		new HydratorTypeCaster(),
	)
);

add_filter('template_redirect', function () use ($hydrator) {
	// Get the queried object
	$queried_object = get_queried_object();

	// Check if it's a page
	if ($queried_object instanceof WP_Post && is_page()) {
		if ($queried_object->post_name === 'the-rating-form') {
			global $form;
			if ($form === null) {
				$form = $hydrator->create(RatingForm::class, []);
			}
		}
	}
});

It's worth noting that we've instantiated the Hydrator class outside any specific function, enabling us to reuse it for all necessary callbacks. With the RatingForm instance now available, we'll proceed to craft the markup for the form within the page-the-rating-form.php file.

<?php

use Glpzzz\Yii3press\Forms\RatingForm;
use Yiisoft\FormModel\Field;
use Yiisoft\Html\Html;

/** @var RatingForm $form */
global $form;

?>


<?php get_header(); ?>

<h1><?php the_title(); ?></h1>

<?php the_content(); ?>

<?= Html::form()
  ->post(esc_url(admin_url('admin-post.php')))
  ->open()
?>

<?= Field::hidden($form, 'action')->name('action') ?>
<?= Field::text($form, 'name') ?>
<?= Field::email($form, 'email') ?>
<?= Field::range($form, 'rating') ?>
<?= Field::textarea($form, 'comment') ?>

<?= Html::submitButton('Send') ?>

<?= "</form>" ?>

<?php get_footer(); ?>

In the markup generation of our form, we've leveraged a combination of Yii3's Html helpers and the Field class. Notable points include:

• The form employs the POST method with the action specified as the admin-post.php WordPress endpoint.
• To include the action value in the form submission, we utilized a hidden field named 'action'. We opted to rename the input to 'action' as the Field::hidden method generates field names in the format TheFormClassName[the_field_name], whereas we required it to be simply named 'action'.

This adjustment facilitates hooking into a theme function to handle the form request, as elucidated in the subsequent section.

Before delving further, let's capitalize on Yii's capabilities to enhance the form. Although we've already defined validation rules in the model for validating input post-submission, it's advantageous to validate input within the browser as well. While we could reiterate defining these validation rules directly on the input elements, Yii offers a streamlined approach. By incorporating the following code snippet into the functions.php file:

add_action('init', function () {
	ThemeContainer::initialize([
			'default' => [
				'enrichFromValidationRules' => true,
			]
		], 'default', new ValidationRulesEnricher()
	);
});

By implementing this code snippet, we activate the ValidationRulesEnricher for the default form theme. Upon activation, we'll notice that the form fields are now enriched with validation rules such as 'required', 'min', and ' max', aligning with the validation rules previously defined in the model class. This feature streamlines the process, saving us valuable time and minimizing the need for manual code composition. Indeed, this showcases some of the remarkable functionality offered by Yii3.

Process the POST request ¶

When the form is submitted, it is directed to admin-post.php, an endpoint provided by WordPress. However, when dealing with multiple forms, distinguishing the processing of each becomes essential. This is where the inclusion of the action value in the POST request proves invaluable.

Take note of the initial two lines in the following code snippet: the naming convention for the hook is admin_post_<action_name>. Therefore, if a form has action = 'the-rating-form', the corresponding hook name will be admin_post_the_rating_form.

As for the inclusion of both admin_post_<action_name> and admin_post_nopriv_<action_name>, this is because WordPress allows for different handlers depending on whether the user is logged in or not. In our scenario, we require the same handler regardless of the user's authentication status.

add_action('admin_post_the_rating_form', fn() => handleForms($hydrator));
add_action('admin_post_nopriv_the_rating_form', fn() => handleForms($hydrator));

function handleForms(Hydrator $hydrator): void
{
  global $form;
  $form = $hydrator->create(RatingForm::class, $_POST['RatingForm']);
  $result = (new Yiisoft\Validator\Validator())->validate($form);

  if ($form->isValid()) {
    // handle the form
  }

  get_template_part('page-the-rating-form');
}

Returning to the Yii aspect: we instantiate and load the posted data into the form utilizing the hydrator. We then proceed to validate the data. If the validation passes successfully, we can proceed with the intended actions using the validated data. However, if validation fails, we re-render the form, populating it with the submitted data and any error messages generated during validation.

Conclusion ¶

• This was my first attempt at mixing Yii3 packages with a WordPress site. While I'm satisfied with the result, I think it can be improved, especially regarding the use of global variables. Since I'm not very experienced with WordPress, I'd appreciate any suggestions for improvement.
• The Yii3 packages I used are ready for real-world use and offer the same quality and features as their older versions.
• Now you can use these Yii packages independently. This means you can apply your Yii skills to any PHP project.
• This project shows how we can enhance a WordPress site by tapping into the powerful features of Yii, while still keeping the simplicity of the CMS.

Originally posted on https://glpzzz.dev/2024/03/03/integrating-yii3-packages-into-wordpress.html

Use the following css styles for carousel to work as expected.

  .product_img_slide {
    padding: 100px 0 0 0;
  }

  .product_img_slide > .carousel-inner > .carousel-item {
    overflow: hidden;
    max-height: 650px;
  }

  .carousel-inner {
    position: relative;
    width: 100%;
  }

  .product_img_slide > .carousel-indicators {
    top: 0;
    left: 0;
    right: 0;
    width: 100%;
    bottom: auto;
    margin: auto;
    font-size: 0;
    cursor: e-resize;
    /* overflow-x: auto; */
    text-align: left;
    padding: 10px 5px;
    /*  overflow-y: hidden;*/
    white-space: nowrap;
    position: absolute;
  }

  .product_img_slide > .carousel-indicators li {
    padding: 0;
    width: 76px;
    height: 76px;
    margin: 0 5px;
    text-indent: 0;
    cursor: pointer;
    background: transparent;
    border: 3px solid #333331;
    -webkit-border-radius: 0;
    border-radius: 0;
    -webkit-transition: all 0.7s cubic-bezier(0.22, 0.81, 0.01, 0.99);
    transition: all 1s cubic-bezier(0.22, 0.81, 0.01, 0.99);
  }

  .product_img_slide > .carousel-indicators .active {
    width: 76px;
    border: 0;
    height: 76px;
    margin: 0 5px;
    background: transparent;
    border: 3px solid #c13c3d;
  }

  .product_img_slide > .carousel-indicators > li > img {
    display: block;
    /*width:114px;*/
    height: 76px;
  }

  .product_img_slide .carousel-inner > .carousel-item > a > img, .carousel-inner > .carousel-item > img, .img-responsive, .thumbnail a > img, .thumbnail > img {
    display: block;
    max-width: 100%;
    line-height: 1;
    margin: auto;
  }

  .product_img_slide .carousel-control-prev {
    top: 58%;
    /*left: auto;*/
    right: 76px;
    opacity: 1;
    width: 50px;
    bottom: auto;
    height: 50px;
    font-size: 50px;
    cursor: pointer;
    font-weight: 700;
    overflow: hidden;
    line-height: 50px;
    text-shadow: none;
    text-align: center;
    position: absolute;
    background: transparent;
    text-transform: uppercase;
    color: rgba(255, 255, 255, 0.6);
    -webkit-box-shadow: none;
    box-shadow: none;
    -webkit-border-radius: 0;
    border-radius: 0;
    -webkit-transition: all 0.6s cubic-bezier(0.22, 0.81, 0.01, 0.99);
    transition: all 0.6s cubic-bezier(0.22, 0.81, 0.01, 0.99);
  }

  .product_img_slide .carousel-control-next {
    top: 58%;
    left: auto;
    right: 25px;
    opacity: 1;
    width: 50px;
    bottom: auto;
    height: 50px;
    font-size: 50px;
    cursor: pointer;
    font-weight: 700;
    overflow: hidden;
    line-height: 50px;
    text-shadow: none;
    text-align: center;
    position: absolute;
    background: transparent;
    text-transform: uppercase;
    color: rgba(255, 255, 255, 0.6);
    -webkit-box-shadow: none;
    box-shadow: none;
    -webkit-border-radius: 0;
    border-radius: 0;
    -webkit-transition: all 0.6s cubic-bezier(0.22, 0.81, 0.01, 0.99);
    transition: all 0.6s cubic-bezier(0.22, 0.81, 0.01, 0.99);
  }

  .product_img_slide .carousel-control-next:hover, .product_img_slide .carousel-control-prev:hover {
    color: #c13c3d;
    background: transparent;
  }

Here is a Corousel widget that is an extension of yii\bootstrap5\Carousel, to show image thumbnails as indicators for the carousel.

Here is the widget code.

<?php
namespace app\widgets;
use Yii;
use yii\bootstrap5\Html;

class Carousel extends \yii\bootstrap5\Carousel
{
    public $thumbnails = [];

    public function init()
    {
        parent::init();     
        Html::addCssClass($this->options, ['data-bs-ride' => 'carousel']);
        if ($this->crossfade) {
            Html::addCssClass($this->options, ['animation' => 'carousel-fade']);
        }
    }

    public function renderIndicators(): string
    {
        if ($this->showIndicators === false){
            return '';
        }
        $indicators = [];
        for ($i = 0, $count = count($this->items); $i < $count; $i++){
            $options = [
                'data' => [
                    'bs-target' => '#' . $this->options['id'],
                    'bs-slide-to' => $i
                ],
                'type' => 'button',
                'thumb' => $this->thumbnails[$i]['thumb']
            ];
            if ($i === 0){
                Html::addCssClass($options, ['activate' => 'active']);
                $options['aria']['current'] = 'true';
            }       

             $indicators[] = Html::tag('li',Html::img($options['thumb']), $options);
        }
        return Html::tag('ol', implode("\n", $indicators), ['class' => ['carousel-indicators']]);
    } }

You can use the above widget in your view file as below:

    <?php  
$indicators = [
   '0' =>[ 'thumb' => "https://placehold.co/150X150?text=A"],
   '1' => ['thumb' => 'https://placehold.co/150X150?text=B'],
   '2' => [ 'thumb' => 'https://placehold.co/150X150?text=C']
];
$items = [
    [ 'content' =>Html::img('https://live.staticflickr.com/8333/8417172316_c44629715e_w.jpg')],
    [ 'content' =>Html::img('https://live.staticflickr.com/3812/9428789546_3a6ba98c49_w.jpg')],
    [ 'content' =>Html::img('https://live.staticflickr.com/8514/8468174902_a8b505a063_w.jpg')]   
];

echo Carousel::widget([
    'items' => 
        $items,
     'thumbnails'  => $indicators,
     'options' => [       
          'data-interval' => 3, 'data-bs-ride' => 'scroll','class' => 'carousel product_img_slide',
      ],

]);

How To Add Internationalisation to the NavBar Menu in Yii2 ¶

1. Create the required Files
2. Edit the /config/web.php file
3. Edit all the files in the "views" folder and any sub folders
4. Create the texts to be translated
5. Create a Menu Item (Dropdown) to Change the Language
6. Optional Items

Yii comes with internationalisation (i18n) "out of the box". There are instructions in the manual as to how to configure Yii to use i18n, but little information all in one place on how to fully integrate it into the bootstrap menu. This document attempts to remedy that.

The Github repository also contains the language flags, some country flags, a list of languages codes and their language names and a list of the languages Yii recognises "out of the box". A video will be posted on YouTube soon.

Ensure that your system is set up to use i18n. From the Yii2 Manual:

Yii uses the PHP intl extension to provide most of its I18N features, such as the date and number formatting of the yii\i18n\Formatter class and the message formatting using yii\i18n\MessageFormatter. Both classes provide a fallback mechanism when the intl extension is not installed. However, the fallback implementation only works well for English target language. So it is highly recommended that you install intl when I18N is needed.

Create the required Files ¶

First you need to create a configuration file.

Decide where to store it (e.g. in the ./messages/ directory with the name create_i18n.php). Create the directory in the project then issue the following command from Terminal (Windows: CMD) from the root directory of your project:

./yii message/config-template ./messages/create_i18n.php

or for more granularity:

./yii message/config --languages=en-US --sourcePath=@app --messagePath=messages ./messages/create_i18n.php

In the newly created file, alter (or create) the array of languages to be translated:

  // array, required, list of language codes that the extracted messages
  // should be translated to. For example, ['zh-CN', 'de'].
  'languages' => [
    'en-US',
    'fr',
    'pt'
  ],

If necessary, change the root directory in create_i18n.php to point to the messages directory - the default is messages. Note, if the above file is in the messages directory (recommended) then don't alter this 'messagePath' => __DIR__,. If you alter the directory for messages to, say, /config/ (not a good idea) you can use the following:

  // Root directory containing message translations.
  'messagePath' => __DIR__ . DIRECTORY_SEPARATOR . 'config',

The created file should look something like this after editing the languages you need:

<?php

return [
  // string, required, root directory of all source files
  'sourcePath' => __DIR__ . DIRECTORY_SEPARATOR . '..',
  // array, required, list of language codes (in alphabetical order) that the extracted messages
  // should be translated to. For example, ['zh-CN', 'de'].
  'languages' => [
    // to localise a particular language use the language code followed by the dialect in CAPS
    'en-US',  // USA English
    'es',
    'fr',
    'it',
    'pt',
  ],
  /* 'languages' => [
    'af', 'ar', 'az', 'be', 'bg', 'bs', 'ca', 'cs', 'da', 'de', 'el', 'es', 'et', 'fa', 'fi', 'fr', 'he', 'hi',
    'pt-BR', 'ro', 'hr', 'hu', 'hy', 'id', 'it', 'ja', 'ka', 'kk', 'ko', 'kz', 'lt', 'lv', 'ms', 'nb-NO', 'nl',
    'pl', 'pt', 'ru', 'sk', 'sl', 'sr', 'sr-Latn', 'sv', 'tg', 'th', 'tr', 'uk', 'uz', 'uz-Cy', 'vi', 'zh-CN',
    'zh-TW'
    ], */
  // string, the name of the function for translating messages.
  // Defaults to 'Yii::t'. This is used as a mark to find the messages to be
  // translated. You may use a string for single function name or an array for
  // multiple function names.
  'translator' => ['\Yii::t', 'Yii::t'],
  // boolean, whether to sort messages by keys when merging new messages
  // with the existing ones. Defaults to false, which means the new (untranslated)
  // messages will be separated from the old (translated) ones.
  'sort' => false,
  // boolean, whether to remove messages that no longer appear in the source code.
  // Defaults to false, which means these messages will NOT be removed.
  'removeUnused' => false,
  // boolean, whether to mark messages that no longer appear in the source code.
  // Defaults to true, which means each of these messages will be enclosed with a pair of '@@' marks.
  'markUnused' => true,
  // array, list of patterns that specify which files (not directories) should be processed.
  // If empty or not set, all files will be processed.
  // See helpers/FileHelper::findFiles() for pattern matching rules.
  // If a file/directory matches both a pattern in "only" and "except", it will NOT be processed.
  'only' => ['*.php'],
  // array, list of patterns that specify which files/directories should NOT be processed.
  // If empty or not set, all files/directories will be processed.
  // See helpers/FileHelper::findFiles() for pattern matching rules.
  // If a file/directory matches both a pattern in "only" and "except", it will NOT be processed.
  'except' => [
    '.*',
    '/.*',
    '/messages',
    '/migrations',
    '/tests',
    '/runtime',
    '/vendor',
    '/BaseYii.php',
  ],
  // 'php' output format is for saving messages to php files.
  'format' => 'php',
  // Root directory containing message translations.
  'messagePath' => __DIR__,
  // boolean, whether the message file should be overwritten with the merged messages
  'overwrite' => true,
  /*
    // File header used in generated messages files
    'phpFileHeader' => '',
    // PHPDoc used for array of messages with generated messages files
    'phpDocBlock' => null,
   */

  /*
    // Message categories to ignore
    'ignoreCategories' => [
    'yii',
    ],
   */

  /*
    // 'db' output format is for saving messages to database.
    'format' => 'db',
    // Connection component to use. Optional.
    'db' => 'db',
    // Custom source message table. Optional.
    // 'sourceMessageTable' => '{{%source_message}}',
    // Custom name for translation message table. Optional.
    // 'messageTable' => '{{%message}}',
   */

  /*
    // 'po' output format is for saving messages to gettext po files.
    'format' => 'po',
    // Root directory containing message translations.
    'messagePath' => __DIR__ . DIRECTORY_SEPARATOR . 'messages',
    // Name of the file that will be used for translations.
    'catalog' => 'messages',
    // boolean, whether the message file should be overwritten with the merged messages
    'overwrite' => true,
   */
];

Edit the /config/web.php file ¶

In the web.php file, below 'id' => 'basic', add:

  'language' => 'en',
  'sourceLanguage' => 'en',

Note: you should always use the 'sourceLanguage' => 'en' as it is, usually, easier and cheaper to translate from English into another language. If the sourceLanguage is not set it defaults to 'en'.

Add the following to the 'components' => [...] section:

    'i18n' => [
      'translations' => [
        'app*' => [
          'class' => 'yii\i18n\PhpMessageSource',  // Using text files (usually faster) for the translations
          //'basePath' => '@app/messages',  // Uncomment and change this if your folder is not called 'messages'
          'sourceLanguage' => 'en',
          'fileMap' => [
            'app' => 'app.php',
            'app/error' => 'error.php',
          ],
          //  Comment out in production version
          //  'on missingTranslation' => ['app\components\TranslationEventHandler', 'handleMissingTranslation'],
        ],
      ],
    ],

Edit all the files in the "views" folder and any sub folders ¶

Now tell Yii which text you want to translate in your view files. This is done by adding Yii::t('app', 'text to be translated') to the code.

For example, in /views/layouts/main.php, change the menu labels like so:

    'items' => [
          //  ['label' => 'Home', 'url' => ['/site/index']],	// Orignal code
          ['label' => Yii::t('app', 'Home'), 'url' => ['/site/index']],
          ['label' => Yii::t('app', 'About'), 'url' => ['/site/about']],
          ['label' => Yii::t('app', 'Contact'), 'url' => ['/site/contact']],
          Yii::$app->user->isGuest ? ['label' => Yii::t('app', 'Login'), 'url' => ['/site/login']] : '<li class="nav-item">'
            . Html::beginForm(['/site/logout'])
            . Html::submitButton(
             // 'Logout (' . Yii::$app->user->identity->username . ')', // change this line as well to the following:
              Yii::t('app', 'Logout ({username})'), ['username' => Yii::$app->user->identity->username]),
              ['class' => 'nav-link btn btn-link logout']
            )
            . Html::endForm()
            . '</li>',
        ],

Create the texts to be translated ¶

To create the translation files, run the following, in Terminal, from the root directory of your project:

./yii message ./messages/create_i18n.php

Now, get the messages translated. For example in the French /messages/fr/app.php

  'Home' => 'Accueil',
  'About' => 'À propos',
  ...

Create a Menu Item (Dropdown) to Change the Language ¶

This takes a number of steps.

1. Create an array of languages required ¶

A key and a name is required for each language.

The key is the ICU language code ISO 639.1 in lowercase (with optional Country code ISO 3166 in uppercase) e.g.

French: fr or French Canada: fr-CA

Portuguese: pt or Portuguese Brazil: pt-BR

The name is the name of the language in that language. e.g. for French: 'Français', for Japanese: '日本の'. This is important as the user may not understand the browser's current language.

In /config/params.php create an array named languages with the languages required. For example:

  /* 		List of languages and their codes
   *
   * 		format:
   * 		'Language Code' => 'Language Name',
   * 		e.g.
   * 		'fr' => 'Français',
   *
   * 		please use alphabetical order of language code
   * 		Use the language name in the "user's" Language
   *            e.g.
   *            'ja' => '日本の',
   */
  'languages' => [
//    'da' => 'Danske',
//    'de' => 'Deutsche',
//    'en' => 'English', // NOT REQUIRED the sourceLanguage (i.e. the default)
    'en-GB' => 'British English',
    'en-US' => 'American English',
    'es' => 'Español',
    'fr' => 'Français',
    'it' => 'Italiano',
//    'ja' => '日本の',  // Japanese with the word "Japanese" in Kanji
//    'nl' => 'Nederlandse',
//    'no' => 'Norsk',
//    'pl' => 'Polski',
    'pt' => 'Português',
//    'ru' => 'Русский',
//    'sw' => 'Svensk',
//    'zh' => '中国的',
  ],

2. Create an Action ¶

In /controllers/SiteController.php, the default controller, add an "Action" named actionLanguage(). This "Action" changes the language and sets a cookie so the browser "remembers" the language for page requests and return visits to the site.

  /**
   * Called by the ajax handler to change the language and
   * Sets a cookie based on the language selected
   *
   */
  public function actionLanguage()
  {
    $lang = Yii::$app->request->post('lang');
    // If the language "key" is not NULL and exists in the languages array in params.php, change the language and set the cookie
    if ($lang !== NULL && array_key_exists($lang, Yii::$app->params['languages']))
    {
      $expire = time() + (60 * 60 * 24 * 365); //  1 year - alter accordingly
      Yii::$app->language = $lang;
      $cookie = new yii\web\Cookie([
        'name' => 'lang',
        'value' => $lang,
        'expire' => $expire,
      ]);
      Yii::$app->getResponse()->getCookies()->add($cookie);
    }
    Yii::$app->end();
  }

Remember to set the method to POST. In behaviors(), under actions, set 'language' => ['post'], like so:

      'verbs' => [
        'class' => VerbFilter::class,
        'actions' => [
          'logout' => ['post'],
          'language' => ['post'],
        ],
      ],

3. Create a Language Handler ¶

Make sure that the correct language is served for each request.

In the /components/ directory, create a file named: LanguageHandler.php and add the following code to it:

<?php

/*
 * Copyright ©2023 JQL all rights reserved.
 * http://www.jql.co.uk
 */
/*
  Created on : 19-Nov-2023, 13:23:54
  Author     : John Lavelle
  Title      : LanguageHandler
 */

namespace app\components;

use yii\helpers\Html;

class LanguageHandler extends \yii\base\Behavior
{

	public function events()
	{
		return [\yii\web\Application::EVENT_BEFORE_REQUEST => 'handleBeginRequest'];
	}

	public function handleBeginRequest($event)
	{
		if (\Yii::$app->getRequest()->getCookies()->has('lang') && array_key_exists(\Yii::$app->getRequest()->getCookies()->getValue('lang'), \Yii::$app->params['languages']))
		{
      //  Get the language from the cookie if set
			\Yii::$app->language = \Yii::$app->getRequest()->getCookies()->getValue('lang');
		}
		else
		{
			//	Use the browser language - note: some systems use an underscore, if used, change it to a hyphen
			\Yii::$app->language = str_replace('_', '-', HTML::encode(locale_accept_from_http($_SERVER['HTTP_ACCEPT_LANGUAGE'])));
		}
	}

}

/* End of file LanguageHandler.php */
/* Location: ./components/LanguageHandler.php */