shipwire.module

<?php

/**
 * @file
 * Shipwire API to integrate services provided by shipwire.com 
 */

/**
 * Implements hook_menu().
 */
function shipwire_menu() {
  $items = array();

  $items['admin/shipwire/settings'] = array(
    'title' => 'Settings',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('shipwire_admin_account_settings'),
    'access arguments' => array('edit shipwire settings'),
    'file' => 'shipwire.admin.inc',
  );
  $items['admin/shipwire/settings/account'] = array(
    'title' => 'Account',
    'type' => MENU_DEFAULT_LOCAL_TASK,
  );
  $items['admin/shipwire/settings/cron'] = array(
    'title' => 'Cache & Cron',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('shipwire_admin_cron_settings'),
    'access arguments' => array('edit shipwire settings'),
    'file' => 'shipwire.admin.inc',
    'type' => MENU_LOCAL_TASK,
  );
  $items['admin/shipwire/settings/misc'] = array(
    'title' => 'Misc',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('shipwire_admin_misc_settings'),
    'access arguments' => array('edit shipwire settings'),
    'file' => 'shipwire.admin.inc',
    'type' => MENU_LOCAL_TASK,
  );
  $items['admin/shipwire/shipment/%shipwire_shipment'] = array(
    'page callback' => 'shipwire_shipment_view',
    'page arguments' => array(3),
    'access arguments' => array('view all shipwire shipments'),
    'file' => 'shipwire.admin.inc',
  );
  $items['admin/shipwire/shipment/%shipwire_shipment/view'] = array(
    'title' => 'View',
    'weight' => -5,
    'type' => MENU_DEFAULT_LOCAL_TASK,
  );
  $items['admin/shipwire/shipment/%shipwire_shipment/edit'] = array(
    'title' => 'Edit',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('shipwire_shipment_edit', 3),
    'access arguments' => array('edit all shipwire shipments'),
    'type' => MENU_LOCAL_TASK,
    'file' => 'shipwire.admin.inc',
  );

  return $items;
}

/**
 * Implements hook_permission().
 */
function shipwire_permission() {
  return array(
    'edit shipwire settings' => array(
      'title' => t('Edit Shipwire settings'),
      'description' => t('Edit Shipwire settings.'),
    ),
    'edit all shipwire shipments' => array(
      'title' => t('Edit all Shipwire shipments'),
      'description' => t('Edit all Shipwire shipments.'),
    ),
    'view all shipwire shipments' => array(
      'title' => t('View all Shipwire shipments'),
      'description' => t('View all Shipwire shipments.'),
    ),
    'create shipwire shipments' => array(
      'title' => t('Create Shipwire shipments'),
      'description' => t('Create Shipwire shipments.'),
    ),
  );
}

/**
 * Caches order products, address, and rates.
 * 
 * Products and address are needed to ensure that cached rate is still valid. If
 * either of these change then the cache is invalidated.
 * 
 * @param ShipwireRateRequestOrder $request_order
 *   A fully populated Rate request order containing products and address.
 * @param array $rates
 *   The array of calculated shipping rates to save.
 */
function shipwire_rates_cache_set(ShipwireRateRequestOrder $request_order, $rates) {
  $lifetime = variable_get('shipwire_cache_life', 21600);
  $expiration = REQUEST_TIME + $lifetime;
  $cid = $request_order->order_id;

  $data = array(
    'rates' => $rates,
    'order' => $request_order,
  );

  cache_set($cid, $data, 'cache_shipwire_rates', $expiration);
}

/**
 * Load rates for an order from the cache.
 * 
 * @param ShipwireRateRequestOrder $request_order
 *   A fully populated Rate request order containing products and address.
 * 
 * @return FALSE|array
 *   FALSE on empty or array of cache information.
 */
function shipwire_rates_cache_get(ShipwireRateRequestOrder $request_order) {
  $cid = $request_order->order_id;
  $return = FALSE;
  $cache = cache_get($cid, 'cache_shipwire_rates');

  if (!empty($cache)) {
    if ($cache->data['order']->address == $request_order->address && $cache->data['order']->products == $request_order->products) {
      $return = $cache->data;
    }
    else {
      shipwire_rates_cache_clear($cid);
    }
  }

  return $return;
}

