Skip to content

Commit

Permalink
Merge pull request totten#114 from totten/master-upgnote
Browse files Browse the repository at this point in the history 
UPGRADE.md - Consolidtate general notes. Sort special tasks chronologically.
  • Loading branch information
@totten
totten authored Nov 14, 2017
2 parents 273f542 + 801f523 commit 0b3aa22
Showing 1 changed file with 88 additions and 86 deletions.
174 changes: 88 additions & 86 deletions UPGRADE.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
## Upgrade: General
## General Tasks

From time-to-time, the templates in civix may change. If you want to update
your module to match the newer templates, then use this procedure:
Expand All @@ -11,9 +11,48 @@ your module to match the newer templates, then use this procedure:
4. Compare the new code with the old code (e.g. "**git diff**" or "**svn diff**").
5. Look for additional, version-specific upgrade steps (below).

## Upgrade: The Big `E`
### General Tasks: Hook Stubs

### Upgrade to v17.08.1+
Sometimes new versions introduce new hook stubs. These generally are not
mandatory. However, in civix documentation and online support, we will
assume that they have been properly configured, so it's recommended that you
update your extension's main PHP file. For example, if the main PHP file
for the extension is "/var/www/extensions/org.example.myext/myext.php", the
snippets mentioned below (adjusting `myext` to match your extension).

Hook stubs are documented below as special tasks.

### General Tasks: Upgrader Class

Sometimes new versions introduce changes to the `Upgrader` classes (e.g.,
`CRM_Myext_Upgrader_Base` and its child). These generally are not mandatory --
CiviCRM is largely agnostic as to how modules manage schema upgrades -- but
`civix` suggests a reasonable approach to doing so, and documentation and online
support will assume this approach.

The steps for upgrading the `Upgrader` are as follows:

1. Make sure you have a backup of your code. If you use version-control (git/svn), then you should be good to go.
2. In the shell, navigate to your extension's root directory (e.g., "/var/www/extensions/org.example.myext").
3. Re-run the **civix generate:upgrader** command. This will regenerate the upgrader base class
(e.g. "/var/www/extensions/org.example.myext/CRM/Myext/Upgrader/Base.php").
4. Compare the new code with the old code (e.g. "**git diff**" or "**svn diff**").
5. Look for additional, version-specific upgrade steps (below).

## Special Tasks

### Upgrade to v17.10.0+: Test Files

The PHPUnit bootstrap file (`tests/phpunit/bootstrap.php`) has been updated to support autoloading of utility classes within your extensions `tests` folder. To follow this revised convention, update `bootstrap.php`. After the the call to `eval(...);`, say:

```php
$loader = new \Composer\Autoload\ClassLoader();
$loader->add('CRM_', __DIR__);
$loader->add('Civi\\', __DIR__);
$loader->register();
```

### Upgrade to v17.08.1+: The Big `E`

civix v17.08.1 makes corrections to the behavior of the new helpers, `E::path()` and `E::url()`. They are now
more consistent in that:
Expand All @@ -23,30 +62,66 @@ more consistent in that:

Suggestion: search your codebase for instances of `E::path` or `E::url` to ensure consistent path construction.

### Upgrade to v17.08.0+
### Upgrade to v17.08.0+: The Big `E`

civix v17.08.0+ introduces a new helper class. You can generate following the "General" upgrade procedure (above). No other changes are required.
civix v17.08.0+ introduces a new helper class. You can generate it by following the "General Tasks" (above). No other changes are required.

Optionally, if you want to *use* this helper class, then add a line like this to your other `*.php` files:

```php
use CRM_Myextension_ExtensionUtil as E;
```

## Upgrade: Test Files
### Upgrade to v16.10+

### Upgrade v17.10.0+
*(See also: "General Tasks: Upgrader Class")*

The PHPUnit bootstrap file (`tests/phpunit/bootstrap.php`) has been updated to support autoloading of utility classes within your extensions `tests` folder. To follow this revised convention, update `bootstrap.php`. After the the call to `eval(...);`, say:
In version 16.10.0, hook_civicrm_postInstall was implemented in the extension's
main PHP file and delegated to the Upgrader base class. If you wish to run
your own code post-install, you should copy the following snippet (or something
like it) into the Upgrader class (e.g. "/var/www/extensions/org.example.myext/CRM/Myext/Upgrader.php"):

```php
$loader = new \Composer\Autoload\ClassLoader();
$loader->add('CRM_', __DIR__);
$loader->add('Civi\\', __DIR__);
$loader->register();
/**
* Example: Work with entities usually not available during the install step.
*
* This method can be used for any post-install tasks. For example, if a step
* of your installation depends on accessing an entity that is itself
* created during the installation (e.g., a setting or a managed entity), do
* so here to avoid order of operation problems.
*/
public function postInstall() {
$customFieldId = civicrm_api3('CustomField', 'getvalue', array(
'return' => array("id"),
'name' => "customFieldCreatedViaManagedHook",
));
civicrm_api3('Setting', 'create', array(
'myWeirdFieldSetting' => array('id' => $customFieldId, 'weirdness' => 1),
));
}
```

