Changeset 12898

Timestamp:

04/20/2021 04:02:43 PM (2 years ago)

Author:

dcavins

Message:

Introduce BP_Optouts.

Add capability to store opt-out requests from
nonmembers who have been contacted by
communication from a BuddyPress site. These
new objects are represented by the class BP_Optout
and are stored in a new database table
wp_bp_optouts. This commit adds the following capabilities:

• Add new class BP_Optout.
• Add new table wp_bp_optouts.
• Create new table on installation or upgrade.
• Add convenience functions for adding, fetching or

deleting opt-outs.

• Add tests for basic opt-out management.

See #8448.

Location:

trunk

Files:

• src/bp-core/admin/bp-core-admin-schema.php (modified) (2 diffs)
• src/bp-core/bp-core-cache.php (modified) (1 diff)
• src/bp-core/bp-core-functions.php (modified) (1 diff)
• src/bp-core/bp-core-update.php (modified) (1 diff)
• src/bp-core/classes/class-bp-optout.php (added)
• src/bp-members/classes/class-bp-members-component.php (modified) (1 diff)
• src/class-buddypress.php (modified) (1 diff)
• tests/phpunit/testcases/core/optouts.php (added)

trunk/src/bp-core/admin/bp-core-admin-schema.php

@@ -40 +40 @@
     // Install the invitations table.
     bp_core_install_invitations();
+
+    // Install the nonmember opt-outs table.
+    bp_core_install_nonmember_opt_outs();
 
     // Notifications.
@@ -591 +594 @@
     do_action( 'bp_core_install_invitations' );
 }
+
+/**
+ * Install database tables to store opt-out requests from nonmembers.
+ *
+ * @since 8.0.0
+ *
+ * @uses bp_core_set_charset()
+ * @uses bp_core_get_table_prefix()
+ * @uses dbDelta()
+ */
+function bp_core_install_nonmember_opt_outs() {
+    $sql             = array();
+    $charset_collate = $GLOBALS['wpdb']->get_charset_collate();
+    $bp_prefix       = bp_core_get_table_prefix();
+    $optouts_class   = new BP_Optout();
+    $table_name      = $optouts_class->get_table_name();
+    $sql = "CREATE TABLE {$table_name} (
+        id bigint(20) NOT NULL AUTO_INCREMENT PRIMARY KEY,
+        email_address_hash varchar(255) NOT NULL,
+        user_id bigint(20) NOT NULL,
+        email_type varchar(255) NOT NULL,
+        date_modified datetime NOT NULL,
+        KEY user_id (user_id),
+        KEY email_type (email_type),
+        KEY date_modified (date_modified)
+        ) {$charset_collate};";
+    dbDelta( $sql );
+
+    /**
+     * Fires after BuddyPress adds the nonmember opt-outs table.
+     *
+     * @since 8.0.0
+     */
+    do_action( 'bp_core_install_nonmember_opt_outs' );
+}

trunk/src/bp-core/bp-core-cache.php

@@ -416 +416 @@
 add_action( 'bp_type_updated', 'bp_clear_object_type_terms_cache' );
 add_action( 'bp_type_deleted', 'bp_clear_object_type_terms_cache' );
+
+/**
+ * Resets all incremented bp_optout caches.
+ *
+ * @since 8.0.0
+ */
+function bp_optouts_reset_cache_incrementor() {
+    bp_core_reset_incrementor( 'bp_optouts' );
+}
+add_action( 'bp_optout_after_save', 'bp_optouts_reset_cache_incrementor' );
+add_action( 'bp_optout_after_delete', 'bp_optouts_reset_cache_incrementor' );

trunk/src/bp-core/bp-core-functions.php

@@ -4277 +4277 @@
     return apply_filters( 'bp_get_widget_max_count_limit', 50, $widget_class );
 }
+
+/**
+ * Add a new BP_Optout.
+ *
+ * @since 8.0.0
+ *
+ * @param array $args {
+ *     An array of arguments describing the new opt-out.
+ *     @type string $email_address Email address of user who has opted out.
+ *     @type int    $user_id       Optional. ID of user whose communication
+ *                                 prompted the user to opt-out.
+ *     @type string $email_type    Optional. Name of the email type that
+ *                                 prompted the user to opt-out.
+ *     @type string $date_modified Optional. Specify a time, else now will be used.
+ * }
+ * @return false|int False on failure, ID of new (or existing) opt-out if successful.
+ */
+function bp_add_optout( $args = array() ) {
+    $optout = new BP_Optout();
+    $r      = bp_parse_args(
+        $args, array(
+            'email_address' => '',
+            'user_id'       => 0,
+            'email_type'    => '',
+            'date_modified' => bp_core_current_time(),
+        ),
+        'add_optout'
+    );
+
+    // Opt-outs must have an email address.
+    if ( empty( $r['email_address'] ) ) {
+        return false;
+    }
+
+    // Avoid creating duplicate opt-outs.
+    $optout_id = $optout->optout_exists(
+        array(
+            'email_address' => $r['email_address'],
+            'user_id'       => $r['user_id'],
+            'email_type'    => $r['email_type'],
+        )
+    );
+
+    if ( ! $optout_id ) {
+        // Set up the new opt-out.
+        $optout->email_address = $r['email_address'];
+        $optout->user_id       = $r['user_id'];
+        $optout->email_type    = $r['email_type'];
+        $optout->date_modified = $r['date_modified'];
+
+        $optout_id = $optout->save();
+    }
+
+    return $optout_id;
+}
+
+/**
+ * Find matching BP_Optouts.
+ *
+ * @since 8.0.0
+ *
+ * @see BP_Optout::get() for a description of parameters and return values.
+ *
+ * @param array $args See {@link BP_Optout::get()}.
+ * @return array See {@link BP_Optout::get()}.
+ */
+function bp_get_optouts( $args = array() ) {
+    $optout_class = new BP_Optout();
+    return $optout_class::get( $args );
+}
+
+/**
+ * Delete a BP_Optout by ID.
+ *
+ * @since 8.0.0
+ *
+ * @param int $id ID of the optout to delete.
+ * @return bool True on success, false on failure.
+ */
+function bp_delete_optout_by_id( $id = 0 ) {
+    $optout_class = new BP_Optout();
+    return $optout_class::delete_by_id( $id );
+}

trunk/src/bp-core/bp-core-update.php

@@ -652 +652 @@
         }
     }
+
+    bp_core_install_nonmember_opt_outs();
 }
 

trunk/src/bp-members/classes/class-bp-members-component.php

@@ -179 +179 @@
                 'table_name_invitations'   => bp_core_get_table_prefix() . 'bp_invitations',
                 'table_name_last_activity' => bp_core_get_table_prefix() . 'bp_activity',
+                'table_name_optouts'       => bp_core_get_table_prefix() . 'bp_optouts',
                 'table_name_signups'       => $wpdb->base_prefix . 'signups', // Signups is a global WordPress table.
             )

trunk/src/class-buddypress.php

@@ -598 +598 @@
             'BP_REST_Attachments'          => 'core',
             'BP_Admin_Types'               => 'core',
+            'BP_Optout'                    => 'core',
 
             'BP_Core_Friends_Widget'   => 'friends',