Hooks - Plugixa Permalink Manager

Everything on this page is for developers. Hook names all start with plugixa_permalink_manager_.

Functions

Three functions cover the common cases without touching a class.

// The custom address of a post or term, or null when it uses WordPress's own.
$uri = plugixa_permalink_manager_get_uri( 'post', 36 );       // "shop/tents/skyline-2"
$uri = plugixa_permalink_manager_get_uri( 'term', 34 );

// Give an item a custom address. Returns the stored row, or a WP_Error.
$result = plugixa_permalink_manager_set_uri( 'post', 36, 'shop/tents/skyline-2' );

// Which item owns an address. Case, slashes and encoding do not matter.
$owner = plugixa_permalink_manager_find_object( '/shop/tents/skyline-2/' );
// array( 'type' => 'post', 'id' => 36 ) or null

plugixa_permalink_manager_set_uri() behaves exactly like a hand edit: the address is cleaned, must be free, the old one becomes a redirect, and the change is written to the history. When the address is taken, the error’s data carries the owner and a free suggestion.

Wrap calls in function_exists() if your code may run without the plugin.

get_permalink(), get_term_link() and every WordPress function built on them already return the custom address. You rarely need the plugin’s own functions just to print a link.

Reacting to changes

Action	Fires	Arguments
`plugixa_permalink_manager_uri_updated`	After an address changed	`$type`, `$id`, `$old_uri`, `$new_uri`, `$reason`
`plugixa_permalink_manager_uri_removed`	After a custom address was removed	`$type`, `$id`, `$old_uri`, `$reason`
`plugixa_permalink_manager_settings_saved`	After the settings are saved	`$settings`
`plugixa_permalink_manager_loaded`	Once the plugin is fully booted	`$container`
`plugixa_permalink_manager_activated` / `_deactivated`	On activation and deactivation
`plugixa_permalink_manager_uninstall`	During uninstall, before the tables are dropped
`plugixa_permalink_manager_cascade_needed`	When a change to a parent touched more children than one request refreshes. The bulk tools listen and queue a job	`$type`, `$id` (the parent)

add_action( 'plugixa_permalink_manager_uri_updated', function ( $type, $id, $old, $new, $reason ) {
	// $old is null the first time an item gets an address.
	if ( 'post' === $type && null !== $old ) {
		my_cdn_purge( home_url( $old ) );
	}
}, 10, 5 );

Changing generated addresses

Filter	Changes	Arguments
`plugixa_permalink_manager_default_uri`	The address a pattern generated	`$uri`, `$kind`, `$object`
`plugixa_permalink_manager_tag_value`	The text one tag resolved to	`$value`, `$tag`, `$context`
`plugixa_permalink_manager_primary_term`	Which term is used when an item has several	`0`, `$post`, `$taxonomy` (return a term ID)
`plugixa_permalink_manager_reserved_uris`	Addresses nobody may use	`$reserved`

// Shorten one tag everywhere.
add_filter( 'plugixa_permalink_manager_tag_value', function ( $value, $tag ) {
	return 'monthname' === $tag ? substr( $value, 0, 3 ) : $value;
}, 10, 2 );

// Keep an address free for a campaign.
add_filter( 'plugixa_permalink_manager_reserved_uris', function ( $reserved ) {
	$reserved[] = 'summer';
	return $reserved;
} );

A reserved word blocks the first part of an address, so summer also reserves summer/anything. Reserved addresses can be added to but the built-in ones cannot be removed.

To add a tag of your own, register a resolver on the plugixa_permalink_manager_register_tags action.

Deciding what is managed

Filter	Decides	Arguments
`plugixa_permalink_manager_post_type_enabled`	Whether a post type has custom addresses	`$enabled`, `$post_type`
`plugixa_permalink_manager_taxonomy_enabled`	Whether a taxonomy has them	`$enabled`, `$taxonomy`
`plugixa_permalink_manager_can_edit_object`	Whether the current user may edit the item an address belongs to
`plugixa_permalink_manager_user_can`	Whether a user may perform an action
`plugixa_permalink_manager_capabilities`	The permissions handed to the admin app

Routing and redirects

Filter	Changes	Arguments
`plugixa_permalink_manager_request_is_routable`	Whether a request may be routed by the plugin at all	`$routable`, `$path`, `$query_vars`
`plugixa_permalink_manager_resolved_query`	The query built for a request that matched a stored address
`plugixa_permalink_manager_filter_redirect`	The redirect about to be sent. Return `null` to cancel it	`$decision`, `$request`
`plugixa_permalink_manager_filter_final_permalink`	The final link of an item that has a custom address	`$url`, `$row`, `$kind`, `$native`

// Never redirect requests made by a monitoring service.
add_filter( 'plugixa_permalink_manager_filter_redirect', function ( $decision ) {
	return isset( $_SERVER['HTTP_X_UPTIME_CHECK'] ) ? null : $decision;
} );

Extending the plugin

Hook	Use it to
`plugixa_permalink_manager_register_tools` (action)	Register another bulk tool
`plugixa_permalink_manager_rest_tools` (filter)	Allow the Tools screen to start it
`plugixa_permalink_manager_import_sources` (filter)	Add an import source
`plugixa_permalink_manager_register_rest_routes` (action)	Register more REST routes
`plugixa_permalink_manager_conflicting_plugins` (filter)	Change which plugins count as a conflict
`plugixa_permalink_manager_language_provider` (filter)	Supply languages from a translation plugin of your own
`plugixa_permalink_manager_sanitize_settings` / `_settings_choices` (filters)	Add settings a module owns
`plugixa_permalink_manager_settings_defaults` (filter)	Declare the default of a setting a module owns. Clean it in `_sanitize_settings` too, or the key is refused when saved
`plugixa_permalink_manager_admin_config` (filter)	Change the configuration handed to the admin app
`plugixa_permalink_manager_config_settings_keys` (filter)	Choose which setting keys are printed onto the page for the admin app’s first paint. Argument: `$keys`
`plugixa_permalink_manager_bootstrap_payload` (filter)	Add a dataset to the admin app’s startup data. Argument: `$payload`
`plugixa_permalink_manager_filter_output` (filter)	Change, or remove fields from, a successful REST payload before it is sent. Arguments: `$data`, `$entity_type`
`plugixa_permalink_manager_modules` (filter)	Add a module class of your own. Argument: `$classes`, fully qualified class names
`plugixa_permalink_manager_request_contexts` (filter)	Correct what kind of request the plugin thinks it is serving, for a host with an unusual REST mount. Argument: `$contexts`
`plugixa_permalink_manager_admin_submenus` (action)	Register another admin submenu. Arguments: `$parent_slug`, `$render`
`plugixa_permalink_manager_enqueue_assets` (action)	Enqueue your own script or style on the plugin’s screen, after the app bundle. Argument: `$hook_suffix`

Safe mode from wp-config.php

define( 'PLUGIXA_PERMALINK_MANAGER_SAFE_MODE', true );

Stops the plugin serving custom addresses, whatever the setting says. Nothing stored is changed. See Troubleshooting.

REST API

The admin app is built on a REST API you can call too. See REST API.

Recent searches