__( 'Entry awaiting approval: {form_title}', 'fieldwren' ), 'email_field' => '', 'approved_subject' => __( 'Your submission was approved', 'fieldwren' ), 'approved_message' => __( "Hi,\n\nGood news: your submission to {form_title} has been approved.\n\nThank you.", 'fieldwren' ), 'declined_subject' => __( 'About your submission', 'fieldwren' ), 'declined_message' => __( "Hi,\n\nThank you for your submission to {form_title}. Unfortunately we could not approve it.", 'fieldwren' ), ), (array) ( $d['admin_approval'] ?? array() ) ); return $d; } /* ------------------------------------------------------------------ * * Reviewer email * ------------------------------------------------------------------ */ /** Entry held back as pending: notify the reviewer. */ public static function on_gated( $row, $values, $status, $payment = null ) { if ( 'pending' !== $status || empty( $row['id'] ) ) { return; } self::notify_reviewer( (array) $row, (array) $values ); } /** @return string Signed review link. */ public static function review_url( $entry_id, $action ) { return add_query_arg( array( 'action' => 'fwren_review', 'entry' => (int) $entry_id, 'do' => $action, 'sig' => Helpers::sign( 'review|' . (int) $entry_id . '|' . $action ), ), admin_url( 'admin-post.php' ) ); } /** Send the reviewer email. */ public static function notify_reviewer( array $entry, array $values ) { $form_id = (int) $entry['form_id']; $s = Form::settings( $form_id )['admin_approval']; $to = (string) $s['notify_email']; if ( '' === trim( $to ) ) { return false; } $btn = 'display:inline-block;padding:10px 18px;border-radius:6px;text-decoration:none;font-weight:600;margin-right:8px;'; $buttons = '

' . esc_html__( 'Approve', 'fieldwren' ) . '' . '' . esc_html__( 'Decline', 'fieldwren' ) . '' . '' . esc_html__( 'View entry', 'fieldwren' ) . '

'; $n = array( 'id' => 'admin_approval', 'enabled' => true, 'name' => __( 'Approval request', 'fieldwren' ), 'to_type' => 'email', 'to' => $to, 'to_field' => '', 'routing' => array(), 'cc' => '', 'bcc' => '', 'reply_to' => '', 'from_name' => '', 'from_email' => '', 'subject' => (string) $s['notify_subject'], 'message' => '

' . esc_html__( 'A new entry is waiting for your approval.', 'fieldwren' ) . '

' . $buttons . '{all_data}', 'attach_uploads' => false, ); return Notifications::send( apply_filters( 'fwren/admin_approval/reviewer_email', $n, $entry, $values ), $entry, $values ); } /* ------------------------------------------------------------------ * * Decisions * ------------------------------------------------------------------ */ /** Not logged in: log in, then come back to the same link. */ public static function login_first() { auth_redirect(); exit; } /** Approve / decline from the email link (signature) or an entry screen button (nonce). */ public static function handle() { $id = absint( $_GET['entry'] ?? 0 ); // phpcs:ignore WordPress.Security.NonceVerification $action = sanitize_key( wp_unslash( $_GET['do'] ?? '' ) ); // phpcs:ignore WordPress.Security.NonceVerification $sig = sanitize_text_field( wp_unslash( $_GET['sig'] ?? '' ) ); // phpcs:ignore WordPress.Security.NonceVerification $nonce = sanitize_text_field( wp_unslash( $_GET['_wpnonce'] ?? '' ) ); // phpcs:ignore WordPress.Security.NonceVerification if ( ! in_array( $action, array( 'approve', 'decline' ), true ) || ! $id ) { wp_die( esc_html__( 'Invalid request.', 'fieldwren' ), 400 ); } $valid = Helpers::verify( 'review|' . $id . '|' . $action, $sig ) || wp_verify_nonce( $nonce, 'fwren_review_' . $id ); if ( ! $valid || ! current_user_can( 'fwren_manage_entries' ) ) { wp_die( esc_html__( 'You are not allowed to review this entry.', 'fieldwren' ), 403 ); } $ok = 'approve' === $action ? self::approve( $id ) : self::decline( $id ); if ( $nonce ) { wp_safe_redirect( add_query_arg( 'fwren_notice', $ok ? 'entry_' . $action . 'd' : 'entry_review_failed', wp_get_referer() ? wp_get_referer() : admin_url( 'admin.php?page=fwren-entries&entry=' . $id ) ) ); exit; } $entry = Entries::get( $id ); $view = '

' . esc_html__( 'View entry', 'fieldwren' ) . '

'; if ( $ok ) { Helpers::page( 'approve' === $action ? __( 'Entry approved', 'fieldwren' ) : __( 'Entry declined', 'fieldwren' ), $view ); } /* translators: %s status */ Helpers::page( __( 'Nothing to do', 'fieldwren' ), '

' . esc_html( sprintf( __( 'This entry is no longer awaiting approval (status: %s).', 'fieldwren' ), $entry ? $entry['status'] : '—' ) ) . '

' . $view ); } /** * Approve an entry (pending or declined). * * @param int $id Entry id. * @return bool */ public static function approve( $id ) { $entry = Entries::get( $id ); if ( ! $entry || ! in_array( $entry['status'], array( 'pending', 'declined' ), true ) ) { return false; } $lock = 'fwren_lock_review_' . (int) $id; if ( ! add_option( $lock, time(), '', 'no' ) ) { return false; } try { if ( 'declined' === $entry['status'] ) { Entries::update( $id, array( 'status' => 'pending' ) ); } self::log( $id, 'approved' ); Submission::complete( $id, 'approved' ); } finally { delete_option( $lock ); } $entry = Entries::get( $id ); $s = Form::settings( (int) $entry['form_id'] )['admin_approval']; if ( ! empty( $s['approved_email'] ) ) { self::email_submitter( $entry, (string) $s['approved_subject'], (string) $s['approved_message'], 'approved' ); } do_action( 'fwren/admin_approval/approved', $entry ); return true; } /** * Decline a pending entry. * * @param int $id Entry id. * @return bool */ public static function decline( $id ) { $entry = Entries::get( $id ); if ( ! $entry || 'pending' !== $entry['status'] ) { return false; } Entries::update( $id, array( 'status' => 'declined' ) ); $entry['status'] = 'declined'; self::log( $id, 'declined' ); $s = Form::settings( (int) $entry['form_id'] )['admin_approval']; if ( ! empty( $s['declined_email'] ) ) { self::email_submitter( $entry, (string) $s['declined_subject'], (string) $s['declined_message'], 'declined' ); } do_action( 'fwren/admin_approval/declined', $entry ); return true; } /** Decision log row. */ private static function log( $id, $action ) { Entries::add_meta( $id, '_approval', array( 'action' => $action, 'by' => get_current_user_id(), 'at' => current_time( 'mysql', true ), ) ); } /** Email the submitter. */ private static function email_submitter( array $entry, $subject, $message, $kind ) { $form_id = (int) $entry['form_id']; $settings = Form::settings( $form_id ); $field = $settings['admin_approval']['email_field'] ? $settings['admin_approval']['email_field'] : $settings['double_optin']['email_field']; $to = Helpers::email_of( $form_id, (array) $entry['response'], (string) $field ); if ( ! $to ) { return false; } $n = array( 'id' => 'approval_' . $kind, 'enabled' => true, /* translators: %s approved | declined */ 'name' => sprintf( __( 'Submitter email (%s)', 'fieldwren' ), $kind ), 'to_type' => 'email', 'to' => $to, 'to_field' => '', 'routing' => array(), 'cc' => '', 'bcc' => '', 'reply_to' => '', 'from_name' => '', 'from_email' => '', 'subject' => $subject, 'message' => $message, 'attach_uploads' => false, ); return Notifications::send( $n, $entry, (array) $entry['response'] ); } /* ------------------------------------------------------------------ * * Admin UI * ------------------------------------------------------------------ */ /** Per-form tab. */ public static function tab( $tabs, $form_id = 0 ) { $tabs['admin_approval'] = __( 'Admin approval', 'fieldwren' ); return $tabs; } /** Tab content. */ public static function render_tab( $form_id, $settings ) { $s = $settings['admin_approval']; $n = 'fwren[admin_approval]'; echo ''; Helpers::row_toggle( $n . '[enabled]', ! empty( $s['enabled'] ), __( 'Require approval', 'fieldwren' ), __( 'New entries wait as “Awaiting approval”. Notifications and integrations run once an entry is approved (notifications set to send on “approved” run at that moment too).', 'fieldwren' ) ); Helpers::row_text( $n . '[notify_email]', $s['notify_email'], __( 'Reviewer email(s)', 'fieldwren' ), __( 'Comma separated. Gets the entry with Approve / Decline links; the reviewer must be logged in with the “manage entries” capability.', 'fieldwren' ) ); Helpers::row_text( $n . '[notify_subject]', $s['notify_subject'], __( 'Reviewer email subject', 'fieldwren' ) ); Helpers::row_textarea( $n . '[pending_message]', $s['pending_message'], __( 'Message after submitting', 'fieldwren' ), '', 3 ); Helpers::row_field( $n . '[email_field]', $form_id, $s['email_field'], __( 'Submitter email field', 'fieldwren' ), Helpers::types( array( 'email' ) ), __( 'Empty: the double opt-in email field, else the first email field.', 'fieldwren' ) ); Helpers::row_toggle( $n . '[approved_email]', ! empty( $s['approved_email'] ), __( 'Email the submitter when approved', 'fieldwren' ) ); Helpers::row_text( $n . '[approved_subject]', $s['approved_subject'], __( 'Approved – subject', 'fieldwren' ) ); Helpers::row_textarea( $n . '[approved_message]', $s['approved_message'], __( 'Approved – message', 'fieldwren' ), '', 5 ); Helpers::row_toggle( $n . '[declined_email]', ! empty( $s['declined_email'] ), __( 'Email the submitter when declined', 'fieldwren' ) ); Helpers::row_text( $n . '[declined_subject]', $s['declined_subject'], __( 'Declined – subject', 'fieldwren' ) ); Helpers::row_textarea( $n . '[declined_message]', $s['declined_message'], __( 'Declined – message', 'fieldwren' ), '', 5 ); echo ''; } /** Approve / Decline buttons. */ public static function entry_actions( $entry ) { if ( empty( $entry['id'] ) || ! current_user_can( 'fwren_manage_entries' ) || ! in_array( $entry['status'] ?? '', array( 'pending', 'declined' ), true ) ) { return; } $id = (int) $entry['id']; $base = admin_url( 'admin-post.php?action=fwren_review&entry=' . $id ); echo '' . esc_html__( 'Approve', 'fieldwren' ) . ' '; if ( 'pending' === $entry['status'] ) { echo '' . esc_html__( 'Decline', 'fieldwren' ) . ' '; } } /** Decision history. */ public static function entry_sidebar( $entry ) { if ( empty( $entry['id'] ) ) { return; } $rows = Entries::meta_rows( (int) $entry['id'], '_approval' ); if ( ! $rows && ! in_array( $entry['status'] ?? '', array( 'pending', 'declined' ), true ) ) { return; } echo '

' . esc_html__( 'Approval', 'fieldwren' ) . '

'; if ( ! $rows ) { echo '

' . esc_html__( 'Awaiting a decision.', 'fieldwren' ) . '

'; } echo '
'; } /** Bulk actions. */ public static function bulk_actions( $actions ) { $actions['approve'] = __( 'Approve', 'fieldwren' ); $actions['decline'] = __( 'Decline', 'fieldwren' ); return $actions; } /** Bulk approve. */ public static function bulk_approve( $ids ) { if ( current_user_can( 'fwren_manage_entries' ) ) { foreach ( array_map( 'absint', (array) $ids ) as $id ) { self::approve( $id ); } } } /** Bulk decline. */ public static function bulk_decline( $ids ) { if ( current_user_can( 'fwren_manage_entries' ) ) { foreach ( array_map( 'absint', (array) $ids ) as $id ) { self::decline( $id ); } } } }