Getting Started With osCommerce
by Ric Shreves

osCommerce is a open source catalog and shopping cart system that comes loaded straight out of the box with a wide range of features. It is head and shoulders above the crowd in terms of functionality and options and is often lauded as not simply an excellent open source product, but an excellent e-commerce product by any standard.

The system embodies a great deal of flexibility, but like any complex application, it also has its share of limitations and peculiarities. In the course of this article we’ll step through not only what it takes to get up and running with osCommerce but we’ll also take a peek under the hood for those who want to do more with this product.

Getting started with osCommerce is a pretty straight forward matter. With little technical expertise you can get a site online in about 30 minutes. However, if you wish to customize or modify the default package extensively you will need (or need to know) someone with PHP skills. Be advised that osCommerce it is not the simplest system to customize, but the good news is that it can be done -- and for a fraction of the cost of a proprietary solution.

Before you begin you need to address two preliminary matters. First, setup a mySQL database on the web host. For most people this will involve accessing phpMyAdmin to create and name a new database. Take note of the database name, and your username and password, as you will need them later in the installation process.

Second obtain the archive containing the osCommerce files, then extract the files and move them to your server. To get the files, make a quick trip to SourceForge or to the osCommerce parent site where you can download the archive. (It’s free of charge.) The archive comes as a .Tar file and weighs in at a mere 871k.

.Tar files can be extracted by using WinZip or a similar file compression utility. Once extracted you will find the default structure of osCommerce looks like this:

/oscommerce-2.2ms2
/catalog
/extras

Set up the directory structure you desire on your server and then move the entire set of files up to your server via FTP.

The simplest and probably most common configuration of the directory structure places the files inside the /oscommerce-2.2ms2 directory at your web host root. The extras directory is not necessary for your installation. The admin directory, located inside of the catalog directory contains the admin access to the catalog.

Once you have the files on your server, direct your browser to http://yourroot/catalog. If the extraction was successful you will be greeted by the welcome screen of the installation utility.

Click Install a New Online Store and you are off... The next screen to appear prompts you for the database information you wrote down earlier -- the name of the database and your username and password. You’ll also need your host name or IP address. (In the vast majority of cases the correct answer to this question is localhost, though you should check with your web host if in doubt.)

If all is correct the system will confirm that the initial installation was successful and warn you prior to performing the installation of the SQL data. Once that is completed you are almost home. The next screen that will appear shows you some important system data you should take note of, including the full URL of the catalog you have just installed, the web server root directory, the HTTP cookie domain and the path where cookies are stored. You should not attempt to change any of this data unless you have a very good reason and you really know your way around a server.

Note that this page also contains one other item of importance -- a check box that allows you to enable SSL. I encourage you to select this option as it adds a modicum of security to your site. Be aware that support for this feature depends on whether your web host provides SSL as an option for your account.

Once you’ve noted down the information for future reference and made a decision on SSL, click Continue. The next screen repeats your database info for your reference, but you already wrote that down earlier, didn’t you? Click Continue and move on…

At this stage you may be prompted with a warning that the permissions for certain files are not set as osCommerce requires. Should that be the case you will need to use your FTP program to CHMOD the directories to their required state. Once the changes have been made click the Retry button. If all is in order, you will be shown a confirmation message that setup is complete (If not, check the information again and CHMOD the necessary files.)

The osCommerce installation routine is a breeze to use and generally not problematic. There is one task that it omits to do, however, and to remedy that you will need to fire up your FTP program. Access the site via FTP and create a directory named backups inside of /catalog/admin. This directory is missing from the set up procedure and is needed for you to make backups of your database by way of the backup function in the admin system. Note that you will also need to set permissions on this directory to 777 for the osCommerce backup function to work properly. Hopefully the next release will fix this oversight in the Installer routine.

That’s all there is to it. Check your new catalog and the admin section to verify that all is working properly.

Once you are happy that the site installation is correct, you will need to take a couple of simple steps to secure your installation from unwanted visitors.

First, use your FTP program to re-name or delete the /installation directory; this is absolutely necessary to avoid someone from re-running the installation routine and thereby overwriting your site files or gaining access.

Second, you will need to limit permissions on key directories. During construction and customization of the site I find it easiest to leave directory and file permissions set to 777, but don’t forget to use CHMOD to lock these files down prior to launch, as follows:

/Directory/file Permission Level
/admin/includes chmod 755
/catalog/includes chmod 755
/catalog/images chmod 777
/admin/includes/configure.php chmod 644
/catalog/includes/configure.php chmod 644

Third, I will also typically insert a blank index.html file in all directories that you don't want browsed. It’s a very simple way to keep prying eyes out of your directory structures.

Finally, one of the security issues with osCommerce is that the default installation does not include password protection for the admin section. Again, fingers crossed that this gets fixed in the next release, but until then you must takes steps to plug this hole yourself. The most common solutions involve either using your web host control panel to password protect the directory, or modifying your .htaccess file to add password protection. There are also third party solutions that address this issue.

