Zen Cart Support - Blogs http://www.zen-cart.com/blog.php This is the support site for the popular Zen Cart e-commerce shopping cart software. en Fri, 24 May 2013 04:25:25 GMT vBulletin 60 http://www.zen-cart.com/images/styles/zencart/misc/rss.jpg Zen Cart Support - Blogs http://www.zen-cart.com/blog.php Hey Look, We have a Blog system http://www.zen-cart.com/entry.php?1-Hey-Look-We-have-a-Blog-system Tue, 09 Oct 2012 20:31:19 GMT One of the many benefits of the upgrade to vBulletin 4 is that it gives us this shiny blog system. However because it is nice and shiny, for now we are keeping it all to ourselves. :D It may be in the future we open up the system more to our user base, but for now, you will just have to put up... One of the many benefits of the upgrade to vBulletin 4 is that it gives us this shiny blog system. However because it is nice and shiny, for now we are keeping it all to ourselves. :D

It may be in the future we open up the system more to our user base, but for now, you will just have to put up with the ramblings of the Zen Cart development team.

Generally we hope to Blog about stuff that would not normally be relevant within the Forum context. Some stuff about PA-DSS, or thoughts about general trends in E-Commerce, maybe even a rant or two.

Watch this space :D ]]> wilt http://www.zen-cart.com/entry.php?1-Hey-Look-We-have-a-Blog-system Creating an Observer Class: send a specialized additional email during Create Account http://www.zen-cart.com/entry.php?4-Creating-an-Observer-Class-send-a-specialized-additional-email-during-Create-Account Fri, 07 Sep 2012 03:42:51 GMT Task:
  • Storeowner wants to send the customer an email with a unique code when the customer creates an account.
  • The code pattern is "ABC00001", where ABC is fixed text, and 00001 is the customer number, with leading zeros up to exactly 5 digits.
  • There is no need to build a database of already-issued codes, since the customer ID number is already unique per customer.
  • The store is using v1.5.0 code.


The thinking and coding process:
First, since this must happen during account-creation, it makes sense to consider looking at the /includes/modules/create_account.php script which handles those activities.

Since the intention is to see whether an Observer class can be used for this, I started by scanning the file for any notifier hooks. These can be identified in either of two ways: calls to $zco_notifier->notify() for procedural code or $this->notify() from inside any class method.

We want a notifier point that fires sometime after a customer has submitted their user information and it's been validated.

So, at the end of the validation code there's this one:
Code:
    $zco_notifier->notify('NOTIFY_FAILURE_DURING_CREATE_ACCOUNT');
… but we're not interested in a failure case, so we keep looking:

The next one is this:
Code:
    $zco_notifier->notify('NOTIFY_MODULE_CREATE_ACCOUNT_ADDED_CUSTOMER_RECORD', array_merge(array('customer_id' => $_SESSION['customer_id']), $sql_data_array));
And, looking closely at the code immediately above it, we see that that part of the code has just finished building the new customer data for the database, inserted that record, and set the customer ID into the session, effectively logging them in. This is perfect! And what's even better is that the $sql_data_array has also been passed, so we can make use of that to customize the email with the customer's name and email address.

So, now we start with creating an observer class. We start with the basic structure:
PHP Code:
<?php
/**
 * Observer class for sending an extra email during customer-creation/welcome process
 */
class send_extra_email_at_welcome extends base {

  function __construct() 
  {
  }

  function update(&$class, $eventID, $paramsArray = array())
  {
  }
 }
You'll see here that we've given the class a name of send_extra_email_at_welcome. This name will be used later in the auto_loader to activate this observer class. The name itself just needs to be unique from any other class used in the store.

Next we need to set up the constructor to watch the NOTIFY_MODULE_CREATE_ACCOUNT_ADDED_CUSTOMER_RECORD hook we identified earlier. Since the notifier hook is activated via a $zco_notifier call, we set the observer up to attach to that $zco_notifier->notify() call:
Code:
  function __construct() 
  {
    global $zco_notifier;
    $zco_notifier->attach($this, array('NOTIFY_MODULE_CREATE_ACCOUNT_ADDED_CUSTOMER_RECORD'));
  }