/**
 * Clear the rates cache entirely or for a specific order.
 * 
 * @param string $cid
 *   The order prefix and order id as string.
 */
function shipwire_rates_cache_clear($cid = NULL) {
  cache_clear_all($cid, 'cache_shipwire_rates');
}

/**
 * Implements hook_flush_caches().
 */
function shipwire_flush_caches() {
  return array('cache_shipwire_rates');
}

/**
 * Implements hook_entity_info().
 */
function shipwire_entity_info() {
  $return = array(
    'shipwire_shipment' => array(
      'module' => 'shipwire',
      'token_type' => 'shipwire-shipment',
      'label' => t('Shipwire shipment'),
      'entity class' => 'ShipwireShipment',
      'controller class' => 'ShipwireShipmentController',
      'extra fields controller class' => 'EntityDefaultExtraFieldsController',
      'base table' => 'shipwire_shipments',
      'label callback' => 'entity_class_label',
      'uri callback' => 'entity_class_uri',
      'fieldable' => FALSE,
      'metadata controller class' => '',
      'entity keys' => array(
        'id' => 'shipwire_shipment_id',
        'bundle' => 'type',
      ),
      'bundle keys' => array(
        'bundle' => 'type',
      ),
      'bundles' => array(),
      'view modes' => array(
        'full' => array(
          'label' => t('Full shipment'),
          'custom settings' => FALSE,
        ),
      ),
      'access callback' => 'shipwire_shipment_access',
    ),
  );

  return $return;
}

/**
 * Implements hook_field_info().
 */
function shipwire_field_info() {
  return array(
    'shipwire_shipment_reference' => array(
      'label' => t('Shipwire shipment reference'),
      'description' => t('This field stores the ID of a related Shipwire shipment as an integer value.'),
      'settings' => array('allowed_values' => array(), 'allowed_values_function' => ''),
      'instance_settings' => array(),
      'default_widget' => 'shipwire_shipment_reference_hidden',
      'default_formatter' => 'hidden',
      'property_type' => 'shipwire_shipments',
      'property_callbacks' => array('shipwire_shipment_property_info_callback'),
    ),
  );
}

/**
 * Implements hook_field_widget_info().
 */
function shipwire_field_widget_info() {
  $widgets = array();

  $widgets['shipwire_shipment_reference_hidden'] = array(
    'label' => t('Do not show a widget'),
    'description' => t('Will not display the shipment reference field on forms.'),
    'field types' => array('shipwire_shipment_reference'),
    'settings' => array(),
    'behaviors' => array(
      'multiple values' => FIELD_BEHAVIOR_CUSTOM,
    ),
  );

  return $widgets;
}

/**
 * Implements hook_entity_property_info().
 */
