pathauto.api.php 6.3 KB

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