Troubleshooting Login Related Problems in Zen Cart

You may face problems during login as a customer, or in the administration area. These problems are mainly due to some settings which control session handling and the authentication of users. The following sections highlight some common problems related to login.

Session Handling in Admin Area

It has been said earlier that Zen Cart's sessions are managed using the PHP session handling features. In general, it works as follows:

  1. A session is generated upon login of a user. For customers, the session's name is zenid, and for admin users, it is zenAdminId.
  2. On starting the session, PHP attempts to set a cookie in your browser. The cookie stores that session ID so that it does not need to be shown in the browser URL all the time. If the session ID is not in the cookie, it is shown as part of the URL; something like &zenAdminID=243524524524525 is appended to the URL. If a cookie is set, the session ID is in the cookie, and the session name and number don't need to be appended to the URLs. Zen Cart needs this session ID to keep you logged in.
  3. When you log out, or the session ID is lost, the session data is reset and your authentication data is removed. As the session ID is lost, you need to login again. This generates a new session ID.

Starting from Zen Cart v 1.3.8, a security token is generated, and embedded in the login form to identify that same person while logging again.

Understanding this session management helps you identify the cause. As discussed earlier, you may identify a problem while generating session ID, storing it in cookies, retrieving it from a cookie, or while re-using it. Session management problems may occur when Zen Cart cannot recognize the user's session ID:

  • When cookies are blocked by a firewall, or a browser configuration. If you are using a firewall, first check whether it blocks cookies. If not, suspect the browser. By default, browsers receive cookies. However, in case of a problem, you should check the browser's configuration options.
  • When PHP is configured wrongly, or has certain session settings set to methods incompatible with Zen Cart, such as session-auto-start and transitive-sid. You will get warning messages during installation if these PHP settings are found at that time. However, these may change after installation, and create problems to your Zen Cart's session management.
  • When you have configured your site to store session data in files but your file system does not have permissions to write on the files. Appropriate permissions to the session file may be the problem.
  • When you have configured your site to store session data in the database but the database table (that is zc_sessions) is corrupt, or the database storage is full and new records cannot be added.

Sometimes this may occur that you cannot remain logged in to the admin area. This shows the problems of handling PHP sessions in Zen Cart's administration area. First, try closing the browser windows, clearing the browser cache, cookies, and restart your computer. In most of the cases, this will solve your problem if that is due to caching of cookies in the browser. If the problem is not related to caching, it may also be due to incorrect SSL configuration. To solve such problems, edit your /admin/includes/configure.php file and change ENABLE_SSL_ADMIN to false. Then, clear browser cache, cookies, and try again.

Security Error during Login as Customer

If you have upgraded to Zen Cart v 1.3.8, you may receive an error message while trying to login, "There was a security error when trying to login".

This happens due to the fact that Zen Cart v1.3.8 has an added security feature to prevent spoofed external logins. All login forms have been designed to include a security token field. When a user tries to login, the security token is also submitted with the username and password. This security token needs to be current in order to login successfully. If the security token field is not the current one, or is outdated, then an error will be thrown.

If you have a customized template's login files, there is a possibility that the old files don't have that security token field with the login form. You need to merge new security features into the login file template.

In general, the following files are affected by this new security feature:

  • /includes/templates/CUSTOM_TEMPLATE/templates/tpl_login_default.php'
  • /includes/templates/CUSTOM_TEMPLATE/templates/tpl_timeout_default.php'

And for admin area the file will be: /admin/login.php.

In tpl_login_default.php, you find the following code block:

<label class="inputLabel" for="login-password"> <?php echo ENTRY_PASSWORD; ?></label>
<?php echo zen_draw_password_field('password', '', zen_set_field_length(TABLE_CUSTOMERS, 'customers_password')
. ' id="login-password"'); ?>
<br class="clearBoth" />
</fieldset>

You have to insert the following line of code before the code block shown above:


<?php echo zen_draw_hidden_field('securityToken', $_SESSION['securityToken']); ?>

Similarly, you have to add the above line in the tpl_timeout_default.php file.

Additionally, if you have customized your /includes/functions/sessions.php file for some reason, you'll also need to merge the new changes for this core file into your customized version. In your old customized /includes/functions/sessions.php file, you will find the following code block:

function zen_session_start() {
@ini_set('session.gc_probability', 1);
@ini_set('session.gc_divisor', 2);
if (defined('DIR_WS_ADMIN')) {
@ini_set('session.gc_maxlifetime', (SESSION_TIMEOUT_ADMIN < 900 ? (SESSION_TIMEOUT_ADMIN + 900) :
SESSION_TIMEOUT_ADMIN));
}
return session_start();
}

