Skip to content

Commit

Permalink
Issue #905: Adding/fixing docblocks related to Redirect module. Enabl…
Browse files Browse the repository at this point in the history 
…ing Redirect in standard profile.
  • Loading branch information
@quicksketch
quicksketch committed Apr 25, 2016
1 parent 62a34fc commit 7ac090e
Show file tree
Hide file tree
Showing 12 changed files with 233 additions and 311 deletions.
24 changes: 23 additions & 1 deletion core/includes/database/select.inc
View file
Expand Up @@ -22,12 +22,21 @@ interface QueryExtendableInterface {
/**
* Enhance this object by wrapping it in an extender object.
*
* The core implementations of QueryExtendableInterface include:
* - TableSort: Extend a query to sort based on query strings.
* - PagerDefault: Extend a query to limit results based on query strings.
* - SearchQuery: Extend a query to join on the search index tables.
*
* Other implementations may be added by other modules, but for the sake of
* code validation, these core extenders are specified as possible return
* values of this interface.
*
* @param $extender_name
* The base name of the extending class. The base name will be checked
* against the current database connection to allow driver-specific subclasses
* as well, using the same logic as the query objects themselves. For example,
* PagerDefault_mysql is the MySQL-specific override for PagerDefault.
* @return QueryExtendableInterface
* @return QueryExtendableInterface|SelectQueryInterface|TableSort|PagerDefault|SearchQuery
* The extender object, which now contains a reference to this object.
*/
public function extend($extender_name);
Expand Down Expand Up @@ -1291,6 +1300,19 @@ class SelectQuery extends Query implements SelectQueryInterface {
return $alias;
}

/**
* Add columns to be retrieved from a database table.
*
* @param $table_alias
* The table alias used when specifying a table to be added to the query,
* either through SelectQueryInterface::select(),
* SelectQueryInterface::join(), or other joining methods.
* @param array $fields
* An array of column names to be selected from this table.
*
* @return SelectQueryInterface
* The current select object.
*/
public function fields($table_alias, array $fields = array()) {

if ($fields) {
Expand Down
53 changes: 38 additions & 15 deletions core/modules/redirect/redirect.admin.inc
View file
Expand Up @@ -151,13 +151,20 @@ function redirect_list_form($form, &$form_state) {
}

/**
* Return a form to filter URL redirects.
* Return a partial form to filter URL redirects.
*
* @param string $filter_value
* The default value for the filter textfield.
*
* @return array
* The partial form for filtering redirects.
*
* @see redirect_list_form().
* @see redirect_list_filter_form_submit()
*
* @ingroup forms
*/
function redirect_list_filter_form($keys = '') {
function redirect_list_filter_form($filter_value = '') {
$form['#attributes'] = array('class' => array('search-form'));
$form['basic'] = array(
'#type' => 'fieldset',
Expand All @@ -167,7 +174,7 @@ function redirect_list_filter_form($keys = '') {
$form['basic']['filter'] = array(
'#type' => 'textfield',
'#title' => '',
'#default_value' => $keys,
'#default_value' => $filter_value,
'#maxlength' => 128,
'#size' => 25,
);
Expand All @@ -176,7 +183,7 @@ function redirect_list_filter_form($keys = '') {
'#value' => t('Filter'),
'#submit' => array('redirect_list_filter_form_submit'),
);
if ($keys) {
if ($filter_value) {
$form['basic']['reset'] = array(
'#type' => 'submit',
'#value' => t('Reset'),
Expand All @@ -203,12 +210,14 @@ function redirect_list_filter_form_reset($form, &$form_state) {
/**
* Extends a query object for URL redirect filters.
*
* @param $query
* @param QueryAlterableInterface $query
* Query object that should be filtered.
* @param $keys
* The filter string to use.
* @param array $fields
* The fields within the query that should be checked for the $keys value.
* @param string $keys
* The filter string on which asterisks should be replaced with
*/
function redirect_build_filter_query(QueryAlterableInterface $query, array $fields, $keys = '') {
function redirect_build_filter_query(SelectQueryInterface $query, array $fields, $keys = '') {
if ($keys && $fields) {
// Replace wildcards with PDO wildcards.
$conditions = db_or();
Expand Down Expand Up @@ -271,6 +280,11 @@ function redirect_list_form_operations_submit($form, &$form_state) {
/**
* Form callback; Confirm a bulk operation on a list of redirects.
*
* @param string $operation
* An operation string from hook_redirect_operations().
* @param int[] $rids
* An array of redirect IDs on which the operation will be performed.
*
* @see redirect_list_form()
*/
function redirect_list_form_operations_confirm_form($form, &$form_state, $operation, $rids) {
Expand Down Expand Up @@ -318,6 +332,9 @@ function redirect_add_redirect_page() {
/**
* Form builder to add or edit an URL redirect.
*
* @param Redirect|NULL $redirect
* The redirect object to be edited or NULL if creating a new redirect.
*
* @see redirect_element_validate_source()
* @see redirect_element_validate_redirect()
* @see redirect_edit_form_validate()
Expand Down Expand Up @@ -465,7 +482,7 @@ function redirect_element_validate_source($element, &$form_state) {

$parsed_value = _redirect_extract_url_options($element, $form_state);

// Disallow redirections from the frontpage.
// Disallow redirects from the front page.
if ($parsed_value['path'] === '<front>') {
form_error($element, t('The source path cannot be the front page.'));
}
Expand Down Expand Up @@ -597,12 +614,15 @@ function redirect_edit_form_submit($form, &$form_state) {
/**
* Form builder to delete an URL redirect.
*
* @param Redirect $redirect
* The redirect object to be deleted.
*
* @see redirect_delete_form()
* @see confirm_form()
*
* @ingroup forms
*/
function redirect_delete_form($form, &$form_state, $redirect) {
function redirect_delete_form($form, &$form_state, Redirect $redirect) {
$form['rid'] = array(
'#type' => 'value',
'#value' => $redirect->rid,
Expand Down Expand Up @@ -647,7 +667,7 @@ function redirect_settings_form($form, &$form_state) {
'#type' => 'checkbox',
'#title' => t('Retain query string through redirect.'),
'#default_value' => $config->get('passthrough_querystring'),
'#description' => t('For example, given a redirect from %source to %redirect, if a user visits %sourcequery they would be redirected to %redirectquery. The query strings in the redirection will always take precedence over the current query string.', array('%source' => 'source-path', '%redirect' => 'node?a=apples', '%sourcequery' => 'source-path?a=alligators&b=bananas', '%redirectquery' => 'node?a=apples&b=bananas')),
'#description' => t('For example, given a redirect from %source to %redirect, if a user visits %source_query they would be redirected to %redirect_query. The query strings in the redirection will always take precedence over the current query string.', array('%source' => 'source-path', '%redirect' => 'node?a=apples', '%source_query' => 'source-path?a=alligators&b=bananas', '%redirect_query' => 'node?a=apples&b=bananas')),
);
$form['additional_statuses'] = array(
'#type' => 'radios',
Expand Down Expand Up @@ -773,11 +793,14 @@ function redirect_404_list($form = NULL) {
/**
* Return a form to filter URL redirects.
*
* @param string $filter_value
* The current string by which the list of 404s will be filtered.
*
* @see redirect_list_filter_form_submit()
*
* @ingroup forms
*/
function redirect_list_404_filter_form($form, &$form_state, $keys = '') {
function redirect_list_404_filter_form($form, &$form_state, $filter_value = '') {
$form['#attributes'] = array('class' => array('search-form'));
$form['help'] = array(
'#markup' => '<p>' .
Expand All @@ -792,7 +815,7 @@ function redirect_list_404_filter_form($form, &$form_state, $keys = '') {
$form['basic']['filter'] = array(
'#type' => 'textfield',
'#title' => '',
'#default_value' => $keys,
'#default_value' => $filter_value,
'#maxlength' => 128,
'#size' => 25,
);
Expand All @@ -801,7 +824,7 @@ function redirect_list_404_filter_form($form, &$form_state, $keys = '') {
'#value' => t('Filter'),
'#submit' => array('redirect_list_404_filter_form_submit'),
);
if ($keys) {
if ($filter_value) {
$form['basic']['reset'] = array(
'#type' => 'submit',
'#value' => t('Reset'),
Expand All @@ -828,7 +851,7 @@ function redirect_list_404_filter_form_reset($form, &$form_state) {
/**
* Display a list of redirects. Used on forms when editing an entity.
*
* @param Redirects[] $redirects
* @param Redirect[] $redirects
* An array of Redirect objects.
* @param $header
* The table header columns for the table.
Expand Down
110 changes: 59 additions & 51 deletions core/modules/redirect/redirect.api.php
View file
Expand Up @@ -8,43 +8,25 @@
/**
* @defgroup redirect_api_hooks Redirect API Hooks
* @{
* During redirect operations (create, update, view, delete, etc.), there are
* several sets of hooks that get invoked to allow modules to modify the
* redirect operation:
* - All-module hooks: Generic hooks for "redirect" operations. These are
* always invoked on all modules.
* - Entity hooks: Generic hooks for "entity" operations. These are always
* invoked on all modules.
*
* Here is a list of the redirect and entity hooks that are invoked, and other
* steps that take place during redirect operations:
* - Creating a new redirect (calling redirect_save() on a new redirect):
* - hook_redirect_presave() (all)
* - Redirect written to the database
* - hook_redirect_insert() (all)
* - hook_entity_insert() (all)
* - Updating an existing redirect (calling redirect_save() on an existing redirect):
* - hook_redirect_presave() (all)
* - Redirect written to the database
* - hook_redirect_update() (all)
* - hook_entity_update() (all)
* - Loading a redirect (calling redirect_load(), redirect_load_multiple(), or
* entity_load() with $entity_type of 'redirect'):
* - Redirect information is read from database.
* - hook_entity_load() (all)
* - hook_redirect_load() (all)
* - Deleting a redirect (calling redirect_delete() or redirect_delete_multiple()):
* - Redirect is loaded (see Loading section above)
* - Redirect information is deleted from database
* - hook_redirect_delete() (all)
* - hook_entity_delete() (all)
* - Preparing a redirect for editing (note that if it's
* an existing redirect, it will already be loaded; see the Loading section
* above):
* - hook_redirect_prepare() (all)
* - Validating a redirect during editing form submit (calling
* redirect_form_validate()):
* - hook_redirect_validate() (all)
* Redirects may be created by end-users to manually redirect from one URL on
* the site to another one (or to an external URL). For example the path
* "about" may be redirected to "pages/about-us" after a site redesign. The old
* URLs should be redirect to the new ones to maintain search engine rankings,
* existing links, and bookmarks to the old URL.
*
* Redirects are stored in the database in the "redirect" table. Loading and
* saving of redirects should be done through the Redirect API to ensure modules
* responding to the modification of redirects also have an opportunity to
* make adjustments as needed. The Redirect object is used to wrap around all
* the operations that can be done on redirects. It is recommended that
* redirects be loaded using one of the existing functions for loading, or
* if creating a new redirect, created by instantiating a new Redirect object.
*
* @see Redirect
* @see redirect_load()
* @see redirect_load_multiple()
* @see redirect_load_by_source()
*
* @}
*/

Expand All @@ -57,15 +39,12 @@
* Act on redirects being loaded from the database.
*
* This hook is invoked during redirect loading, which is handled by
* entity_load(), via classes RedirectController and
* DefaultEntityController. After the redirect information is read from
* the database or the entity cache, hook_entity_load() is invoked on all
* implementing modules, and then hook_redirect_load() is invoked on all
* implementing modules.
* redirect_load_multiple(). After the redirect information is read from
* the database hook_redirect_load() is invoked on all implementing modules.
*
* This hook should only be used to add information that is not in the redirect
* table, not to replace information that is in that table (which could
* interfere with the entity cache). For performance reasons, information for
* interfere with saving). For performance reasons, information for
* all available redirects should be loaded in a single query where possible.
*
* The $types parameter allows for your module to have an early return (for
Expand Down Expand Up @@ -123,7 +102,7 @@ function hook_redirect_load_by_source_alter(array &$redirects, $source, array $c
* block access, return REDIRECT_ACCESS_IGNORE or simply return nothing.
* Blindly returning FALSE will break other redirect access modules.
*
* @param $redirect
* @param Redirect|string $redirect
* The redirect object on which the operation is to be performed, or, if it
* does not yet exist, the type of redirect to be created.
* @param $op
Expand All @@ -135,10 +114,10 @@ function hook_redirect_load_by_source_alter(array &$redirects, $source, array $c
* A user object representing the user for whom the operation is to be
* performed.
*
* @return
* @return string|NULL
* REDIRECT_ACCESS_ALLOW if the operation is to be allowed;
* REDIRECT_ACCESS_DENY if the operation is to be denied;
* REDIRECT_ACCESSS_IGNORE to not affect this operation at all.
* REDIRECT_ACCESS_IGNORE to not affect this operation at all.
*
* @see redirect_access()
* @ingroup redirect_api_hooks
Expand Down Expand Up @@ -171,16 +150,24 @@ function hook_redirect_access($op, $redirect, $account) {
/**
* Act on a redirect object about to be shown on the add/edit form.
*
* This hook is invoked from the Redirect object contructor in
* This hook is invoked from the Redirect object constructor in
* Redirect::__construct().
*
* @param $redirect
* The redirect that is about to be shown on the add/edit form.
* @param Redirect $redirect
* A newly initialized redirect object. Likely to be shown on the form for
* adding or editing a redirect.
* @param array $values
* The default values for the Redirect from the database if editing an
* existing Redirect.
*
* @ingroup redirect_api_hooks
*/
function hook_redirect_prepare($redirect) {

function hook_redirect_prepare(Redirect $redirect, array $values) {
// Change the default type to be a 302 temporary redirect instead of a 301
// permanent redirect.
if (empty($values['type'])) {
$redirect->type = 302;
}
}

/**
Expand Down Expand Up @@ -289,6 +276,27 @@ function hook_redirect_delete($redirect) {
* @ingroup redirect_api_hooks
*/
function hook_redirect_alter($redirect) {
// Make any redirect going to the homepage considered temporary.
if ($redirect->redirect = '<front>') {
$redirect->type = 302;
}
}

/**
* Provide additional operations that may be done on redirects.
*
* @return array
* An array of callback information for executing the operation.
*/
function hook_redirect_operations() {
// Example from redirect_redirect_operations():
$operations['delete'] = array(
'action' => t('Delete'),
'action_past' => t('Deleted'),
'callback' => 'redirect_delete_multiple',
'confirm' => TRUE,
);
return $operations;
}

/**
Expand Down
7 changes: 6 additions & 1 deletion core/modules/redirect/redirect.class.inc
View file
Expand Up @@ -84,6 +84,11 @@ class Redirect {
*/
public $count = 0;

/**
* A timestamp of the last time this redirect was accessed.
*/
public $access = 0;

/**
* Hashes are an alternative ID by which a redirect may be loaded.
*
Expand Down Expand Up @@ -122,7 +127,7 @@ class Redirect {
$this->redirect_options = unserialize($this->redirect_options);
}

module_invoke_all('redirect_prepare', $this);
module_invoke_all('redirect_prepare', $this, $values);
}

/**
Expand Down

1 comment on commit 7ac090e

@backdrop-ci
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Related to: backdrop/backdrop-issues#905

Please sign in to comment.