Creating Magento Connect Extension Package
This is an old revision of the document!
The first heading will show up as page title. When a developer starts creating an extension, he or she can face the issue with giving it an appropriate name. The best practice for naming extensions is the use of simple words that describe the functionality of an extension. It is not recommended to use very long words or many words at once. Also, the developer must not add any obscure words in the extension name (except for the name of the developer or the company).
The name of a new extension must consist of letters and the underscore character (_), other characters are not allowed. It is good practice to name extensions using the module name.
A module must be correctly placed. For detailed instruction, read the corresponding article at magentocommerce.com knowledge base. If, for example, we create a simple extension with the Bloghome_Blog name, the module can have the following structure:
Also, the following files and folders are required for the correct work of a module:
- File magento/app/design/adminhtml/default/default/layout/bloghome_blog.xml - contains layout updates of the administrative interface.
- Folder magento/app/design/adminhtml/default/default/template/bloghome - contains templates of the administrative interface.
- File magento/app/design/frontend/base/default/layout/bloghome_blog.xml - contains layout updates of the frontend.
- Folder magento/app/design/frontend/base/default/template/bloghome - includes templates of the frontend.
- File magento/app/etc/modules/Bloghome_Blog.xml - module activation file.
- File magento/app/locale/en_US/Bloghome_Blog.csv - contains translations for the U.S. localization.
- File magento/app/locale/de_DE/Bloghome_Blog.csv - contains translations for the German localization.
When a developer creates an extension package, she or he needs to use the account information taken from the www.magentocommerce.com website. The developer needs to register at the website to get the account information. When the module is ready and fully functional, and the developer has all necessary information, he or she can create an extension package in the Magento administrative interface by clicking System > Magento Connect > Package Extensions. There are the following five tabs on the Create Extension Package page.
- Package Info
- Release Info
Many developers have difficulties with filling out all the fields on this page, and the following topics will reveal the mystery of these tabs.
- Name - the field must contain the extension package name which corresponds to previously mentioned naming best practices.
- Channel - so far, only one channel is available for publishing extensions - community.
- Supported releases - the field is intended for backward compatibility. If an extension package is supposed to be installed in Magento 1.4.x and lower, select the Pre-184.108.40.206 option in this case, the package will be created in a PEAR format and all associated files will be saved in the magento/var/pear/ folder. Select 220.127.116.11 & later to create an extension package for Magento 1.5.x and later in which case the package file will be saved in magento/var/connect/. If we need packages of old and new formats, we can select both options.
- Summary and Description - brief but descriptive data about the package extension being created must be added in these fields. There are no restrictions on contents in these fields.
- License - the name of the license to which this extension applies must be specified in this field. The full list of possible licenses as stated on the Magento community website are:
- * GNU General Public License (GPL)
- * GNU Lesser General Public License (LGPL)
- * Open Software License (OSL)
- * Mozilla Public License (MPL)
- * BSD License
- * Apache Software License
- * MIT License
- * Academic Free License (AFL)
- * you can specify another (commercial) license if you distribute the extension package as paid
- License URI - In this field, enter the link to the license text. It is not required, but at least recommended to fill out, for example http://opensource.org/licenses/osl-3.0.php
On the Release Info tab, the number of fields is fewer comparing to the previous tab; however, very often these fields bring up a lot of questions from software developers. What version should be entered in the Release Version field? In order to understand this issue, read the page Software versioning in Wikipedia. The following example of filled out fields can be used:
On this tab, we can specify the dependence of our code in regard to the PHP version. If it is necessary, the dependence on other extension packages can be filled out as well. During the installation of an extension, the system will check it in regard to all versions specified for it, and if dependent extensions are not installed, Magento Connect Manager (MCM) offers to install them. Also, we can specify the dependence on the PHP extensions, for example, if our module uses GD library functions of the latest version. In this case, if a necessary PHP extension is not installed on the server, MCM will send an alert the administrator.
The following screen shot provides an example of dependency on the Mage_Core_Modules package. This means that our extension will only work with Magento versions within the set range. The PHP version_compare function http://php.net/version-compare is used to verify the compatibility of versions during the extension installation.
Perhaps the most important place when creating an extension package in Magento is the Contents tab. For proper compilation of extension package contents, we can use the following tips for the Target| field. The following options correspond to the path on the disk:
- Magento Local module file - ./app/code/local
- Magento Community module file - ./app/code/community
- Magento Core team module file - ./app/code/core
- Magento User Interface (layouts, templates) - ./app/design
- Magento Global Configuration - ./app/etc
- Magento PHP Library file - ./lib
- Magento Locale language file - ./app/locale
- Magento Media library - ./media
- Magento Theme Skin (Images, CSS, JS) - ./skin
- Magento Other web accessible file - ./
- Magento PHPUnit test - ./tests
- Magento other - ./
Where “./” represents the Magento root directory.
In the Path field, we should enter the path relative to the path specified in the Target field. In the Include and Ignore fields, we can enter a regular expression which will check the path with the file name only for the rows where the Type field is set to Recursive Dir. A file to be included in the extension package must match the expression specified in the Include field. If the file matches the expression in the Ignore field, it will not be included in the extension package correspondingly.
When all data is correctly filled in, you can click the Save Data and Create Package button to save it in the package data file (Extension Package XML data file) and instantly create an extension file (Extension Package .tgz file).
The package data file is an XML document that stores the rules for building a package. This file is saved on the disk in the magento/var/connect/ folder. A different location can be specified if you click the Save As... button.
An Extension Package file contains all source code of a package. In addition, the archive includes another file that is created by a packager - package.xml. This file contains information about the extension, including the description of the structure of files and folders included in the package, and md5 sum for each file. Package file extension is saved in the magento/var/connect/ folder (or as it is described in Package Info section of this article).
When the extension package file is ready, it can be uploaded to the http://magentocommerce.com website or be directly sent to the store owner.