Hooks and Filters

SnipShare provides 8 filters, 12 lifecycle action hooks, and 21 template hooks so you can customise paste behaviour, react to events, and inject content anywhere in the front-end templates - without editing core files.

---

Filters

snipshare_before_create_paste

Fires immediately before a new paste is inserted into the database. Use this to validate, modify, or augment paste data.

Signature:

$data = apply_filters( 'snipshare_before_create_paste', $data );

Parameters:

Param	Type	Description
$data	array	Paste data array before INSERT. Keys: user_id, title, description, visibility, status, password_hash, burn_after_read, expires_at, share_hash, file_count

Return: Modified $data array.

Example - force all new pastes to be unlisted:

add_filter( 'snipshare_before_create_paste', function( $data ) {
    $data['visibility'] = 'unlisted';
    return $data;
} );

---

snipshare_paste_query_args

Fires inside SnipShare_Paste::query() before the SQL query is built. Use this to modify query arguments - add custom filters, override defaults, or restrict results.

Signature:

$args = apply_filters( 'snipshare_paste_query_args', $args );

Parameters:

Param	Type	Description
$args	array	Query args array. Keys: user_id, visibility, status, language, tag, search, per_page, page, orderby, order

Return: Modified $args array.

Example - exclude a specific user’s pastes from all public queries:

add_filter( 'snipshare_paste_query_args', function( $args ) {
    // Exclude user ID 5 from all queries
    if ( empty( $args['user_id'] ) ) {
        $args['exclude_user'] = 5; // you'd also need to handle this in a custom query
    }
    return $args;
} );

---

snipshare_unlock_max_attempts

Filters how many wrong passwords are allowed before unlock requests are refused. Default 5.

$max = apply_filters( 'snipshare_unlock_max_attempts', 5, $paste_id );

Param	Type	Description
$max	int	Allowed failed attempts per window
$paste_id	int	Paste being unlocked

Since: 1.1.0. Return: int.

---

snipshare_unlock_window

Filters the throttle window in seconds. Default 900 (15 minutes).

$seconds = apply_filters( 'snipshare_unlock_window', 900, $paste_id );

Param	Type	Description
$seconds	int	Window length in seconds
$paste_id	int	Paste being unlocked

Since: 1.1.0. Return: int.

---

snipshare_client_ip

Filters the visitor IP used for unlock throttling. Defaults to REMOTE_ADDR. Use it only when your site sits behind a trusted proxy.

$ip = apply_filters( 'snipshare_client_ip', $ip );

Param	Type	Description
$ip	string	IP address from REMOTE_ADDR

Since: 1.1.0. Return: string.

Example - trust a Cloudflare header:

add_filter( 'snipshare_client_ip', function( $ip ) {
    if ( ! empty( $_SERVER['HTTP_CF_CONNECTING_IP'] ) ) {
        return sanitize_text_field( wp_unslash( $_SERVER['HTTP_CF_CONNECTING_IP'] ) );
    }
    return $ip;
} );

Only do this if all traffic reaches PHP through that proxy. Otherwise visitors can spoof the header and bypass the throttle.

---

snipshare_retention_days

Filters how many days trashed, expired, and burned pastes are kept before permanent deletion. Default 30. The hourly cleanup deletes at most 200 pastes per run.

$days = apply_filters( 'snipshare_retention_days', 30 );

Param	Type	Description
$days	int	Retention period in days

Since: 1.1.0. Return: int.

---

snipshare_limits_exempt

Filters whether a user skips the hourly paste rate limit and the max-pastes-per-member limit. Default: true for users with the snipshare/moderate ability.

$exempt = apply_filters( 'snipshare_limits_exempt', $is_moderator, $user_id );

Param	Type	Description
$exempt	bool	Whether the user is exempt
$user_id	int	User being checked

Since: 1.1.0. Return: bool.

---

snipshare_rewrite_slugs

Filters the URL bases. Default array( 'single' => 'paste', 'plural' => 'pastes' ): /paste/{hash}/ for a paste, /pastes/ for the archive, create, tags, profiles and collections. Each must be one URL-safe segment and the two must differ; an invalid value falls back to the default. Rewrite rules flush and the Pastes page slug follows automatically. Old URLs on the default bases redirect (301) to the new ones.

add_filter( 'snipshare_rewrite_slugs', fn() => array( 'single' => 'snippet', 'plural' => 'snippets' ) );

Since: 1.1.0. Return: array.

---

snipshare_redirect_legacy_slug

Filters whether old /paste/ and /pastes/ URLs redirect (301) after the bases are renamed. Default true.

add_filter( 'snipshare_redirect_legacy_slug', '__return_false' );

Since: 1.1.0. Return: bool.

---

snipshare_ability_map

Filters which WordPress capability grants each SnipShare ability. By default every logged-in member (read) can create, fork and manage their own pastes and make collections, and moderate_comments (editors and admins) grants moderation. Works with every role, including roles added by other plugins.

// Only users who can write posts may create pastes.
add_filter( 'snipshare_ability_map', function ( $map ) {
  $map['snipshare/create-paste'] = 'edit_posts';
  return $map;
} );

Param	Type	Description
$map	array	Ability name => capability

Since: 1.1.0. Return: array.

---

Actions

snipshare_db_error

Fires when a SnipShare database write fails (a paste, file or revision could not be saved). With WP_DEBUG on, the error is also written to the PHP error log.

do_action( 'snipshare_db_error', $context, $db_error );

