dlds/yii2-giixer

Extended Yii2 Gii module with common handlers

4.0.47 2017-12-08 13:08 UTC

Requires

• dlds/yii2-metronic: ~2.0.0
• dlds/yii2-rels: ~0.8.0
• kartik-v/yii2-dynagrid: ~1.4.0
• yiisoft/yii2-gii: ~2.0.0
• yiisoft/yii2-imagine: ~2.0.0

Requires (Dev)

• codeception/specify: *
• codeception/verify: *
• yiisoft/yii2-codeception: *
• yiisoft/yii2-debug: *
• yiisoft/yii2-faker: *

BSD-3-Clause

• Jiri Svoboda

• yii2
• extended
• gii

README

Extended gii module for Yii2 including a bunch of useful handler, helpers, traits and other components. This module generates required models, controllers and other classes with dependency on own components. Default yii-gii generator is not available when your are usint yii2-giiixer module.

Installation

The preferred way to install this extension is through composer.

Either run

$ composer require dlds/yii2-giixer

or add

"dlds/yii2-giixer": "~3.0.0"

to the require section of your composer.json file.

Migration

There is not any migration required to run. Module itself does not store any data in DB.

Structure

Giixer defines its own easy to maintain and extendable application structure which is sligtly different from default (gii generated) structure. Below you can find what all and how giixer generates.

ActiveRecords

Giixer uses its own ActiveRecords (AR) strucutre. Below are all 4 ARs with descriptions about what they stand for. Each is placed on notional level as in application.

1. Base AR
   • Top level and not editable AR
   • Maintained only by giixer itself.
   • Always extends GxActiveRecord
   • Manual changes are lost after next giixer generation
   • File is placed in common\models\db\base or common\modules\modulename\models\db\base
2. Common AR
   • Extends Base AR
   • Editable and maintained by developer
   • Manual changes are not lost after any giixer generation
   • File is placed in common\models\db or common\modules\modulename\models\db
   • Only this model can be directly used by application

Structure schema is shown in this diagram

This AR model structure gives you opportunity to easily update your DB schema and still be able to regenerate your AR model without loosing your current code changes.

Some additional features stored in Base AR is shown in MyModel

ActiveQueries

Each AR model is generated with its custom ActiveQuery class which is assigned to Base AR.

Giixer creates following 3 ActiveQuery (AQ) classes during ARs generation.

1. Common AQ
   • Extends \yii\db\ActiveQuery
   • Editable and maintained by developer
   • File is placed in common\models\db\base or common\modules\modulename\models\db\base
   • Always loaded in Base AR (Only this can be directly used by application)

Base AR will automatically loads appropriate AQ.

Structure schema is shown in this diagram

Giixer generates default AQ logic to be able to easily use appropriate AR model class in custom queries.

Default AQ logic is show in MyModelQuery

Helpers

Giixer defines bunch of useful helpers. Below you can see which helpers giixer offers.

URL Helpers

Own url route and rule helpers are generated for each AR model.

Giixer creates following 2 helpers (HLP) for both backend and frontend application.

1. Route HLP
   • Extends \dlds\giixer\components\helpers\GxRouteHelper or your custom class set in helperRouteBaseClass (see Configuration section)
   • Contains all default routes generated by giixer
   • Directly used by application
   • Frontend file is placed in frontend\components\helpers\url\routes or frontend\modules\modulename\components\helpers\url\routes
   • Backend file is placed in backend\components\helpers\url\routes or backend\modules\modulename\components\helpers\url\routes
2. Rule HLP
   • Extends \dlds\giixer\components\helpers\GxUrlRuleHelper or your custom class set in helperRuleBaseClass (see Configuration section)
   • Contains rules for all giixer generated routes
   • Usually used in url rules configuration
   • Frontend file is placed in frontend\components\helpers\url\rules or frontend\modules\modulename\components\helpers\url\rules
   • Backend file is placed in backend\components\helpers\url\rules or backend\modules\modulename\components\helpers\url\rules

Main idea of both helpers is to encapsulate rules/routes in single class and provide developer with easy interface for using it.

Basic route and rule helpers examples: MyBasicRouteHelper, MyBasicUrlRuleHelper

To be able to have translatable url slug defined in translation files (i18n) you have to load your rules in application bootstrap like bellow. Otherwise translation will not work. See Yii2 Adding Rules Dynamically

class AppBootstrapHandler implements \yii\base\BootstrapInterface {

    public function bootstrap($app)
    {
        return $this->addMainRules($app);
    }

    /**
     * Adds main application rules
     */
    protected function addMainRules(\yii\web\Application $app)
    {
        $rules = require(\Yii::getAlias('@frontend/config/url/rules.php'));

        return $app->getUrlManager()->addRules($rules, false);
    }
}

Where @frontend/config/url/rules.php should look like below.

$rules = [
    // ...
    MyBasicUrlRuleHelper::index(),
    MyBasicUrlRuleHelper::view(),
    // ...
];

