class-gravityview-entry-approval-merge-tags.php

Go to the documentation of this file.

<?php
/**
 * @file class-gravityview-entry-moderation-merge-tags.php
 * @package GravityView
 * @license GPL2+
 * @author GravityView <[email protected]>
 * @link https://www.gravitykit.com
 * @copyright Copyright 2023, Katz Web Services, Inc.
 *
 * @since 2.17
 */

/** If this file is called directly, abort. */
if ( ! defined( 'ABSPATH' ) ) {
 die;
}

/**
 * Handles approval links
 *
 * @since 2.17
 */
class GravityView_Entry_Approval_Merge_Tags {

 /**
 * The name of the query arg used to pass token information to the approval URL.
 * Example: ?gv_token=eyJpYXQiOjE2NzM0ODgw[...]
 */
 const TOKEN_URL_ARG = 'gv_token';

 /**
 * Default value for the expiration modifier.
 */
 const DEFAULT_EXPIRATION_VALUE = 24;

 /**
 * Default value for the expiration_unit modifier.
 */
 const DEFAULT_EXPIRATION_UNIT = 'hours';

 const FORM_SETTINGS_KEY = 'gravityview_entry_moderation';

 const NOTICE_URL_ARG = 'gv_approval_link_result';

 /**
 * Initialization.
 */
 public function __construct() {
 $this->add_hooks();
 }

 /**
 * Adds actions and filters related to entry approval links
 *
 * @return void
 */
 private function add_hooks() {
 add_filter( 'gform_form_settings_fields', array( $this, '_filter_gform_form_settings_fields' ), 10, 2 );
 add_filter( 'gform_custom_merge_tags', array( $this, '_filter_gform_custom_merge_tags' ), 10, 4 );
 add_filter( 'gform_replace_merge_tags', array( $this, '_filter_gform_replace_merge_tags' ), 10, 7 );

 add_action( 'init', array( $this, 'maybe_update_approved' ) );
 add_action( 'init', array( $this, 'maybe_show_approval_notice' ) );
 }

 /**
 * Filters existing GF Form Settings Fields
 *
 * @since 2.17
 *
 * @param array $fields Array of sections and settings fields
 * @param array $form GF Form
 *
 * @return array Modified array of sections and settings fields
 */
 public function _filter_gform_form_settings_fields( $fields = array(), $form = array() ) {

 $global_default = gravityview()->plugin->settings->get( 'public_entry_moderation', '0' );

 $fields['restrictions']['fields'][] = array(
 'name' => self::FORM_SETTINGS_KEY,
 'type' => 'radio',
 'horizontal' => true,
 // translators: %s is replaced with a setting label
 'label' => sprintf( esc_html__( 'GravityView - %s', 'gk-gravityview' ), esc_html__( 'Enable Public Entry Moderation', 'gk-gravityview' ) ),
 'description' => strtr(
 // translators: Do not translate the words inside the {} curly brackets; they are replaced.
 __( 'If enabled, adding {public} to {link}entry moderation merge tags{/link} will allow logged-out users to approve or reject entries. If disabled, all entry moderation actions require the user to be logged-in and have the ability to edit the entry.', 'gk-gravityview' ),
 array(
 '{public}' => '<code style="font-size: .9em">:public</code>',
 '{link}' => '<a href="https://docs.gravitykit.com/article/904-entry-moderation-merge-tags" target="_blank" rel="noopener noreferrer">',
 '{/link}' => '<span class="screen-reader-text"> ' . esc_html__( '(This link opens in a new window.)', 'gk-gravityview' ) . '</span></a>',
 )
 ),
 'choices' => array(
 array(
 'label' => _x( 'Enable', 'Setting: On or off', 'gk-gravityview' ),
 'value' => '1',
 ),
 array(
 'label' => _x( 'Disable', 'Setting: On or off', 'gk-gravityview' ),
 'value' => '0',
 ),
 ),
 'default_value' => (string) $global_default,
 );

 return $fields;
 }