For Zen Cart v 1.3.8, you need to change the line return session_start();. Now the code looks like this:

function zen_session_start() {
@ini_set('session.gc_probability', 1);
@ini_set('session.gc_divisor', 2);
if (defined('DIR_WS_ADMIN')) {
@ini_set('session.gc_maxlifetime', (SESSION_TIMEOUT_ADMIN < 900 ? (SESSION_TIMEOUT_ADMIN + 900) :
SESSION_TIMEOUT_ADMIN));
}

$temp = session_start();

if (!isset($_SESSION['securityToken'])) {

$_SESSION['securityToken'] = md5(uniqid(rand(), true));

}

if (ereg_replace('[a-zA-Z0-9]', '', session_id()) != '') session_regenerate_id();

return $temp;
}

Note - The best way to reflect these changes in your custom template file is by using a file comparison, or a merging tool such as WinMerge. You can see the differences and merge them using this tool.

Forgotten Admin Password

The password for the administrator account is assigned during the installation of Zen Cart. Once the installation of Zen Cart is finished, you can log in to the administration area by using the admin account and its password. If you forget the password for the admin account, there is an easy way to get a new password. In the admin login page, click on Resend Password, and then type the administrator's email address and click on the resend button. A new password will be sent to that email address. You then can log in using that password.

If for some reasons you cannot retrieve the admin password using the Resend Password feature, you have to create a temporary admin password for logging into the administration area. However, you need access to your MySQL database. Usually, you get cPanel and phpMyAdmin installed on your server.

For creating a temporary admin account and password to login to the administration area, follow these steps:

  1. Login to cPanel and run phpMyAdmin.
  2. Click on the SQL tab and run the following query:
    DELETE FROM admin WHERE admin_name = 'Admin';  INSERT INTO admin (admin_name, admin_email, admin_pass, admin_level) VALUES ('Admin', 'admin@localhost',  '351683ea4e19efe34874b501fdbf9792:9b', 1);

    If you are using a prefix to the Zen Cart database tables, add that prefix with the table name, for example, INSERT INTO zc_admin.

  3. Running the above query will create an admin account with the password as admin. Now, you can log in to the admin area using the username admin and password admin.
  4. Change the password and email address once you have logged in to the administration area.

For more information on Maintenance an Troubleshooting of Zen Cart, please consult Chapter 9: Maintenance and Troubleshooting of Zen Cart: E-commerce Application Development by Suhreed Sarkar (Packt Publishing, 2008).This is excerpt from that chapter and made available with kind permission of the publisher.

Sample Chapter: Promotions and Public Relations

As part of their policy, the Packt Publishing has released this sample chapter (Chapter 6: Promotions and Public Relations) from my book. You can download this and read it to learn how you can promote your products in a Zen Cart-based shop, and also mainatin public relations to promote your shop and the products.

Create a New Zen Cart Template

Whenever you create a Zen Cart based e-commerce site, you need to change one thing, at least. It is site's look and feel. If you use Zen Cart's default theme, that will show your site in a common look, which is a barrier for branding your shop. You need to change the look of your site. You can do it by two ways: use some third-party templates designed for Zen Cart, or develop a template for Zen Cart at your own. In my book Zen Cart: E-commerce Application Development, I have tried to describe how to build a Zen Cart template. A full chapter is dedicate on building a template and customization of existing templates. My publisher, Packt Publishing, has kindly made the chapter available to public. Please read the article Creating a new Zen Cart template.

Integrating Zen Cart with popular Content Management Systems

There are various types of Content Management Systems (CMS) which are widely used for building and managing a website. Although Zen Cart is very good for running an online shop, it cannot be used for building a company website. Your organization may have a website running a CMS, and as you are going to open an online shop, you may need to integrate Zen Cart with that existing CMS. In my book Zen Cart: E-commerce Application Development, I have added an chapter of integrating Zen Cart with several popular content management systems. The publisher of my book, Packt Publishing Limited, has kindly made this chapter available to public. You may like to have a look at it and find your solution for building a shopping application which can be integrated with your existing CMS. Check the article at http://www.packtpub.com/article/integrating-zen-cart-with-content-management-systems.

Create coupons in Zen Cart: Video Tutorial

