Ultimate URLs 2.15

Features

• Both the stock Zen Cart and alternative URLs can be used to access the pages.
• One can enable automatic 301 redirects from older URLs (both stock and alternative) to the new URLs (both updated stock and alternative).
• Support is included for generating URLs in the native language requested by the browser / customer.
• For category, product, and review pages: one can choose to show just the product / category name or optionally prepend the name with the parent category's name (original or parent).
• For category pages: one can choose to display the categories as directories (off, short, or full).
• For EZ-Pages: the title of the EZ-Page will be used.
• For all other pages: the page type will be used as the name (replaces "main_page=xyz" with "xyz").
• One can optionally chose to have all alternate URLS end with a specific extension (.html, .htm).
• One can configure sitewide string replacements using PCRE rules (regular expressions / preg_replace).
• One can choose to strip all non-alphanumerical characters or just "special" characters (dash is excluded).
• One can choose to "filter" out short words.
• One can select which page types (main_page=xyz) will have rewritten URLs.
• One can choose to have generated URLs cached. Caching is supported at multiple levels including the use of memory and database storage.
• If one chooses to remove Ultimate URLs and switch back to the stock Zen Cart URLs in the future, leaving the .htaccess rules in place will allow both stock and alternative URLs to continue functioning.

Requirements

• Working installation of Zen Cart 1.3.9h or 1.5.x
• Secure FTP access to the Zen Cart installation (while you can use plain FTP it is not recommended)
• An account to access Zen Cart's administrative interface
• Knowledge of regular expressions if filtering names in URLs
• For Zen Cart 1.3.9h, disable SQL Caching
• Read and agree to the License

Configuration

How do I bring up the configuration page?

When this module is installed it provides an administrative page for configuring USU. After a successful login to the Zen Cart administrative interface, users granted permission can access the configuration page can select ConfigurationUltimate URLs.

Cache Notes

If any of the cache settings for Ultimate URLs have been enabled, until the cache is reset existing URLs in the cache will be used. This means one may not see the effect of changing configuration options immediately.

By default cached URLs will be saved for 30 days. The cache can be reset by changing the "Reset URL cache" configuration option to "true".

Numinex Users

Users of various Numinex modifications for Zen Cart may run into some issues configuring this module. This is not a bug with Ultimate URLs. The errant behavior is caused by alterations made by Numinex to the Zen Cart "configuration.php" file.

Basically, Numinex made the assumption it was safe to ignore one of the Zen Cart database fields related to displaying configuration values. This field is used by the Zen Cart configuration management page to display the current value configured for a configuration option.

Ultimate URLs makes use of this core Zen Cart database field to display the values, to determine when a selectable option has been changed (did the admin change how category URLs should appear?), verifies the settings are valid and compatible, correct any invalid settings, and to reset the URL Cache. All this is done on behalf of the admin user without requiring any manual intervention through the use of the core Zen Cart database field Numinex has decided to ignore.

So the end result is: The alterations made by Numinex break the additional functionality utilized by this module. Until the following (or similar code) is added back into "configuration.php", Numinex users with the modified file will experience issues configuring Ultimate URLs.

Numinex users who have installed the Numinex modifications to Zen Cart's "/admin/configuration.php" and are experiencing the above issues should apply the workaround listed in Recommended Patches.

Recommended Patches

The following bugs / issues in other code (not Ultimate URLs) have been identified: during the QA testing of Ultimate URLs, feedback in the Ultimate URLs support thread, and by the Zen Cart community. If any of these apply to your Zen Cart installation, we recommend you apply and test the recommended fixes on your site before installing Ultimate URLs.

Many of these patches and workarounds affect all Zen Cart stores, not just stores using Ultimate URLs. Please take the time to review all of the patches and workarounds. Failure to install applicable patches and workarounds will result in undesired behavior.

Known Zen Cart Bugs

Keeping your version of Zen Cart up to date is extermely important to protect your business and customers. Whenever possible using the latest release of Zen Cart is recommended. Zen Cart's official End of Life policy is to stop providing security and other patches six months after a new version is released.

Here is an example to help understand Zen Cart's End of Life policy. Zen Cart 1.5.3 was released on 5 June 2014. So according to the official policy, Zen Cart 1.5.1 went End of Life on 5 Jan 2015.

• Known Bugs (and fixes) for Zen Cart 1.5.4
• Known Bugs (and fixes) for Zen Cart 1.5.3
• Known Bugs (and fixes) for Zen Cart 1.5.1
• Known Bugs (and fixes) for Zen Cart 1.5.0

Product Listing (add to cart) Bug

