1: <?php
  2: /**
  3:  * Magento
  4:  *
  5:  * NOTICE OF LICENSE
  6:  *
  7:  * This source file is subject to the Open Software License (OSL 3.0)
  8:  * that is bundled with this package in the file LICENSE.txt.
  9:  * It is also available through the world-wide-web at this URL:
 10:  * http://opensource.org/licenses/osl-3.0.php
 11:  * If you did not receive a copy of the license and are unable to
 12:  * obtain it through the world-wide-web, please send an email
 13:  * to license@magentocommerce.com so we can send you a copy immediately.
 14:  *
 15:  * DISCLAIMER
 16:  *
 17:  * Do not edit or add to this file if you wish to upgrade Magento to newer
 18:  * versions in the future. If you wish to customize Magento for your
 19:  * needs please refer to http://www.magentocommerce.com for more information.
 20:  *
 21:  * @category    Mage
 22:  * @package     Mage_Shipping
 23:  * @copyright   Copyright (c) 2012 Magento Inc. (http://www.magentocommerce.com)
 24:  * @license     http://opensource.org/licenses/osl-3.0.php  Open Software License (OSL 3.0)
 25:  */
 26: 
 27: 
 28: abstract class Mage_Shipping_Model_Carrier_Abstract extends Varien_Object
 29: {
 30:     /**
 31:      * Carrier's code
 32:      *
 33:      * @var string
 34:      */
 35:     protected $_code;
 36: 
 37:     /**
 38:      * Rates result
 39:      *
 40:      * @var array
 41:      */
 42:     protected $_rates = null;
 43: 
 44:     /**
 45:      * Number of boxes in package
 46:      *
 47:      * @var int
 48:      */
 49:     protected $_numBoxes = 1;
 50: 
 51:     /**
 52:      * Free Method config path
 53:      *
 54:      * @var string
 55:      */
 56:     protected $_freeMethod = 'free_method';
 57: 
 58:     /**
 59:      * Whether this carrier has fixed rates calculation
 60:      *
 61:      * @var bool
 62:      */
 63:     protected $_isFixed = false;
 64: 
 65:     /**
 66:      * Container types that could be customized
 67:      *
 68:      * @var array
 69:      */
 70:     protected $_customizableContainerTypes = array();
 71: 
 72:     const USA_COUNTRY_ID = 'US';
 73:     const CANADA_COUNTRY_ID = 'CA';
 74:     const MEXICO_COUNTRY_ID = 'MX';
 75: 
 76:     const HANDLING_TYPE_PERCENT = 'P';
 77:     const HANDLING_TYPE_FIXED = 'F';
 78: 
 79:     const HANDLING_ACTION_PERPACKAGE = 'P';
 80:     const HANDLING_ACTION_PERORDER = 'O';
 81: 
 82:     /**
 83:      * Fields that should be replaced in debug with '***'
 84:      *
 85:      * @var array
 86:      */
 87:     protected $_debugReplacePrivateDataKeys = array();
 88: 
 89:     /**
 90:      * Retrieve information from carrier configuration
 91:      *
 92:      * @param   string $field
 93:      * @return  mixed
 94:      */
 95:     public function getConfigData($field)
 96:     {
 97:         if (empty($this->_code)) {
 98:             return false;
 99:         }
100:         $path = 'carriers/'.$this->_code.'/'.$field;
101:         return Mage::getStoreConfig($path, $this->getStore());
102:     }
103: 
104:     /**
105:      * Retrieve config flag for store by field
106:      *
107:      * @param string $field
108:      * @return bool
109:      */
110:     public function getConfigFlag($field)
111:     {
112:         if (empty($this->_code)) {
113:             return false;
114:         }
115:         $path = 'carriers/'.$this->_code.'/'.$field;
116:         return Mage::getStoreConfigFlag($path, $this->getStore());
117:     }
118: 
119:     /**
120:      * Collect and get rates
121:      *
122:      * @abstract
123:      * @param Mage_Shipping_Model_Rate_Request $request
124:      * @return Mage_Shipping_Model_Rate_Result|bool|null
125:      */
126:     abstract public function collectRates(Mage_Shipping_Model_Rate_Request $request);
127: 
128:     /**
129:      * Do request to shipment
130:      * Implementation must be in overridden method
131:      *
132:      * @param Mage_Shipping_Model_Shipment_Request $request
133:      * @return Varien_Object
134:      */
135:     public function requestToShipment(Mage_Shipping_Model_Shipment_Request $request)
136:     {
137:         return new Varien_Object();
138:     }
139: 
140:     /**
141:      * Do return of shipment
142:      * Implementation must be in overridden method
143:      *
144:      * @param $request
145:      * @return Varien_Object
146:      */
147:     public function returnOfShipment($request)
148:     {
149:         return new Varien_Object();
150:     }
151: 
152:     /**
153:      * Return container types of carrier
154:      *
155:      * @param Varien_Object|null $params
156:      * @return array
157:      */
158:     public function getContainerTypes(Varien_Object $params = null)
159:     {
160:         return array();
161:     }
162: 
163:     /**
164:      * Get allowed containers of carrier
165:      *
166:      * @param Varien_Object|null $params
167:      * @return array|bool
168:      */
169:     protected function _getAllowedContainers(Varien_Object $params = null)
170:     {
171:         $containersAll = $this->getContainerTypesAll();
172:         if (empty($containersAll)) {
173:             return array();
174:         }
175:         if (empty($params)) {
176:             return $containersAll;
177:         }
178:         $containersFilter   = $this->getContainerTypesFilter();
179:         $containersFiltered = array();
180:         $method             = $params->getMethod();
181:         $countryShipper     = $params->getCountryShipper();
182:         $countryRecipient   = $params->getCountryRecipient();
183: 
184:         if (empty($containersFilter)) {
185:             return $containersAll;
186:         }
187:         if (!$params || !$method || !$countryShipper || !$countryRecipient) {
188:             return $containersAll;
189:         }
190: 
191:         if ($countryShipper == self::USA_COUNTRY_ID && $countryRecipient == self::USA_COUNTRY_ID) {
192:             $direction = 'within_us';
193:         } else if ($countryShipper == self::USA_COUNTRY_ID && $countryRecipient != self::USA_COUNTRY_ID) {
194:             $direction = 'from_us';
195:         } else {
196:             return $containersAll;
197:         }
198: 
199:         foreach ($containersFilter as $dataItem) {
200:             $containers = $dataItem['containers'];
201:             $filters = $dataItem['filters'];
202:             if (!empty($filters[$direction]['method'])
203:                 && in_array($method, $filters[$direction]['method'])
204:             ) {
205:                 foreach ($containers as $container) {
206:                     if (!empty($containersAll[$container])) {
207:                         $containersFiltered[$container] = $containersAll[$container];
208:                     }
209:                 }
210:             }
211:         }
212: 
213:         return !empty($containersFiltered) ? $containersFiltered : $containersAll;
214:     }
215: 
216:     /**
217:      * Get Container Types, that could be customized
218:      *
219:      * @return array
220:      */
221:     public function getCustomizableContainerTypes()
222:     {
223:         return $this->_customizableContainerTypes;
224:     }
225: 
226:     /**
227:      * Return delivery confirmation types of carrier
228:      *
229:      * @param Varien_Object|null $params
230:      * @return array
231:      */
232:     public function getDeliveryConfirmationTypes(Varien_Object $params = null)
233:     {
234:         return array();
235:     }
236: 
237:     public function checkAvailableShipCountries(Mage_Shipping_Model_Rate_Request $request)
238:     {
239:         $speCountriesAllow = $this->getConfigData('sallowspecific');
240:         /*
241:         * for specific countries, the flag will be 1
242:         */
243:         if ($speCountriesAllow && $speCountriesAllow == 1){
244:              $showMethod = $this->getConfigData('showmethod');
245:              $availableCountries = array();
246:              if($this->getConfigData('specificcountry')) {
247:                 $availableCountries = explode(',',$this->getConfigData('specificcountry'));
248:              }
249:              if ($availableCountries && in_array($request->getDestCountryId(), $availableCountries)) {
250:                  return $this;
251:              } elseif ($showMethod && (!$availableCountries || ($availableCountries
252:                  && !in_array($request->getDestCountryId(), $availableCountries)))
253:              ){
254:                    $error = Mage::getModel('shipping/rate_result_error');
255:                    $error->setCarrier($this->_code);
256:                    $error->setCarrierTitle($this->getConfigData('title'));
257:                    $errorMsg = $this->getConfigData('specificerrmsg');
258:                    $error->setErrorMessage($errorMsg ? $errorMsg : Mage::helper('shipping')->__('The shipping module is not available for selected delivery country.'));
259:                    return $error;
260:              } else {
261:                  /*
262:                 * The admin set not to show the shipping module if the devliery country is not within specific countries
263:                 */
264:                 return false;
265:              }
266:         }
267:         return $this;
268:     }
269: 
270: 
271:     /**
272:      * Processing additional validation to check is carrier applicable.
273:      *
274:      * @param Mage_Shipping_Model_Rate_Request $request
275:      * @return Mage_Shipping_Model_Carrier_Abstract|Mage_Shipping_Model_Rate_Result_Error|boolean
276:      */
277:     public function proccessAdditionalValidation(Mage_Shipping_Model_Rate_Request $request)
278:     {
279:         return $this;
280:     }
281: 
282:     /**
283:      * Determine whether current carrier enabled for activity
284:      *
285:      * @return bool
286:      */
287:     public function isActive()
288:     {
289:         $active = $this->getConfigData('active');
290:         return $active==1 || $active=='true';
291:     }
292: 
293:     /**
294:      * Whether this carrier has fixed rates calculation
295:      *
296:      * @return bool
297:      */
298:     public function isFixed()
299:     {
300:         return $this->_isFixed;
301:     }
302: 
303:     /**
304:      * Check if carrier has shipping tracking option available
305:      *
306:      * @return boolean
307:      */
308:     public function isTrackingAvailable()
309:     {
310:         return false;
311:     }
312: 
313:     /**
314:      * Check if carrier has shipping label option available
315:      *
316:      * @return boolean
317:      */
318:     public function isShippingLabelsAvailable()
319:     {
320:         return false;
321:     }
322: 
323:     /**
324:      *  Retrieve sort order of current carrier
325:      *
326:      * @return mixed
327:      */
328:     public function getSortOrder()
329:     {
330:         return $this->getConfigData('sort_order');
331:     }
332: 
333:     /**
334:      * @param Mage_Shipping_Model_Rate_Request $request
335:      * @return null
336:      */
337:     protected function _updateFreeMethodQuote($request)
338:     {
339:         if ($request->getFreeMethodWeight() == $request->getPackageWeight() || !$request->hasFreeMethodWeight()) {
340:             return;
341:         }
342: 
343:         $freeMethod = $this->getConfigData($this->_freeMethod);
344:         if (!$freeMethod) {
345:             return;
346:         }
347:         $freeRateId = false;
348: 
349:         if (is_object($this->_result)) {
350:             foreach ($this->_result->getAllRates() as $i=>$item) {
351:                 if ($item->getMethod() == $freeMethod) {
352:                     $freeRateId = $i;
353:                     break;
354:                 }
355:             }
356:         }
357: 
358:         if ($freeRateId === false) {
359:             return;
360:         }
361:         $price = null;
362:         if ($request->getFreeMethodWeight() > 0) {
363:             $this->_setFreeMethodRequest($freeMethod);
364: 
365:             $result = $this->_getQuotes();
366:             if ($result && ($rates = $result->getAllRates()) && count($rates)>0) {
367:                 if ((count($rates) == 1) && ($rates[0] instanceof Mage_Shipping_Model_Rate_Result_Method)) {
368:                     $price = $rates[0]->getPrice();
369:                 }
370:                 if (count($rates) > 1) {
371:                     foreach ($rates as $rate) {
372:                         if ($rate instanceof Mage_Shipping_Model_Rate_Result_Method
373:                             && $rate->getMethod() == $freeMethod
374:                         ) {
375:                             $price = $rate->getPrice();
376:                         }
377:                     }
378:                 }
379:             }
380:         } else {
381:             /**
382:              * if we can apply free shipping for all order we should force price
383:              * to $0.00 for shipping with out sending second request to carrier
384:              */
385:             $price = 0;
386:         }
387: 
388:         /**
389:          * if we did not get our free shipping method in response we must use its old price
390:          */
391:         if (!is_null($price)) {
392:             $this->_result->getRateById($freeRateId)->setPrice($price);
393:         }
394:     }
395: 
396:     /**
397:      * Calculate price considering free shipping and handling fee
398:      *
399:      * @param string $cost
400:      * @param string $method
401:      * @return string
402:      */
403:     public function getMethodPrice($cost, $method='')
404:     {
405:         if ($method == $this->getConfigData($this->_freeMethod) && $this->getConfigData('free_shipping_enable')
406:             && $this->getConfigData('free_shipping_subtotal') <= $this->_rawRequest->getBaseSubtotalInclTax()
407:         ) {
408:             $price = '0.00';
409:         } else {
410:             $price = $this->getFinalPriceWithHandlingFee($cost);
411:         }
412:         return $price;
413:     }
414: 
415:     /**
416:      * get the handling fee for the shipping + cost
417:      *
418:      * @param float $cost
419:      * @return float final price for shipping method
420:      */
421:     public function getFinalPriceWithHandlingFee($cost)
422:     {
423:         $handlingFee = $this->getConfigData('handling_fee');
424:         $handlingType = $this->getConfigData('handling_type');
425:         if (!$handlingType) {
426:             $handlingType = self::HANDLING_TYPE_FIXED;
427:         }
428:         $handlingAction = $this->getConfigData('handling_action');
429:         if (!$handlingAction) {
430:             $handlingAction = self::HANDLING_ACTION_PERORDER;
431:         }
432: 
433:         return ($handlingAction == self::HANDLING_ACTION_PERPACKAGE)
434:             ? $this->_getPerpackagePrice($cost, $handlingType, $handlingFee)
435:             : $this->_getPerorderPrice($cost, $handlingType, $handlingFee);
436:     }
437: 
438:     /**
439:      * Get final price for shipping method with handling fee per package
440:      *
441:      * @param float $cost
442:      * @param string $handlingType
443:      * @param float $handlingFee
444:      * @return float
445:      */
446:     protected function _getPerpackagePrice($cost, $handlingType, $handlingFee)
447:     {
448:         if ($handlingType == self::HANDLING_TYPE_PERCENT) {
449:             return ($cost + ($cost * $handlingFee/100)) * $this->_numBoxes;
450:         }
451: 
452:         return ($cost + $handlingFee) * $this->_numBoxes;
453:     }
454: 
455:     /**
456:      * Get final price for shipping method with handling fee per order
457:      *
458:      * @param float $cost
459:      * @param string $handlingType
460:      * @param float $handlingFee
461:      * @return float
462:      */
463:     protected function _getPerorderPrice($cost, $handlingType, $handlingFee)
464:     {
465:         if ($handlingType == self::HANDLING_TYPE_PERCENT) {
466:             return ($cost * $this->_numBoxes) + ($cost * $this->_numBoxes * $handlingFee / 100);
467:         }
468: 
469:         return ($cost * $this->_numBoxes) + $handlingFee;
470:     }
471: 
472:     /**
473:      *  Return weight in pounds
474:      *
475:      *  @param integer Weight in someone measure
476:      *  @return float Weight in pounds
477:      */
478:     public function convertWeightToLbs($weight)
479:     {
480:         return $weight;
481:     }
482: 
483:     /**
484:      * set the number of boxes for shipping
485:      *
486:      * @return weight
487:      */
488:     public function getTotalNumOfBoxes($weight)
489:     {
490:         /*
491:         reset num box first before retrieve again
492:         */
493:         $this->_numBoxes = 1;
494:         $weight = $this->convertWeightToLbs($weight);
495:         $maxPackageWeight = $this->getConfigData('max_package_weight');
496:         if ($weight > $maxPackageWeight && $maxPackageWeight != 0) {
497:             $this->_numBoxes = ceil($weight/$maxPackageWeight);
498:             $weight = $weight/$this->_numBoxes;
499:         }
500:         return $weight;
501:     }
502: 
503:     /**
504:      * Is state province required
505:      *
506:      * @return bool
507:      */
508:     public function isStateProvinceRequired()
509:     {
510:         return false;
511:     }
512: 
513:     /**
514:      * Check if city option required
515:      *
516:      * @return boolean
517:      */
518:     public function isCityRequired()
519:     {
520:         return false;
521:     }
522: 
523:     /**
524:      * Determine whether zip-code is required for the country of destination
525:      *
526:      * @param string|null $countryId
527:      * @return bool
528:      */
529:     public function isZipCodeRequired($countryId = null)
530:     {
531:         return false;
532:     }
533: 
534:     /**
535:      * Log debug data to file
536:      *
537:      * @param mixed $debugData
538:      */
539:     protected function _debug($debugData)
540:     {
541:         if ($this->getDebugFlag()) {
542:             Mage::getModel('core/log_adapter', 'shipping_' . $this->getCarrierCode() . '.log')
543:                ->setFilterDataKeys($this->_debugReplacePrivateDataKeys)
544:                ->log($debugData);
545:         }
546:     }
547: 
548:     /**
549:      * Define if debugging is enabled
550:      *
551:      * @return bool
552:      */
553:     public function getDebugFlag()
554:     {
555:         return $this->getConfigData('debug');
556:     }
557: 
558:     /**
559:      * Used to call debug method from not Payment Method context
560:      *
561:      * @param mixed $debugData
562:      */
563:     public function debugData($debugData)
564:     {
565:         $this->_debug($debugData);
566:     }
567: 
568:     /**
569:      * Getter for carrier code
570:      *
571:      * @return string
572:      */
573:     public function getCarrierCode()
574:     {
575:         return $this->_code;
576:     }
577: 
578:     /**
579:      * Return content types of package
580:      *
581:      * @param Varien_Object $params
582:      * @return array
583:      */
584:     public function getContentTypes(Varien_Object $params)
585:     {
586:         return array();
587:     }
588: }
589: