Application Structure
3.12. EXTENSIONS 137 Recommended Practices
Because extensions are meant to be used by other people, you often need to make an extra eort during development. Below we introduce some common and recommended practices in creating high quality extensions.
Namespaces To avoid name collisions and make the classes in your ex-tension autoloadable, you should use namespaces and name the classes in your extension by following the PSR-4 standard52 or PSR-0 standard53.
Your class namespaces should start withvendorName\extensionName, where
extensionNameis similar to the project name in the package name except that it should not contain the yii2- pre x. For example, for the yiisoft/yii2-imagine extension, we useyii\imagineas the namespace for its classes.
Do not use yii, yii2 or yiisoft as your vendor name. These names are reserved for use by the Yii core code.
Bootstrapping Classes Sometimes, you may want your extension to execute some code during the bootstrapping process stage of an applica-tion. For example, your extension may want to respond to the application's
beginRequest event to adjust some environment settings. While you can in-struct users of the extension to explicitly attach your event handler in the extension to thebeginRequestevent, a better way is to do this automatically.
To achieve this goal, you can create a so-called bootstrapping class by implementing yii\base\BootstrapInterface. For example,
namespace myname\mywidget;
use yii\base\BootstrapInterface;
use yii\base\Application;
class MyBootstrapClass implements BootstrapInterface { public function bootstrap($app)
{
$app->on(Application::EVENT_BEFORE_REQUEST, function () { // do something here
} });
}
You then list this class in thecomposer.json le of your extension like follows,
{ // ...
"extra": {
"bootstrap": "myname\\mywidget\\MyBootstrapClass"
52http://www.php-fig.org/psr/psr-4/
53http://www.php-fig.org/psr/psr-0/
138 CHAPTER 3. APPLICATION STRUCTURE
} }
When the extension is installed in an application, Yii will automatically instantiate the bootstrapping class and call its bootstrap() method during the bootstrapping process for every request.
Working with Databases Your extension may need to access databases.
Do not assume that the applications that use your extension will always use
Yii::$db as the DB connection. Instead, you should declare a db property for the classes that require DB access. The property will allow users of your extension to customize which DB connection they would like your extension to use. As an example, you may refer to the yii\caching\DbCache class and see how it declares and uses thedb property.
If your extension needs to create speci c DB tables or make changes to DB schema, you should
• provide migrations to manipulate DB schema, rather than using plain SQL les;
• try to make the migrations applicable to dierent DBMS;
• avoid using Active Record in the migrations.
Using Assets If your extension is a widget or a module, chances are that it may require some assets to work. For example, a module may display some pages which contain images, JavaScript, and CSS. Because the les of an extension are all under the same directory which is not Web accessible when installed in an application, you have two choices to make the asset les directly accessible via Web:
• ask users of the extension to manually copy the asset les to a speci c Web-accessible folder;
• declare an asset bundle and rely on the asset publishing mechanism to automatically copy the les listed in the asset bundle to a Web-accessible folder.
We recommend you use the second approach so that your extension can be more easily used by other people. Please refer to the Assets section for more details about how to work with assets in general.
Internationalization and Localization Your extension may be used by applications supporting dierent languages! Therefore, if your extension displays content to end users, you should try to internationalize and localize it. In particular,
• If the extension displays messages intended for end users, the messages should be wrapped intoYii::t() so that they can be translated. Mes-sages meant for developers (such as internal exception mesMes-sages) do not need to be translated.
3.12. EXTENSIONS 139
• If the extension displays numbers, dates, etc., they should be formatted using yii\i18n\Formatter with appropriate formatting rules.
For more details, please refer to the Internationalization section.
Testing You want your extension to run awlessly without bringing prob-lems to other people. To reach this goal, you should test your extension before releasing it to public.
It is recommended that you create various test cases to cover your exten-sion code rather than relying on manual tests. Each time before you release a new version of your extension, you may simply run these test cases to make sure everything is in good shape. Yii provides testing support, which can help you to more easily write unit tests, acceptance tests and functionality tests. For more details, please refer to the Testing section.
Versioning You should give each release of your extension a version num-ber (e.g. 1.0.1). We recommend you follow the semantic versioning54 prac-tice when determining what version numbers should be used.
Releasing To let other people know about your extension, you need to release it to the public.
If it is the rst time you are releasing an extension, you should register it on a Composer repository, such as Packagist55. After that, all you need to do is simply create a release tag (e.g. v1.0.1) on the VCS repository of your extension and notify the Composer repository about the new release.
People will then be able to nd the new release, and install or update the extension through the Composer repository.
In the releases of your extension, in addition to code les, you should also consider including the following to help other people learn about and use your extension:
• A readme le in the package root directory: it describes what your extension does and how to install and use it. We recommend you write it in Markdown56format and name the le as readme.md.
• A changelog le in the package root directory: it lists what changes are made in each release. The le may be written in Markdown format and named aschangelog.md.
• An upgrade le in the package root directory: it gives the instructions on how to upgrade from older releases of the extension. The le may be written in Markdown format and named as upgrade.md.
• Tutorials, demos, screenshots, etc.: these are needed if your extension provides many features that cannot be fully covered in the readme le.
54http://semver.org
55https://packagist.org/
56http://daringfireball.net/projects/markdown/
140 CHAPTER 3. APPLICATION STRUCTURE
• API documentation: your code should be well documented to allow other people to more easily read and understand it. You may refer to the Object class le57 to learn how to document your code.
Info: Your code comments can be written in Markdown format.
Theyiisoft/yii2-apidocextension provides a tool for you to gen-erate pretty API documentation based on your code comments.
Info: While not a requirement, we suggest your extension adhere to certain coding styles. You may refer to the core framework code style58.
3.12.3 Core Extensions
Yii provides the following core extensions that are developed and maintained by the Yii developer team. They are all registered on Packagist59 and can be easily installed as described in the Using Extensions subsection.
• yiisoft/yii2-apidoc60: provides an extensible and high-performance API documentation generator. It is also used to generate the core frame-work API documentation.
• yiisoft/yii2-authclient61: provides a set of commonly used auth clients, such as Facebook OAuth2 client, GitHub OAuth2 client.
• yiisoft/yii2-bootstrap62: provides a set of widgets that encapsulate the Bootstrap63 components and plugins.
• yiisoft/yii2-codeception64: provides testing support based on Codecep-tion65.
• yiisoft/yii2-debug66: provides debugging support for Yii applications.
When this extension is used, a debugger toolbar will appear at the bottom of every page. The extension also provides a set of standalone pages to display more detailed debug information.
• yiisoft/yii2-elasticsearch67: provides the support for using Elasticsearch68. It includes basic querying/search support and also implements the Ac-tive Record pattern that allows you to store acAc-tive records in Elastic-search.
3.12. EXTENSIONS 141
• yiisoft/yii2-faker69: provides the support for using Faker70 to generate fake data for you.
• yiisoft/yii2-gii71: provides a Web-based code generator that is highly extensible and can be used to quickly generate models, forms, modules, CRUD, etc.
• yiisoft/yii2-imagine72: provides commonly used image manipulation functions based on Imagine73.
• yiisoft/yii2-jui74: provides a set of widgets that encapsulate the JQuery UI75 interactions and widgets.
• yiisoft/yii2-mongodb76: provides the support for using MongoDB77. It includes features such as basic query, Active Record, migrations, caching, code generation, etc.
• yiisoft/yii2-redis78: provides the support for using redis79. It includes features such as basic query, Active Record, caching, etc.
• yiisoft/yii2-smarty80: provides a template engine based on Smarty81.
• yiisoft/yii2-sphinx82: provides the support for using Sphinx83. It in-cludes features such as basic query, Active Record, code generation, etc.
• yiisoft/yii2-swiftmailer84: provides email sending features based on swiftmailer85.
• yiisoft/yii2-twig86: provides a template engine based on Twig87.
69https://github.com/yiisoft/yii2-faker
70https://github.com/fzaninotto/Faker
71https://github.com/yiisoft/yii2-gii
72https://github.com/yiisoft/yii2-imagine
73http://imagine.readthedocs.org/
74https://github.com/yiisoft/yii2-jui
75http://jqueryui.com/
76https://github.com/yiisoft/yii2-mongodb
77http://www.mongodb.org/
78https://github.com/yiisoft/yii2-redis
79http://redis.io/
80https://github.com/yiisoft/yii2-smarty
81http://www.smarty.net/
82https://github.com/yiisoft/yii2-sphinx
83http://sphinxsearch.com
84https://github.com/yiisoft/yii2-swiftmailer
85http://swiftmailer.org/
86https://github.com/yiisoft/yii2-twig
87http://twig.sensiolabs.org/
142 CHAPTER 3. APPLICATION STRUCTURE