PHP Super Cart 4.0 Installation/Configuration Documentation

Introduction

PHP Super Cart is the ideal shopping cart solution for merchants and web developers who wish to bring their business online with a full-featured shopping cart. PHP Super Cart is very easy to install and operate. PHP Super Cart requires a MySQL database which is easy to set up and is available on almost all PHP hosting platforms. PHP Super Cart has a robust catalog front-end for your web store. You can choose to use PHP Super Cart as your entire website, use it to display your catalog of products or just use the shopping cart feature. You can let PHP Super Cart build a dynamic menu of your product categories and list you products or you can build your own product pages with special links to the cart.

PHP Super Cart is 100% template-based and you can customize the look-and-feel of every page. Setting up the main template is easy and, depending on your site design, can take from about 5 minutes to over an hour to implement.  Once complete, PHP Super Cart will start to take on the look of your existing website. PHP Super Cart has a very powerful yet simple template system that gives you the flexibility to create the exact look you want for your shopping cart and your entire website. You can leave the templates as they are or you can customize the templates using your favorite HTML editor. 

PHP Super Cart is encoded.  It is not open source.  You have the choice of using Zend encoded software or the IonCube encoded version.  They are exactly the same script.  Why do we encode much of the script?  This protects both you and us.  By not exposing the core of PHP Super Cart it makes it much more difficult for hackers/crackers to exploit your website.  This protects you and your website’s integrity.

The PHP Super Cart script is encoded with the Zend encoder or the IonCube encoder. The Zend encoder requires the Zend Optimizer be installed on your web hosting server (most php web hosts already have this installed).  None of the template files are encoded, giving you complete control over the design of your website, catalog and cart.  This gives you the flexibility to modify key areas of PHP Super Cart to suit your needs.  The gateway modules, coupon system, shipping system and tax system are not encoded.

Installation

Step 1.

Download PHP Super Cart from the website. There are two different download files to choose from.  One is the Zend encoded cart and one is the IonCube encoded cart.  The script is exactly the same but the key script files are encoded by different methods.  If your web host supports the Zend Optimizer (most do) then download the Zend encoded cart.  If your web host does not support the Zend Optimizer then download the IonCube encoded version.  If your web host does not support either encoder then you will not be able to run PHP Super Cart in that hosting environment.

Step 2.

Unzip the downloaded PHP Super Cart zip file on to your local PC (you’ll need Winzip or some other zip file extractor software).  If you are familiar with unix and SSH, you can unzip PHP Super Cart directly on your web server.  PHP Super Cart will create a subdirectory called phpsupercart and all the files and directories will be created below that folder.

Step 3.

Log into your hosting control panel and create a database for PHP Super Cart.  You might call this database “cart” but your host may add your account name to the beginning of the database so your full database name may be “admin_cart” (where “admin” is your account name).  Remember this name.  It is not recommended to use an existing database as the PHP Super Cart database as some table names may conflict.

Step 4.

Use PHPMyAdmin (typically available from your hosting control panel) to upload the database.sql file that was included in the zip file from Step 2. Here you will use PHPMyAdmin to select the database created in Step 3.  Then click on the Import tab.  Browse to the /phpsupercart directory on your local PC and select the download.sql file.  Click the “Go” button to upload the file and create the database tables.  You must only do this one time.  This will create the database tables needed to run PHP Super Cart.

Step 5.

Use Notepad or a text editor on your local PC (do not use Word) on your workstation to edit the file /phpsupercart/Connections/catalog.php.  When editing this file you must change the following variables to match your database login credentials.

$hostname_catalog = “localhost”; // This is typically left as “localhost”.

$database_catalog = “admin_cart”; // Use the name of the database created in Step 3.

$username_catalog = “admin”; // This is the account name for your hosting account.

$password_catalog = “yourpassword”; // This is the password for your account name.

Save the file and exit Notepad.

Step 6.