 /**
 * Adds custom merge tags to merge tag options.
 *
 * @since 2.17
 *
 * @param array $custom_merge_tags
 * @param int $form_id GF Form ID
 * @param GF_Field[] $fields Array of fields in the form
 * @param string $element_id The ID of the input that Merge Tags are being used on
 *
 * @return array Modified merge tags
 */
 public function _filter_gform_custom_merge_tags( $custom_merge_tags = array(), $form_id = 0, $fields = array(), $element_id = '' ) {

 $entry_moderation_merge_tags = array(
 array(
 'label' => __( 'Moderation: Approve entry link', 'gravityview' ),
 'tag' => '{gv_approve_entry}',
 ),
 array(
 'label' => __( 'Moderation: Disapprove entry link', 'gravityview' ),
 'tag' => '{gv_disapprove_entry}',
 ),
 array(
 'label' => __( 'Moderation: Reset entry approval link', 'gravityview' ),
 'tag' => '{gv_unapprove_entry}',
 ),
 );

 return array_merge( $custom_merge_tags, $entry_moderation_merge_tags );
 }

 /**
 * Matches the merge tag in replacement text for the field.
 *
 * @since 2.17
 *
 * @see replace_merge_tag Override replace_merge_tag() to handle any matches
 *
 * @param string $text Text to replace
 * @param array $form Gravity Forms form array
 * @param array $entry Entry array
 * @param bool $url_encode Whether to URL-encode output
 *
 * @return string Original text if {_custom_merge_tag} isn't found. Otherwise, replaced text.
 */
 public function _filter_gform_replace_merge_tags( $text, $form = array(), $entry = array(), $url_encode = false, $esc_html = false ) {

 $matches = array();
 preg_match_all( '/{gv_((?:dis|un)?approve)_entry:?(?:(\d+)([d|h|m|s]))?:?(public)?}/', $text, $matches, PREG_SET_ORDER );

 // If there are no matches, return original text
 if ( empty( $matches ) ) {
 return $text;
 }

 if ( ! isset( $form[ self::FORM_SETTINGS_KEY ] ) ) {
 $form[ self::FORM_SETTINGS_KEY ] = gravityview()->plugin->settings->get( 'public_entry_moderation' );
 }

 return $this->replace_merge_tag( $matches, $text, $form, $entry, $url_encode, $esc_html );
 }

 /**
 * Replaces merge tags
 *
 * @since 2.17
 *
 * @param array $matches Array of Merge Tag matches found in text by preg_match_all
 * @param string $text Text to replace
 * @param array|bool $form Gravity Forms form array. When called inside {@see GFCommon::replace_variables()} (now deprecated), `false`
 * @param array|bool $entry Entry array. When called inside {@see GFCommon::replace_variables()} (now deprecated), `false`
 * @param bool $url_encode Whether to URL-encode output
 * @param bool $esc_html Whether to apply `esc_html()` to output
 *
 * @return mixed
 */
 protected function replace_merge_tag( $matches = array(), $text = '', $form = array(), $entry = array(), $url_encode = false, $esc_html = false ) {

 foreach ( $matches as $match ) {

 $full_tag = $match[0];
 $action = $match[1];
 $expiration_value = ! empty( $match[2] ) ? (int) $match[2] : self::DEFAULT_EXPIRATION_VALUE;
 $expiration_unit = ! empty( $match[3] ) ? $match[3] : self::DEFAULT_EXPIRATION_UNIT;
 $privacy = isset( $match[4] ) ? $match[4] : 'private';

 switch ( $expiration_unit ) {
 case 'd':
 $expiration_unit = 'days';
 break;
 case 'h':
 default:
 $expiration_unit = 'hours';
 break;
 case 'm':
 $expiration_unit = 'minutes';
 break;
 case 's': // Seconds should really only be used for testing purposes :-) But it's here if you need it.
 $expiration_unit = 'seconds';
 break;
 }

 if ( false === (bool) \GV\Utils::get( $form, self::FORM_SETTINGS_KEY, false ) ) {
 $privacy = 'private';
 }

 $expiration_timestamp = strtotime( "+{$expiration_value} {$expiration_unit}" );
 $expiration_seconds = $expiration_timestamp - time();

 $token = $this->get_token( $action, $expiration_timestamp, $privacy, $entry );

 if ( ! $token ) {
 continue;
 }

 $link_url = $this->get_link_url( $token, $expiration_seconds, $privacy );

 $anchor_text = GravityView_Entry_Approval_Status::get_action( $action . 'd' );

 $link = sprintf( '<a href="%s">%s</a>', esc_url_raw( $link_url ), esc_html( $anchor_text ) );

 $text = str_replace( $full_tag, $link, $text );
 }

 return $text;
 }