This is a known issue in Zen Cart 1.3.9 and newer (verified to exist through Zen Cart 1.5.4).
The Zen Cart module handling product listings can incorrectly add the "products_id" twice to a URL. This bug can cause problems with the "Add to Cart" behavior on product listing pages.

Here is the proposed fix (by lhungil).

Page Not Found (zen_href_back) Bug

This is a known issue in Zen Cart 1.3.9 and newer (verified to exist through Zen Cart 1.5.4).
The Zen Cart "Page Not Found" page is added to the navigation history. This can cause the "back button" (link generated by the zen_href_back function) to point to "Page Not Found".

Here is the proposed fix (by lat9).

Ajax.php (zen_href_back) Bug

This is a known issue in Zen Cart 1.5.4.
The Zen Cart "/ajax.php" calls are added to the navigation history. This can cause the "back button" (link generated by the zen_href_back function) to point to non-existent pages.

Here is the proposed fix (by DrByte).

Query Factory (sql cache) Bug

This is a known issue in Zen Cart 1.3.9 - 1.5.1 (fixed in Zen Cart 1.5.2 and newer).
When SQL caching is enabled in the Zen Cart configuration file queryFactory (database calls) do not always return a database result object (queryFactoryResult). When a database result has been cached, functions such as "RecordCount()" and "Move" do not return correct information and may generate errors.

Here is the proposed fix (by lhungil).

Multilingual Stores

Zen Cart already includes support for serving pages in multiple languages. Zen Cart is setup and configured for multiple languages, Ultimate URLs reads the language information from Zen Cart when generating URLs.

Ultimate URLs already supports multiple languages and multilingual stores. No modifications are needed to support multiple languages!

Optional:b> If one wishes to also add alternative language links to their pages, they can add the following snippet to "html_header.php" in their template:

<meta http-equiv="Content-Type" content="text/html; charset=<?php echo CHARSET; ?>" />
<?php
// START add links specific to a "language" to the header
// See http://support.google.com/webmasters/answer/189077

// Recommend disabling the individual caches to reduce the memory
// footprint of using this code. The global cache can be left enabled.
$tmp_lng = new language();
foreach($tmp_lng->catalog_languages as $lng) {
	// Initialize a new generator for a specific language (by language_id).
	${'usu_' . $lng['code']} = new usu($lng['id']);

	// Create a link using the generator for a specific language.
	${'link_' . $lng['code']} = ${'usu_' . $lng['code']}->href_link(
		$current_page,
		'language=' . $lng['code'] . '&' . zen_get_all_get_params('language'),
		$request_type,
		false
	);

	// Fallback to Zen Cart generated.
	if(${'link_' . $lng['code']} === null) {
		${'link_' . $lng['code']} = zen_href_link(
			$current_page,
			'language=' . $lng['code'] . '&' . zen_get_all_get_params('language'),
			$request_type,
			false
		);
	} ?>
	<link rel="alternate" hreflang="<?php
		echo $lng['code']; ?>" href="<?php
		echo ${'link_' . $lng['code']};
	?>"/><?php
	unset(${'usu_' . $lng['code']}, ${'link_' . $lng['code']});
}
unset($tml_lng, $lng);
// END add links specific to a "language" to the header ?>
<meta name="keywords" content="<?php echo META_TAG_KEYWORDS; ?>" />

Numinex configuration (cannot change settings) Workaround

The alterations made by Numinex to Zen Cart's administrative configuration page break the additional functionality utilized when configuring this module. See Configuration for more information.

Starting around line 215 in the Numinex "configuration.php" find the following code:

<div class="mod-header">
	<h1><?php echo $cfg_group->fields['configuration_group_title']; ?></h1>
</div>
<div class="mod-content">

Replace with the following code:

<div class="mod-header">
	<h1><?php echo $cfg_group->fields['configuration_group_title']; ?></h1>
</div>
<?php // START fix code to utilize the use_function (1 / 2) ?>
<div style="padding-bottom: 1em"><?php
foreach($tabs as $tab => $tab_vals) {
	foreach($tab_vals['options'] as $configuration_option) {
		if(zen_not_null($configuration_option['use_function'])) {
			// First call the use_function
			if (preg_match('/->/', $configuration_option['use_function'])) {
				$class_method = explode('->', $configuration_option['use_function']);
				if (!is_object(${$class_method[0]})) {
					include(DIR_WS_CLASSES . $class_method[0] . '.php');
					${$class_method[0]} = new $class_method[0]();
				}
				zen_call_function($class_method[1], $configuration_option['configuration_value'], ${$class_method[0]});
			} else {
				zen_call_function($configuration_option['use_function'], $configuration_option['configuration_value']);
			}
		}
	}
} ?> 
</div>
<?php // END fix code to utilize the use_function (1 / 2) ?>
<div class="mod-content">