When you first visit the front end of your virginal site you’ll find that a number of the site features have been activated and illustrated with sample products. You’ll also see some explanatory notes occupying the central position on the catalog home page. Take a minute to read through this as it contains useful information. You’ll note that one of the references goes to explaining the text at the top of your page with the pink background -- this is the area where major warning messages appear from the system. Odds are the first time you look at your site you’ll see a warning at the top of the page:

Warning: I am able to write to the configuration file: /home/www/osctest/catalog/includes/configure.php. This is a potential security risk - please set the right user permissions on this file.

As noted above, you’ll probably want to hold off on fixing this issue until you finalize things and are ready to go live. Until then, you’ll have to live with this little reminder on all your pages.

Before we get into what you can’t do, or what you might want to change or add to make the system do more, let’s take a look at what it will do straight out of the box, so to speak.

A number of useful features are enabled by default. Site visitors are provided with a search function, the ability to sort by manufacturer, the ability to read product reviews or post some of their own. Useful product marketing features include a “what’s new?” function and “specials.” Users can also subscribe to product notifications by email and are provided with an option to email product information to their friends.

Visitors to the site can add products to a shopping cart without having to register. They are only prompted for login or registration when they decide to execute the order. By default the system is set to calculate shipping at a flat rate and to accept payment via credit card or cash on delivery. These options, and most others mentioned above, can be changed easily via the admin console. Most common payment gateways and shipping methods are supported in the default installation and many others can be added to the system by installing various third party solutions.

Registered users benefit from a variety of features including the ability to store multiple shipping addresses and maintain order histories.

osCommerce includes a variety of useful management tools for administering the catalog and handling orders. This is one of the areas where this tool excels and one of the best reasons for choosing the system.

Product listings carry all the information necessary for site visitors and for order processing, including product names, descriptions, weight, images, and model numbers. You can include pricing at both net and gross rates and select tax classes.

The system supports basic inventory tracking. You can input the number of units in stock, then as orders are placed the available total is automatically updated. You can set automatic re-stocking reminders that are triggered when user-defined inventory levels are reached.

Orders run through the system can be tracked by the catalog managers. The system generates basic invoices and shipping slips and as orders progress through your system, you can log the orders’ status and send email updates to clients.

osCommerce also produces a variety of basic order history reports, allowing managers to identify the most valuable customers and the most popular products.

System tools are somewhat limited. You can perform database backups and restore and you can control the caching, but that is about it. One the biggest complaints with osCommerce is the lack of content management tools for the non-catalog pages. Changing the copy on the content pages is arcane exercise involving visiting the Define Languages section under the Tools tab. Once there you find a list of file names. You then click on the name of the file you desire to change and edit the PHP code within the window. This approach is fraught with opportunities for non-technical staff to crater pages.

So, whether you are a customer, a catalog manager, or a webmaster, osCommerce has virtually every feature one needs to produce and manage a professional ecommerce presence. Now, while all that is well and good, users who want something dramatically less, dramatically more, or simply something different may find the system frustrating. This is where we start to separate the dudes from the duds, the hackers from the slackers…

osCommerce comes with only one template. The default installation, while it does include all the features one needs to get going quickly, is frankly neither very attractive nor very flexible.

It would appear the osCommerce team was more comfortable with the functionality aspects of the project than with the design aspects. When I speak of design I am referring to both the look and feel and the usability. Part of the problem is that the interface was designed years ago and is not aging very well -- it just looks old school.

The dated approach shows in the way the pages are built -- layer upon layer of nested tables. The system is absolutely clogged up with tables. CSS is not implemented effectively and even basic pages have hundreds of lines of code. Hence, customizing the front end’s appearance makes for some long hours in front of a screen.

But let’s step back a moment. Say, you’re not totally unhappy with the default installation. Say, instead of a complete facelift you only want to change the colors and upgrade the appearance with some improved graphics. If your ambitions are limited, you can do this easily by one of the oldest and simplest tricks in the book: overwrite the existing files with ones of your own.

osCommerce images are stored in two primary locations. The images directory holds a number of the generic icons and product-related images. Note also that the subdirectory infobox contains the rounded corners you see on the boxes in the left and right column on the front end of the default site. You can overwrite these with your own versions easily. Replace the osCommerce logo with your company’s logo to re-brand the site.

If you want to go further and re-do the graphical buttons on the site you have to look a bit harder. Buttons with text in them are kept in includes/languages/english/images/buttons. To access the buttons in the other two default languages, simply change the word english in the path to the desired language name. Again, overwriting these with buttons of your choice is an easy task and a fast and simple way to skin the site, assuming you like the default layout.

But now let’s reach further - say you don’t like the default layout. You want two columns, not three, or you want to move a box from one side of the page to the other (or elsewhere).

The next level of hacking the presentation of osCommerce requires you to dig into the underlying .php files. You had best be comfortable with working at the code level as WYSIWYG editor functions are of little help with osCommerce. So, fire up your fave editor and let’s look at 4 key files.