function shipwire_entity_property_info() {
  $info = array();

  $info['shipwire_shipment']['properties']['shipwire_shipment_id'] = array(
    'label' => t('Shipwire shipment ID'),
    'description' => t('The internal numeric ID of the shipment.'),
    'type' => 'integer',
    'schema field' => 'shipwire_shipment_id',
  );
  $info['shipwire_shipment']['properties']['order_id'] = array(
    'label' => t('Order ID'),
    'description' => t('The order id that the shipment is for.'),
    'type' => 'integer',
    'schema field' => 'order_id',
  );
  $info['shipwire_shipment']['properties']['order_prefix'] = array(
    'label' => t('Order prefix'),
    'description' => t('Order prefix prepended to order id.'),
    'type' => 'text',
    'schema field' => 'order_prefix',
  );
  $info['shipwire_shipment']['properties']['shipwire_id'] = array(
    'label' => t('Shipwire shipment ID'),
    'description' => t('Shipwire shipment id'),
    'type' => 'text',
    'schema field' => 'shipwire_id',
  );
  $info['shipwire_shipment']['properties']['shipwire_uri'] = array(
    'label' => t('Shipwire URI'),
    'description' => t('The URI to the shipment on the Shipwire site.'),
    'type' => 'uri',
    'schema field' => 'shipwire_uri',
  );
  $info['shipwire_shipment']['properties']['shipping_method'] = array(
    'label' => t('Shipping method'),
    'description' => t('Shipping method id.'),
    'type' => 'text',
    'schema field' => 'shipping_method',
    'options list' => Shipwire::getShippingMethods(),
  );
  $info['shipwire_shipment']['properties']['status'] = array(
    'label' => t('Status'),
    'description' => t('The current status of the shipment.'),
    'type' => 'text',
    'schema field' => 'status',
    'options list' => Shipwire::getStatusCodes(),
  );
  $info['shipwire_shipment']['properties']['trackable'] = array(
    'label' => t('Trackable'),
    'description' => t('Whether the shipment is tracked by the carrier.'),
    'type' => 'boolean',
    'schema field' => 'trackable',
  );
  $info['shipwire_shipment']['properties']['carrier_code'] = array(
    'label' => t('Carrier code'),
    'description' => t('Shipwire code identifying the shipping company and delivery method.'),
    'type' => 'text',
    'schema field' => 'carrier_code',
    'options list' => Shipwire::getCarriers(),
  );
  $info['shipwire_shipment']['properties']['warehouse_code'] = array(
    'label' => t('Warehouse code'),
    'description' => t('Code identifying the warehouse the shipment was sent from.'),
    'type' => 'text',
    'schema field' => 'warehouse_code',
    'options list' => Shipwire::getWarehouses(TRUE, FALSE),
  );
  $info['shipwire_shipment']['properties']['date_submitted'] = array(
    'label' => t('Date submitted'),
    'description' => t('The date indicating when shipment was submitted to Shipwire.'),
    'type' => 'date',
    'schema field' => 'date_submitted',
  );
  $info['shipwire_shipment']['properties']['date_shipped'] = array(
    'label' => t('Date shipped'),
    'description' => t('The date indicating when the shipment left Shipwire warehouse.'),
    'type' => 'date',
    'schema field' => 'date_shipped',
  );
  $info['shipwire_shipment']['properties']['date_expected'] = array(
    'label' => t('Date expected'),
    'description' => t('The date indicating when the shipment is expected to arrive.'),
    'type' => 'date',
    'schema field' => 'date_expected',
  );
  $info['shipwire_shipment']['properties']['date_delivered'] = array(
    'label' => t('Date delivered'),
    'description' => t('The date indicating when the shipment was delivered.'),
    'type' => 'date',
    'schema field' => 'date_delivered',
  );
  $info['shipwire_shipment']['properties']['created'] = array(
    'label' => t('Date created'),
    'description' => t('The date the shipment was created.'),
    'type' => 'date',
    'schema field' => 'created',
  );
  $info['shipwire_shipment']['properties']['changed'] = array(
    'label' => t('Date changed'),
    'description' => t('The date the shipment was last modified.'),
    'type' => 'date',
    'schema field' => 'changed',
  );
  $info['shipwire_shipment']['properties']['tracking_number'] = array(
    'label' => t('Tracking number'),
    'description' => t('Number used to locate the shipment while it is in transit.'),
    'type' => 'text',
    'schema field' => 'tracking_number',
  );
  $info['shipwire_shipment']['properties']['tracking_uri'] = array(
    'label' => t('Tracking URI'),
    'description' => t('The URI to a site that provides tracking information.'),
    'type' => 'uri',
    'schema field' => 'tracking_uri',
  );
  $info['shipwire_shipment']['properties']['currency'] = array(
    'label' => t('Currency code'),
    'description' => t('ISO 4217 3 digit currency code for the costs.'),
    'type' => 'text',
    'schema field' => 'currency',
    'options list' => Shipwire::getCurrencies(),
  );
  $info['shipwire_shipment']['properties']['cost_total'] = array(
    'label' => t('Total cost'),
    'description' => t('Total cost of the shipment as decimal.'),
    'type' => 'decimal',
    'schema field' => 'cost_total',
  );
  $info['shipwire_shipment']['properties']['cost_freight'] = array(
    'label' => t('Frieght cost'),
    'description' => t('Freight cost of the shipment as decimal.'),
    'type' => 'decimal',
    'schema field' => 'cost_freight',
  );
  $info['shipwire_shipment']['properties']['cost_handling'] = array(
    'label' => t('Handling cost'),
    'description' => t('Handling cost of the shipment as decimal.'),
    'type' => 'decimal',
    'schema field' => 'cost_handling',
  );
  $info['shipwire_shipment']['properties']['cost_packaging'] = array(
    'label' => t('Packaging cost'),
    'description' => t('Packaging cost of the shipment as decimal.'),
    'type' => 'decimal',
    'schema field' => 'cost_packaging',
  );
  $info['shipwire_shipment']['properties']['cost_insurance'] = array(
    'label' => t('Insurance cost'),
    'description' => t('Insurance cost of the shipment as decimal.'),
    'type' => 'decimal',
    'schema field' => 'cost_insurance',
  );
  $info['shipwire_shipment']['properties']['manually_edited'] = array(
    'label' => t('Manually edited'),
    'description' => t('Whether the shipment order was manually edited in Shipwire.'),
    'type' => 'boolean',
    'schema field' => 'manually_edited',
  );
  return $info;
}