Create a directory on your website where you wish to keep PHP Super Cart (typically public_html/phpsupercart but you can upload it to the main directory so it becomes your home page). Use an FTP program to upload (in BINARY mode) all of the files in your local /phpsupercart directory that were unzipped in Step 2 (don’t upload the actual zip file).  This will create the file structure. Remember to set your FTP program to upload in BINARY mode.  Most FTP programs default to ASCII mode.  Since many of the PHP files are encoded, they are now binary files and must be uploaded in BINARY mode.

Step 7.

Upload your license file.  The license file is called license.php and is specific to your domain name.  There are two different ways to get a license file. 

1.       Go to www.phpsupercart.com and create a demo license.  This license will be good for 30 days to allow you to evaluate every part of PHP Super Cart.  The demo license does not remove any features.  Everything runs exactly the same.

2.      Go to www.phpsupercart.com and purchase a license.  Once you complete the purchase, you can log in at www.phpsupercart.com/phplicenser/ and add your domain name.  You can then download your license file and upload it to your website.

PHP Super Cart will run in a limited functionality mode without a license file as well.

Patches

There may be one or more patches available for the version of PHP Super Cart you are running.  Check the forum to see if there are any patches that need to be loaded.  The forum will document the installation procedures for the patches.  This typically requires you to upload a few more files over the existing files on your site.

It’s now time to configure PHP Super Cart

You are now ready to log in to the PHP Super Cart admin control panel and start the configuration. Point your browser to:

http://www.yourdomain.com/phpsupercart/admin/

and log in.  If you installed PHP Super Cart in the root of your website, then the path is:

http://www.yourdomain.com/admin/

The default user name is “admin” and the default password is “password”.  Make sure you change your password immediately.

Warning: The catalog portion of PHP Super Cart will not work until you first log into the admin control panel and configure your installation. You must log in to the admin control panel and configure the installation.  This will only take a couple of minutes.

Configuration

After installation, point your browser to www.yourdomain.com/ phpsupercart/admin/ and login with the default username of “admin” and default password of “password”.

Scroll down to the Account Settings menu item (on the left) and click on Change Password.  Change your password immediately.

You will now need to go to each of the configuration pages and configure the settings on each page.  There are many configuration pages under the Configuration menu section.  Don’t worry, they are short and several do not need any configuration changes made. 

Here are some notes while configuring:

Installation Screen:

This is the most important configuration screen.  PHP Super Cart won’t work unless you configure this screen. You must set the following:

Web Path To Catalog - This is the full URL to the index.php file located in your phpsupercart directory.

Web Path To Cart - This is the full URL to the cart.php file located in your phpsupercart directory.  If you use a shared SSL certificate to protect your cart pages, be sure to use the URL your web host provides and not your domain name url.

File Path To PHP Super Cart - This is the server file path to the /phpsupercart directory.  An example might be /home/adminuser/public_html/phpsupercart/

Domains That Can Access The Cart - This needs to be set to the domains that are used such as  “yourdomain.com www .yourdomain.com”.  Notice that both the domain and the domain with www are included and are separated by a space.  If you are using a shared ssl certificate from your web host, make sure you enter the server name from your web host as well.  For example:  If your web host informs you that you can use a shared ssl certificate at https://secure.myserverhost.com/~myadmin then make sure you add “secure.myserverhost.com” to the allowable domains list.

Use Search Engine Friendly URLs - If your web hosting environment supports apache’s .htaccess file to rewrite URLs then you can enable this feature.  If you enable this feature then you must take the htaccess.txt file found in the /phpsupercart directory and upload it to the root of your website.  You must also rename the file by removing the file extension (‘.txt’) and putting a period in front of the name so the filename becomes “.htaccess”. 

Warning: this file will not work if it is in the /phpsupercart directory.  It must be in the root directory (example, you would be able to access it via “www.yourdomain.com/.htaccess”).

If you change the name of the installation directory from “phpsupercart” to some other directory or if you install the cart in the root directory or in a directory below one level deep (as in “www.yourdomain.com/catalog/phpsupercart”) then you will need to edit the .htaccess file to reflect the new directory structure.

Company Screen:

Information on this configuration page is displayed on several templates and emails.  If you don’t want certain information to show up you can leave the configuration field blank or modify the template file(s) and remove the TS tag for that configuration setting.