### Upgrade v16.03.2+
### Upgrade to v16.10+: hook_civicrm_postInstall

Prior to v16.10.0, extension schema versions were stored in the `civicrm_settings`
table under the namespace `org.example.myext:version`. This storage
mechanism proved problematic for multisites utilizing more than one domain (see
[CRM-19252](https://issues.civicrm.org/jira/browse/CRM-19252)). `civix` now
utilizes `hook_civicrm_postInstall` and an [updated Upgrader](#upgrade-to-v1609) to
store schema versions in the `civicrm_extension` table.

```php
/**
* Implements hook_civicrm_postInstall().
*
* @link http://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_postInstall
*/
function myext_civicrm_postInstall() {
_myext_civix_civicrm_postInstall();
}
```

### Upgrade v16.03.2+: Test Files

Prior to civix v16.03, civix included the commands `civix generate:test` and `civix test`. Beginning with v16.03, civix templates now
comply with the [Testapalooza PHPUnit Template](https://github.com/civicrm/org.civicrm.testapalooza/tree/phpunit). The key changes:
Expand Down Expand Up @@ -76,35 +151,6 @@ here are some expectations:
* Note: Legacy tests executed this way may reset key variables (e.g. `CRM_Core_Config::singleton()`) extra times.
However, the pool of existing extension tests is fairly small, so we don't expect this to have a big real-world impact.

## Upgrade: Hook Stubs

Sometimes new versions introduce new hook stubs. These generally are not
mandatory. However, in civix documentation and online support, we will
assume that they have been properly configured, so it's recommended that you
update your extension's main PHP file. For example, if the main PHP file
for the extension is "/var/www/extensions/org.example.myext/myext.php", the
snippets mentioned below (adjusting `myext` to match your extension).

### Upgrade to v16.10+: hook_civicrm_postInstall

Prior to v16.10.0, extension schema versions were stored in the `civicrm_settings`
table under the namespace `org.example.myext:version`. This storage
mechanism proved problematic for multisites utilizing more than one domain (see
[CRM-19252](https://issues.civicrm.org/jira/browse/CRM-19252)). `civix` now
utilizes `hook_civicrm_postInstall` and an [updated Upgrader](#upgrade-to-v1609) to
store schema versions in the `civicrm_extension` table.

```php
/**
* Implements hook_civicrm_postInstall().
*
* @link http://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_postInstall
*/
function myext_civicrm_postInstall() {
_myext_civix_civicrm_postInstall();
}
```

### Upgrade to v15.10+: hook_civicrm_navigationMenu

Prior to v4.7, the hook for manipulating the navigation menu required that the
Expand Down Expand Up @@ -191,47 +237,3 @@ function myext_civicrm_alterSettingsFolders(&$metaDataFolders = NULL) {
_myext_civix_civicrm_alterSettingsFolders($metaDataFolders);
}
```

## Upgrade: Upgrader Class

Sometimes new versions introduce changes to the Upgrader classes (e.g.,
`CRM_Myext_Upgrader_Base` and its child). These generally are not mandatory --
CiviCRM is largely agnostic as to how modules manage schema upgrades -- but
`civix` suggests a reasonable approach to doing so, and documentation and online
support will assume this approach.

The steps for upgrading the Upgrader are as follows:

1. Make sure you have a backup of your code. If you use version-control (git/svn), then you should be good to go.
2. In the shell, navigate to your extension's root directory (e.g., "/var/www/extensions/org.example.myext").
3. Re-run the **civix generate:upgrader** command. This will regenerate the upgrader base class
(e.g. "/var/www/extensions/org.example.myext/CRM/Myext/Upgrader/Base.php").
4. Compare the new code with the old code (e.g. "**git diff**" or "**svn diff**").
5. Look for additional, version-specific upgrade steps (below).

### Upgrade to v16.10+

In version 16.10.0, hook_civicrm_postInstall was implemented in the extension's
main PHP file and delegated to the Upgrader base class. If you wish to run
your own code post-install, you should copy the following snippet (or something
like it) into the Upgrader class (e.g. "/var/www/extensions/org.example.myext/CRM/Myext/Upgrader.php"):

```php
/**
* Example: Work with entities usually not available during the install step.
*
* This method can be used for any post-install tasks. For example, if a step
* of your installation depends on accessing an entity that is itself
* created during the installation (e.g., a setting or a managed entity), do
* so here to avoid order of operation problems.
*/
public function postInstall() {
$customFieldId = civicrm_api3('CustomField', 'getvalue', array(
'return' => array("id"),
'name' => "customFieldCreatedViaManagedHook",
));
civicrm_api3('Setting', 'create', array(
'myWeirdFieldSetting' => array('id' => $customFieldId, 'weirdness' => 1),
));
}
```

0 comments on commit 0b3aa22

Please sign in to comment.