Introduction
PHPCart is the ideal shopping cart solution for merchants who wish to bring their business online with a full-featured shopping cart. PHPCart is very easy to install and operate. Furthermore, PHPCart does not require a database, thus reducing the fuss and complexity normally associated with other shopping cart solutions. PHPCart is not a catalog front-end for your web store.  You build your own product pages with special links to the cart.  PHPCart is template-based and you can customize the look-and-feel of every page. Setting up the main template is easy and takes about 5 minutes.  Once complete, PHPCart will start to take on the look of your existing website. PHPCart has a very powerful yet simple template system that gives you the flexibility to create the exact look you want for your shopping cart. You can leave the templates as they are and run your ecommerce site or you can customize the templates using your favorite HTML editor.  The PHPCart script is encoded with the Zend Encoder and requires the Zend Optimizer be installed on your web hosting server (most php web hosts already have this installed).  Only a few key files are encoded.  This gives you the flexibility to modify key areas of PHPCart to suite your needs.  The gateway modules, coupon system, shipping system and tax system are not encoded.  And, of course, none of the templates are encoded so you can make PHPCart look just the way you want.

Installation
Create a directory on your website where you wish to keep PHPCart (typically PHPCart). Upload (in BINARY mode) the distribution package and unpack it with the following commands (via telnet):

gunzip phpCartx.x.zip (where x.x is the version number)

If you do not have telnet access to your server (e.g. if you are using Windows NT/2000), you must unpack the distribution with WinZip or similar program, and then upload each file by FTP (in BINARY mode).

If you are using PHPCart on Linux, make sure the script has read and write access (777) to the sessions directory and the orders directory. You can do this by typing chmod 777 sessions and chmod 777 orders via telnet. Alternatively, use your FTP program to change the permissions.

You must also set write access to the following files in the admin folder:
admin_1.php
configuration_1.php
coupon_1.php
payment_1.php
processor_1.php
regions_1.php
countries_1.php

Upgrade
Upgrading from a previous 4.x version of PHPCart is very easy.  Follow the below steps and remember to upload all files in BINARY mode:

1.      Make a complete backup of your PHPCart installation (just to be safe).

2.      Make absolutely sure you have backed up any files that you have customized (did you remember the template files?).

