Troubleshooting Zen Cart

From TroubleshootingWiki

Zen Cart

Official Page

Project Documentation

Download

Source Book Zen Cart: E-commerce Application Development ISBN 978-1-847191-17-5 Publisher Packt Publishing Author(s) Suhreed Sarkar

Contents 1 Common Problems and Troubleshooting 1.1 PHP Related Problems 1.2 Login Related Problems 1.2.1 Session Handling in Admin Area 1.2.2 Security Error during Login as Customer 1.2.3 Forgotten Admin Password 1.3 Template Related Problems 1.4 Image Related Problem 1.4.1 Catalog Images Directory 1.4.2 Image Distortion 1.5 Trouble with E-mails 1.5.1 Emails are not Arriving 1.5.2 Email Transport Methods 1.5.3 Bounce Handling 1.6 Database Related Errors 2 Additional References 3 Source

[edit] Common Problems and Troubleshooting

While running your Zen Cart shop, you may face some common problems which can be broadly categorized as PHP and configuration related problems and Zen Cart related problems. The following sections highlight such problems.

[edit] PHP Related Problems

If there is any problem in configuring your Zen Cart shop, you may encounter various error and warning messages. Some of the common warning messages, their causes and remedies are discussed below.

Warning: Cannot modify header information headers already sent by (output started at <path/to/output_file>:<line number>) in <path/to/current_file> on line <number>.

You may encounter this message after modifying some .php files. This warning shows up if you leave a space or extra line at the beginning, or the end of a .php file. The file causing a problem is indicated by its name and line number. Look at after output started atand within brackets in the error message above. Fixing this error is as easy as removing that extra space or extra line. Open that file and go to the line number as reported in the error message. Then ensure that no space or extra line is present before <?php or after the ?> tag.

Usually this kind of error happens when you are working with some custom editors such as Dreamweaver. For example, you have edited files using Dreamweaver and uploaded the files via Dreamweaver without using check-in features. You can avoid this error by using check-in features in Dreamweaver.

Sometimes 'header already sent' error appears after other error messages. In that case, always resolve other errors first, as the other error messages may cause the 'header already sent' error.

Warning: Variable passed to each() is not an array or object in .../includes/classes/db/mysql/query_factory.php on line 100

This error may be displayed if magic_quotes_runtime is enabled. To be sure, check your phpinfo and see if magic_quotes_runtime is enabled. If it is enabled, you need to turn it off. You can do this by editing the following files:

 '''includes/application_top.php '''
 '''admin/includes/application_top.php'''

Open the files in the editor, and just after the licensing terms, add the following lines:

if (get_magic_quotes_runtime()) { set_magic_quotes_runtime(0);

Warning: main(<...>): failed to open stream: No such file or directory in <...> }

This error occurs when some files included in the.php files are not found in the set path. For correcting this, first ensure that you have uploaded all files and set correct permissions, especially for the file in question. If that does not fix the problem, check your PHP include_path. You can see these paths along with the error messages you have received. You can also check this setting with phpinfo().

On a Windows server, the include_path needs to start with .; and on a Unix/Linux server, it must start with .:. If the include_path does not contain this, you must configure it in php.ini, or in a .htaccess file.

In the php.ini file, add the following lines:

 include_path = ".;Drive:\path\to\php\includes" //for windows server
 include_path = ".:/path/to/php/includes" //for linux/unix server

Similarly, you configure it by editing the .htaccess file.

For Windows host, add the following line in the .htaccess file:

php_value include_path ".; Drive:\path\to\php\includes"

For Unix/Linux host, add the following line in the .htaccess file:

php_value include_path ".:/path/to/php/includes"

Warning: <restricted function>: open_basedir restriction in effect. File (<path to file>) is not within the allowed path(s): (<allowed paths>) in <file producing the error> on line <line>

This error occurs when you try to access a directory on which you do not have access permission. To get rid of this error message, ensure that the directories listed in the error messages are configured to be accessible by Zen Cart. On a Windows server, the directories are shown separated by a semi-colon (;) and on Unix/Linux servers, these are separated by a colon (:).

You entered the wrong username or password.

This may happen when you are typing a wrong username or password. Remember that passwords are case-sensitive. So, ensure that the Caps Lock is not ON while you are typing your passwords. If you have really forgotten your password there is still hope to recover it, even if it is your admin account password.

The first attempt to recover a forgotten password will be to click on the Resend Password button and enter the admin email address. You will find this button on the admin login screen. Usually, you will get the password in your email box. If, for some reason, you do not receive the password, you can create a temporary password to login only if you have access to a Zen Cart database.