/**
 * Implements hook_field_is_empty().
 */
function shipwire_field_is_empty($item, $field) {
  if ($field['type'] == 'shipwire_shipment_id') {
    return empty($item['shipwire_shipment_id']);
  }
}

/**
 * Callback to alter the property info of the reference field.
 *
 * @see commerce_customer_field_info()
 */
function shipwire_shipment_property_info_callback(&$info, $entity_type, $field, $instance, $field_type) {
  $property = &$info[$entity_type]['bundles'][$instance['bundle']]['properties'][$field['field_name']];
  $property['options list'] = 'entity_metadata_field_options_list';
}

/**
 * Title callback for Shipwire shipment.
 */
function shipwire_shipment_title(ShipwireShipment $shipment) {
  return t('Shipment !id', array('!id' => $shipment->shipwire_shipment_id));
}

/**
 * URI callback for Shipwire shipment.
 */
function shipwire_shipment_uri(ShipwireShipment $shipment) {
  return array('path' => 'admin/shipwire/shipment/' . $shipment->shipwire_shipment_id);
}

/**
 * Load a single Shipwire shipment.
 */
function shipwire_shipment_load($shipwire_shipment_id, $reset = FALSE) {
  $models = shipwire_shipment_load_multiple(array($shipwire_shipment_id), array(), $reset);
  return reset($models);
}

/**
 * Load multiple Shipwire shipments.
 */
function shipwire_shipment_load_multiple($shipwire_shipment_ids, $conditions = array(), $reset = FALSE) {
  return entity_load('shipwire_shipment', $shipwire_shipment_ids, $conditions, $reset);
}

/**
 * Saves a Shipwire shipment.
 */
function shipwire_shipment_save(ShipwireShipment $shipment) {
  return $shipment->save();
}

/**
 * Access callback to edit a Shipwire shipment.
 * 
 * @return bool
 *   TRUE or FALSE value indicating user access.
 */
function shipwire_shipment_access() {
  return user_access('edit all shipwire shipments');
}

/**
 * Create a Shipwire shipment.
 */
function shipwire_shipment_create($values = array()) {
  return entity_get_controller('shipwire_shipment')->create($values);
}

/**
 * Deletes a Shipwire shipment.
 */
function shipwire_shipment_delete(ShipwireShipment $shipment) {
  $shipment->delete();
}

/**
 * Delete multiple Shipwire shipments.
 */
function shipwire_shipment_delete_multiple(array $shipwire_shipment_ids) {
  entity_get_controller('shipwire_shipment')->delete($shipwire_shipment_ids);
}

/**
 * Implements hook_views_api().
 */
function shipwire_views_api() {
  return array(
    'api' => 3,
    'path' => drupal_get_path('module', 'shipwire') . '/includes/views',
  );
}

/**
 * Implements hook_date_views_tables().
 */
function shipwire_date_views_tables() {
  return array('shipwire_shipments');
}

