Club Drupal

<?php

/**

 * @file

 * Language Negotiation API.

 *

 * @see http://drupal.org/node/1497272

 */

/**

 * No language negotiation. The default language is used.

 */

define('LANGUAGE_NEGOTIATION_DEFAULT', 'language-default');

/**

 * @defgroup language_negotiation Language Negotiation API functionality

 * @{

 * Functions to customize the language types and the negotiation process.

 *

 * The language negotiation API is based on two major concepts:

 * - Language types: types of translatable data (the types of data that a user

 *   can view or request).

 * - Language negotiation providers: functions for determining which language to

 *   use to present a particular piece of data to the user.

 * Both language types and language negotiation providers are customizable.

 *

 * Drupal defines three built-in language types:

 * - Interface language: The page's main language, used to present translated

 *   user interface elements such as titles, labels, help text, and messages.

 * - Content language: The language used to present content that is available

 *   in more than one language (see

 *   @link field_language Field Language API @endlink for details).

 * - URL language: The language associated with URLs. When generating a URL,

 *   this value will be used by url() as a default if no explicit preference is

 *   provided.

 * Modules can define additional language types through

 * hook_language_types_info(), and alter existing language type definitions

 * through hook_language_types_info_alter().

 *

 * Language types may be configurable or fixed. The language negotiation

 * providers associated with a configurable language type can be explicitly

 * set through the user interface. A fixed language type has predetermined

 * (module-defined) language negotiation settings and, thus, does not appear in

 * the configuration page. Here is a code snippet that makes the content

 * language (which by default inherits the interface language's values)

 * configurable:

 * @code

 * function mymodule_language_types_info_alter(&$language_types) {

 *   unset($language_types[LANGUAGE_TYPE_CONTENT]['fixed']);

 * }

 * @endcode

 *

 * Every language type can have a different set of language negotiation

 * providers assigned to it. Different language types often share the same

 * language negotiation settings, but they can have independent settings if

 * needed. If two language types are configured the same way, their language

 * switcher configuration will be functionally identical and the same settings

 * will act on both language types.

 *

 * Drupal defines the following built-in language negotiation providers:

 * - URL: Determine the language from the URL (path prefix or domain).

 * - Session: Determine the language from a request/session parameter.

 * - User: Follow the user's language preference.

 * - Browser: Determine the language from the browser's language settings.

 * - Default language: Use the default site language.

 * Language negotiation providers are simple callback functions that implement a

 * particular logic to return a language code. For instance, the URL provider

 * searches for a valid path prefix or domain name in the current request URL.

 * If a language negotiation provider does not return a valid language code, the

 * next provider associated to the language type (based on provider weight) is

 * invoked.

 *

 * Modules can define additional language negotiation providers through

 * hook_language_negotiation_info(), and alter existing providers through

 * hook_language_negotiation_info_alter(). Here is an example snippet that lets

 * path prefixes be ignored for administrative paths:

 * @code

 * function mymodule_language_negotiation_info_alter(&$negotiation_info) {

 *   // Replace the core function with our own function.

 *   module_load_include('language', 'inc', 'language.negotiation');

 *   $negotiation_info[LANGUAGE_NEGOTIATION_URL]['callbacks']['language'] = 'mymodule_from_url';

 *   $negotiation_info[LANGUAGE_NEGOTIATION_URL]['file'] = drupal_get_path('module', 'mymodule') . '/mymodule.module';

 * }

 *

 * function mymodule_from_url($languages) {

 *   // Use the core URL language negotiation provider to get a valid language

 *   // code.

 *   module_load_include('language', 'inc', 'language.negotiation');

 *   $langcode = language_from_url($languages);

 *

 *   // If we are on an administrative path, override with the default language.

 *   if (isset($_GET['q']) && strtok($_GET['q'], '/') == 'admin') {

 *     return language_default()->langcode;

 *   }

 *   return $langcode;

 * }

 * @endcode

 *

 * For more information, see

 * @link http://drupal.org/node/1497272 Language Negotiation API @endlink

 */

/**

 * Returns all the defined language types.

 *

 * @return

 *   An array of language type names. The name will be used as the global

 *   variable name the language value will be stored in.

 */

function language_types_info() {

  $language_types = &drupal_static(__FUNCTION__);

  if (!isset($language_types)) {

    $language_types = module_invoke_all('language_types_info');

    // Let other modules alter the list of language types.

    drupal_alter('language_types_info', $language_types);

  }

  return $language_types;

}