Login to your webhosting control panel, open phpMyAdmin, select the Zen Cart database and click on the SQL tab. In the query box, type the following query and click on run:

 DELETE FROM zc_admin WHERE admin_name = 'Admin'; INSERT INTO zc_admin (admin_name, admin_email, admin_pass,
 admin_level) VALUES ('Admin', 'admin@localhost', '351683ea4e19efe34874b501fdbf9792:9b', 1);

Here zc_ is the prefix for the Zen Cart tables. Your database may use different prefixes or none. In that case, replace zc_ with the prefix you are using. Running this query will create a temporary admin account with a username admin and a password admin. You can now login to the administration area using these usernames and passwords.

It is important that, after you log in, delete this temporary admin account and create a new one from Tools | Admin Settings. Click on the insert button to create a new admin account. You have to provide the username, email address, and password for creating a a new admin account.

Warning: session.auto_start is enabled please disable this PHP feature in php.ini and restart the web server.

Enabling the session.auto_start setting starts a session automatically which creates a problem with proper session management. If you receive this warning, you have to disable this setting. You can do this by editing php.ini or the .htaccess file.

If you have access to the php.ini file, set the directive session.auto_start to 0, as follows:

session.auto_start = 0

In most of the cases you can edit the .htaccess file. If you do not see the .htaccess file in your Zen Cart directory, create one. Then add the following line to that .htaccess file and save it:

php_value session.auto_start 0

Your last resort will be to contact your host provider and ask them to disable this setting on the server.

Parse Error: syntax error, unexpected T_CONSTANT_ENCAPSED_STRING in /home/Suhreed/public_html/zencart/includes /languages/english/packt/product_info.php on line 17