 /**
 * Generates a JWT token based on the merge tag parameters.
 *
 * @see https://jwt.io
 *
 * @since 2.17
 *
 * @param string|bool $action Action to be taken by the merge tag.
 * @param int $expiration_timestamp Timestamp when the token expires.
 * @param string $privacy Approval link privacy. Accepted values are 'private' or 'public'.
 * @param array $entry Entry array.
 *
 * @return string Encrypted token.
 */
 protected function get_token( $action = false, $expiration_timestamp = 0, $privacy = 'private', $entry = array() ) {

 if ( ! $action || ! $entry['id'] ) {
 return false;
 }

 if ( ! $expiration_timestamp ) {
 return false;
 }

 if ( ! $privacy ) {
 $privacy = 'private';
 }

 $approval_status = $this->get_approval_status( $action );

 if ( ! $approval_status ) {
 return false;
 }

 $jti = uniqid();
 $expiration_seconds = $expiration_timestamp - time();

 $scopes = array(
 'entry_id' => $entry['id'],
 'approval_status' => $approval_status,
 'expiration_seconds' => $expiration_seconds,
 'privacy' => $privacy,
 );

 $token_array = array(
 'iat' => time(),
 'exp' => $expiration_timestamp,
 'scopes' => $scopes,
 'jti' => $jti,
 );

 $token = rawurlencode( base64_encode( json_encode( $token_array ) ) );

 $secret = wp_salt( 'nonce' );

 $sig = hash_hmac( 'sha256', $token, $secret );

 $token .= '.' . $sig;

 return $token;
 }

 /**
 * Returns an approval status based on the provided action
 *
 * @since 2.17
 *
 * @param string|bool $action
 *
 * @return int Value of respective approval status
 */
 protected function get_approval_status( $action = false ) {

 if ( ! $action ) {
 return false;
 }

 $key = GravityView_Entry_Approval_Status::get_key( $action . 'd' );
 $values = GravityView_Entry_Approval_Status::get_values();

 return $values[ $key ];
 }

 /**
 * Generates an approval link URL
 *
 * @since 2.17
 *
 * @param string|bool $token
 * @param string $privacy Approval link privacy. Accepted values are 'private' or 'public'.
 *
 * @return string Approval link URL
 */
 protected function get_link_url( $token = false, $expiration_seconds = DAY_IN_SECONDS, $privacy = 'private' ) {

 if ( 'public' === $privacy ) {
 $base_url = home_url( '/' );
 } else {
 $base_url = admin_url( 'admin.php?page=gf_entries' );
 }

 $query_args = array();

 if ( ! empty( $token ) ) {
 $query_args[ self::TOKEN_URL_ARG ] = $token;
 }

 if ( 'private' === $privacy && DAY_IN_SECONDS >= (int) $expiration_seconds ) {
 $query_args['nonce'] = wp_create_nonce( self::TOKEN_URL_ARG );
 }

 return add_query_arg( $query_args, $base_url );
 }