One of the great features of Zen Cart is to configure coupons and sending those to the customers. The coupons in Zen Cart can be used for discount by the customers. In Zen cart, you can also sell coupons as gift certificate. To learn, how to create a coupon in Zen Cart, view the video below.

For a step-by-step guide on building a Zen Cart e-commerce site, including configuring coupons and gift voucher, read the book Zen Cart: E-commerce Application Development, published by Packt Publishing

.

Installing Zen Cart

Before installing Zen Cart on your server, ensure that you have the required server environment. As prerequisites, you need a web server that can support PHP and run MySQL database server. The following sections describe the prerequisites for installing Zen Cart in more detail.

The minimum recommended server requirements for Zen cart installation is:

  • PHP 4.3.2 or higher (PHP 4.4.x for optimal performance),
  • Apache 1.3.x and higher; and
  • MySQL 3.2.x or higher.

Although  Register Globals may be on or off, it is recommended to keep safe_mode off. For many shipping and payment modules, CURL has to be installed/compiled with PHP.

Support for HTTPS may be required depending on the payment methods being accepted. The use of SSL during account creation and check out is also recommended.

At present, Zen Cart does not officially support PHP5. However, many shops are successfully running on servers, using PHP5. In August 2007, it was announced on Zen Cart's website that Zen Cart version 1.4 and higher will require PHP 5.2 as the minimum.

Web Server

You can use Zen Cart on Apache, Microsoft IIS and other web servers that can support PHP. If you are using Zen Cart for development or testing purposes, you may have local web servers such as Apache or IIS installed. For live shops, you must have a web server running for live websites. You may have a dedicated web host server or a shared web server for hosting. There are a lot of web hosting companies offering budget web hosting on Linux-Apache-MySQL-PHP hosting. On windows server, PHP or MySQL may not be available in a standard hosting package.

For your local computer, you may install web server, PHP and MySQL server separately, or install one of the following bundled packages :

  • WAMP: WAMP is a package of Apache-MySQL-PHP for Windows computers. You can download it from http://www.wampserver.com and install it as a windows application. You can get Apache, MySQL and PHP running within a few minutes. You will also have phpMyAdmin pre-installed to administer MySQL databases.
  • EasyPHP: EasyPHP, a package of Apache-MySQL-PHP, is simple to install and use. You can download it free of charge at http://www.easyphp.org.
  • XAMPP: XAMPP is an easy-to-install Apache distribution containing MySQL, PHP and Perl. XAMPP is very easy to install and use just download, extract and start. You can download a version for Linux, Windows, Mac, or Solaris. It is available at http://www.apachefriends.org/en/xampp.html.

Installing any of these packages will ease your administration task for web server and MySQL database. However, you are free to install and configure Apache, MySQL, and PHP separately.

If you are playing around with Zen Cart, I recommend using a development server. You will also need a development environment for customizing themes and testing third party contributions. In Linux, you can set it up by installing Apache, MySQL, and PHP packages. For Windows machines, you need to use one of the above-mentioned Apache-MySQL-PHP packages. In Appendix A, we will show how to set up a development environment by installing and configuring WAMP on a Windows machine.

PHP

If you plan to use Zen Cart, I am sure that you know about PHP. PHP is the hot scripting language for the web. You can get the latest version of PHP from www.php.net. You can download and install PHP package with your web server. For IIS, PHP can be configured as CGI or ISAPI; you can use either modes. For Linux, Apache-PHP-MySQL is installed by default. If you use WAMP, EasyPHP, or XAMPP web server package, you don't have to install and configure PHP separately.

Database

At present, Zen Cart supports only MySQL. MySQL version 4.1.x is recommended. However, Zen Cart can run on MySQL 5 server, but advanced features of MySQL 5 cannot be used in Zen Cart tables.

The data structure of Zen Cart is given in the mysql_zencart.sql file located in the zc_install/sql directory. Database tables will automatically be built during installation. However, you have to create the database and the user for login to that database before hand.

If you have installed WAMP or XAMPP, you will get MySQL server installed automatically. You can also use phpMyAdmin for managing databases in MySQL server. If you are using Linux hosting and cPanel, you can also use cPanel's database management tool and phpMyAdmin to create, delete, and manage databases and users.

Step-by-Step Installation

Once all prerequisites have been met, you can proceed to the installation of Zen Cart. The following sections describe the installation process for Zen Cart systematically, by using Fantastico and by uploading files to the server.

Through Fantastico