Param	Type	Description
$context	string	What was being written, e.g. paste create
$db_error	string	The database error message

Since: 1.1.0

---

snipshare_paste_burned

Fires after a reader reveals a burn-after-read paste and its content is deleted. Moderators viewing a paste never fire it.

do_action( 'snipshare_paste_burned', $paste_id );

Param	Type	Description
$paste_id	int	ID of the burned paste

Since: 1.1.0. Use case: BuddyPress activity removal (built-in).

---

snipshare_paste_created

Fires after a new paste is successfully inserted.

do_action( 'snipshare_paste_created', $paste_id, $data );

Param	Type	Description
$paste_id	int	ID of the newly created paste
$data	array	The raw data array passed to SnipShare_Paste::create()

Use case: Send notifications, update external indexes, trigger webhooks.

---

snipshare_paste_updated

Fires after a paste is successfully updated.

do_action( 'snipshare_paste_updated', $paste_id, $data );

Param	Type	Description
$paste_id	int	ID of the updated paste
$data	array	The data array passed to the update call

---

snipshare_paste_trashed

Fires after a paste’s status is set to trashed.

do_action( 'snipshare_paste_trashed', $paste_id );

---

snipshare_paste_deleted

Fires after a paste is permanently deleted from the database.

do_action( 'snipshare_paste_deleted', $paste_id );

Note: At this point the paste row and all related records (files, revisions, tags, stars) have already been deleted.

---

snipshare_paste_forked

Fires after a paste is forked.

do_action( 'snipshare_paste_forked', $fork_id, $original_paste_id, $user_id );

Param	Type	Description
$fork_id	int	ID of the newly created fork
$original_paste_id	int	ID of the paste that was forked
$user_id	int	ID of the user who performed the fork

Use case: BuddyPress fork notification (built-in). Updating fork counts on external systems.

---

snipshare_paste_starred

Fires after a user stars a paste (toggle on).

do_action( 'snipshare_paste_starred', $paste_id, $user_id );

Use case: BuddyPress star notification (built-in). Gamification points.

---

snipshare_paste_unstarred

Fires after a user removes their star from a paste (toggle off).

do_action( 'snipshare_paste_unstarred', $paste_id, $user_id );

---

snipshare_paste_reported

Fires after a user submits a report.

do_action( 'snipshare_paste_reported', $report_id, $paste_id, $reporter_id );

Param	Type	Description
$report_id	int	ID of the new report record
$paste_id	int	ID of the reported paste
$reporter_id	int	WP user ID of the reporter

Use case: Email notification to admins when a new report is filed.

add_action( 'snipshare_paste_reported', function( $report_id, $paste_id, $reporter_id ) {
    wp_mail(
        get_option( 'admin_email' ),
        'New paste reported',
        "Paste ID {$paste_id} was reported. View it at: " . admin_url( 'admin.php?page=snipshare-moderation' )
    );
}, 10, 3 );

---

snipshare_report_reviewed

Fires after an admin reviews a report.

do_action( 'snipshare_report_reviewed', $report_id, $action );

Param	Type	Description
$report_id	int	ID of the reviewed report
$action	string	reviewed or dismissed

---

snipshare_collection_created

Fires after a new collection is created.

do_action( 'snipshare_collection_created', $collection_id, $data );

---

snipshare_paste_added_to_collection

Fires after a paste is added to a collection.

do_action( 'snipshare_paste_added_to_collection', $collection_id, $paste_id );

---

Template Overrides

A theme can replace any SnipShare template by copying it from the plugin’s templates/ folder into yourtheme/snipshare/, keeping the same path. For example, copy templates/partials/paste-card.php to yourtheme/snipshare/partials/paste-card.php. Use a child theme so updates to the parent theme do not remove your copy.

Templates run inside a function, so the variables they set (such as $paste or $paged) stay local and never affect WordPress or your theme.

snipshare_template

Filters the file used for a SnipShare template, after any theme override has been found.

$path = apply_filters( 'snipshare_template', $path, $name );

Param	Type	Description
$path	string	Absolute path to the template file
$name	string	Template name relative to templates/, e.g. single-paste.php

Since: 1.1.0. Return: string.

---

Template Actions

SnipShare also fires template hooks in all front-end templates for injecting custom content:

Hook	Location
snipshare_before_archive	Before paste archive content
snipshare_after_archive	After paste archive content
snipshare_before_paste_loop	Before paste loop in archive
snipshare_after_paste_loop	After paste loop in archive
snipshare_before_paste_card	Before each paste card (receives $paste)
snipshare_after_paste_card	After each paste card (receives $paste)
snipshare_before_single_paste	Before single paste view (receives $paste)
snipshare_after_single_paste	After single paste view (receives $paste)
snipshare_before_paste_files	Before file tabs on single view (receives $paste)
snipshare_after_paste_files	After file tabs on single view (receives $paste)
snipshare_before_paste_form	Before create/edit form
snipshare_after_paste_form	After create/edit form
snipshare_paste_form_fields	Inside form - add custom fields
snipshare_before_user_profile	Before user profile content (receives $profile_user)
snipshare_after_user_profile	After user profile content (receives $profile_user)
snipshare_before_collection	Before collection view (receives $collection)
snipshare_after_collection	After collection view (receives $collection)
snipshare_before_diff	Before diff view (receives $paste)
snipshare_after_diff	After diff view (receives $paste)
snipshare_before_embed	Before embed view (receives $paste)
snipshare_after_embed	After embed view (receives $paste)