/**

 * Returns only the configurable language types.

 *

 * A language type maybe configurable or fixed. A fixed language type is a type

 * whose language negotiation providers are module-defined and not altered

 * through the user interface.

 *

 * @param $stored

 *   Optional. By default retrieves values from the 'language_types' variable to

 *   avoid unnecessary hook invocations.

 *   If set to FALSE retrieves values from the actual language type definitions.

 *   This allows to react to alterations performed on the definitions by modules

 *   installed after the 'language_types' variable is set.

 *

 * @return

 *   An array of language type names.

 */

function language_types_configurable($stored = TRUE) {

  $configurable = &drupal_static(__FUNCTION__);

  if ($stored && !isset($configurable)) {

    $types = variable_get('language_types', drupal_language_types());

    $configurable = array_keys(array_filter($types));

  }

  if (!$stored) {

    $result = array();

    foreach (language_types_info() as $type => $info) {

      if (!isset($info['fixed'])) {

        $result[] = $type;

      }

    }

    return $result;

  }

  return $configurable;

}

/**

 * Disables the given language types.

 *

 * @param $types

 *   An array of language types.

 */

function language_types_disable($types) {

  $enabled_types = variable_get('language_types', drupal_language_types());

  foreach ($types as $type) {

    unset($enabled_types[$type]);

  }

  variable_set('language_types', $enabled_types);

}

/**

 * Updates the language type configuration.

 */

function language_types_set() {

  // Ensure that we are getting the defined language negotiation information. An

  // invocation of module_enable() or module_disable() could outdate the cached

  // information.

  drupal_static_reset('language_types_info');

  drupal_static_reset('language_negotiation_info');

  // Determine which language types are configurable and which not by checking

  // whether the 'fixed' key is defined. Non-configurable (fixed) language types

  // have their language negotiation settings stored there.

  $defined_providers = language_negotiation_info();

  foreach (language_types_info() as $type => $info) {

    if (isset($info['fixed'])) {

      $language_types[$type] = FALSE;

      $negotiation = array();

      foreach ($info['fixed'] as $weight => $id) {

        if (isset($defined_providers[$id])) {

          $negotiation[$id] = $weight;

        }

      }

      language_negotiation_set($type, $negotiation);

    }

    else {

      $language_types[$type] = TRUE;

    }

  }

  // Save language types.

  variable_set('language_types', $language_types);

  // Ensure that subsequent calls of language_types_configurable() return the

  // updated language type information.

  drupal_static_reset('language_types_configurable');

}

/**

 * Checks whether a language negotiation provider is enabled for a language type.

 *

 * This has two possible behaviors:

 *  - If $provider_id is given return its ID if enabled, FALSE otherwise.

 *  - If no ID is passed the first enabled language negotiation provider is

 *    returned.

 *

 * @param $type

 *   The language negotiation provider type.

 * @param $provider_id

 *   The language negotiation provider ID.

 *

 * @return

 *   The provider ID if it is enabled, FALSE otherwise.

 */

function language_negotiation_get($type, $provider_id = NULL) {

  $negotiation = variable_get("language_negotiation_$type", array());

  if (empty($negotiation)) {

    return empty($provider_id) ? LANGUAGE_NEGOTIATION_DEFAULT : FALSE;

  }

  if (empty($provider_id)) {

    return key($negotiation);

  }

  if (isset($negotiation[$provider_id])) {

    return $provider_id;

  }

  return FALSE;

}

/**

 * Checks if the language negotiation provider is enabled for any language type.

 *

 * @param $provider_id

 *   The language negotiation provider ID.

 *

 * @return

 *   TRUE if there is at least one language type for which the given language

 *   provider is enabled, FALSE otherwise.

 */

function language_negotiation_get_any($provider_id) {

  foreach (language_types_configurable() as $type) {

    if (language_negotiation_get($type, $provider_id)) {

      return TRUE;

    }

  }

  return FALSE;

}

/**

 * Returns the language switch links for the given language.

 *

 * @param $type

 *   The language negotiation type.

 * @param $path

 *   The internal path the switch links will be relative to.

 *

 * @return

 *   A keyed array of links ready to be themed.

 */