return array_merge(
    $rules, require(__DIR__.'/rules-local.php')
);
?>

Than in application config you just set your AppBootstrapHandler to be processed.

// ...
'bootstrap' => [
    '\frontend\components\handlers\AppBootstrapHandler',
    // ...
]    
// ...

TIP: Usually you want to have better looking urls without model primary key shown in it. For instance you have own CMS system where each of your Post model has its own slug looks like my-custom-post-title and you want to have final url be like http://www.mydomain.com/my-custom-post-title/. For this case you have to update your UrlRuleHelper class according to MyAdvancedRuleHelper

Model Helper

This helper defines methods used in GxActiveRecord class. There are methods for adapting query params to pass mass assignemnt, methods to easily change validation rules or scenario definitions.

For more information see GxModelHelper

Other Helpers

Giixer defines a few another helper class which is more or less complex and useful in basic manipulation with application. Each helper has it own well-documented class.

For more information see Giixer Helpers

Handlers

Giixer defines two main handler class useful for controllers to keep its methods lean and well-arranged.

1. GxCrudHandler
   • Defines its own approach of Create, Read, Update, Delete methods
   • Invokes GxCrudEvent during each action which holds all data about action result
   • Usually used for manipulationg standart AR model classes and their appropriate DB entries
2. GxHandler
   • Defines its own approach to validate model and based on validation result processes appropriate callback
   • Usually used for non AR models manipulation when save() means creating multiple ARs etc...

For more information see Giixer Handlers

Configuration

Enable gii module in your config file by adding it to app bootstrap.

$config['bootstrap'][] = 'gii';

Replace default gii module class with giixer one.

$config['modules']['gii'] = [
    'class' => 'dlds\giixer\Module',
];

You can also modify giixer module behavior to your requirements by setting additional config options. See bellow.

namespaces option

Defines namespaces map to generated classes. This is useful if the namespace for some class does not match the default one. For instance if your application is divided into modules and you need to generate classes for these modules.

[
    '^{Modules}[a-zA-Z]+Form$' => '{module}\models\\forms',
    '^Core[a-zA-Z]+Form$' => 'models\\forms',
    '^{modules}-[a-z-]+$' => '{module}\\views',
]

In example above we can see our application contains modules and also some direct laying "Core" files.

You can see that we defined also rule for views to be able to place generated view files to appropriate folder.

There are some special tags you can use when you specifying your rules.

Special tags

• {Module} - will be replaced with current module name
• {Modules} - will be replaced with all modules names regex
• {module} - will be replaced with current module id
• {modules} - will be replaced with all modules ids regex

To be able to use these special tags you have to specify your modules names and ids.

[
    'edu' => 'Edu',
    'shop' => 'Shop',
    // ...
]

Array index is used for modules IDs. Array values for modules Names.

During generation Giixer will automatically replace these tags so final rules look like bellow (we are generating some Edu model).

[
    '^(Edu|Shop){1}[a-zA-Z]+Form$' => 'modules\edu\models\\forms',
    '^Core[a-zA-Z]+Form$' => 'models\\forms',
    '^(edu|shop){1}-[a-z-]+$' => 'modules\edu\\views',
]

bases option

Defines base classes for specific components, controllers and other application classes. It is based on regex of descendant class and fully qualified name of base class.

[
	BaseHelper::RK_CONTROLLER_BE => [
		'{Modules}[a-zA-Z]+Controller$' => '{module}\\controllers\\base\\{Module}BaseController',
		'Core[a-zA-Z]+Controller$' => 'controllers\\base\\CoreBaseController',
	],
	BaseHelper::RK_CONTROLLER_FE => [
		'{Modules}[a-zA-Z]+Controller$' => '{module}\\controllers\\base\\{Module}BaseController',
		'Core[a-zA-Z]+Controller$' => 'controllers\\base\\CoreBaseController',
    ],
    // ...
]	

Above you can see configuration for modules controllers which have custom base classes.

If custom controller (frontend or backend) base class is specified it must extends GxController. Otherwise the GxController will be used directly as parent class. (GxController extends default \yii\web\Controller).

If custom route helper base class is set it must extends GxRouteHelper. Otherwise the GxRouteHelper will be used directly as parent class.

If custom route helper base class is set it must extends GxUrlRuleHelper. Otherwise the GxUrlRuleHelper will be used directly as parent class.

translations option

Defines which translations files should be automatically generated. This option is defined by array containing languages codes.

['en', 'de', 'cs']

For above the english, german and czech translations files will be generated.

messages option

Defines custom translations categories.

[
	'dynagrid' => [
 		'^{Modules}[a-zA-Z]+$' => '{module}/dynagrid',
    ],
],

For above generator use category 'edu/dynagrid' instead of 'dynagrid' everywhere in class which match regex '^Edu[a-zA-Z]+$'.

For more information see Giixer Module main class

Copyright 2016 © Digital Deals s.r.o.