Fantastico is an excellent tool for installing a number of PHP applications on a server. Most of the Linux hosting services will give you access to your account through cPanel. Along with cPanel, you may also get Fantastico support. One of the benefits of installing a PHP application using Fantastico is that you don't need to bother about creating databases and uploading Zen Cart files separately.

Step-by-step guidelines for installing Zen Cart using Fantastico are given below:

1. Login to cPanel and click on the Fantastico icon.

2. A list of available PHP applications will be displayed. Go to the E-commerce section and click on Zen Cart link.

3. A short description of Zen Cart, current installations, and a link for new installation will be displayed. You will be informed about the space required for the new installation too. Click on the New Installation link to install Zen Cart.

4. Zen Cart installation will be shown. Then , you have to provide the following information:

  • Install on domain: Select the domain on which Zen Cart will be installed. If you have a sub-domain of, say, shop.yourdomain.com, you can select it, or you can install on yourdomain.com domain.
  • Install on directory: Enter the name of the directory on which Zen Cart will be installed. The directory should not already-exist; Fantastico will create a new one. If you want to install Zen Cart in the shop directory under your domain's root directory, just type shop in this field. Keep it blank to install it in that domain's root directory.
  • Administrator-username: Enter the name of administrative account. This will be used to login to Zen cart administration panel.
  • Password: Enter a password in this field. This will be needed to access the administrative panel.
  • Site name: Give your shop an attractive name, which will be displayed in the browser title bar.
  • Admin email: Enter the email address of the administrative user. All emails regarding administration will be sent to this address. If you forget the administrator account's password, a new password will be sent to this email address.

5. Once these fields are filled in, click on the Install Zen Cart button.

 6. On clicking Finish Installation, the required files are copied to the target directory and a database is created with a user and password. The configuration file for Zen cart will also be created automatically. Then, a screen will indicate that you have installed Zen Cart successfully. You can notify others about this installation by entering their email address and pressing Send E-mail Button. You will also see links to your shop catalog and the administrative area in this screen.

By Uploading Files

If you do not have Fantastico, do not worry. You can easily install Zen Cart by uploading the required files to the web server. Before doing this, you must download the latest version of Zen Cart from www.zen-cart.com. Unzip the zipped or gzipped package on your computer. Then, create the directory on your web server's webroot, and a database for Zen Cart on the MySQL server. Also, configure a database user to have the appropriate permissions (SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX, DROP ) on this database. If you are using  cPanel, you can use its tools such as  phpMyAdmin for this.

You need  an FTP program for uploading files to the server.  FileZilla is a nice choice for this.

Web hosts have their preferences in naming folders for running a website. You can have many files that don't even get shown to the public. The ones that are available for access via a browser are usually in a specific folder, for example, /home/yourname/public_html or /var/www/yourname/httpdocs or /usr/accounts/a/b/yourname/httpd and so on.

You need to upload your files to one of these folders. If you want the shop to be in a directory different to that of the webroot, you must create a directory, say shop, in the webroot.

Before running the installer, you need to know the following facts:

You must take note of these paths before starting the installation. You should also know your database name, username, and the password to access it. You have now uploaded the files to the shop directory, and you will use it for the following examples.

Once you have all of the information at hand, and have completed uploading all the files to the web server, you must start the installation with the following steps:

1. Open the browser and point to http://www.yourdomain.com/shop/zc_install/. You will find the following Zen Cart Setup, Welcome screen.

2. You can see a brief description in the Welcome page. To see the full description, you must scroll down and click on the Continue button to start the installation. On clicking the Continue button, the following License Confirmation page is shown:

3. Zen Cart uses GNU General Public License (GPL). To accept the licensing conditions, you must read and select I have read and agreed to abide by the Terms and Conditions as stated above. On clicking the Continue button, the System inspection screen will be shown.

4. The System Inspection screen will show your server environment variables. Variables suitable for Zen Cart installation are shown in green. Any variable configuration not suitable for Zen Cart installation will be shown in red. To know about that variable's desired configuration click on Click here for more info link. If you find any variable in red, you must reconfigure it on your server and click on the Recheck button at the bottom. If everything is alright, then click on the Install button. The following Database Setup screen is then shown:

5. In the Database Setup screen, you have to configure the following options for the database:

  • Database Type: Select the type of database to be used for the Zen Cart shop. At present, you can only select MySQL as the Database Type.
  • Store Identifier (Table-Prefix): If you are using the same database for another application, it is better to separate Zen Cart tables with a prefix. Type a prefix for the tables, for example, zen, in this field.
  • Database Host: Enter the database server's name in this field. Usually, it is localhost. If not, you can enter the hostname as dbserver.yourdomain.com in the Database Host field.
  • Database Username': For connecting to the database, you need a database username. Remember that for shared hosting on the linux server, the username used to log into cPanel is prefixed to the database username, for example suhreed_zen, where suhreed is the account on that server, and zen is the database username.
  • Database Password': Enter password for that database user in this field. This password must match with the existing database user's password.
  • Database Name: You have to specify the name of the database that will be used for the Zen Cart Shop, for example, zencart or yourname_zencart. You must provide the name of an existing database. Therefore, you need to create this database beforehand. However, Zen Cart Setup can create the tables in the database.
  • Database Sessions: You can store your session information in the database or separate file system. For storing sessions in the database, select Yes in this field.
  • SQL Cache method': Caching SQL queries improves the performance of the Zen Cart shop. You can store SQL queries in the database or in file systems. Select the method that you want to use.
  • Session/SQL Cache Directory': If you select a file system as SQL Cache method, specify the directory to be used for caching. By default, this is the cache directory under the Zen Cart installation.

 



This article has been extracted from: Zen Cart: E-commerce Application Development

Zen Cart: E-commerce Application Development

A step-by-step developer's guide

  • Install, configure, and customize Zen Cart for your customers
  • Enhance and modify Zen Cart
  • Walk through the creation of a fully functional book store
  • Learn advanced features of Zen Cart with practical examples

For more information, please visit:
http://www.PacktPub.com/zen-cart-ecommerce-application-development/book

 


6. Click on the Save Database Settings button to proceed to the next step. The installation process will create the database structures for Zen Cart. You will see an Installation in progress message while the database creation is ongoing. Once the database creation is complete, the following System Setup screen is shown:

7. You have to provide some more information on the System Setup screen. First, enter the physical path to your Zen Cart directory in the Physical Path field. This will look like /home/Suhreed/public_html/shop or, for windows host, e:/www/shop. Then, enter the virtual path/URL of your Zen Cart shop in URL to your Zen Cart store field, For all paths, do not include a trailing slash, '/ ' at the end of the path. For an explanation of a fields, click on the more info link beside the field. In the SSL Details section enter the URL of virtual directory for secure Zen Cart shop in HTTPS Domain field. The full virtual path of this secure directory should be mentioned in HTTPS Server URL field. If you want to use SSL to provide enhanced security for your shop, select Yes in the Enable SSL field. Select Yes in the Enable SSL in Admin Area field if you want to use SSL for access to the admin section. Usually, this screen will show the detected values for your server as defaults. Click on the Redetect defaults for this host button to get new values for these fields. Once you have entered all required paths and configurations, click on the Save System Settings button. The following phpBB Setup screen is shown:

8. The phpBB screen gives you an option to integrate the phpBB forum with your shop. If you want to use phpBB with Zen Cart shop, select YES and then type the path of the phpBB installation in phpBB Directory field. You can get an explanation of these setting by clicking on the more info link. Now, click on the Save phpBB settings button. The Store Setup screen is shown.

9. In the Store Setup screen, you must provide the Store Name, Store Owner, Store Owner Email, Store Country, Store Zone, Store Address, Default Language and Default Currency. Zen Cart comes with some example products and categories. To load these demo categories and products, select Yes in the Store Demo field. If you want to build a completely new product catalog, select No. Once these options are configured, click on the Save Store Settings button to proceed to the next step. The Administrator Account Setup screen appears, as shown below:

10. In the Administrator Account Setup screen, enter an Administrator's Username, Administrator's Password and Administrator's email. These will be used to login into the Administration panel for your shop. You have to confirm the administrator's password by retyping it in the Confirm Administrator's Password field. If you select Check for Zen Cart updates when logging into Admin, you will be notified about new versions of the Zen Cart release when you (as the administrator) log on. Click on the Save Admin Settings button.

11. Now, the Zen Cart Setup Finished screen is displayed. This screen will congratulate you on the successful installation of Zen Cart. It will also tell you about the next steps setting permissions to the configure.php file, zc_install and admin/includes/ folders. It will also show you some links for getting help. At the bottom of this page, you will see two buttons: Click here to go to the Store and Click here to open the Admin area. First check the store, and then try the admin area. You are going to explore these in a few minutes.

Conclusion

That's all. You have installed Zen Cart. Now it's time to explore the store and it back-end administration panel.