/**
 * Implements hook_date_views_fields().
 *
 * All modules that create custom fields that use the
 * 'views_handler_field_date' handler can provide
 * additional information here about the type of
 * date they create so the date can be used by
 * the Date API views date argument and date filter.
 */
function shipwire_date_views_fields($field) {
  $values = array(
    // The type of date: DATE_UNIX, DATE_ISO, DATE_DATETIME.
    'sql_type' => DATE_UNIX,
    // Timezone handling options: 'none', 'site', 'date', 'utc' .
    'tz_handling' => 'site',
    // Needed only for dates that use 'date' tz_handling.
    'timezone_field' => '',
    // Needed only for dates that use 'date' tz_handling.
    'offset_field' => '',
    // Array of "table.field" values for related fields that should be
    // loaded automatically in the Views SQL.
    'related_fields' => array(),
    // Granularity of this date field's db data.
    'granularity' => array('year', 'month', 'day', 'hour', 'minute', 'second'),
  );

  switch ($field) {
    case 'shipwire_shipments.date_submitted':
    case 'shipwire_shipments.date_shipped':
    case 'shipwire_shipments.date_expected':
    case 'shipwire_shipments.date_delivered':
      return $values;
  }
}

/**
 * Return a formatted price.
 * 
 * Uses commerce or ubercart formatters if they exist or returns a basic string
 * with currency code.
 * 
 * @param float $amount
 *   The amount to format.
 * @param string $currency_code
 *   The 3 character ISO currency code to format with.
 * 
 * @return string
 *   The formatted amount.
 */
function shipwire_currency_format($amount, $currency_code) {
  if (function_exists('commerce_currency_format')) {
    return commerce_currency_format($amount, $currency_code, NULL, FALSE);
  }
  elseif (function_exists('uc_currency_format')) {
    return uc_currency_format($amount);
  }
  else {
    return $currency_code . ' ' . str_pad(round($amount, 2), 2, '0', STR_PAD_RIGHT);
  }
}

/**
 * Return a currency code symbol.
 * 
 * Uses commerce or ubercart function if they exist or return the original 
 * currency code.
 * 
 * @param string $currency_code
 *   The 3 character ISO currency code to format with.
 * 
 * @return string
 *   The currency symbol or currency code.
 */
function shipwire_currency_symbol($currency_code) {
  if (function_exists('commerce_currency_load')) {
    $currency = commerce_currency_load($currency_code);
    return $currency['code'];
  }
  elseif ($symbol = variable_get('uc_currency_sign', FALSE)) {
    return $symbol;
  }
  else {
    return $currency_code;
  }
}

/**
 * Render shipment messages array into an unordered list.
 * 
 * @param array $messages
 * 
 * @return string
 */
function shipwire_shipment_render_messages($messages) {
  $output = '';
  if (!empty($messages)) {
    $output = '<ul class="shipwire-messages">';
    foreach ($messages as $message) {
      $output .= '<li class="' . $message['type'] . '">' . $message['message'] . '</li>';
    }
    $output .= '</ul>';
  }
  return $output;
}

/**
 * Converts a tracking uri into an order uri.
 * 
 * @param string $tracking_uri
 * 
 * @return string
 */
function shipwire_order_uri($tracking_uri) {
  // Tracking Uri: 
  // https://beta.shipwire.com/c/t/1a1c94a0fbb5542c53c41b7d7e059400:1050511
  // Order Uri:
  // https://merchant.beta.shipwire.com/merchants/ship/confirm/orderId/1050511

  $order_uri = '';
  $order_id_pos = strrpos($tracking_uri, ':');
  $shipwire_pos = strpos($tracking_uri, 'shipwire.com');

  if ($order_id_pos && $shipwire_pos) {
    $order_id = substr($tracking_uri, $order_id_pos + 1);
    $endpoint = substr($tracking_uri, 0, $shipwire_pos + 12);
    if (strstr($endpoint, 'beta')) {
      $endpoint = str_replace('beta', 'merchant.beta', $endpoint);
    }
    $order_uri = $endpoint . '/merchants/ship/confirm/orderId/' . $order_id;
  }
  return $order_uri;
}