Payment Gateways

PHP Super Cart supports multiple payment gateways simultaneously.  There are two basic types of payment gateways.  Local gateways and remote gateways.  Local payment gateways take all of the payment information locally on your website.  Remote gateways send the client to third-party websites to process their payment.  You can activate as many gateways as you need.

Some gateways can be configured with certain return URLs depending on whether or not the payment was completed. Remember, not all payment gateways support these return URLs.  If you use a gateway that does not support returning the client back to the cart or if the user does not return after a successful payment for any reason, the order will show up in the Abandoned/Uncleared screen.  You can activate the order manually once you confirm payment.

Setting Up Your Template

If you have problems setting up your template please post in the forum for assistance.  It is not hard to set up the template and just takes a few minutes.  Setting up your template is extremely easy. You only need to set up one template to make PHP Super Cart look like the rest of your website.  First, you will need an html file of your template. Just take one of your web pages and make a copy of it and call it index.php. Next, clean out all of the data in the template so you just have your header and footer. Now, place the Template System Tag %%DATA%% right where you want the shopping cart to be displayed. Finally, upload your index.php file to the phpsupercart/template/classic/ directory (overwriting the original template). If you would prefer to use the “generic” shopping cart then copy your index.php file into the phpsupercart/template/generic/ directory and then log into the control panel and change your configuration option to the generic template (the default is the classic template).

If your template and cart don’t line up correctly, you may have removed too much  of the html code or not enough of the html code. You should insert your %%DATA%% tag right in between the table cell tags (<td>%%DATA%%</td>) that previously held the main content of the page (some web pages use <div> and </div> tags instead of <td> tags).  If you have problems with this just post in our forum and we’ll help you straighten this part out.

That’s it, your cart will now match the look of your site by using your own web page layout as the shopping cart layout. You can modify any of the existing templates that layout the rest of the shopping cart by modifying the files in the phpsupercart/templates/classic directory. You can see the full documentation on how to modify a template by viewing the PHPCart Template System (TS) documentation.

Remember, you can start out small by just making a few adjustments to the templates until you get a better understanding of how it works. Just make a backup copy before you start.

Shipping

PHP Super Cart has several options for calculating shipping.  They are broken down into 3 groups: By product, by weight, and by order.

By Product:

It is easy to add variable shipping/handling/postage fees by product when adding an item to your shopping basket. You can add a fee to each item by including the shipping variable.  This amount will be added for each quantity. If the customer orders 5 of an item then this amount will be added 5 times.

Use the shipping1 variable to set the shipping fee for the first item when the quantity field is set to higher than 1.  An example would be setting shipping1=2.95 for product A.  If the customer orders (on the same line) a quantity of 3 then the shipping for all three would still be 2.95.  This is different from the “shipping” variable which would charge 8.85 for shipping 3 items.

Use the shipping2 variable to set the shipping fee for each additional item after the first item.  An example would be setting shipping1=2.95 and shipping2=1.95.  If the customer orders (on the same line) a quantity of 3 then the shipping for all three items would be 6.85 (2.95 + 1.95 + 1.95).

By Weight:

You can assign a shipping fee based on the weight of your products.  You must do two things to make this work. First, you must assign a weight variable to the product.  Second, you must set up the Shipping By Weight table in the configuration screen. To assign the weight variable just add weight=5.25 to your product link.  When you set up the Shipping By Weight table you must enter a list of weights and charges using the following format:

            weight:fee;weight:fee;weight:fee

Enter a weight:fee pair (separated with a colon) and then add more weight:fee pairs (separated with a semi-colon).  Make sure the first weight:fee has a weight of 0 if you want a charge to be set for orders between 0 and the first weight.  Below is an example:

            0:1.95;10:5.95:25:10.95:50:15.95

In the above example the following shipping charges for the order would be:

·         If the total weight of all items was greater than 0 but less than or equal to 10 then charge 1.95

·         If the total weight of all items was greater than 10 but less than or equal to 25 then charge 5.95

·         If the total weight of all items was greater than 25 but less than or equal to 50 then charge 10.95

