Author avatar for jason

Manifest Copy Directive in a SugarCRM Module

Posted by on September 20, 2012

When it comes to developing solutions for SugarCRM there are many different ways to go about solving a particular challenge. In our Dev Tips series of blogs we will be highlighting various best practices for add-on development with the end goal of creating higher quality solutions while minimizing the chances of an end user experiencing an issue.

One way to create solutions for SugarCRM is by creating installable packages called modules. Modules contain all the required files along with a manifest.php which defines how the module should be installed. Here are a couple of links which help define and provide examples of a manifest:

Atcore Systems: Manifest Development Guide
SugarCRM Support: Creating an Installable Package for a Logic Hook

Most of the possible options within a manifest are fairly safe as most use the Extension framework to guarantee that there will not be conflicts with other modules that are installed. However, the option that is used in near every module but doesn’t utilize the Extension framework is the copy array option. The copy array defines what files and/or directories from the module zip should be copied over and to where it should be copied to. There is good reason for copy being unique from the Extension framework, but because of how it is used to copy over both files and directories, care must be taken to prevent accidental or unneeded removal of existing customizations.

More importantly, the copy array should accurately list the customizations that are being copied into an install as it is useful for users to be able to open and see if anything being copied over will overwrite a customization of their own. With SugarOutfitters we do that scanning for users and present them a list of the files that may have a chance of conflicting with their own customizations (whether they be from another module, studio, or hand coded). Here are the items that we flag along with some suggestions on how to improve that manifest entry:

Blank Copy to Root

Example:

'copy' => array (
array (
'from' => '<basepath>/files/',
'to' => '',
),
),
view raw manifest_copy-blank_copy_to_root.php hosted with ❤ by GitHub
Why we flag it:
This definition is simply copying over everything in the /files directory in the module zip to the root Sugar directory. As a user, it is unknown what exactly is being copied over.
Alternative:
'copy' => array (
array (
'from' => '<basepath>/files/modules/MyAwesomeModule',
'to' => 'modules/MyAwesomeModule',
),
),
view raw manifest_copy-blank_copy_to_root-alt.php hosted with ❤ by GitHub
In this case, only a new module is being copied over so a blanket directory copy works well. This lets a user know that it is not going to conflict with customizations as there is a 99.999999% chance that the MyAwesomeModule does not exist yet.

Full Directory Copy

Example:

'copy' => array (
array (
'from' => '<basepath>/files/custom/modules/Accounts',
'to' => 'custom/modules/Accounts',
),
),
view raw manifest_copy-full_directory_copy.php hosted with ❤ by GitHub
Why we flag it:
It is too vague and could include files that overwrite anything from the Account bean to a metadata file.
Alternative:
'copy' => array (
array (
'from' => '<basepath>/files/custom/modules/Accounts/EmailAccount.php',
'to' => 'custom/modules/Accounts/EmailAccount.php',
),
array (
'from' => '<basepath>/files/custom/modules/Accounts/metadata/detailviewdefs.php',
'to' => 'custom/modules/Accounts/metadata/detailviewdefs.php',
),
),
view raw manifest_copy-full_directory_copy-alt.php hosted with ❤ by GitHub
This clearly illustrates to a user what is being modified.

Core File Copy

Example:

'copy' => array (
array (
'from' => '<basepath>/files/modules/Accounts/metadata/detailviewdefs.php',
'to' => 'modules/Accounts/metadata/detailviewdefs.php',
),
),
view raw manifest_copy-core_file_copy.php hosted with ❤ by GitHub
Why we flag it:
It overrides a core file and will be lost upon the next upgrade of SugarCRM.
Alternative:
'copy' => array (
array (
'from' => '<basepath>/files/custom/modules/Accounts/metadata/detailviewdefs.php'
'to' => 'custom/modules/metadata/detailviewdefs.php',
),
),
view raw manifest_copy-core_file_copy-alt.php hosted with ❤ by GitHub
Although it is possible that this definition will overwrite an existing custom view.edit.php at least it is a safer way of doing so.

Custom File Copy

Example:

'copy' => array (
array (
'from' => '<basepath>/files/custom/modules/Accounts/views/view.edit.php',
'to' => 'custom/modules/Accounts/views/view.edit.php',
),
),
view raw manifest_copy-custom_file_copy.php hosted with ❤ by GitHub
Why we flag it:
Although this customization is being done in the custom directory, it is a custom version of a core file which could cause conflicts with other modules or customizations that need to modify this file. This may be unavoidable, but users still need to know about the change so that they can be prepared to work with it if they already have a customized version of that file.By changing the copy directive to be as descriptive as possible it allows for users to be better prepared for possible conflicts.

With the above suggestions, members will be well-informed about and feel more comfortable with what they’re getting into when purchasing your custom modules. This gives a much better chance for a good user experience when installing and using the module as the user will know what to expect. Furthermore, with SugarOutfitters, we can better present accurate conflict notifications including possible conflicts with other previously purchased add-ons.

So when it comes to the copy directive option, be as descriptive as possible. It will save both users and yourself some headaches.