We have a few main tasks to perform when this notifier hook is called:
a) create a formatted "code" based on the customer number
b) assemble email text with the code
c) send the email

Let's look at these one at a time:
a) create the formatted code from the customer number. We'll use the PHP function str_pad() to add enough zeros to make a 5-digit value from the customer number:
PHP Code:
    /**
     * Here we take the customer number, and add enough zeros to the left of it to make it be 5 digits long.
     */
    $code = str_pad($_SESSION['customer_id'],5,'0',STR_PAD_LEFT); 
and then add the ABC prefix to the beginning of it:
PHP Code:
    /**
     * Then the 'ABC' prefix is added to it:
     */
    $code = 'ABC' . $code; 
b) Put together some email text, using the code. The first line here is the plain-text content. The $html_msg array will contain the same content, but formatted as HTML, in case the customer has opted to receive html-formatted messages in their preferences during signup.
PHP Code:
    $email_text = 'Here is your unique code: ' . $code;
    $html_msg['EMAIL_MESSAGE_HTML'] .= nl2br($email_text); 
We'll need a subject line for the email:
PHP Code:
    $email_subject = 'Your unique customer code!';
    $html_msg['EMAIL_SUBJECT'] = $email_subject; 
c) To send the email, we need to get the customer's email address. The call to $zco_notifier->notify() included some extra parameters, which show up in this observer class via the $paramsArray variable:
PHP Code:
    $customer_email_address = $paramsArray['customers_email_address']; 
Similarly, in this case we happen to also have access to the customer's firstname/lastname, based on whatever they supplied during signup. Here we concatenate both values into a single string:
PHP Code:
    $customer_name = $paramsArray['customers_firstname'] . ' ' . $paramsArray['customers_lastname']; 
And now we send the email, using all the data we've prepared:
PHP Code:
    zen_mail($customer_name, $customer_email_address, $email_subject, $email_text, STORE_NAME, EMAIL_FROM, $html_msg); 
When we put it all together, the finished code looks like this:
PHP Code:
<?php
/**
 * Observer class for sending an extra email during customer-creation/welcome process
 */
class send_extra_email_at_welcome extends base {

  function __construct() 
  {
    global $zco_notifier;
    $zco_notifier->attach($this, array('NOTIFY_MODULE_CREATE_ACCOUNT_ADDED_CUSTOMER_RECORD'));
  }

  function update(&$class, $eventID, $paramsArray = array())
  {
    /**
     * Here we take the customer number, and add enough zeros to the left of it to make it be 5 digits long.
     */
    $code = str_pad($_SESSION['customer_id'],5,'0',STR_PAD_LEFT);
    /**
     * Then the 'ABC' prefix is added to it:
     */
    $code = 'ABC' . $code;
    /**
     * Now build and send the email to the customer
     */
    $email_text = 'Here is your unique code: ' . $code;
    $html_msg['EMAIL_MESSAGE_HTML'] .= nl2br($email_text);
    
    $email_subject = 'Your unique customer code!';
    $html_msg['EMAIL_SUBJECT'] = $email_subject;

    $customer_name = $paramsArray['customers_firstname'] . ' ' . $paramsArray['customers_lastname'];
    $customer_email_address = $paramsArray['customers_email_address'];

    zen_mail($customer_name, $customer_email_address, $email_subject, $email_text, STORE_NAME, EMAIL_FROM, $html_msg);
  }
}
We'll store this code into a new file, named /includes/classes/observers/class.send_extra_email_at_welcome.php


Finally, to turn the whole thing on, we add the auto_loader code to tell Zen Cart to load the observer class and instantiate it. The file will be uploaded to: /includes/auto_loaders/config.send_extra_email_at_welcome.php :
PHP Code:
<?php
$autoLoadConfig[190][] = array('autoType'=>'class',
                              'loadFile'=>'observers/class.send_extra_email_at_welcome.php');
$autoLoadConfig[190][] = array('autoType'=>'classInstantiate',
                              'className'=>'send_extra_email_at_welcome',
                              'objectName'=>'send_extra_email_at_welcome');
The value of 190 is used to essentially process all of this at the end of the normal autoloader stack.
The load file points to the class file created earlier. And the className matches the class name in the class file we made, and the objectName is basically the instantiation object built to fire the observer when appropriate … it usually is just the same as the className.

