www.aleph1.co.uk Git - yaffs-website/blob - web/modules/contrib/pathauto/pathauto.api.php

   1 <?php
   2
   3 /**
   4  * @file
   5  * Documentation for pathauto API.
   6  */
   7
   8 use Drupal\Core\Language\Language;
   9
  10 /**
  11  * @todo Update for 8.x-1.x
  12  *
  13  * It may be helpful to review some examples of integration from
  14  * pathauto.pathauto.inc.
  15  *
  16  * Pathauto works by using tokens in path patterns.  Thus the simplest
  17  * integration is just to provide tokens.  Token support is provided by Drupal
  18  * core. To provide additional token from your module, implement the following
  19  * hooks:
  20  *
  21  * hook_tokens() - http://api.drupal.org/api/function/hook_tokens
  22  * hook_token_info() - http://api.drupal.org/api/function/hook_token_info
  23  *
  24  * If you wish to provide pathauto integration for custom paths provided by your
  25  * module, there are a few steps involved.
  26  *
  27  * 1. hook_pathauto()
  28  *    Provide information required by pathauto for the settings form as well as
  29  *    bulk generation.  See the documentation for hook_pathauto() for more
  30  *    details.
  31  *
  32  * 2. pathauto_create_alias()
  33  *    At the appropriate time (usually when a new item is being created for
  34  *    which a generated alias is desired), call pathauto_create_alias() with the
  35  *    appropriate parameters to generate and create the alias. See the user,
  36  *    taxonomy, and node hook implementations in pathauto.module for examples.
  37  *    Also see the documentation for pathauto_create_alias().
  38  *
  39  * 3. pathauto_path_delete_all()
  40  *    At the appropriate time (usually when an item is being deleted), call
  41  *    pathauto_path_delete_all() to remove any aliases that were created for the
  42  *    content being removed.  See the documentation for
  43  *    pathauto_path_delete_all() for more details.
  44  *
  45  * 4. hook_path_alias_types()
  46  *    For modules that create new types of content that can be aliased with
  47  *    pathauto, a hook implementation is needed to allow the user to delete them
  48  *    all at once.  See the documentation for hook_path_alias_types() below for
  49  *    more information.
  50  *
  51  * There are other integration points with pathauto, namely alter hooks that
  52  * allow you to change the data used by pathauto at various points in the
  53  * process.  See the below hook documentation for details.
  54  */
  55
  56 /**
  57  * Alter pathauto alias type definitions.
  58  *
  59  * @param array &$definitions
  60  *   Alias type definitions.
  61  */
  62 function hook_path_alias_types_alter(array &$definitions) {
  63 }
  64
  65 /**
  66  * Determine if a possible URL alias would conflict with any existing paths.
  67  *
  68  * Returning TRUE from this function will trigger pathauto_alias_uniquify() to
  69  * generate a similar URL alias with a suffix to avoid conflicts.
  70  *
  71  * @param string $alias
  72  *   The potential URL alias.
  73  * @param string $source
  74  *   The source path for the alias (e.g. 'node/1').
  75  * @param string $langcode
  76  *   The language code for the alias (e.g. 'en').
  77  *
  78  * @return bool
  79  *   TRUE if $alias conflicts with an existing, reserved path, or FALSE/NULL if
  80  *   it does not match any reserved paths.
  81  *
  82  * @see pathauto_alias_uniquify()
  83  */
  84 function hook_pathauto_is_alias_reserved($alias, $source, $langcode) {
  85   // Check our module's list of paths and return TRUE if $alias matches any of
  86   // them.
  87   return (bool) \Drupal::database()->query("SELECT 1 FROM {mytable} WHERE path = :path", [':path' => $alias])->fetchField();
  88 }
  89
  90 /**
  91  * Alter the pattern to be used before an alias is generated by Pathauto.
  92  *
  93  * This hook will only be called if a default pattern is configured (on
  94  * admin/config/search/path/patterns).
  95  *
  96  * @param \Drupal\pathauto\PathautoPatternInterface $pattern
  97  *   The Pathauto pattern to be used.
  98  * @param array $context
  99  *   An associative array of additional options, with the following elements:
 100  *   - 'module': The module or entity type being aliased.
 101  *   - 'op': A string with the operation being performed on the object being
 102  *     aliased. Can be either 'insert', 'update', 'return', or 'bulkupdate'.
 103  *   - 'source': A string of the source path for the alias (e.g. 'node/1').
 104  *   - 'data': An array of keyed objects to pass to token_replace().
 105  *   - 'bundle': The sub-type or bundle of the object being aliased.
 106  *   - 'language': A string of the language code for the alias (e.g. 'en').
 107  *     This can be altered by reference.
 108  */
 109 function hook_pathauto_pattern_alter(\Drupal\pathauto\PathautoPatternInterface $pattern, array $context) {
 110   // Switch out any [node:created:*] tokens with [node:updated:*] on update.
 111   if ($context['module'] == 'node' && ($context['op'] == 'update')) {
 112     $pattern->setPattern(preg_replace('/\[node:created(\:[^]]*)?\]/', '[node:updated$1]', $pattern->getPattern()));
 113   }
 114 }
 115
 116 /**
 117  * Alter Pathauto-generated aliases before saving.
 118  *
 119  * @param string $alias
 120  *   The automatic alias after token replacement and strings cleaned.
 121  * @param array $context
 122  *   An associative array of additional options, with the following elements:
 123  *   - 'module': The module or entity type being aliased.
 124  *   - 'op': A string with the operation being performed on the object being
 125  *     aliased. Can be either 'insert', 'update', 'return', or 'bulkupdate'.
 126  *   - 'source': A string of the source path for the alias (e.g. 'node/1').
 127  *     This can be altered by reference.
 128  *   - 'data': An array of keyed objects to pass to token_replace().
 129  *   - 'type': The sub-type or bundle of the object being aliased.
 130  *   - 'language': A string of the language code for the alias (e.g. 'en').
 131  *     This can be altered by reference.
 132  *   - 'pattern': A string of the pattern used for aliasing the object.
 133  */
 134 function hook_pathauto_alias_alter(&$alias, array &$context) {
 135   // Add a suffix so that all aliases get saved as 'content/my-title.html'.
 136   $alias .= '.html';
 137
 138   // Force all aliases to be saved as language neutral.
 139   $context['language'] = Language::LANGCODE_NOT_SPECIFIED;
 140 }
 141
 142 /**
 143  * Alter the list of punctuation characters for Pathauto control.
 144  *
 145  * @param array $punctuation
 146  *   An array of punctuation to be controlled by Pathauto during replacement
 147  *   keyed by punctuation name. Each punctuation record should be an array
 148  *   with the following key/value pairs:
 149  *   - value: The raw value of the punctuation mark.
 150  *   - name: The human-readable name of the punctuation mark. This must be
 151  *     translated using t() already.
 152  */
 153 function hook_pathauto_punctuation_chars_alter(array &$punctuation) {
 154   // Add the trademark symbol.
 155   $punctuation['trademark'] = array('value' => '™', 'name' => t('Trademark symbol'));
 156
 157   // Remove the dollar sign.
 158   unset($punctuation['dollar']);
 159 }