function language_negotiation_get_switch_links($type, $path) {

  $links = FALSE;

  $negotiation = variable_get("language_negotiation_$type", array());

  // Only get the languages if we have more than one.

  if (count(language_list()) >= 2) {

    $language = language_initialize($type);

  }

  foreach ($negotiation as $id => $provider) {

    if (isset($provider['callbacks']['switcher'])) {

      if (isset($provider['file'])) {

        require_once DRUPAL_ROOT . '/' . $provider['file'];

      }

      $callback = $provider['callbacks']['switcher'];

      $result = $callback($type, $path);

      // Add support for WCAG 2.0's Language of Parts to add language identifiers.

      // http://www.w3.org/TR/UNDERSTANDING-WCAG20/meaning-other-lang-id.html

      foreach ($result as $langcode => $link) {

        $result[$langcode]['attributes']['xml:lang'] = $langcode;

      }

      if (!empty($result)) {

        // Allow modules to provide translations for specific links.

        drupal_alter('language_switch_links', $result, $type, $path);

        $links = (object) array('links' => $result, 'provider' => $id);

        break;

      }

    }

  }

  return $links;

}

/**

 * Removes any unused language negotiation providers from the configuration.

 */

function language_negotiation_purge() {

  // Ensure that we are getting the defined language negotiation information. An

  // invocation of module_enable() or module_disable() could outdate the cached

  // information.

  drupal_static_reset('language_negotiation_info');

  drupal_static_reset('language_types_info');

  $defined_providers = language_negotiation_info();

  foreach (language_types_info() as $type => $type_info) {

    $weight = 0;

    $negotiation = array();

    foreach (variable_get("language_negotiation_$type", array()) as $id => $provider) {

      if (isset($defined_providers[$id])) {

        $negotiation[$id] = $weight++;

      }

    }

    language_negotiation_set($type, $negotiation);

  }

}

/**

 * Saves a list of language negotiation providers.

 *

 * @param $type

 *   The language negotiation type.

 * @param $language_providers

 *   An array of language negotiation provider weights keyed by provider ID.

 *   @see language_provider_weight()

 */

function language_negotiation_set($type, $language_providers) {

  // Save only the necessary fields.

  $provider_fields = array('callbacks', 'file', 'cache');

  $negotiation = array();

  $providers_weight = array();

  $defined_providers = language_negotiation_info();

  $default_types = language_types_configurable(FALSE);

  // Initialize the providers weight list.

  foreach ($language_providers as $id => $provider) {

    $providers_weight[$id] = language_provider_weight($provider);

  }

  // Order providers list by weight.

  asort($providers_weight);

  foreach ($providers_weight as $id => $weight) {

    if (isset($defined_providers[$id])) {

      $provider = $defined_providers[$id];

      // If the provider does not express any preference about types, make it

      // available for any configurable type.

      $types = array_flip(isset($provider['types']) ? $provider['types'] : $default_types);

      // Check whether the provider is defined and has the right type.

      if (isset($types[$type])) {

        $provider_data = array();

        foreach ($provider_fields as $field) {

          if (isset($provider[$field])) {

            $provider_data[$field] = $provider[$field];

          }

        }

        $negotiation[$id] = $provider_data;

      }

    }

  }

  variable_set("language_negotiation_$type", $negotiation);

}

/**

 * Returns all the defined language negotiation providers.

 *

 * @return

 *   An array of language negotiation providers.

 */

function language_negotiation_info() {

  $language_providers = &drupal_static(__FUNCTION__);

  if (!isset($language_providers)) {

    // Collect all the module-defined language negotiation providers.

    $language_providers = module_invoke_all('language_negotiation_info');

    // Add the default language negotiation provider.

    $language_providers[LANGUAGE_NEGOTIATION_DEFAULT] = array(

      'callbacks' => array('language' => 'language_from_default'),

      'weight' => 10,

      'name' => t('Default'),

      'description' => t('Use the default site language (@language_name).', array('@language_name' => language_default()->native)),

    );

    // Let other modules alter the list of language negotiation providers.

    drupal_alter('language_negotiation_info', $language_providers);

  }

  return $language_providers;

}

/**

 * Helper function used to cache the language negotiation providers results.

 *

 * @param $provider_id

 *   The language negotiation provider's identifier.

 * @param $provider

 *   (optional) An associative array of information about the provider to be

 *   invoked (see hook_language_negotiation_info() for details). If not passed

 *   in, it will be loaded through language_negotiation_info().

 *

 * @return

 *   A language object representing the language chosen by the provider.

 */