Starting around line 233 in the Numinex "configuration.php" find the following code:

foreach($tab_vals['options'] as $configuration_option) {
	echo '<tr>' . "\n";
	echo '	<td class="cl">' . $configuration_option['configuration_title'] . '</td>' . "\n";							
	echo '	<td class="cl is-details"><em>' . $configuration_option['configuration_description'] . '</em></td>' . "\n";
	echo '	<td class="cl">' . "\n";

Replace with the following code:

foreach($tab_vals['options'] as $configuration_option) {
	// START fix code to utilize the use_function (2 / 2)
	$configuration_value = $configuration_option['configuration_value'];
	if(zen_not_null($configuration_option['use_function'])) {

		// Run the use_function for display purposes
		if (preg_match('/->/', $configuration_option['use_function'])) {
			$class_method = explode('->', $configuration_option['use_function']);
			if (!is_object(${$class_method[0]})) {
				include(DIR_WS_CLASSES . $class_method[0] . '.php');
				${$class_method[0]} = new $class_method[0]();
			}
			$configuration_value = zen_call_function($class_method[1], $configuration_option['configuration_value'], ${$class_method[0]});
		} else {
			$configuration_value = zen_call_function($configuration_option['use_function'], $configuration_option['configuration_value']);
		}

		// The stock Zen Cart configuration file "reloads" the
		// page between displaying configuration settings and
		// editing a configuration setting. This "extra" query
		// is needed to "replicate" the default Zen Cart behavior.
		$query = $db->Execute(
			'SELECT `configuration_title`, `configuration_value`, ' .
				'`configuration_description`, `configuration_key`, ' .
				'`use_function`, `set_function` ' .
			'FROM `' . $configuration_table . '` ' .
			'WHERE `configuration_id`=\''  . (int)$configuration_option['configuration_id'] . '\''
		);
		if (!$query->EOF) {
			$configuration_option['configuration_title'] = $query->fields['configuration_title'];
			$configuration_option['configuration_description'] = $query->fields['configuration_description'];
			$configuration_option['configuration_value'] = $query->fields['configuration_value'];
			$configuration_option['configuration_key'] = $query->fields['configuration_key'];
			$configuration_option['use_function'] = $query->fields['use_function'];
			$configuration_option['set_function'] = $query->fields['set_function'];
		}
		unset($query);
	}
	// END fix code to utilize the use_function (2 / 2)
	echo '<tr>' . "\n";
	echo '	<td class="cl">' . $configuration_option['configuration_title'] . '</td>' . "\n";							
	echo '	<td class="cl is-details"><em>' . $configuration_option['configuration_description'] . '</em></td>' . "\n";
	echo '	<td class="cl">' . "\n";

Installation, Upgrades, and Removal

Folders inside the distribution archive

• 1_new_files (files added by this module)
• 2_htaccess (Apache configuration directives)
• 3_install (manual installation files)
• 4_uninstall (manual uninstallation files)
• readme (documentation)
• modified_files/xyz (example modified core Zen Cart files where xyz is the Zen Cart version)

Important Notes

Ultimate URLs can be installed, upgraded, and removed via Plugin Manager or manually using the included installation code. One should never attempt to bypass these instructions when installing, upgrading, or removing Ultimate URLs.

There are some known bugs and issues present in Zen Cart and 3rd party modules which may impact your Zen Cart installation. Please apply any relevant patches and workarounds before installing Ultimate URLs. Additional patches and workarounds may be available in the Support Thread.

The location "/temp" in this section refers to the temporary location where the distribution archive for Ultimate URLs has been extracted.

Installation and Upgrade Steps

1. Pre - Installation.
   Backup your Zen Cart installation and database. Best practice is to keep regular backups and perform a manual backup prior to the installation or modification of any portion of Zen Cart.
   1. You can use Secure FTP to backup the files. Two well known FTP programs are WinSCP and FileZilla.
   2. You can backup the MySQL database either using a tool such as PhpMyAdmin or from the Zen Cart admin interface using DrByte's Backup MYSQL Plugin
2. New Files. ("/temp/1_new_files")
   These files do not include modifications to any core Zen Cart files. We will be adding these new files to Zen Cart as part of the installation.
   1. Rename the "your_admin_folder" folder to match the name of the store's admin folder.
   2. If you have installed any other plugins or modifications to your Zen Cart installation which make changes to any of the New Files you will need to use a tool like Winmerge or Beyond Compare to incorporate those changes into these files.
   3. Upload all of the folders and files inside the New Files folder to the location of the Zen Cart installation. The directory structure should match the store's directory structure.
      Do not upload the "1_new_files" folder to the store, just the files and folders inside the New Files directory.
3. Apache Directives (htaccess). ("/temp/2_htaccess")
   This file contains directives for Apache web servers on how to handle incoming requests for URLs including those generated by Ultimate URLs.
   1. If you are using Apple OSX, UNIX, or BSD based Operating System you may need to change some settings to allow you to see the files in this folder. Look for an option to "show hidden files".
      By default these Operating Systems may be configured to hide files which start with a dot.
   2. Open up and edit the supplied sample ".htaccess" file with a plaintext editor (such as notepad). Adjust the Apache directives (especially RewriteBase) as needed for the web server where Zen Cart is installed.
      Pay particular attention to the notes and comments inside the sample ".htaccess" file.
   3. If an existing ".htaccess" file exists at the root of your Zen Cart installation you may need to add directives from your existing file to the example provided with Ultimate URLs.
   4. Upload the edited ".htaccess" file to the root of your Zen Cart installation.
4. Install / Upgrade (using Plugin Manager)
   This module is compatible with Plugin Manager and can be installed and upgraded using the administrative page included with a full installation of Plugin Manager.
   1. This is the recommended method for completing the installation!
   2. See the Plugin Manager documentation for more details.
5. Manual Install / Upgrade. ("/temp/3_install")
   These files trigger the installation or upgrade of this module. These are only needed if Plugin manager has not already been installed. These steps should not be used when a full installation of Plugin Manager is available / installed (use Plugin Manager instead).
   1. Log into the admin side of your Zen Cart installation using a web browser. Yes, log into your admin interface now before continuing.
      Failing to first login can result in you missing vital installation and error messages.
   2. Upload all of the folders and files inside the Install folder to the location of your Zen Cart installation. The directory structure should match your store's directory structure.
      Do not upload the "3_install" folder to your store, just the files and folders inside the Install directory.
   3. Click on ANY link in the admin interface (The "Admin Home" link is a good choice).
   4. Note any error or success messages which appear on the top of the site.
      • If all goes well it should report success.
      • If additional steps need to be performed, follow the instructions. When done go back to Install Step C (previous step). The previous step should start with the text "Click on ANY link" .

Uninstalling / Removal

1. Pre - Removal.
   Backup your Zen Cart installation and database. Best practice is to keep regular backups and perform a manual backup prior to the installation or modification of any portion of Zen Cart.
   1. You can use Secure FTP to backup the files. Two well known FTP programs are WinSCP and FileZilla.
   2. You can backup the MySQL database either using a tool such as PhpMyAdmin or from the Zen Cart admin interface using DrByte's Backup MYSQL Plugin
2. Un-Install (using Plugin Manager)
   This module is compatible with Plugin Manager and can be removed using the administrative page included with a full installation of Plugin Manager.
   1. This is the recommended method for uninstalling this module!
   2. See the Plugin Manager documentation for more details.
3. Manual Un-Install. ("/temp/3_uninstall")
   These files trigger the removal of this module and are only needed if Plugin manager has not already been installed. These steps should not be used when a full installation of Plugin Manager is available / installed (use Plugin Manager instead).
   1. Log into the admin side of your Zen Cart installation using a web browser. Yes, log into your admin interface now before continuing.
      Failing to first login can result in you missing vital installation and error messages.
   2. Upload all of the folders and files inside the Un-Install folder to the location of your Zen Cart installation. The directory structure should match your store's directory structure.
      Do not upload the "4_uninstall" folder to your store, just the files and folders inside the Un-Install directory.
   3. Click on ANY link in the admin interface (The "Admin Home" link is a good choice).
   4. Note any error or success messages which appear on the top of the site.
      • If all goes well it should report success.
      • If additional steps need to be performed, follow the instructions. When done go back to Un-Install Step C (previous step). The previous step should start with the text "Click on ANY link" .
4. Apache Directives (htaccess). (optional)
   One may wish to optionally revert / remove the lines added during installation. Leaving these lines in place (or modifying them to issue a 301 redirect) is recommended.
   1. Removing the directives for Apache web servers letting them know how to handle incoming requests for URLs generated by Ultimate URLs may cause "404" errors for links found in search engines and any bookmarks saved by a user. Consulting a knowledgeable expert to help with handling the transition back to stock Zen Cart URLs is highly recommended.
   2. If you are using Apple OSX, UNIX, or BSD based Operating System you may need to change some settings to allow you to see the files in this folder. Look for an option to "show hidden files".
      By default these Operating Systems may be configured to hide files which start with a dot.
   3. Retrieve a copy of the ".htaccess" file from the existing Zen Cart website to your local computer.
      One can use Secure FTP to copy the files. Two well known FTP programs are WinSCP and FileZilla.
   4. Open up and edit the local copy of the ".htaccess" file with a plaintext editor (such as notepad). Adjust or remove the Apache directives added by Ultimate URLs as needed.
   5. Upload the edited ".htaccess" file to the root of your Zen Cart installation.

Modified Core Files

During the normal installation process you should not do anything with these files. These files are not used by the Ultimate URLs installer and copying these files over to the server may interfere with the installation process. In most cases the installer will handle making the required modifications on your behalf during both installation and uninstallation.

This does require the web server to have write access to files and folders which are part of the Zen Cart installation. This is allowed (and configured by default) on many hosting providers (especially those utilizing suexec or suPHP for security purposes).

In the event your hosting provider does not allow granting write access to the files and folders which are part of the Zen Cart installation some additional steps may be required in order to install Ultimate URLs. These steps should only be used as a last resort.

Make sure to use the correct Modified Core Files ("/temp/modified_xxx_files") matching the version of Zen Cart in use by the store. For example if the installed version of Zen Cart is 1.5.4 only use the Modified Core Files from the "/temp/modified_154_files" folder.

Manually Merging for Installations / Upgrades

1. Determine which version of Zen Cart is installed. Navigate to the folder matching the installed version of Zen Cart. Modified Core Files refers to this folder.
   1. For example: If using Zen Cart 1.5.3 use the files in "modified_files/1.5.3".
2. Rename the "your_admin_folder" folder (inside the Modified Core Files folder) to match the name of your store's admin folder.
   1. This usually uses the same name as the location where one performs Zen Cart administration. For example if the URL in the web browser's address bar is "http://zen-cart.com/EriL83X0b/", the admin folder name would normally be "EriL83X0b".
3. If one has installed any other plugins or modifications to their Zen Cart installation:
   1. Use a tool such as Winmerge or Beyond Compare to compare the Modified Core Files with an unmodified copy of the file from the Zen Cart distribution. In most cases, the changes made by this plugin will be surrounded by comments to make locating the changes easier.
   2. Download a copy of the current file from the Zen Cart installation on the server. Use a tool such as Winmerge or Beyond Compare to apply (merge) the identified changes from this plugin to the file from the Zen Cart installation.
4. Upload all of the folders and files inside the Modified Core Files folder to the location of your Zen Cart installation. The directory structure should match your store's directory structure.
   1. Do not upload the "modified_files/xyz" folder to your store, just the files and folders inside the Modified Core Files directory.

Manually Merging for Removal

1. Determine which version of Zen Cart is installed. Navigate to the folder matching the installed version of Zen Cart. Modified Core Files refers to this folder.
   1. For example: If using Zen Cart 1.5.3 use the files in "modified_files/1.5.3".
2. Rename the "your_admin_folder" folder (inside the Modified Core Files folder) to match the name of your store's admin folder.
   1. This usually uses the same name as the location where one performs Zen Cart administration. For example if the URL in the web browser's address bar is "http://zen-cart.com/EriL83X0b/", the admin folder name would normally be "EriL83X0b".
3. Download a copy of each modified file from the Zen Cart installation on the server. Remove (merge) the changes added by this plugin.
   1. Use a tool such as Winmerge or Beyond Compare to remove (merge) the identified changes from the server files.
   2. In most cases, the changes made by this plugin will be surrounded by comments to make identifying the changes easier. If needed compare Modified Core Files to the corresponding &clean& version of the files downloaded from the Zen Cart website to identify changes made by this plugin.
   3. Overwrite the modified files supplied with this plugin with the merged files from the server.
4. Upload all of the folders and files inside the Modified Core Files folder to the location of your Zen Cart installation. The directory structure should match your store's directory structure.
   1. Do not upload the "modified_files/xyz" folder to your store, just the files and folders inside the Modified Core Files directory.

Confused or Need Some Help?

Feel free to stop by the Zen Cart forums! At some point in our lives we all need some help. Make sure to read through the support thread for this module and search for answers before posting. Keep in mind Zen Cart is free software, and the forum members are volunteers. When one has a time critical project, issue(s) which cannot be duplicated, or a complex request... It may be in one's best interest to hire a professional to handle the project or address the issue(s).

Changelog

License

Ultimate URLs is released under the General Public License (see the file named LICENSE in the distribution archive for full details).

This script is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Always backup your shop and database before making changes.