That's it. With both of those files in place, when the customer creates a new account, they will receive an extra email (in addition to the normal Welcome email) in which they are told their unique customer code.


----------

What about making it multi-language capable?
To do this, we must change the language text into defined constants.
So, we'll take these two lines:

Code:
    $email_text = 'Here is your unique code: ' . $code;
    $email_subject = 'Your unique customer code!';
and make language defines for them:
Code:
  define('EMAIL_SUBJECT_EXTRA_EMAIL_WELCOME', 'Your unique customer code!');
  define('EMAIL_TEXT_EXTRA_EMAIL_MESSAGE', 'Here is your unique code: ');
and change the code to use those constants in place of the text.
Code:
    $email_text = EMAIL_TEXT_EXTRA_EMAIL_MESSAGE . $code;
    $email_subject = EMAIL_SUBJECT_EXTRA_EMAIL_WELCOME;
Now those define statements can be placed into new files in corresponding language folders so they can be translated to suit whatever language the customer has selected while visiting the site. The define statements would go into a file at /includes/languages/NAME_OF_A_LANGUAGE_HERE/extra_definitions/send_extra_email_at_welcome.php.


This blog post was inspired from the more specific use-case discussed on the forum at: http://www.zen-cart.com/showthread.p...01#post1148601 ]]> DrByte http://www.zen-cart.com/entry.php?4-Creating-an-Observer-Class-send-a-specialized-additional-email-during-Create-Account How do I rebuild my site on the new version, instead of upgrading? http://www.zen-cart.com/entry.php?3-How-do-I-rebuild-my-site-on-the-new-version-instead-of-upgrading Mon, 03 Sep 2012 23:12:37 GMT TL;DR / Executive Summary:
Are you looking for a quick way to understand best practices when upgrading your Zen Cart site? The easiest way to view it is as "a rebuild while keeping all the existing data."

This article contains 3 sections:
1. What an upgrade is, and what it is not.
2. An overview of how to rebuild a site using the new version, instead of upgrading.
3. How to upgrade while keeping the store live, and not losing any sales/customer/product data.


What is an upgrade anyway?

I've observed a number of misconceptions about what it means to upgrade a Zen Cart store from one ZC version to another.

Some people come at it from the angle of having used other frameworks that do things in different ways, or from any of a number of popular CMS systems that are architected differently perhaps with more of a plugin-style architecture where code or feature customizations are housed externally. In all of these cases the idea of "upgrading" comes with many preconceptions, and when the person discovers that upgrading in Zen Cart is done differently, they dig their heels in and object and complain that it should work the same as "XYZ" other software application.
Curiously, the same behavior is exhibited when someone comes to Zen Cart looking to set up a store or template, and discovers that ZC doesn't use Smarty or some other templating system that they're already familiar with, and they find that frustrating … because they have to learn another way of doing things.

It's not wrong. It's just different.

The v1.x.x architecture of Zen Cart does "separate the business logic from the presentation logic", which thankfully allows most upgrades to have minimal impact on templates specifically. But when it comes to other core components, many times a number of core files must be touched. And while this in itself is not usually a big deal, it does get complicated when someone has installed a number of 3rd-party addons which have altered core code functionality. It's also particularly complicated when a new version NEEDS to change a LOT of files in order to integrate new features that have been in high demand. While v2 is being built to have more of a plugin architecture, the v1.x series requires a little bit of care when upgrading.

Anyway, back to the misconceptions…