 /**
 * Checks page load for approval link token then maybe process it
 *
 * @since 2.17
 *
 * Expects a $_GET request with the following $_GET keys and values:
 *
 * @return void
 * @global array $_GET {
 * @type string $gv_token Approval link token
 * @type string $nonce (optional) Nonce hash to be validated. Only available if $expiration_seconds is smaller than DAY_IN_SECONDS.
 * }
 *
 */
 public function maybe_update_approved() {

 $token_string = GV\Utils::_GET( self::TOKEN_URL_ARG );

 if ( ! $token_string ) {
 return;
 }

 $token = $this->decode_token( $token_string );

 if ( is_wp_error( $token ) ) {

 gravityview()->log->error( 'Decoding the entry approval token failed.', array( 'data' => $token ) );

 wp_die( sprintf( __( 'Entry moderation failed: %s', 'gravityview' ), $token->get_error_message() ) );
 }

 // Ensure the token is formatted properly.
 $is_valid_token = $this->is_token_valid( $token );

 if ( is_wp_error( $is_valid_token ) ) {

 gravityview()->log->error( 'Validating the entry approval token failed.', array( 'data' => $is_valid_token ) );

 wp_die( sprintf( __( 'Entry moderation failed: %s', 'gravityview' ), $is_valid_token->get_error_message() ) );
 }

 $is_request_valid = $this->is_request_valid( $token );

 if ( is_wp_error( $is_request_valid ) ) {

 gravityview()->log->error( 'Validating the entry approval token failed.', array( 'data' => $is_request_valid ) );

 wp_die( sprintf( __( 'Entry moderation failed: %s', 'gravityview' ), $is_request_valid->get_error_message() ) );
 }

 $scopes = $token['scopes'];

 $entry_id = $scopes['entry_id'];
 $approval_status = $scopes['approval_status'];

 $entry = GFAPI::get_entry( $entry_id );

 if ( is_wp_error( $entry ) ) {
 gravityview()->log->error( 'Entry moderation failed: the entry was not found.', array( 'data' => $entry ) );

 wp_die( $entry->get_error_message() );
 }

 $form_id = $entry['form_id'];

 if ( 'private' === $scopes['privacy'] ) {
 $return_url = admin_url( '/admin.php?page=gf_entries&s=' . $entry_id . '&field_id=entry_id&operator=is&id=' . $form_id );
 } else {
 $return_url = home_url( '/' );
 }

 // Valid status
 if ( ! GravityView_Entry_Approval_Status::is_valid( $approval_status ) ) {

 gravityview()->log->error( 'Invalid approval status', array( 'data' => $scopes ) );

 wp_safe_redirect( add_query_arg( array( self::NOTICE_URL_ARG => 'error' ), $return_url ) );

 exit;
 }

 if ( empty( $entry_id ) || empty( $form_id ) ) {

 gravityview()->log->error( 'entry_id or form_id are empty.', array( 'data' => $scopes ) );

 wp_safe_redirect( add_query_arg( array( self::NOTICE_URL_ARG => 'error' ), $return_url ) );

 exit;
 }

 if ( 'private' === $scopes['privacy'] && ! GVCommon::has_cap( 'gravityview_moderate_entries', $entry_id ) ) {

 gravityview()->log->error( 'User does not have the `gravityview_moderate_entries` capability.' );

 wp_safe_redirect( add_query_arg( array( self::NOTICE_URL_ARG => 'error' ), $return_url ) );

 exit;
 }

 $this->update_approved( $entry_id, $approval_status, $form_id, $scopes, $return_url );
 }

 /**
 * Verifies the token
 *
 * @since 2.17
 *
 * @param array $token
 *
 * @return bool|WP_Error
 */
 protected function is_request_valid( $token ) {

 if ( 'private' === $token['scopes']['privacy'] && ! is_user_logged_in() ) {
 return new WP_Error( 'user_not_logged_in', __( 'You are not allowed to perform this operation.', 'gravityview' ) );
 }

 if ( $token['exp'] < time() ) {
 gravityview()->log->error( 'The entry moderation link expired.', array( 'data' => $is_valid_token ) );

 return new WP_Error( 'link_expired', esc_html__( 'The link has expired.', 'gk-gravityview' ) );
 }

 // Since nonces are only valid for 24 hours, we only check the nonce if the token is valid for less than 24 hours.
 if ( 'private' === $token['scopes']['privacy'] && DAY_IN_SECONDS >= $token['scopes']['expiration_seconds'] ) {

 if ( ! isset( $_REQUEST['nonce'] ) ) {
 gravityview()->log->error( 'Entry moderation failed: No nonce was set for entry approval.' );

 return new WP_Error( 'missing_nonce', esc_html__( 'The link is invalid.', 'gk-gravityview' ) );
 }

 $nonce_validation = wp_verify_nonce( GV\Utils::_GET( 'nonce' ), self::TOKEN_URL_ARG );

 if ( ! $nonce_validation ) {
 gravityview()->log->error( 'Entry moderation failed: Nonce was invalid.', array( 'data' => $nonce_validation ) );

 return new WP_Error( 'invalid_nonce', esc_html__( 'The link has expired.', 'gk-gravityview' ) );
 }
 }

 return true;
 }

 /**
 * Checks page load for approval link result then maybe show notice
 *
 * @since 2.17
 *
 * Expects a $_GET request with the following $_GET keys and values:
 *
 * @return void
 * @global array $_GET {
 * @type string $gv_approval_link_result Approval link result
 * }
 *
 */
 public function maybe_show_approval_notice() {

 $result = GV\Utils::_GET( self::NOTICE_URL_ARG );
 $approval_status = \GV\Utils::_GET( 'approval_status' );
 $entry_id = \GV\Utils::_GET( 'entry_id' );

 if ( ! $result || ! $approval_status || ! $entry_id ) {
 return;
 }

 $approval_label = GravityView_Entry_Approval_Status::get_label( (int) $approval_status );
 $approval_label = mb_strtolower( $approval_label );

 if ( 'success' === $result ) {

 // translators: Do not translate the words inside the {} curly brackets; they are replaced.
 $message = esc_html__( 'Success: Entry #{entry_id} has been {approval_label}.', 'gk-gravityview' );

 $css_class = 'updated';
 } else {

 // translators: Do not translate the words inside the {} curly brackets; they are replaced.
 $message = esc_html__( 'There was an error updating entry #{entry_id}.', 'gk-gravityview' );

 $css_class = 'error';
 }

 $message = strtr( $message, array(
 '{entry_id}' => esc_html( $entry_id ),
 '{approval_label}' => esc_html( $approval_label ),
 ) );

 $message = \GVCommon::generate_notice( wpautop( $message ), $css_class );

 if ( is_admin() ) {
 echo $message;
 } else {
 wp_die( $message );
 }
 }