This error occurs when you forget to put a backslash (\) before a single quote (') in one of your define() statements in the language file. For example, the following line will result in similar error:

define('TEXT_SOMETHING','This is something simple that's used as an example');

Here a ' is not escaped, so this will fire an error message. To correct this error, escape the character as follows:

define('TEXT_SOMETHING','This is something simple that\'s used as an example');

This page contains both secure and non-secure items. Do you want to display the non-secure items?

Sometimes, you may have a symptom whereby clicking on a login link will result in a message saying that the page contains both secure and non-secure items. Usually this happens on all secure pages, especially in My Account and Checkout areas.

This problem occurs when:

• You have hard-coded actual URL links such as http://xxxxxx in your templates, instead of using relative paths to objects.
• You have added banners with the [http:// http://] links and not marked them to skip display on the SSL pages
• You have added click-tracking tools to your site via JavaScript, which link to [http:// http://] pages somewhere.

To solve the problem on your browser, view the source of the pages creating the problem and search for src=http://. When you find the links, edit the corresponding template files, and remove the hard-coded links. If they are caused by click-tracking scripts somewhere, try converting them to https:// links, or contact the vendor for assistance with alternate scripts.

Note - To be on the safe side, never hard-code a http:// URL into any page on your site, always use the relative URL in such links. You can hard-code such URLs only when you are sure that doing so will not produce this sort of error, or when you are using only a non-secure mode, that is, without SSL. Be especially careful about the <img src=...> and <script src=...> tags.

[edit] Login Related Problems

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.

[edit] 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.

[edit] 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.

[edit] 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.

[edit] Template Related Problems

Zen Cart templates are located in the /includes/templates/ folder. Under this, you will find a folder named classic, the files that exist there can be overridden by placing a copy of the file you wish to alter inside another folder named after your custom template. The name of custom template is defined in the template_info.php file.

The folder with the template_info.php file, a css folder and the .css files needs to be located at includes/templates/your_template. The other folders that are in the template_default can be created in your_template folder, such as includes/templates/your_template/css and so on.

Once this is done, you should be able to see the template name from your administration area in Tools | Template Selection. If you do not see it there and cannot select it, you have done something incorrectly.

Remember that you need to put only the edited files in an override folder. As you edit more files in other locations, you will have several folders that are named after your template name. Note that, wherever there is a classic folder, you can create a template folder to keep your copied and edited files to have an override effect.

[edit] Image Related Problem

Sometimes, the images shown on your online shop may have problems due to inappropriate configurations related to image display or changes in the images directory. The following sections highlights two categories of problems related to images in the Zen Cart online shop.

[edit] Catalog Images Directory

When you are adding products to the catalogue and uploading the product image which is uploaded to the /images directory, or a sub-directory under the /images directory, the /images directory needs to be writable by Zen Cart. In other words, it means that you need to apply CHMOD 777 on this folder (including sub-directories) for write access. This should include all subdirectories for /images as well as their subdirectories such as:

• /images/large'
• /images/medium'
• /images/attributes'
• /images/dvd'
• /images/large/dvd'
• /images/medium/dvd'

If you do not set appropriate permissions (that is write access), you will not be able to upload product images.

The sub-directories in the /images directory needs to be created manually to be shown in the drop-down list while selecting image upload location, when adding products. Whenever you add a sub-directory, make sure that the sub-directory is writable to Zen Cart.

[edit] Image Distortion

Sometimes product images on your online shop may appear distorted. This happens when the size of your product image is large, but in your configuration display sizes have fixed height and width specifications. Distortion happens when your product images are not sized in the ratio of the specified height and width.

To get rid of image distortion, first set the image height and width proportions that you want to use throughout the online shop catalogue. Then, specify the height and width in the administration area from the Configuration | Images screen. Problems occur when any of the value for the following option pairs is set to 0:

• Small Image Width & Small Image Height
• Subcategory Image Width & Subcategory Image Height
• Category Icon Image Width Product Info Pages & Category Icon Image Height Product Info Pages
• Product Info Image Width & Product Info Image Height
• Image Product Listing Width & Image Product Listing Height
• Image Product New Listing Width & Image Product New Listing Height
• Image New Products Width & Image New Products Height
• Image Featured Products Width & Image Featured Products Height
• Image Product All Listing Width & Image Product All Listing Height

Also ensure that Calculate Image Size is set to true, and Use Proportional Images on Products and Categories is set to 1. Choosing these options will allow your images to be resized according to their own proportions.

[edit] Trouble with E-mails

Emails are very important for an online shop. Customers are notified about the status of their orders through emails, administrators are also notified by e-mail about new orders. Email communication in Zen Cart works fine, once it is configured correctly. However, sometimes you may experience troubles in communicating through emails. The following sections highlight the email related problems in Zen Cart.

[edit] Emails are not Arriving

Sometimes you may face problem in sending emails from your Zen Cart shop. This may happen for various reasons. Mostly, it is related to mail server configuration. Sometimes, your mail server configuration requires a particular format in which messages are to be sent. In such cases, you may try the following options:

1. First check whether email transport methods are configured correctly. You can see email configuration options from Configuration | E-mail Options.
2. Enable the Emails Must Be Sent From Known Domain? option and also set the appropriate email address in the Email Address (sent FROM) field. Zen Cart will only send emails from domains specified in your from address.
3. Try a different E-mail Transport method. First try php. If that does not solve your problem, try SMTP and other methods. If you are using sendmail, try using sendmail -f. If SMTP does not work, try SMTPAUTH and provide correct login credentials for the SMTP server account.
4. Try to send the email to more than one email account. It may so happen that the problem resides in the receiving server. Try to send emails to a non-free email address; do not test only with Yahoo, Hotmail, or Gmail accounts. These email servers have built-in spam protection, and it is likely that the mail sent from your Zen Cart shop is redirected to a spam folder, or blocked entirely. Checking with some other email accounts will possibly help you find the exact cause.
5. If your email system has junk mail filters or spam protection, try searching for your mail in junk mails or spam folders. Try disabling the protection or filter temporarily, and send mails from Zen Cart again.
6. Another way to check whether a mail has been sent from your Zen Cart shop is to look at email archives. First, enable email archiving by setting the E-mail Archiving Active? option value to true. Enabling this will archive all emails you are sending from Zen Cart. However, there is no built-in mechanism to see archived emails from within the Zen Cart administration area. A contribution named Email Archive Viewer can be used for viewing archived emails. Download this contribution from the Zen Cart website, install it, and use it to see whether Zen Cart has really processed the email for sending. If it has been sent, and the email is not delivered to the recipient, the problem may be in some other place.

Remember that sending a mail involves PHP script for processing the email, email transport and network connectivity. You have to investigate and find the cause for non-delivery of the mail, and then take appropriate action to resolve the problem.

[edit] Email Transport Methods

Your emails may not be transmitted if you have not configured appropriate email transport. You can select email transport in the administration panel from Configuration | Email Options. In the E-mail Transport Method field, you can select the following methods:

1. php: If you choose this method, Zen Cart will send emails using the email transport method your web server is configured to use for PHP mail commands. In most cases, this will work fine. If this does not work, it is possible that the mail host for PHP is not configured.
2. smtp or smtpauth: Selecting this transport method will use simple mail transfer protocol (SMTP). Use smtpauth if your SMTP mail server requires authentication. If you are running your web server on a windows operating system, then smtp or smtpauth is your only choice. Remember that when you are using the smtp or smtpauth methods, you have to configure mail server address in SMTP E-Mail Mail Host and SMTP E-Mail Mail Server Port. For smtpauth, you need to configure SMTP E-mail Account Mailbox and SMTP E-mail Account Password. Double check these settings if you have problems with sending email using smtp or smtpauth transport methods.
3. sendmail: If you are not running the Windows web server, and the php transport method is not working, then you can try sendmail. Selecting this method will use sendmail as the email transport method. Before trying this method, be sure that your web server has sendmail installed. If you are using cPanel for linux hosting, you can see the sendmail path and be sure that it is installed and configured for email transportation.
4. sendmail f: You should not try this at first. Use it when sendmail transport has some difficulties. This is usually used in some cases where your web server configuration has some tighter security requirements. For example, busy shared-hosting environments may need this option.

[edit] Bounce Handling

You may face problems with bounced emails from newsletter subscribers. By default, Zen Cart has no mechanism to handle bounced emails. If you see that newsletters/emails have bounced back, the first thing you should do is turn off that particular subscriber. You can unsubscribe someone by going to the Customers | Customers screen. Enter email address in the search box in the upper right corner, and then press Enter. When you find the customer with that email address, click on that and edit the settings for that customer. Turn off subscription to newsletters.

Note - When you find that a customer's email address is not active, or newsletters bounce from a particular address, you can email that customer directly to test whether their account is really active or not. For your store's security, you should not allow any user without a valid email address.

[edit] Database Related Errors

Database connection errors are very rare if you continue to use the same server after installing Zen Cart. However, connection errors may occur when you are migrating to another server, or when you have upgraded your MySQL database server.

In case of database connection errors, you will get exact error messages indicating connectivity problems. This error may be connected to the server, or a specific database. You will find database connectivity related configurations in the /includes/configure.php file. Check the following settings in this file:

 // define our database connection
  define('DB_TYPE', 'mysql');
  define('DB_PREFIX', '');
  define('DB_SERVER', 'localhost');
  define('DB_SERVER_USERNAME', 'root');
  define('DB_SERVER_PASSWORD', '');
  define('DB_DATABASE', 'zencart');
  define('USE_PCONNECT', 'false'); // use persistent connections?

The above defines mean:

• DB_TYPE : Database type this is mysql in most of the cases.
• DB_PREFIX: If you are using the same database for some other application, using a prefix for Zen Cart tables will be useful. If you are using a separate database for Zen Cart, you may keep this blank.
• DB_SERVER: This is MySQL database server name. If the MySQL database server and the web server are the same, the value of this field will be localhost. If the servers are separate, mention the hostname of that server.
• DB_SERVER_USERNAME: This is the username which will be used to connect to the database. Ensure that this user has appropriate permissions to connect to, select from, insert into, delete from, and update from the Zen Cart database. If you are using cPanel in Linux hosting, a prefix is used before each database username. For example, if your hosting account name is suhreed, and you create a database user named user1, then the full name of the database user becomes suhreed_user1. Also remember that while installing Zen Cart from Fantastico, a database user and corresponding password are automatically generated which are used for connecting to Zen Cart database. This user account is automatically deleted when you uninstall it using Fantastico.
• DB_SERVER_PASSWORD: This is the password for the username mentioned in DB_SERVER_USERNAME. Always remember that passwords are case sensitive, so you need to type them carefully. The key thing in any connectivity problem should be to ensure the password's validity.
• DB_DATABASE: This is the type name of the database used for Zen Cart. Generally, it is named as zencart or zc. Be sure that database name is correctly mentioned in this field.
• USE_PCONNECT: Database connection can be persistent or non-persistent. Persistent connection remains open for some time. For a small number of users, this saves time in establishing connections again and again, and thus improves performance. But for a large number of requests to a database, a lot of memory may be used for maintaining persistent connection to database. If you see that a lot of memory is used up for a database, you may check this setting and set it to false.

If you are facing a problem with database connectivity, check whether the database itself is running. Try connecting to the database from another application. If you can connect to the database from other applications, then it is likely that you have a problem with the database configuration for Zen Cart. Check the above variables and test the results.

[edit] Additional References

• For instructions on Creating a new template for Zen Cart, click here
• For instructions on Installing Zen Cart, click here

[edit] Source

The source of this content is Chapter 9: Maintenance and Troubleshooting of Zen Cart: E-commerce Application Development by Suhreed Sarkar (Packt Publishing, 2008).