In summary, a Zen Cart upgrade in version 1.x.x …
  • is NOT merely a "replace these 5 files" exercise. (There are often 20-50 files affected)
  • is NOT a magical "click this button and you're suddenly on the new version". (There is no reliable "one-click upgrade" feature yet. Stay tuned for v2.)
  • IS a quick rebuild of your site (quick meaning that it's way faster than when you built it the first time, since you already have a frame of reference)
  • DOES keep your existing data intact


The EASIEST way to conceptualize an upgrade is that it's an accelerated re-build of your site, using the new version, and keeping all your existing store data/configuration.

Now … DON'T LET THAT word "rebuild" scare you! IT WILL NOT TAKE AS LONG to upgrade as it did to build your site in the first place!!
Maybe the first time you set up your store it took you a few weeks … mostly because you were starting green, had no idea what a template was or where to put your graphics or product images, etc. But since your existing site is now a map of all the things you've done to customize your site, the rebuild is a much shorter exercise.


How do I rebuild my site on the new version, instead of upgrading?

Well, an upgrade *is* basically a rebuild. At least, that's what I find to be the simplest approach to take when upgrading.

In a nutshell, an upgrade is simply this:

a) make a list of all your existing customizations
- This includes all your addons/plugins, templates, custom features, etc
- There are handy file-comparison tools that help you quickly see any changes/additions/deletions you've made
- If you've already made good notes about your own customizations over the years, these notes will be very handy checklists/references for the next stage

b) re-make those on the new version
- installing updated addons/plugins designed for the new version, if necessary
- adding any small templating changes from the new version into a new copy of your existing template, or maybe using a new template altogether if that suits
- re-making your custom coding changes into the new version's files
- sometimes it might mean merging changes from the new version's core files into your own customized files, and/or vice-versa. This is no different than what you need to do when installing two addons that touch the same files, since their unique changes need to be merged together before they can be safely used together anyway.

c) upgrade the database to the new version
The zc_install script is used to do this in an automated way. Just a couple clicks to take care of keeping all your data intact and bringing its data structure up-to-date to work with the new version.

And of course, doing all of this in a TEST COPY of your site first, not on your live site directly, lets you ensure that everything is working and nothing is missed, before putting it all onto the live site. This way, when it comes time to actually touch your live site, you can do it in just a few minutes instead of potentially having your store down for much longer while testing/checking addons and customizations, etc.



How do I do an upgrade and still keep my live store running in the meantime?

You're a busy storeowner. You know you need to keep the business running while you safely test your upgrade, and you don't want to lose any data in the process.

The SMARTEST way to do that is this:

a) keep your live store running, as-is. With its own admin. Its own database. Its own folder of files on the server. Everything as-is.

b) build your new store in a temporary location. THIS IS ONLY FOR TESTING AND PREPARING FOR LIVE DEPLOYMENT.
This separate testing area will use a complete copy of your live site, in another subdirectory of your site, AND another database.
This is done following the main upgrade procedure as described in steps a), b), c) above, and in more detail at this FAQ article: http://www.zen-cart.com/content.php?...-zen-cart-site
REMEMBER: Any settings you adjust in your Admin, and any SQL scripts you run against your database will need to be re-done after "going live". SO TAKE REALLY GOOD NOTES so you know all the things you need to do again.
Same with any addons that you install. You'll need to re-run their installation process and configure them, since their setup won't be present in that database until you do. (See next step to understand these last 2 statements better.)

c) once you're ready to "go live", your temporary "new" store will be out-of-date because you'll have new customers, new orders, new payments, new products, etc in the live store.
So, you simply upgrade your live shop (since it has the most current data):
(THIS IS *AFTER* YOU'VE BUILT AND TESTED YOUR "TEST" SITE IN PREPARATION)
You can do this upgrade now on your live site BECAUSE you've already done all the testing and preparation in a temporary space.
This is the only scenario when you should upgrade your live site directly!

Pick a time when your live store is less-busy. This might be a typically "slow day", or an evening or a weekend, depending on your business. Follow these steps:

  1. Put your live shop down for maintenance (Admin->Configuration->Website Maintenance->first option, turn it on)
  2. Backup your live database for safekeeping http://www.zen-cart.com/content.php?...ith-phpmyadmin
    It's also wise to backup all your existing php files/folders, images, etc … everything in your hosting account.
  3. Replace all the Zen Cart php files/folders/images/everything in your live store with the new files (except the configure.php files which usually stay the same)
    Be sure to also delete any files that don't belong anymore.
  4. Upload all the files for the zc_install folder, and run zc_install/index.php and choose database-upgrade
  5. Re-do any admin settings and SQL changes, new addons/modules, etc relevant to the new setup.
    Refer to the list of notes you took while you did any additional customizing in your temporary site
  6. Turn off down-for-maintenance
  7. Do a test transaction to be sure checkout works
    And browse around all the pages to make sure things are working correctly.
  8. Do another backup of everything for peace-of-mind.
  9. Take a deep breath. :)