·         If the total weight of all items was greater than 50 then charge 19.95

Note:  With the above scenario if the total weight value of all items in the shopping cart = 0 or there is no weight value then the amount charged for shipping will be 0 unless another shipping rule adds a shipping charge.

By Order:

You can assign shipping fees based on the order.  You can assign a fee for each product or for the entire order.  You can set a free shipping level.  You can also set a shipping fee as a percentage of the total order. Finally, you can set a minimum or maximum shipping fee that will override all other shipping calculations. You can set these options in the configuration screen.

Taxes

PHP Super Cart allows you to determine if a customer should be taxed based on their state/region or by their country.  You do this by assigning up to two different tax rates to that state/region or country in the tax configuration screens. You can then either configure each product to be taxible/non-taxible or you can just set PHP Super Cart to tax all products (if the customer is taxible). PHP Super Cart allows you to assign one of two different tax codes to each product so if you sell products that must be taxed at different rates you can easily set this up.

In order to tax a customer, that customer must be considered taxible.  Taxibility is determined based on the state/region and country the customer is in.  You must edit the States/Regions Tax Settings and/or the Country Tax Settings in the PHP Super Cart control panel.  You can add/modify states/regions and countries and then assign two tax rates two each state/region or country.  If a product is assigned a taxrate id of 1 then any taxible customer will be charged the taxrate1 tax rate as assigned to that state/region or country.

Instead of assigning a taxrateid to each product you can set a flag in the configuration of PHP Super Cart that sets all products to be taxed if the customer is taxible.  You can also set a flag in the configuration to determine if shipping should be taxed.  If the customer is taxible and shipping is taxed, it is taxed at the taxrate1 tax rate. 

PHP Super Cart allows you to set a default tax rate.  This rate will be used if the shopper has not yet provided billing information.  You can configure the default state/region or country from the Tax Configuration screen.

PHP Super Cart allows you to display prices in the catalog and the cart with the tax included.  You can configure this from the Tax Configuration screen.

Creating Your Own Content Blocks

The PHP Super Cart Ecommerce System allows you to easily add and edit your own content by using content “blocks”.  Content Blocks allow you to choose when, where and how to display content along with your category and product pages.  You can use Content Blocks to display rotating advertisements, messages, reviews, FAQs, help topics or any other type of information.  Blocks are integrated into the Template System by using special TS Comments and TS Tags.  Once these are set up in your template you can manage the content from within the admin control panel (under the Content Blocks configuration menu).  See the Template System documentation on how to set up your template to support Content Blocks.

Once a Content Block is set up in your template, you can manage the content from within the admin control panel.  Content Blocks have 3 components:  The “block” component, the “list” component and the “item” component.

The block component of a Content Block is the part of the content that shows up as a small section of your template, typically off to the side (below your menu) or at the bottom of your page in the footer area.  However, the block component can appear anywhere such as the heading/logo area, etc.  The main site template defines how a particular block component will look.  The block title, item title, item text and item date can all be displayed.  You can also choose how many items to display in the block and whether or not they show up in a random order.

The list component is a way to show all of the items in a block in a list view.  The list view shows up in the body area of the template (where the categories and products usually display).  In the list view you can display the block title and then you can display individual sections for each item title with the individual item text displayed below.

The item component shows in the body area of the template and displays the full text of the individual block item that is selected.  Item text can be html code so you can really design just about anything you need to show.

Coupon System

PHP Super Cart supports coupons. A coupon can give a fixed amount discount, a shipping discount or a percentage of the subtotal discount. Coupons can also be set to expire. Discounts are calculated based on the subtotal of the order.

If a coupon gives a fixed amount discount and the subtotal is less than the discount then the subtotal becomes the discount amount. Example: Discount is $10 but the subtotal is $9. The customer only gets a $9 discount. The extra $1 will not go towards shipping or postage or tax. You can add an unlimited number of coupons in the admin section. You can not edit a coupon but you can easily delete and recreate a coupon if you make a mistake. Remember the percentage discount must be in whole numbers such as 35 (for 35%). Don’t enter .35.

Displaying Cart Info On Your Own Pages

