So, you have your shiny new osCommerce installed and up and running. Maybe you’ve even got to the point where you actually have paying customers buying from it, which after all, is the whole point of the all the pain in getting it is set up in the first place.

It’s usually only a matter of time though before most osCommerce site operators start to identify things that could work better for them, or would improve the shopping experience for their customers.

Enter stage right…. The Contribution!!

Well, hopefully you all know what I’m talking about anyway, but just in case…contributions can be found at http://www.oscommerce.com/community/contributions . In a nutshell, these are code extensions of varying complexity and quality, written by users of osCommerce and then shared with the community. Together, they cover extensions for just about every imaginable aspect of your store.

As I mentioned in that last paragraph, contributions vary tremendously in both complexity and quality. The results can vary from flawless operation, to some simple mistakes the following the instructions that are easily corrected, to “Oh my god there’s no way this is ever going to work!”. Given this, there are a few things you should consider in mind before launching into your first contribution installation:-

1. Read the forum support topic for a contribution before you even download it. If there are major problems with it, you can always choose to avoid it at this point.

2. Always take a backup of your existing files and database before you begin to change anything.

3. Always put comments around the code you add such as /* Contribution x Start*/ and /*Contribution x End*/, so that you can easily identify where changes have been made. This comes in particularly useful when ignoring rule number 2 and trying to take a contribution that didn’t work back out again!

4. When a line of code is replaced or deleted by a contribution, simply comment it out for the time being using // or /* */. This will help during the testing phase and will allow you to easily see how the line used to look. This is particularly important for when you are installing a contribution which affects code which you previously changed for another contrib – in this case you have to combine the code in a sensible way or otherwise you are going to break one or both of the contribs.

5. Never work on a live store directly if at all possible. If you can, work on a spare account or folder on your server, or on a local installation on your PC. If you can’t have to work live, try and be sure to leave the critical file changes (i.e., those that will be immediately obvious to your customers if they screw things up generally) until last. This way, you can quickly undo the change that caused the problem and buy some time to think about what to do next sanely. Files that would fall into this category would be product_info.php, index.php, checkout_process.php, etc.

6. Test thoroughly. In addition to checking the obvious (i.e. that the contrib. actually does something like what it said on the tin), also do some non-regression testing. This is in fact a fancy engineering term for “check that I didn’t mess anything else seemingly unrelated up whilst I was in there”. Even if you don’t think you messed with anything near the checkout process, it’s always worth doing a quick test checkout as there are a few key files that only need an extra blank line to find its way in at the end of the file to completely nuke your checkout process, maybe costing you a few days worth of sales until someone tells you about it.

7. Finally, if you are like me and ignore rules 1 to 6, make sure that you know how to get your hands on any scheduled backup files in a hurry. You can be sure that sooner or later you are going to need them. :o)

Once you’ve uploaded any new files, made the directed changes to your existing files and made any changes to your database, it’s time to do some testing on your new functionality. If all has gone well, that will be the end of the job. If not, you will need to work out where the problem has crept in. What follows below is a summary of some of the most common problems you may encounter and how to fix them. Most often, these are caused either by small errors in installation instructions, or “finger trouble” when following them. In all cases, when you get an obvious error that generates a php error message on screen, be sure to read it carefully because most times it will tell you exactly where the problem lies.

Parse Errors. Here php is saying “I just couldn’t make any sense of this line because it doesn’t follow my rules for how things should be written”. Common causes of this are:
Missing or extra quotes “ or ‘. Check that the number each type of opening and closing quote balance.
Missing or extra parentheses (). Again make sure you have an equal number of opening and closing one.
Missing or extra curly brackets {}
Missing a semicolon ; on the end of a line
Php tags in the wrong place. All php code should be enclosed by <?php ?> tags.

File inclusion errors. If you have something on the screen which is all capital letters, for instance /catalog/includes/languages/english/FILENAME_CONTRIBUTION then it means that a definition within /catalog/includes/filenames.php for FILENAME_CONTRIBUTION has been missed. It should look something like:
define (‘FILENAME_CONTRIBUTION’, ‘contribution.php’);

Database table doesn’t exist errors. Again, if you see something in all capital letters like “table oscommer.TABLE_VOUCHERS doesn’t exist”, it means that a necessary change to /catalog/includes/database_tables.php wasn’t made. It should look something like:
define(‘TABLE_VOUCHERS’, ‘vouchers’);

Access denied errors. Usually this means that a file or folder wasn’t available for reading and/or writing as required. To correct this, you will need to set the permissions (CHMOD) on the file or folder concerned. Check again the instructions to see what value it should be set to.

More complicated errors need more advance techniques, such as the “print_r is my friend” technique, which I will be covering in a future article. Failing that, if your time and patience has run out, this can be a good point at which to hire a specialist to put things right for you.