Guidelines For Extension Authoring

[color="#006400"]/* continued from this topic: http://www.yiiframew…review-version/ */[/color]

@Qiang: I urge you to create guidelines for extensions, before too many Yii2 extensions are getting released.

I really appreciate the work of the developers, but it’s also a crucial point to have a common base for extensions.

@schmunk: We have https://github.com/yiisoft/yii2/wiki/Core-framework-code-style. This is enough for the people who make the extensions for preview version. I do not think people who need guideline will release extensions for preview version of framework. So guideline can well wait until alpha.

Yes, you’re right. I know that we’re “only” at Public Preview and that this feature is under development.

For me the extension concept is just the most important core feature of Yii.

And the way extensions are developed and included in an app influences their usage and maintenance a lot.

I’ll stay patient :)

schmunk, started a wiki article:

https://github.com/yiisoft/yii2/wiki/Extension-development

Any suggestions?

Extensions must use migrations, if it requires additions/mods to the db.

No home grown sql scripts or installers, please. :)

Added.

I am not sure if this fits here - and I admit that I haven’t checked out how migrations work in Yii2, but I write like this in the migration script for a module I am working on:


class m130226_185845_initial_tables extends CDbMigration

{

	public function up()

	{


    	if(! isset(Yii::app()->getDb()->tablePrefix)) { Yii::app()->getDb()->tablePrefix = ''; };


    	$this->createTable('{{wikipage}}', array(

        	'id' => 'pk',



If a table prefix is not set, I set the prefix to an empty string, and then carry on using {{tablename}} so that my module will respect the tableprefix if it has been set.

That should probably be added as well?

@samdark: You can review my additions here: https://github.com/schmunk42/yii2/wiki/_compare/0d4d1690be9999644e6fd47d7f4ebc820eafa513...ec4d618bbd1dfc46141ab85b2964ee0a99553f5f

See also this page for a nice sample workflow for github wikis.

Just add my wiki fork as a remote: https://github.com/schmunk42/yii2.wiki.git and merge.

Note: There are many points which need more clarification. You may also not agree with everything ;) but I thought it’s better to add everything I have in mind now,

Maybe we should also open a separate topic for the upcoming discussion, but I’ll leave this up to you.

Done. I split the topic in two, if you don’t mind. ;)

jacmoe

What about jquery plugins? What if extension provides such a framework?

  1. Why "src" dir? Does that mean that extension should be under vendor/libName/src namespace?

I assume that you are asking Schmunk, not me Samdark. :)

However, I think he means that the extension must not ship with other Yii extensions (like Yiistrap, etc.)

Not sure what he means by CSS frameworks…

Would be prudent to include the framework if you are doing an extension like Yiistrap or Foundation for Yii.

In some worlds, those would be handled by a composer script, of course, but - like YiiBootstrap - the extensions could be modified to suit the extension / ease the integration.

And, no matter how hard Schmunk tries, not everyone is fond of using composer. ;p

That needs to be clarified.

Of course, if the extension ships with Yii framework and other readily available Yii extensions, that is wrong.

Having looked at Schmunk’s additions, I think it’s safe to say that I never will release an official Yii2 extension, ever. ;)

((just kidding))

I think that extensions for Yii should use English, in code and in docs.

If they are in Chinese, Russian, etc. they should be clearly marked as such.

I hope there is a language filter for Yii extension repository?

I also think that they must be hosted on a public repository so that the extension registry can point to it.

That would prevent stale downloads, etc.

[edit]

Most of the additions are sane, but many can only be recommendations IMO.

Partially agree. Namespace creocoder\yii\behaviors\nestedSet fits this rule?

I think rule should be more flexible. Like vendorName\...\extensionName.

Thanks, for your feedback, my additions are not carved in stone :)

Sure, there’s a difference - sorry about the CSS Framework, this has to be clarified. And with jQuery you’re also hitting the point!

What I mean is that an extension must not include a complete CSS framework if it’s just a eg. plugin like chosen, select2 or editable. And also not jQuery for sure. The exception is the CSS Framework extension oder JavaScript lib extension itself.

But jQuery is part of the core and therefore treated in another way than bootstrap. Bootstrap may become part of the core, but what’s about Zurb Foundation, mootools, etc. then? @jacmoe: Right ;)

That said, I sometime stumbled upon incompatibilities with jQuery versions in Yii 1.x. With scriptMap you can overcome this problem, but wouldn’t it be nicer just to define the version of “yii2-jquery” you want to have or just download it and place it into your app? You could also remove “yii2-bootstrap” and include “yii2-zurb-foundation” - without composer, may do this by hand, but the code has to be structured in a certain way.

And on the other hand, that an extension must not include existing (PHP, Yii) extension code, take YiiBooster and yii-boostrap for example.

In the first releases YiiBooster included a slightly modified version of yii-bootstrap, which would have lead to incompatibility issues. That must not happen.

I am inspired by the Unix philosophy Rule of Composition and Rule of Separation.

If such a thing happens, we should use the composer.json file to define either a require(ment) or conflict(s).

Please, you don’t need to actually use(!) composer. This file would just contain a very basic set of meta information in JSON format, which would make it also very easy to create a custom Yii2 package repository. I would make this a requirement , not just for the sake of composer, more because it would take a ton of load off the core-devs maintaining the extension platform.

Don’t has to be src/, but as far as I understand the PSR-0 Examples you have to have kind of an entry point for autoloading your classes via a namespaces. Note: I am not experienced with namespaces, so I may overlook something here.

But to give you also an example here, this one line enables me to use any class from packages, which support autoloading via namespaces, without adding an alias or import - even in Yii 1.x.

How will we "install" an extension in Yii2?

100% correct :D

I also totally agree here. btw: I tried to use the word SHOULD instead of MUST on the “debatable” points ;D .

And for sure we should provide something like a downloadable extension template to start with.

Ah, that would be a very nice yiic command or gii module!

Sure sorry, like in PSR-0: \<Vendor Name>\(<Namespace>\)*<Class Name>

@samdark: Please let me know if there are points which keep you from merging.

Lack of time to review it properly.

Ok, thanks for your feedback.

Looking forward to discuss this again…