If you create your own web pages outside of PHP Super Cart, you may want to display some information to the shopper about the contents of their cart.  PHP Super Cart comes with a php file called minicart.php.  Include minicart.php at the very top of your web page by using the following syntax:

<?

include('Connections/catalog.php');

include ("includes/functions.inc.php");

include ("includes/minicart.php");

?>

NOTE:  You must include the above lines as the first line of the file.

You can now display the following pieces of information about the content of the shopping cart:

To display any of the information above you must add some PHP code right where you want the data to appear.  It is very easy to do.  The syntax is:

<? echo $_SESSION["XXX"]; ?>

Enter the above line exactly where you want your data to appear.  You will change the actual variable name XXX to match the variable name of what you want to display.  Below is a table that lists the different pieces of information along with their variable name

Product count

PRODUCTCOUNT

Item count

ITEMCOUNT

Total shipping

TOTALSHIPPING

Total taxes

TOTALTAX

Total discount

DISCOUNT

Grand total

GRANDTOTAL

You HTML code might look like the following:

<p>You have <? echo $_SESSION["ITEMCOUNT"]; ?> item(s) in the basket.</p>

Newsletters

The newsletter feature in PHP Super Cart is very easy to use.  The billing screen templates are already designed to support newsletter signups during the shopper checkout.  There are three components to the newsletter set of features. 

1.       Shopper signup

2.      Administrative back-end (admin control panel)

3.      Shopper unsubscribe

When a shopper checks out, they are given the option to sign up for your newsletter.  They can choose either HTML or plain text.  Once they complete the checkout, their choice is stored in the database and their account is flagged as subscribed.

When you are ready to send out a newsletter you have two choices.  You can send out emails via the PHP Super Cart admin control panel or you can export a list of subscribers to use with your favorite newsletter system.  If you choose to email all subscribers via the admin control panel, simply create a new newsletter in both HTML and plain text and save it.  Then, click on the Send button to send the newsletter to all subscribers.

When you create the newsletter you can insert a couple of different TS Tags to customize the newsletter.  You can include the First Name, Last Name, Email Address and also the unsubscribe URL. 

·         First Name = %%FIRSTNAME%%

·         Last Name = %%LASTNAME%%

·         Email = %%EMAIL%%

·         Unsubscribe URL = %%UNSUBSCRIBEURL%%

When a subscriber receives the newsletter, they can click on the unsubscribe URL to unsubscribe from the newsletter system. 

Administrators can also delete subscribers from the newsletter database.

Downloadable Products

PHP Super Cart supports downloadable products, also known as electronic delivery of soft good.  Each product can have an unlimited number of downloadable files associated with it and each file can be associated with an unlimited number of products.  Files can be uploaded via the Admin Control Panel or can be uploaded via FTP.  The file directory can be changed to any name and can be moved outside of your web root to help prevent direct downloading of files by unauthorized customers.

There are several configuration options involving downloadable products.  From the Cart Configuration screen in the Admin Control Panel, you can set the download directory and the number of hours after a sale that a downloadable file is available to the shopper.

The download file path is the true server path, not the path from your web root.  If your website files are stored on the server in a directory called /home/youdomain/public_html/ then you may wish to use a directory called /home/yourdomain/downloads/.  Note that because the directory ‘downloads’ is not in the public_html directory, web surfers will not be able to directly access your download files via the browser.

You can upload files via the Admin Control Panel.  To do so, the download directory must have permissions set to 777.  This can be a security risk.  The alternative is to set permissions to 644 and then just upload your files via FTP.  Once you have uploaded your files into the download directory via FTP, you can then add them to products.  Either technique will work and you can switch between one and the other as needed.

Copyright Notice

Please note that all files in this distribution are copyright the Author. You may not re-distribute any portion of the distribution without the expressed permission of the author.

License

You have purchased a copy of PHP Super Cart. Depending of your license you may not be able to use this cart on as many subfolders and domain names as you like.  Please read the license agreement file licenseagreement.txt that is distributed with your copy of PHP Super Cart. You are bound by the license agreement once you install PHP Super Cart.