Guideline

Is there a simple howto/guideline on how to write a Yii extension?

Not yet, but if you would share with us what exactly you want to do, we probably can given you the right directions which in turn could be extended to be a guide ^^

Greetings from Hamburg / Germany

  • rojaro -

Well… I've to do a Google Map wrapper, I just need to know how extensions should be structured/organized.

We don't have specific guideline for extension yet, as we are still working on it.

The following points are valid, though:

  1. All extensions should be placed under AppBasePath/extensions (the default is protected/extensions). You cannot customize this path.

  2. Each extension should be a subdirectory of AppBasePath/extensions, and the directory name is the extension name. Therefore, classes in a specific extension can be referenced using path alias as: application.extensions.ExtensionName.ClassName

  3. We will have an extension repository system ready before the 1.0 formal release (which should be by the end of year).

  4. A yiic command will be provided to simplify downloading and installing of extensions from the extension repository. Of course, you can also manually do these.

Things that are not decided include:

  1. How to package an extension? Should we go with the PEAR package way or a simpler way?

  2. Should we support dependency check for extensions?

  3. How to write a meta file that contains meta information about an extension package?

Your opinions are welcome!

Thank you for your reply.

Quote

Things that are not decided include:
  1. How to package an extension? Should we go with the PEAR package way or a simpler way?

  2. Should we support dependency check for extensions?

  3. How to write a meta file that contains meta information about an extension package?

Your opinions are welcome!

  1. I never used PEAR  :D

  2. It would be very nice.

  3. I think an XML based solution would be good.

Quote

3. I think an XML based solution would be good.

I think for performance and consistency, we should not use an XML file, but a simple .php file instead. Reasons are the very same for which we use a php file for the application configuration now.

I don't know… do you need this meta-informations to be cached?

Generally, PHP-based config file, lang file etc. are not a good idea if you want max performances, because of the overhead needed to load, encode to bytecode, execute etc. the PHP file.

This



$array = array(


    'main' => 1,


    'header' => 2,


    'body' => 3,


  );


is about 2 times slower than a CSV file like



main,1


header,2


body,3


with



$content = file('file.dat');


while(list(, $value) = each($content)) {


  if (!$value) continue;


  


  list($key, $line) = explode(',', $value);


  $array[$key] = $line;


}


however using a PHP caching system you can mitigate this issue.

So…

Plain text = generally faster

PHP = fast if cached, easy to manage

XML = maybe not so fast (I should test it), but very elegant in my opinion

Performance is not an issue here because the meta information is only used when you use yiic to install an extension. So either XML or PHP-based meta information is fine. The main point is about how to make this meta file easy to write.

Yes, I presumed this… this is why I said "XML". If it was performance-related, of course XML was't the best choice.

My opinions on the undecided things:

  1. A simpler way. A .tar.gz archive would be fine, as it makes it easy to install extensions manually. (And also to package extensions.)

  2. Yes, please.

  3. For consistency, use the same syntax as in config/main.php

My 2 cents

Quote

Things that are not decided include:
  1. How to package an extension? Should we go with the PEAR package way or a simpler way?

  2. Should we support dependency check for extensions?

  3. How to write a meta file that contains meta information about an extension package?

  1. Please no pear !

  2. Only support download dependencies not version dependencies.

  3. XML would allow for a dtd specification,

nz

I'm using the letter "E" as prefix for the extension class.

Ex.

"EGoogleMaps"

I think it should be good.

Probably is phar a good packing system. It’s native supported (or in the next versions) by PHP.  It’s possible to move the pharchive right in the extensions directory without uncompress the whole thing but I don’t know how that’s working out for performance.

I'd like also an option to place extensions in the common (shared) framework tree so all apps can use it. My idea behind this, is that you can use the extensions like 'frameworks' containing modeling classes and all kind of other stuff that needs to be commonly available.

I like the idea of phar archives, but unfortunately it requires PHP 5.2.0 or newer. My servers are using 5.2, but I'm not sure everyone else's are.

I don't like to modify the framework tree, but maybe we could configure additional (common) framework folders in config/main.php?

My 3 cents:

  1. phar, or gzip if supporting PHP < 5.2… and no PEAR please.

  2. Yes

  3. XML with DTD

For 1 and 3: I don't think performance should be a factor to consider when installing extensions.

For 2: I love the way perl's CPAN works.

I posted here some related questions.

I have yet more questions, Qiang:

  • Which should be the attributions for an user contributed extension.
  • I assume the extension should be released under BSD or compatible licence (?)
  • What about if the extension has 4th-party code (ie. javascript or php libraries)? should it follow the vendors convention, including the LICENCE.txt file?
  • Also, I assume that only 4th-party code must be compatible with the BSD licence used by Yii. I suggest making this clear here or in the website.

Thanks.

In general, the guide line is that the extension should be IP clear.

  • User-contributed extensions belong to the developer himself.

  • It is recommended that extensions posted to this site use BSD-compatible license.

  • If an extension uses 3rd party code, please include clearly its license.

Quote

In general, the guide line is that the extension should be IP clear.

Ok, I think this is a very important point. Effort should be done to insure that the code is IP clear, in the form of patents and copyrights, specially since you’re distributing from the USA. Also, 3rd party contributors should somehow protect the project by being careful with IP. I’m not a lawyer, but I think the EFF or the FSF could help here.

I'd like to make the following recomendation for extension writing, which I consider could be useful:

You should use i18n for the messages of your extension, following this example:

throw new CException(Yii::t('MyExtension', 'Invalid value'));

Notice that [tt]MyExtension[/tt] should be the name of the class.