First, as a basic principle, osCommerce relies heavily on Server Side Includes as a way of emphasizing reuse of modules of code. As a result, knowing where to look for the key includes sets you on the right track.

The header and footer are the easiest to deal with, being called, respectively header.php and footer.php and being located logically in the includes directory. Hacking either of those files is a pretty simple matter and does give you quite a bit of room to maneuver.

The left and right columns are a bit more difficult. First, the columns themselves are the files column_left.php and column_right.php, located in the includes directory. So far so good. However, it turns out that the contents of the columns are almost entirely located inside of units osCommerce calls ‘boxes’ and those are different files altogether.

If you wish to remove a box from one of the columns, you can access the appropriate column file, find the line that refers to the box in issue, then comment out the 'include' line, or remove it totally. You can also move boxes from one column to another by cutting and pasting. If, on the other hand, you wish is to customize the appearance of any box, then you must visit the file that creates that particular box and modify it. All those files can be found in includes/boxes.

Now if all this so far has seemed pretty non-threatening, well, you are right. You want to change the colors and the graphics - no problem. You want to move around or delete come boxes and have a custom header and footer - really no problem there either. But now let’s say you don’t like the way the page layouts themselves are done. Step into my parlor said the spider to the fly…

This is where osCommerce becomes real fun and developers earn their money (as they guzzle liters of caffeine and rip out their hair). Turns out the default osCommerce file structure means that, despite numerous includes and database calls, the system basically uses different files for every single page and that making changes means going through every single page and making the changes over and over again (all the while testing and double checking to make sure you don’t introduce your own crafty little errors).

The good news is that at least you can use all the comment tags to help you. No, wait a sec, that’s the bad news. OsCommerce comment tags are essentially limited to “header”, “footer”, ”main body”, “left nav” and “right nav”. Hate to be negative, but thanks for nothing guys! You give us hundred of lines of nested tables and you can’t be bothered to add a few meaningful context-sensitive comment tags??

OK, that said, we live with what we get, so while you are in there hacking away you might want to go ahead and clean up that horrible nest of unnecessary tables and spacer gifs. You can knock out 20% of the page weight pretty consistently by simply killing off redundancy and shifting to a more aggressive CSS approach to positioning items.

Why not go all the way and dump these pages in favor of a pure, or at least mostly, CSS approach? This is one area where you should beware the sirens’ call. While it may initially seem tempting to just toss the whole structure I urge you to think carefully and take the word of one who has gone down that path before: osCommerce is a complex system and you will likely find that the slash and burn approach winds up having unforeseen negative effects. So, while you may be tempted, I urge you to resist. Look for other less destructive approaches to achieving your goals.

That brings us to our next topic…

The large and resourceful osCommerce community has responded to the lack of certain features by providing their own solutions. osCommerce calls the third party solutions “Contributions” and they are invaluable resources that allow you to extend and customize the feature set without having to re-invent the wheel (oh the joys of Open Source!).

Implementing a Contribution typically involves downloading the archive, unpacking it, then overwriting some of the default osCommerce files with new ones from the Contribution. More advanced Contributions require you to execute SQL queries to modify your database. (Do I need to say this? Back up your site and archive the original files before you install any Contribution. It isn’t simply a precaution against a Contribution being buggy, but rather more often you find the Contribution either doesn’t perform like you want it to or that it isn’t quite what you had hoped for and you wish to uninstall it.)

One of the most powerful and popular Contributions is called STS - Simple Template System. It allows you to build HTML page designs and then drop placeholders that call different osCommerce functions into your design. STS really opens up the front end of osCommerce and makes it possible to do heavily customized interfaces without delving deeply into the PHP pages of the default site.

Another personal favorite of mine is called Easy Populate. I love it because it lets me move large catalogs of products in and out of the system in a few clicks, thereby bypassing tedious key punching. Use this Contribution, save somebody’s life.

There are also legion of Contributions to enable support of a wide variety of languages, pricing and discount structures, shipping and payment methods and
additional catalog features. To get some idea of what is out there, go to the osCommerce site and explore: http://www.oscommerce.com/community/contributions
The page lists more than 2000 Contributions, ranging from mundane to marvelous.

Contributions are a godsend and will make your life much easier but never forget that they were not developed by the core osCommerce Team and as a result they often employ non-standard solutions to the problems at hand. As a result, while any particular Contribution may work with the core, it may not work with another Contribution. Your best bet to avoid problems is to plan very well and to use a dev server. Figure out exactly what features you will need, match Contributions to your wish list, then set it all up on a dev server and test it heavily before you deploy. Trust me on this: Retrofitting Contributions to an existing site is simply asking for punishment. Get it right before you let it loose in the wild (or make sure you have a support and maintenance contract in place!).

So there you have it - an osCommerce jump start. Don’t be put off by my whingeing about the difficult of hacking the tool; osCommerce is powerful and reliable and gets the job done. Now, at the end of the day which would you prefer: An easy to modify but unreliable system, or one that you may have to tussle with a bit, but always gets the job done? I’ll take the latter. (Besides, if it was too easy, clients wouldn’t need us!)

About the Author