 /**
 * Decodes received token to its original form.
 *
 * @since 2.17
 *
 * @param string|bool $token
 *
 * @return array|WP_Error Original scopes or WP Error object
 */
 protected function decode_token( $token = false ) {

 if ( ! $token ) {
 return new WP_Error( 'missing_token', __( 'Invalid security token.', 'gk-gravityview' ) );
 }

 $parts = explode( '.', $token );

 if ( count( $parts ) < 2 ) {
 return new WP_Error( 'missing_period', __( 'Invalid security token.', 'gk-gravityview' ) );
 }

 /**
 * @param string $body_64 $parts[0]
 * @param string $sig $parts[1]
 */
 list( $body_64, $sig ) = $parts;

 if ( empty( $sig ) ) {
 return new WP_Error( 'approve_link_no_signature', esc_html__( 'The link is invalid.', 'gk-gravityview' ) );
 }

 $secret = wp_salt( 'nonce' );
 $verification_sig = hash_hmac( 'sha256', $body_64, $secret );
 $verification_sig2 = hash_hmac( 'sha256', rawurlencode( $body_64 ), $secret );

 if ( ! hash_equals( $sig, $verification_sig ) && ! hash_equals( $sig, $verification_sig2 ) ) {
 return new WP_Error( 'approve_link_failed_signature_verification', esc_html__( 'The link is invalid.', 'gk-gravityview' ) );
 }

 $body_json = base64_decode( $body_64 );
 $decoded_token = json_decode( $body_json, true );

 if ( empty( $body_json ) || empty( $decoded_token ) ) {
 $decoded_token = base64_decode( urldecode( $body_64 ) );
 }

 if ( empty( $decoded_token ) ) {
 return new WP_Error( 'approve_link_failed_base64_decode', esc_html__( 'The link is invalid.', 'gk-gravityview' ) );
 }

 return $decoded_token;
 }

 /**
 * Validates an approval token
 *
 * @since 2.17
 *
 * @param array $token
 *
 * @return true|WP_Error Token is valid or there was an error.
 */
 protected function is_token_valid( array $token ) {

 $required_keys = array(
 'jti',
 'exp',
 'scopes',
 );

 foreach ( $required_keys as $required_key ) {
 if ( ! isset( $token[ $required_key ] ) ) {
 return new WP_Error( 'approve_link_no_' . $required_key, esc_html__( 'The link is invalid.', 'gk-gravityview' ) );
 }
 }

 $required_scopes = array(
 'expiration_seconds',
 'privacy',
 'entry_id',
 'approval_status',
 );

 foreach ( $required_scopes as $required_scope ) {
 if ( ! isset( $token['scopes'][ $required_scope ] ) ) {
 return new WP_Error( 'approve_link_no_' . $required_scope . '_scope', esc_html__( 'The link is invalid.', 'gk-gravityview' ) );
 }
 }

 return true;
 }

 /**
 * Updates the entry approval status and redirects to $return_url.
 *
 * @param int $entry_id Entry ID.
 * @param int $approval_status Approval status.
 * @param int $form_id Form ID.
 * @param array $scopes Token scopes to be passed to the return URL and used in {@see maybe_show_approval_notice()}.
 * @param string $return_url Url to redirect to once moderation happens.
 *
 * @return void
 */
 protected function update_approved( $entry_id, $approval_status, $form_id, $scopes, $return_url ) {

 $result = GravityView_Entry_Approval::update_approved( $entry_id, $approval_status, $form_id );

 $query_args = $scopes;

 $query_args[ self::NOTICE_URL_ARG ] = $result ? 'success' : 'error';

 $return_url = add_query_arg( $query_args, $return_url );

 wp_safe_redirect( esc_url_raw( $return_url ) );

 exit;
 }
}

new GravityView_Entry_Approval_Merge_Tags;