@@ -38,6 +38,9 @@ Each class in the `CRM_Upgrade_Incremental_php` corresponds to a major release o
| `php public function upgrade_X_Y_Z() ` | Perform any changes in a specific queue order for version X.Y.Z. During this function you *MUST* call `php $upgrade->processSQL($rev)`. Without calling this function the X.Y.Z.sql.tpl file will not be executed |
| `php public function setPostUpgradeMessage() ` | Called after each incremental upgrade. Any messages generated by this function will be displayed to site-administrators *after* the upgrade has completed. (This is called several times – once for each incremental upgrade.) |
## Upgrading message templates
Message templates that need upgrading should be declared - currently under CRM_Upgrade_Incremental_MessageTemplates::getTemplateUpdates although this may be defined. The upgrade script will pick them up from there (5.4+)
## Tips: Prefer simple SQL semantics over API/BAO/DAO
When writing upgrade steps in PHP its preferable to use direct sql queries rather than relying on BAOs and DAOs as they may change between versions. Whereas writing SQL is more rigorous. Further it is preferable to write SQL statements especially if it involves adding or removing columns, indexes from database tables. There are helper functions such as `CRM_Core_BAO_SchemaHandler::dropIndexIfExists()`, `CRM_Upgrade_Form::addColumn()`, `CRM_Upgrade_Form::dropColumn()`. These helper functions don't depend on version specific business logic and also help protect against hard database fails by checking if what your trying to add or drop exists already.
