************************************************************************
USPSMethods 5.2.1 for osCommerce
USPS Rate V4 and Intl Rate V2 Syntax
Jan 15, 2010 by Fulluv Scents
Released under the GPL
************************************************************************
Support Forum :
http://forums.oscommerce.com/topic/146950-contribution-usps-methods/
***************
Description
***************
With many options in the configuration (admin) panel, this is the most versatile and business friendly USPS module offered to date. This module will give you complete control over your shipping options. Options include choosing domestic and international shipping methods, whether to display package weight, transit time, and insurance, whether to charge retail rates or commercial rates, add delivery confirmation and/ or signature confirmation with order total threshhold for sig confirmation. Charge handling for domestic or international, insure domestic and int'l packages via USPS or private insurance carrier. Insure purchase only, tax, and cost of shipping if you so desire. Set weight thresholds on domestic packages to keep your customers from choosing methods that don't apply.
****************************
Requested Additions
****************************
USPS responses provide country specific shipping prohibitions. I would like to see a pop up containing the text to the international prohibitions with an agreement to be responsible for customs clearance before the customer can order. This should be turned on or off from the admin panel. If someone can get the script for the pop up, I can set the admin panel options.
USPS Methods Install Instructions
For new and upgrade
/////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
BACK UP YOUR DATABASE
MAKE COPIES OF YOUR ORIGINAL FILES
/////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
IMPORTANT NOTES
Sign up for USPS API tools here:
https://secure.shippingapis.com/registration/
USPS technical guides can be found here:
http://www.usps.com/webtools/technical.htm
USPS offers no test server for this API syntax. After you have registered
with USPS and received your user ID, you must email USPS per instructions
in the email from them, and ask them to switch you over to the production
Mention that you are using OSCommerce. If you haven't received a reply within
24 hours, then email a second time and ensure them that your script has been
tested and is ready to go live.
Write down your USPS User ID
1. Uninstall usps module from within admin panel
2. Overwrite includes/languages/english/modules/shipping/usps.php
3. Overwrite includes/modules/shipping/usps.php
4. From your admin panel click configuration/email options - and set "Use MIME HTML When Sending Emails" to true.
-- if not set to true, emails will not convert the trademark legend and customers will receive emails containing ® instead of ®
5. If you have one page checkout, then modify the following. If not, then skip to step 6.
catalog/includes/checkout/shipping_method.php
Find:
<td class="main" width="75%"><?php echo $quotes[$i]['methods'][$j]['title']; ?></td>
Replace with:
<?php
$search = array(' reg', ' trade');
$replace = array('<sup>®</sup>',
'<sup>™</sup>');
?>
<td class="mainContent" width="75%"><?php echo str_replace($search, $replace, $quotes[$i]['methods'][$j]['title']);
?></td>
6. For stock checkout, modify the following (even if you have one page checkout):
catalog/checkout_shipping.php
Find:
<td class="main" width="75%"><?php echo $quotes[$i]['methods'][$j]['title']; ?></td>
Replace with:
<?php
$search = array(' reg', ' trade');
$replace = array('<sup>®</sup>', '<sup>™</sup>');
?>
<td class="main" width="75%"><?php echo
str_replace($search, $replace, $quotes[$i]['methods'][$j]['title']); ?></td>
7. Modify the following:
catalog/includes/modules/order_totals/ot_shipping.php
Find:
$this->output[] = array('title' => $order->info['shipping_method'] . ':',
Replace with:
$search = array(' reg', ' trade');
$replace = array('<sup>®</sup>', '<sup>™</sup>');
$this->output[] = array('title' => str_replace($search, $replace, $order->info['shipping_method']) . ':',
8. Set your time zone if it is not already set within your php.ini file (on your server) or within your script.
This will keep the script from sending your server time zone if the server is on a different zone than your store.
catalog/includes/application_top.php
Find on line 13:
// start the timer for the page parse time log
define('PAGE_PARSE_START_TIME', microtime());
Add Before -
For city list see http://www.php.net/manual/en/timezones.america.php.
You must replace "YOURNEARESTCITY" with the one closest to you:
// set default store time zone
ini_set('date.timezone',
'America/YOURNEARESTCITY');
9. If upgrading any previous version of "usps methods", modify the following and skip to line 13. If this is a new install, then skip this step and go onto step 10.
catalog/admin/includes/functions/general.php
Find:
// Alias function for Store configuration values in the Administration Tool
function tep_cfg_select_multioption($select_array, $key_value, $key = '') {
for ($i=0; $i<sizeof($select_array); $i++) {
$name = (($key) ? 'configuration[' . $key . '][]' : 'configuration_value');
$string .= '<br><input type="checkbox" name="' . $name . '" value="' . $select_array[$i] . '"';
$key_values = explode( ", ", $key_value);
if ( in_array($select_array[$i], $key_values)) $string .= ' CHECKED';
$string .= '> ' . $select_array[$i];
}
$string .= '<input type="hidden" name="' . $name . '" value="--none--">';
return $string;
}
Replace with:
// Alias function for Store configuration values in the Administration Tool
function tep_cfg_select_multioption($select_array, $key_value, $key = '') {
for ($i=0; $i<sizeof($select_array); $i++) {
$search = array(' reg', ' trade');
$replace = array('<sup>®</sup>', '<sup>™</sup>');
$name = (($key) ? 'configuration[' . $key . '][]' : 'configuration_value');
$string .= '<br><input type="checkbox" name="' . $name . '" value="' . $select_array[$i] . '"';
$key_values = explode( ", ", $key_value);
if ( in_array($select_array[$i], $key_values)) $string .= ' CHECKED';
$string .= '> ' . str_replace($search, $replace,$select_array[$i]);
}
$string .= '<input type="hidden" name="' . $name . '" value="--none--">';
return $string;
}
10. If this is a new install or an upgrade from stock or old version, then make the following modifications. If not, then skip to step 13.
catalog/admin/includes/functions/general.php
Find somewhere around line 767:
////
// Alias function for module configuration keys
function tep_mod_select_option($select_array, $key_name, $key_value) {
reset($select_array);
while (list($key, $value) = each($select_array)) {
if (is_int($key)) $key = $value;
$string .= '<br><input type="radio" name="configuration[' . $key_name . ']" value="' . $key . '"';
if ($key_value == $key) $string .= ' CHECKED';
$string .= '> ' . $value;
}
return $string;
}
Insert After
// Alias function for Store configuration values in the Administration Tool
function tep_cfg_select_multioption($select_array, $key_value, $key = '') {
for ($i=0; $i<sizeof($select_array); $i++) {
$search = array(' reg', ' trade');
$replace = array('<sup>®</sup>', '<sup>™</sup>');
$name = (($key) ? 'configuration[' . $key . '][]' : 'configuration_value');
$string .= '<br><input type="checkbox" name="' . $name . '" value="' . $select_array[$i] . '"';
$key_values = explode( ", ", $key_value);
if ( in_array($select_array[$i], $key_values)) $string .= ' CHECKED';
$string .= '> ' . str_replace($search, $replace,$select_array[$i]);
}
$string .= '<input type="hidden" name="' . $name . '" value="--none--">';
return $string;
}
// USPS Methods. Added by Greg Deeth
// Alias function for Store configuration values in the Administration Tool.
function tep_cfg_multiinput_list($select_array, $key_value, $key = '') {
$key_values = explode( ", ", $key_value);
for ($i=0; $i<sizeof($select_array); $i++) {
$name = (($key) ? 'configuration[' . $key . '][]' : 'configuration_value');
$string .= '<br><input type="text" name="' . $name . '" value="' . $key_values[$i] . '"> ' . $select_array[$i];
}
$string .= '<input type="hidden" name="' . $name . '" value="--none--">';
return $string;
}
// USPS Methods. Added by Greg Deeth
// Alias function for Store configuration values in the Administration Tool.
function tep_cfg_multiinput_duallist_oz($select_array, $key_value, $key = '') {
$key_values = explode( ", ", $key_value);
$string .= '<center>';
for ($i=0; $i<sizeof($select_array); $i++) {
$current_key_value = current($key_values);
$name = (($key) ? 'configuration[' . $key . '][]' : 'configuration_value');
$string .= '<br><input type="text" name="' . $name . '" size="3" value="' . $current_key_value . '"><i>oz</i>';
$string .= ' <b><</b> ' . $select_array[$i] . ' <u><b><</b></u>';
next($key_values);
$current_key_value = current($key_values);
$string .= '<input type="text" name="' . $name . '" size="3" value="' . $current_key_value . '"><i>oz</i>';
next($key_values);
}
$string .= '<input type="hidden" name="' . $name . '" value="--none--">';
$string .= '</center>';
return $string;
}
function tep_cfg_multiinput_duallist_lb($select_array, $key_value, $key = '') {
$key_values = explode( ", ", $key_value);
$string .= '<center>';
for ($i=0; $i<sizeof($select_array); $i++) {
$current_key_value = current($key_values);
$name = (($key) ? 'configuration[' . $key . '][]' : 'configuration_value');
$string .= '<br><input type="text" name="' . $name . '" size="3" value="' . $current_key_value . '"><i>lbs</i>';
$string .= ' <b><</b> ' . $select_array[$i] . ' <u><b><</b></u>';
next($key_values);
$current_key_value = current($key_values);
$string .= '<input type="text" name="' . $name . '" size="3" value="' . $current_key_value . '"><i>lbs</i>';
next($key_values);
}
$string .= '<input type="hidden" name="' . $name . '" value="--none--">';
$string .= '</center>';
return $string;
}
11. Add the following:
catalog/includes/functions/general.php
Find somewhere around line 287:
////
// Wrapper function for round()
function tep_round($number, $precision) {
if (strpos($number, '.') && (strlen(substr($number, strpos($number, '.')+1)) > $precision)) {
$number = substr($number, 0, strpos($number, '.') + 1 + $precision + 1);
if (substr($number, -1) >= 5) {
if ($precision > 1) {
$number = substr($number, 0, -1) + ('0.' . str_repeat(0, $precision-1) . '1');
} elseif ($precision == 1) {
$number = substr($number, 0, -1) + 0.1;
} else {
$number = substr($number, 0, -1) + 1;
}
} else {
$number = substr($number, 0, -1);
}
}
return $number;
}
Insert After:
////
// Round up function for non whole numbers by GREG DEETH
// The value for the precision variable determines how many digits after the decimal and rounds the last digit up to the next value
// Precision = 0 -> xx.xxxx = x+
// Precision = 1 -> xx.xxxx = xx.+
// Precision = 2 -> xx.xxxx = xx.x+
function tep_round_up($number, $precision) {
$number_whole = '';
$num_left_dec = 0;
$num_right_dec = 0;
$num_digits = strlen($number);
$number_out = '';
$i = 0;
while ($i + 1 <= strlen($number))
{
$current_digit = substr($number, $i, ($i + 1) - $num_digits);
if ($current_digit == '.') {
$i = $num_digits + 1;
$num_left_dec = strlen($number_whole);
$num_right_dec = ($num_left_dec + 1) - $num_digits;
} else {
$number_whole = $number_whole . $current_digit;
$i = $i + 1;
}
}
if ($num_digits > 3 && $precision < ($num_digits - $num_left_dec - 1) && $precision >= 0) {
$i = $precision;
$addable = 1;
while ($i > 0) {
$addable = $addable * .1;
$i = $i - 1;
}
$number_out = substr($number, 0, $num_right_dec + $precision) + $addable;
} else {
$number_out = $number;
}
return $number_out;
}
12. Add the following:
catalog/admin/modules.php
Find somewhere around line 43:
if (tep_not_null($action)) {
switch ($action) {
case 'save':
while (list($key, $value) = each($HTTP_POST_VARS['configuration'])) {
Insert After
if( is_array( $value ) ){
$value = implode( ", ", $value);
$value = ereg_replace (", --none--", "", $value);
}
13. Reinstall usps module from admin panel
14. Configure the settings.
*************************
TROUBLESHOOTING TIPS:
*************************
1. If you are getting a "parse error" when you click edit in the admin OR
your international options with checkboxes are not showing up in the admin,
you may need to use phpMyAdmin to update the database -> configuration TABLE
and CHANGE "set_function" to TEXT from VARCHAR.
Afterwards:
A. Remove the USPS module in the admin
B. Re-install the USPS module in the admin
C. The options will appear
2. Make sure you have set your store's country and postal code
in admin -> Configuration -> Shipping/Packaging, as these are used in
the rate quote request and if not valid will cause an error.
3. NOTE: SELECTING ANY GIVEN SHIPPING METHOD DOES NOT ENSURE IT WILL BE
AVAILABLE TO YOUR CUSTOMERS. USPS RETURNS A SET OF POSSIBLE SHIPPING METHODS
DEPENDING ON POINT OF ORIGIN AND DESTINATION, AND THIS CONTRIBUTION MERELY
FILTERS THEM SO THAT NON-SELECTED METHODS ARE NOT PRESENTED TO THE CUSTOMER
AS CHOICES. IF YOU DO NOT ENABLE ENOUGH SHIPPING METHODS, IT IS QUITE
POSSIBLE A CUSTOMER WILL NOT BE ABLE TO COMPLETE HIS/HER ORDER. ENABLE AS
MANY METHODS AS MAKE SENSE BASED ON THE NATURE OF YOUR STORE'S MERCHANDISE,
AND THE DESTINATIONS YOU SEEK TO ACCOMODATE.
4. To research persistent errors or to satisfy raw curiosity, you can enable
an embedded hook in the catalog/includes/modules/shipping/usps.php script that
sends an email containing the rate quote response from USPS. The email text
will be in XML format, but careful examination will reveal useful details.
Find the commented statement at line 526, insert your correct email address
in place of "user@localhost.com" in both places it occurs, and remove
the leading "//" characters that make the line a comment. Restore the comment
characters after you have tested using this hook. If you don't receive any
email after testing with this hook, that may indicate a failure in http socket
handling on your server.
********************
REVISION HISTORY
********************
5.2.1
January 23, 2001 by Fulluv Scents
Added date setting for local time.
Removed uneccessary line of code
Fixed trademark legends to show (required by USPS terms of use and federal law)
5.2.0
January 15th, 2011 by Fulluv Scents
Added international handling
Applied V4 IntlV2 syntax / required by May, 2011
Updated transit time responses and displays
Added user defined int'l package sizes - required by new syntax
Added option to charge retail or counter prices
Added delivery confirmation
Added signature confirmation
Added signature confirmation order threshold
Added processing time (to increase the transit time displayed)
Added user defined insurance (for private postal insurance)
Updated dmstc and intl insurance responses and displays
Updated display options - to work independently
transit time, weight, and insurance
Updated option to insure tax
Added option to insure shipping cost
5.1.0
January 6th, 2011 by Fulluv Scents
basic fine tuning for USPS V3 & V4 requirements
WORK IN PROGRESS - improvements forthcoming
5.0.3
January 6, 2011 by wkdwich
repaired handling fee issue
cleaned file for easier read
5.0.2
January 6th, 2011 by a HUGE collaboration of minds -
Fulluv Scents, altoid, pbolyn, wkdwich, and more
5.0.1
January 4, 2011 by Fulluv Scents:
Domestic methods partially fixed to work with rate changes
Standard domestic methods only - Flat rate not included
This is a temporary fix. It is not a clean or fully loaded module.
5.0.0
January 3, 2011 by Fulluv Scents:
International methods fixed to work with rate changes
Domestic methods incomplete / non working
changes since 4.3.1
---------------------
*Fixed bug caused by misplaced if statement that caused an error result if Display Transit Time was not selected
*Fixed hard coded text that should have come from language file
*Fixed error caused by reference to misspelled configuration variable
*Corrected configuration of allowed international types (Global Express Non-Document Rectangular got listed twice when one of them should have been Global Express Non-Document Non-Rectangular)
*updated US insurance costs to those current since May 11, 2009
Changes since v.4.3.0
---------------------
*Fixed dedicated priority flat rate options and added them back
*Added GUI Thresholds for all domestic types
*Added handling charge options for domestic types
*Added two functions that allow multiple input boxes in the admin panel.
Changes since v.4.2.1
---------------------
*Fixed issue with PayPal Express
*Added Global mail rates again with smaller SQL entries to avoid error
*2 added rates priority fltrt box and envelope do not work when arriving at confirmation page.
will try to fix in next release
Changes since v.4.2
-------------------
*Added unified insurance
*Int insurance rate is automatic while domestic rate is manual
Changes since v.4.0
-------------------
*Uses New USPS v3 API
*New package options due to v3 API: Flat-Rate, Letter, small/large package, ...
*Ability to calculate First Class Envelopes and Letters + Machineable options
*Fixed error when installing: SQL Statement too long (Global Express shipping services removed)
*Fixed machineable setting to change to false when package is over 3.5oz
Changes since v.3.0
-------------------
Added the optional shipping insurance order totals module (checkbox): http://addons.oscommerce.com/info/5782
Changes since v.2.9
-------------------
* Update in SQL for International Shipping
* Update usps.php for USPS naming conventions change (all caps)
* Update (once again) the code to make the parcel post quotes be less than priority mail (see 2.7 below)
* Insurance added to all USPS shipping quotes
* Friendly names updated for customer viewing
* Removed "$this->_setMachinable('False');" from usps.php that had crept into the code causing Parcel Post quotes to exceed Priority Mail quotes despite Christian's fix
* Removed deprecated code and 1 sql insert that duplicated a sql key for old usps naming standards
* Updated the instructions substantially and clarified some points
* Removed drop in instructions because it just causes errors for nearly everybody - it is good for people to discover how to edit, copy, and paste code - the instructions are clear
* Included a version WITH insurance and WITHOUT insurance in the same fileset
* Included update instructions
* Added "Estimated" on quotes seen in checkout shipping
* Updated troubleshooting section and the update text file
* Updated the code for Paypal Express http error (posted on forum)
* Fixed the admin USPS registration link to work
* Updated the modules/usps.php file to list the US shipping array so that it is readable
* Updated the insurance amount headings/descriptions in the admin
* Added additional international insurance rates in the admin in case of future USPS changes
* Updated the insurance amounts to format properly in the admin in currency
* Removed deprecated code from the english files
* Removed the library mail option as it does not apply to ecommerce
* Added estimated shipping times for all forms of domestic mail
Changes since v2.8
------------------
* Any reference to the International Names were updated, they were out of date.
* Changes were made to the usps.php file AND the 05092007_updates.txt file.
* This change was built on version 2.8d_1 (never liked these dumb naming conversions, just make it 2.9 instead of 2.8d_1.2.3h.sk.ii)
* Download WinMerge (free) to do a file comparison
* Readded the necessary admin files into this including admin/modules.php and admin/includes/fuctions/general.php.
Changes since v2.7
------------------
* Added step-by-step instructions within the admin to make it easy for developers and their customers to follow to registration at USPS and configuration setup.
* Fixed the parcel post bug where the parcel postage would be greater than priority mail.
* Added in logic/code to ./includes/modules/shipping/usps.php to determine if a package is machinable or non-machinable which determines if the parcel postage would cost more.
* Saved customers a ton of confusion on checkout.
* Fix shipping_ounces and shipping_pounds calculation
Changes since v2.6
------------------
* added service type literals for Bound Printed Material, Library and Media Mail, so these are recognized and offered as choices
* remove duplicate configuration table entry MODULE_SHIPPING_USPS_TAX_CLASS
* Added instructions with proper coding to manually install the modified files "modules.php" and "general.php". If you have an already modified store and you following the previous instructions you will get errors, and other contribs like "PayPal Shopping Cart IPN" AND "Header Tags Controller" will no longer work. Follow the instructions I have added to make this contrib work without harming an already modified store.
* Fixed the parcel post bug where the parcel postage would be greater than priority mail.
* Added in logic/code to ./includes/modules/shipping/usps.php to determine if a package is machinable or non-machinable which determines if the parcel postage would cost more.
* Saved customers a ton of confusion on checkout.
Changes since v2.5
------------------
* revised service type literals to match changes at USPS
Changes since v2.4
------------------
* Brought current with MS2
* Omit diff files
* Add troubleshooting hook
Changes since v2.3
------------------
* Brought current with MS1
* Fixed transit time display bug
* Now supports deselecting all checkboxes
Changes since v2.2
------------------
* Brought current with most recent cvs:
Separate handling charge per shipping module
Hard coded error message is in language file
Shipping charge is taxable
* Repackaged as full files instead of diffs
Changes since v2.1
------------------
* Fixed typos in Step 5 of the instructions. Kevin Cashman was the bugcatcher
this time.
Changes since v2.0
------------------
* Fixed a major bug that halted the installation process.
* Fixed minor bug that complained about a variable type when the destination
country was international.
* Added the new files to the contrib in addition to the diffs to retain others'
sanity as well.
Changes since v1.1
------------------
* Changed to a patch-based install to keep my sanity.
* Added international services support
* Added options to enable/disable weight and transit time display.
Changes since v1.0
------------------
* Adjusted code to reflect usps.php module in CVS.
* Added required SQL to install() function in usps.php (step 7).