3.      Upload all files and directories in the admin directory except the following:
admin_1.php
configuration_1.php
coupon_1.php
payment_1.php
processor_1.php
regions_1.php
countries_1.php (this is a new file, if it doesn't exist, upload it)

4.      Upload all other directories except the templates directory (check to see if there are any new template files and upload them).

5.      Upload all files in the main directory (phpcart.php, etc)

6.      If you have customized any files (such as the shipping module) copy your customized file back over the new version

7.      Log into the admin control panel and select the Configuration menu choice.  Verify all configuration options (some may be new) and save your configuration.

8.      Run through a test order to make sure everything is working properly.

Configuration
After installtion, point your browser to yourdomain.com/phpcart/admin/ and login with the default username of admin and default password of password. Make sure you change your password and then move on to edit the settings required to run PHPCart. The Configuration settings contain configurable variables you must change before using PHPCart. All variables are self-explanatory. They contain information such as company name, your email address, what colors to use and other information used by PHPCart. You must also set up at least one payment method in the Payment Configuration section before running the cart. You will need to review and modify the States/Regions Tax Configuration settings as well (see the Taxes section below).

Payment Gateways
PHPCart 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.

To activate a gateway, log into the admin control panel and select Gateway Settings from the menu.  You can now activate and deactivate any of the gateways.  You also need to set the Display Name for the gateway (only if activated).  Once a gateway is activated you must click on the Configure link next to the gateway name and set the unique configuration options for that gateway.  Once that is complete, your gateway is ready for use.

Some gateways can be configured with certain return URLs depending on whether or not the payment was completed.  If you wish to have the client return you can use the following URLs.

·        http://www.yourdomain.com/phpcart/phpcart.php?action=complete (send to this page if the payment was completed successfully)

·        http://www.yourdomain.com/phpcart/phpcart.php?action=canceled (send to this page if the client canceled the order)

·        http://www.yourdomain.com/phpcart/phpcart.php?action=declined (send to this page if the payment was declined)

Remember, not all payment gateways support these return URLs. 

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 PHPCart 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 template.php. Next, clean out all of the data in the template so you just have your header and footer. Now, just place the Template System Tag %%DATA%% right where you want the shopping cart to be displayed. Finally, upload your template.php file to the phpcart/templates/classic/ directory (overwriting the original template). If you would prefer to use the "generic" shopping cart then copy your template.php file into the phpcart/templates/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 html or not enough html. 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.  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 phpcart/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.

Preparing Your Shop
This is the real easy part. As PHPCart does not use a database of any kind to store information about the products in your shop, all information about each product (description, price etc.) must be included in the link to PHPCart.

Create your product web pages as usual. For each product on your web pages, create a link that surrounds the image or title of the product or create a form with hidden fields and an "Add To Cart" button. Whatever you have will work. In the link include the web-path to phpcart.php.

You can use the Code Generator in the Control Panel to generate your product links.  You can also create them via a scripting language or by hand.  When creating them include the following variables:

• action - always 'add'. required
• id - product ID. required
• descr - product description (short sentence, url encoded; see below). required
• price - product price (must be numerical). required
• quantity - quantity of product to put in basket. required
• weight - weight of the product (must be numerical). Used if shipping charges are calculated by weight. optional
• shipping - Amount to charge per item for shipping/handling/postage. optional
• shipping1 - Amount to charge for the first item for shipping/handling/postage.  See the Shipping section for more information. optional
• shipping2 - Amount to charge for each additional item for shipping/handling/postage. See the Shipping section for more information. optional
• taxrateid - Tax group of this item.  See the Taxes section for more information. optional
• option[] - This allows you to pass an option such as product size or color plus an extra charge to add to the price of each item. optional
• option[] - You can have unlimited options by simply adding more option[] fields.  See the Options section. Optional
• option1 - This is another way to pass options.  Use this form when passing text options. Optional
• option2 - Just increment the number (option3, option4, etc.) to add more options. Optional
• extra1 - This is an extra field.  See the Extra Variables section for more information. Optional
• extra2 - This is an extra field.  See the Extra Variables section for more information.. Optional
• extra3 - This is an extra field.  See the Extra Variables section for more information.. Optional

As an example, consider the following link:

<a href="/phpcart/phpcart.php?action=add&id=1001&descr=Nike+T-Shirt&price=19.95">Add To Cart</a>

This is the minimum amount of information required to add a product to PHPCart.  Here is another example of a link (broken into two lines)

/phpcart/phpcart.php?action=add&id=1001&descr=Nike+T-Shirt
&option[]=Green:2.95&option[]=Small&price=19&quantity=1&shipping=1.59&taxrateid=1

In this case, the variables above have been assigned the following values:

• action - add
• id - 1001
• descr - Nike T-Shirt
• option[] - Green:2.95 (this will charge 2.95 extra for each item)
• option[] - Small (no extra charge)
• price - 19
• quantity - 1
• shipping - 1.59
• taxrateid - 1

Notice how each variable is separated by the ampersand (&). When your customers click on the link, the product will be added to their shopping cart automatically by PHPCart. If you have characters other than letters and numbers in the desription you will need to encode them. You can use the php function urlencode($descr) to replace these characters properly.  This will replace spaces with a plus (+) and replace ampersands (&) with the html special character equivalent ( %26) which are the most common problems when passing product info.  Always test your links on different machines with different browsers to make sure they all work correctly.

Here is an example as a form (with a drop-down for each of the options and a drop-down for the quantity)

<form name="anything">
<input type="hidden" name="action" value="add">
<input type="hidden" name="id" value="1001">
<input type="hidden" name="descr" value="Nike+T-Shirt">
<input type="hidden" name="price" value="19">
<input type="hidden" name="quantity" value="1">
<input type="hidden" name="shipping" value="1.59">
<input type="hidden" name="taxrateid" value="1">
<select name="quantity>
<option value="1 ">1 </option>
<option value="2">2</option>
<option value="3">3</option>
</select>
<select name="option[]">
<option value="Green:2.95">Green - $2.95</option>
<option value="Yellow:1.95">Yellow - $1.95</option>
<option value="Blue">Blue</option>
</select>
<select name="option[]">
<option value="Small">Small</option>
<option value="Medium:3">Medium - $3.00</option>
<option value="Large:5.95">Large - $5.95</option>
</select>
<input type="submit" value="Add to Cart">
</form>

In the example above we use a drop-down selection box to allow the customer to choose the quantity.  You could also use a text box to allow the customer to select the quantity to order.  If the quantity field is left blank then PHPCart will automatically assign a quantity of 1 to the product.

Displaying The Cart Total On Other Pages
You can easily display the cart total and the number of items in the cart on other web pages. You can control the layout of this information by editing the minicart.php template file.  Below are the steps required to add the Cart Total to any web page.

1.      The page must have a ".php" extension or the php code will not work.

2.      Edit the template file minicart.php to match your site layout

3.      Include the minicart.php file exactly in the code where you want the cart total to appear.  Example:
<? include("phpcart/phpcart-display.php"); ?>

That's it.  You can review the Template System documentation to find out which variables are available to be displayed.

Validation
The standard validation setup for PHPCart is configured in the admin control panel.  From the Cart Configuration screen you add the text you want to be displayed if a field is left blank.  If you do not want a field to be validated then just leave the text blank for that field name.  Example:  If you do not want to validate the phone billing field then delete all the text from the Text for Phone field in the Cart Configuration screen. 

Billing Variables
Any form variable you add to the billing template (billing.php) will be available on all other templates (except the cart.php template).  You can easily have clients submit additional information on the billing screen and then add that information to the admin's email template.  An example might be to add a drop-down select box listing where the customer found your site (such as search engine, print ad, mailer, etc).  If the name of the field was "referredby" then you could add this field to the admin email with the TS Tag %%REFERREDBY%%.

Localization
PHPCart is by default in English. In addition, we now support Italian, French and Spanish with thanks to our members. There are just a few phrases used throughout PHPCart that can not easily be put in the template system so they are put in a language file that is easy to edit.

You can translate the included language file to your own language if there is no translation. To do so, make a backup copy the file english.php in the /localization directory. Now, just edit the file and replace every string within double-quotes to the equivalents in your language. Save the file in the /localization directory. To activate your language, just make sure you have selected the English language in the configuration screen of the control panel.

Shipping
PHPCart 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 that 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
PHPCart 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 PHPCart to tax all products (if the customer is taxible).  PHPCart allows you to have two different tax codes per 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 PHPCart 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 PHPCart 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. 

Options
PHPCart supports an unlimited number of options for each product.  In addition, each option can have an extra price associated with it.  For example, you can have an option that determines the size of the item. The choices for that option might be small, medium or large.  You can assign a different price for each choice such as 0.00 if the customer chooses the small choice, 1.95 if the customer chooses the medium choice or 2.95 if the customer chooses the large choice.

There are three different ways to send options to the cart:

1.      use the format "option[]". This is the quickest and easiest to set up options.

2.      use the format "optionX" (where X is a unique number for each option). This is required if you want to use radion buttons as your option.

3.      use the format "optionX[]".  This is required when the option is a text field (see below).

When setting up options you will need to use a form to submit all the cart data (see the section above labeled Preparing Your Shop).  Inside the form you will need to create some sort of choice for the customer to choose.  You can present the optional choice to the user in several ways:

1.      Select Box

2.      Check Box

3.      Radio Button

4.      Text Box

Select Box Option:
You can use a select field for each option and an option field for each choice.  The value parameter of the option field needs to list the text of the option and optionally an additional charge to be applied for that option.  The charge must be separated from the text by a colon.  Also, make sure the text of option is url encoded (use the urlencode() function in php or manually replace any spaces with the %20 string. Example:

<select name="option[]"> // optionally <select name="option1">
  <option value="Size Small">Small</option>
  <option value="Size Large:2.50">Large - $2.50</option>
</select>

Or

<select name="option1">
  <option value="Size Small">Small</option>
  <option value="Size Large:2.50">Large - $2.50</option>
</select>

Check Box Option:
Using a check box option is very simple.  Each check box represents one option.  Example:

<input type="checkbox" name="option[]" value="Gift Wrap:5.95"> Gift Wrap
<input type="checkbox" name="option[]" value="Express Delivery:8.95"> Express Delivery

Or

<input type="checkbox" name="option1" value="Gift Wrap:5.95"> Gift Wrap
<input type="checkbox" name="option2" value="Express Delivery:8.95"> Express Delivery

Radio Button Option:
Radio buttons typically come in groups so you can only use the "option1" form when creating your radio button field.  Example:

<input type="radio" name="option1" value="Color Blue"> Blue
<input type="radio" name="option1" value="Color Red"> Red
<input type="radio" name="option1" value="Color Yellow"> Yellow

If you have a second set of options you would add them as follows:

<input type="radio" name="option2" value="Smooth Finish"> Smooth Finish
<input type="radio" name="option2" value="Rough Finish"> Rough Finish

Text Box Option:
This text box option is slightly more difficult because you can not control what information will be passed to the cart.  You use a combination of both naming conventions and must pass a second hidden field when you set up a text box option:

<input type="text" name="option1[]">
<input type="hidden" name="option1[]" value="Engraving:5">

Extra Variable
You can pass up to 3 extra variables to the shopping cart when you add a product.  These variables can be used for anything and are fully supported by the template system.  The extra variables are:

extra1
extra2
extra3

When you modify a template to display one of the 3 extra variables you can wrap a TS Comment around the TS Tag.  If the variable is empty, the comment and tag will be removed. You can find out more about how to implement the extra variables by referring to the Template System documentation.

The default templates already use the extra1 variable as a way to pass in a return URL to the product detail page.  This allows the customer to click on a link in the shopping cart to return back to the product detail page.  If you do not include any information in the extra1 variable then the link will not be displayed.  If you want to use the extra1 variable for something else, you can simply modify the cart.php file and remove the existing html code and add your own.

Coupon System
PHPCart 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. Add 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.

Making PHPCart work on Windows NT/2000
PHPCart uses the native PHP mail() function for sending out emails when a customer submits his order. You need to do some minor tweaking to make PHP send emails on NT/2000 platforms.

1. Install Microsoft Exchange Server on your server. Create an Internet Connection in the Exchange server giving the name or IP address, on which your ISP is running an SMTP server. Say we give a name to the exchange server MYEXCH. You can contact your ISP and ask him to give you the gateway or the IP address on which your ISP is running the SMTP server.
2. Modify your php.ini file section of the [mail] to include SMTP = MYEXCH. Put a valid e-mail id. Then the mail() function should be able to send email.

If you do not have Exchange Server software you can use Smart Server and Internet Anywhere Mail Server to connect to the gateway of your ISPs SMTP server to send email.

Frequently Asked Questions

• "How can I force the cart content to expire if the customer leaves my web-site?"
  PHPCart uses a php session variable to track customers. The cart contents will expire when the session variable expires or when the visitor closes their browser..
• "Why do I get the error message 'Permission denied'"?
  You probably forgot to set write permission on the sessions directory. See the installation section above for more information.
• "How can the customer delete all contents in his/her cart?"
  Add the following link in your header or footer file (modify to suit your language):

·                <A HREF="phpcart.php?action=clear">Clear Shopping Cart</A>

• "How can the customer view the contents in his/her cart?"
  Add the following link in your header or footer file (modify to suit your language):
  <A HREF="phpcart.php?action=view">View Shopping Cart</A>
• "I get a bunch of garbage on my screen after installation"
  Make sure you upload your files via FTP in binary and that your web host has the Zend Optimizer installed.  This is not the same as just having the Zend Engine installed.

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 PHPCart. Depending of your license you may not be able to use this cart on as many subfolders and domain names as you like.
Help and support is available in our Forum available via our website: PHPCart Web Site