Installation patches are ZenMagick’s way to avoid having to distribute modified zen-cart files. They are small bits of code wrapped in an implementation of ZMInstallationPatch. Each of those is designed to modify one aspect of zen-cart code in order to integrate ZenMagick functionallity into an existing zen-cart installation.

The main advantage is that:

• They are reversible
  Where possible an undo option exists (even though the admin interface is still lacking some features). This makes it much easier to uninstall than manually reverting changes
• The patches work with other mods
  So far there have been no reports of patches failing - except for missing file permissions to update files, but that I would not consider failing.

The descriptions in the installation screen are perhaps not the best ones, so I figured it would be nice to have some more information about the implications of each patch.

The following list is based on the latest subversion which is most likely what 0.8.2 will look like.

• Install ZenMagick admin menu
  Will install the ZenMagick admin main menu entry. Without this there will be only the installation screen available via the menu. All other pages will work, however, you will have to guess the URL
• Patch zen-cart to enable ZenMagick request handling (aka ZenMagick themes)
  This will modify index.php and add a single include of store.php. Without this patch, you will still see the configured zen-cart template. The ZenMagick API will be available in all templates, though.
  For practical purposes this is equivalent to setting ‘isEnableZenMagick‘ to false.
• Create admin dummy files for all installed ZenMagick themes
  Both zen-cart and ZenMagick expect templates or themes to be in a particular directory. Selecting the default zen-cart template corresponds to the default ZenMagick theme. Apart from that there is no way of zen-cart to know about available ZenMagick themes. This patch will create all files required to make zen-cart recognize ZenMagick themes.
  Each time you create/install a new ZenMagick theme, this patch will be available for installation to install files for the new theme.
• Create dummy files for all (side)boxes of the current ZenMagick theme
  Sideboxes work pretty much the same way as templates, so this is to create dummy files in the zen-cart includes/modules/sideboxes folder for all boxes that exist in the current ZenMagick them but not in zen-cart.
  NOTE: This patch will currently consider only the active theme. That means if the themes is changed after the patch is installed and the new theme contains new boxes, the patch needs to be executed again.
• Disable zen-cart’s <code>zen_date_raw</code> function in favour of a ZenMagick implementation
  Not much to add here. The reason behind this patch is to make it easier to change the date format used in the storefront pages. It also means all that is required is to change a format string not the function itself.
  Another advantage is that themes can have different settings.
• Disable zen-cart’s <code>zen_href_link</code> function in favour of a ZenMagick implementation
  Again, quite simple. This will make pretty links and ZenMagick’s SEO support work even in zen-cart code. In most cases this will be for redirect URLs created in zen-cart code.
• Disable zen-cart’s <code>zen_mail</code> function in favour of a ZenMagick implementation
  Even though the ZenMagick email templates basically work with zen-cart’s email functions, there is, for my taste, something missing. For example, the password_forgotten email template will not have the password available as a singe parameter, but only in a three line sentence. This is quite restrictive and resolved in the ZenMagick email code.
  NOTE: Some of the default email templates do now rely on this patch, as they expect certain data to be available. One example would be the variable $newPassword in password_forgotten.
• Patch zen-cart to activate the ZenMagick event proxy service (required for some emails)
  Perhaps the most tricky one to explain in simple (non technical) terms. zen-cart’s code generates events at certain points in the control flow during request handling. While this is a good idea, it is cumbersome to use at times. ZenMagick implements a similar concept which supersedes the zen-cart event mechanism. In order to function properly, one simple modification to a zen-cart file is required.
  Some email templates depend on this patch as the events generated by ZenMagick will prepare and set up data that is expected by some email templates (see previous point).
• Update RewriteBase value in .htaccess (pretty links, SEO)
  Perhaps the patch that creates most problems. One thing ZenMagick can’t predict is the folder name (or lack thereof) underneath the webserver document root that contains the zen-cart installation. However, this folder name is required in the main .htaccess file.
  Once the user logs in into the admin interface, the patch is able to determine this folder name and update the includes .htaccess file.
  The only problem is, that until then the store will not work properly. Also, it might be required to manually key in the admin URL like this: https://hostname/admin/<strong>login.php</strong>.
  NOTE: This is the only patch that can’t be undone. Reason for that is that there is no way of knowing if the .htacces files was installed as part of ZenMagick or not.
• Enable dynamic admin menu support
  Perhaps the only really optional patch. This will enable the fancy menu in all ZenMagick admin pages. This is still somewhat experimental, but I thought some might like it.

So far, all patches explained were file based. There are also a few SQL patches. These will perform all SQL code required to run in order to run ZenMagick.

• Setup ZenMagick config groups and initial values
  This is to set up the basic configuration groups for ZenMagick and Plugins.
• Install Features database tables
  All the SQL to use ZenMagick product features.
• Install account type extensions
  SQL to store/retrieve the account type information ZenMagick needs to handle anonymous checkouts.

All SQL patches can also be installed manually. The SQL scripts can be found in the folder zenmagick/etc/sql.