TIP: You *could* do a "trial run" of this whole upgrade process by making ANOTHER copy of your live site and doing
this upgrade to that site. Then you'll have either a checklist of additional things you'd missed, or you'll have simply the peace-of-mind of knowing that your live upgrade will go smoothly.
In fact, this is what I always do!

d) You can then delete your temporary site (files and database) because it's no longer needed. It was only ever used for "staging" to prepare yourself for the actual live upgrade of the live shop.


ADDENDUM:
If you are considering changing webservers or hosting companies, do ALL of your upgrade activities BEFORE or AFTER the move. NOT DURING. If you confuse the picture by doing an upgrade at the same time, then you make it nearly impossible to determine whether your problems are the result of "moving" or a result of errors in "upgrading". So, always upgrade before OR after, but never "during" a move.
More about moving to another server here: http://www.zen-cart.com/content.php?...fferent-server ]]> DrByte http://www.zen-cart.com/entry.php?3-How-do-I-rebuild-my-site-on-the-new-version-instead-of-upgrading Is your code safe to use on PHP 5.3? http://www.zen-cart.com/entry.php?2-Is-your-code-safe-to-use-on-PHP-5-3 Sun, 02 Sep 2012 21:04:31 GMT When PHP 5.3 was released, some older features were retired (some removed, some "deprecated", etc).

And if your custom code or your addons/plugins are using those features, things will break and you'll encounter the dreaded "white screen of death".

What do you need to change?

Here's the list I generally follow, along with how I usually remedy it:

ereg('searchtext', 'a_string', $optionalVar) becomes preg_match('/searchtext/', 'a_string', $optionalVar)

eregi('searchtext', 'a_string', $optionalVar) becomes preg_match('/searchtext/i', 'a_string', $optionalVar)

ereg_replace('searchtext',.....) becomes preg_replace('/searchtext/',....);
or if the 'searchtext' parameter is just a single character then just change ereg_replace with str_replace

eregi_replace('searchtext',.....) becomes preg_replace('/searchtext/i',....);


split('x', $var)
- if 'x' is a single character, then split( becomes explode(
- if 'x' is multiple characters, then split('chars', $var) becomes preg_split('/chars/', $var)

"short open tags"
Normally PHP files start with a <?php tag
or individual PHP statements start with <?php
But some commonly-used "shortcuts" require the use of "short open tags", such as just <? instead of <?php.
However, in PHP 5.3 the "short open tags" support is turned off by default, and if your code uses these "short" tags, you will cause errors, resulting in a blank page.
So, if your code uses <? followed by a space, change those to <?php
If it uses <?= then change those to <?php echo


That's the bulk of it. Making those changes should accommodate the majority of issues you might encounter when moving from PHP 5.2 to PHP 5.3


If you're working with very old code, or stuff that was inherited or ported from other systems, the following could be relevant to you as well:

Some very old things
The following session-related functions have been obsolete for quite awhile. Zen Cart has never used them, but people using old code converted from old OSC addons might still try to make use of them.
- session_register()
- session_unregister()
- session_is_registered()
Instead, write new logic to handle sessions in a contemporary way.

$HTTP_POST_VARS and $HTTP_GET_VARS and $HTTP_SERVER_VARS, etc are all officially deprecated. Also never used by Zen Cart, but used extensively in old OSC addons. They should be replaced with their $_POST, $_GET, $_SERVER, etc superglobal equivalents. And never need to be declared as globals. See below.

Global vars
Another pattern I've seen carried forward from old OSC addons is the choice to explicitly declare $_POST or $_GET as global inside a function/method. But, $_POST and $_GET (and other $_XXXXX superglobals) are already global.
So, in a PHP statement that starts with global and includes one of these superglobals, that superglobal can be removed from that statement. And if no other variables are mentioned, the whole statement can be removed.
ie: global $var1, $_POST, $var2; becomes global $var1, $var2;
or global $_POST; would just be removed altogether.


-------------------------------
Related reading:
http://www.php.net/manual/en/migration53.deprecated.php ]]> DrByte http://www.zen-cart.com/entry.php?2-Is-your-code-safe-to-use-on-PHP-5-3