function language_provider_invoke($provider_id, $provider = NULL) {

  $results = &drupal_static(__FUNCTION__);

  if (!isset($results[$provider_id])) {

    global $user;

    // Get languages grouped by status and select only the enabled ones.

    $languages = language_list('enabled');

    $languages = $languages[1];

    if (!isset($provider)) {

      $providers = language_negotiation_info();

      $provider = $providers[$provider_id];

    }

    if (isset($provider['file'])) {

      require_once DRUPAL_ROOT . '/' . $provider['file'];

    }

    // If the language negotiation provider has no cache preference or this is

    // satisfied we can execute the callback.

    $cache = !isset($provider['cache']) || $user->uid || $provider['cache'] == variable_get('cache', 0);

    $callback = isset($provider['callbacks']['language']) ? $provider['callbacks']['language'] : FALSE;

    $langcode = $cache && function_exists($callback) ? $callback($languages) : FALSE;

    $results[$provider_id] = isset($languages[$langcode]) ? $languages[$langcode] : FALSE;

  }

  // Since objects are resources, we need to return a clone to prevent the

  // language negotiation provider cache from being unintentionally altered. The

  // same providers might be used with different language types based on

  // configuration.

  return !empty($results[$provider_id]) ? clone($results[$provider_id]) : $results[$provider_id];

}

/**

 * Returns the passed language negotiation provider weight or a default value.

 *

 * @param $provider

 *   A language negotiation provider data structure.

 *

 * @return

 *   A numeric weight.

 */

function language_provider_weight($provider) {

  $default = is_numeric($provider) ? $provider : 0;

  return isset($provider['weight']) && is_numeric($provider['weight']) ? $provider['weight'] : $default;

}

/**

 * Chooses a language based on language negotiation provider settings.

 *

 * @param $type

 *   The language type key to find the language for.

 *

 * @return

 *   The negotiated language object.

 */

function language_initialize($type) {

  // Execute the language negotiation providers in the order they were set up and return the

  // first valid language found.

  $negotiation = variable_get("language_negotiation_$type", array());

  foreach ($negotiation as $provider_id => $provider) {

    $language = language_provider_invoke($provider_id, $provider);

    if ($language) {

      $language->provider = $provider_id;

      return $language;

    }

  }

  // If no other language was found use the default one.

  $language = language_default();

  $language->provider = LANGUAGE_NEGOTIATION_DEFAULT;

  return $language;

}

/**

 * Returns the default language negotiation provider.

 *

 * @return

 *   The default language code.

 */

function language_from_default() {

  return language_default()->language;

}

/**

 * Splits the given path into prefix and actual path.

 *

 * Parse the given path and return the language object identified by the prefix

 * and the actual path.

 *

 * @param $path

 *   The path to split.

 * @param $languages

 *   An array of valid languages.

 *

 * @return

 *   An array composed of:

 *    - A language object corresponding to the identified prefix on success,

 *      FALSE otherwise.

 *    - The path without the prefix on success, the given path otherwise.

 */

function language_url_split_prefix($path, $languages) {

  $args = empty($path) ? array() : explode('/', $path);

  $prefix = array_shift($args);

  // Search prefix within enabled languages.

  foreach ($languages as $language) {

    if (!empty($language->prefix) && $language->prefix == $prefix) {

      // Rebuild $path with the language removed.

      return array($language, implode('/', $args));

    }

  }

  return array(FALSE, $path);

}

/**

 * Returns the possible fallback languages ordered by language weight.

 *

 * @param

 *   (optional) The language type. Defaults to LANGUAGE_TYPE_CONTENT.

 *

 * @return

 *   An array of language codes.

 */

function language_fallback_get_candidates($type = LANGUAGE_TYPE_CONTENT) {

  $fallback_candidates = &drupal_static(__FUNCTION__);

  if (!isset($fallback_candidates)) {

    $fallback_candidates = array();

    // Get languages ordered by weight.

    // Use array keys to avoid duplicated entries.

    foreach (language_list('weight') as $languages) {

      foreach ($languages as $language) {

        $fallback_candidates[$language->language] = NULL;

      }

    }

    $fallback_candidates = array_keys($fallback_candidates);

    $fallback_candidates[] = LANGUAGE_NONE;

    // Let other modules hook in and add/change candidates.

    drupal_alter('language_fallback_candidates', $fallback_candidates);

  }

  return $fallback_candidates;

}

/**

 * @} End of "language_negotiation"

 */