WordPress.org

Make WordPress Core

Ticket #43602: ERASURE.4.md

File ERASURE.4.md, 5.7 KB (added by allendav, 16 months ago)

Updated to show registration using a key instead of a simple numeric array; removed copy paste error (unused export variable)

Line 
1# How to Connect Your Plugin to Core's New Personal Data Eraser
2
3## Background
4
5In WordPress 4.9.x, new tools were added to make compliance easier with laws
6like the European Union's General Data Protection Regulation, or GDPR for
7short. Among the tools added is a Personal Data Removal tool which supports
8erasing/anonymizing personal data for a given user. It does NOT delete
9registered user accounts - that is still a separate step the admin can
10choose whether or not to do.
11
12In addition to the personal data stored in things like WordPress comments,
13plugins can also hook into the eraser feature to erase the personal
14data they collect, whether it be in something like postmeta or even an
15entirely new Custom Post Type (CPT).
16
17## How It Works
18
19Like the exporters, the "key" for all the erasers is the user's email address -
20this was chosen because it supports erasing personal data for both full-fledged
21registered users and also unregistered users (e.g. like a logged out commenter).
22
23However, since performing a personal data erase is a destructive process, we
24don't want to just do it without confirming the request, so the admin-facing
25UX starts all requests by having the admin enter the username or email address
26making the request and then sends then a link to click to confirm their
27request.
28
29A list of requests and whether they have been confirmed is available to
30the administrator in the same user interface.  Once a request has been
31confirmed, the admin can kick off personal data erasure for the user.
32
33## Design Internals
34
35The way the personal data export is erased is similar to how the personal data
36exporters - and relies on hooking "eraser" callbacks to do the dirty work
37of erasing the data.
38
39When the admin clicks on the remove personal data link, an AJAX loop begins
40that iterates over all the erasers registered in the system, one at a time.
41In addition to erasers built into core, plugins can register their own
42eraser callbacks.
43
44The eraser callback interface is designed to be as simple as possible.
45An eraser callback receives the email address we are working with,
46and a page parameter as well. The page parameter (which starts at 1) is
47used to avoid plugins potentially causing timeouts by attempting to erase
48all the personal data they've collected at once.
49
50The eraser callback replies whether items containing personal data were
51erased, whether any items containing personal data were retained, an
52array of messages to present to the admin (explaining why items that were
53retained were retained) and whether it is done or not. If an eraser
54callback reports that it is not done, it will be called again (in a
55separate request) with the page parameter incremented by 1.
56
57When all the exporters have been called to completion, the UX is updated to
58show whether or not all personal data found was erased, and any messages
59explaining why personal data was retained.
60
61A good example is a plugin that takes e-commerce orders. The plugin's settings
62could say that personal data should be retained for orders < XXX days old. The
63plugin's order eraser could look at that setting against each order
64and decide whether or not to remove it. If it decides not to remove it,
65it can emit a message in the AJAX to say as much to the admin (i.e. Order
661234 was not erased because it is less than XXX days old.)
67
68The intention for now is that plugins may choose to expose erasure controls
69in their own settings user interfaces where it makes the most contextual sense.
70
71## What to Do
72
73A plugin can register one or more erasers, but most plugins will only
74need one. Let's work on a hypothetical plugin which adds commenter location
75data to comments.
76
77Let's assume the plugin has used `add_comment_meta` to add location
78data using `meta_key`s of `latitude` and `longitude`
79
80The first thing the plugin needs to do is to create an eraser function
81that accepts an email address and a page, e.g.:
82
83```
84function my_plugin_eraser( $email_address, $page = 1 ) {
85  $number = 500; // Limit us to avoid timing out
86  $page = (int) $page;
87
88  $comments = get_comments(
89    array(
90      'author_email' => $email_address,
91      'number'       => $number,
92      'paged'        => $page,
93      'order_by'     => 'comment_ID',
94      'order'        => 'ASC',
95      )
96  );
97
98  $items_removed = false;
99
100  foreach ( (array) $comments as $comment ) {
101    $latitude  = get_comment_meta( $comment->comment_ID, 'latitude', true );
102    $longitude = get_comment_meta( $comment->comment_ID, 'longitude', true );
103
104    if ( ! empty( $latitude ) ) {
105      delete_comment_meta( $comment->comment_ID, 'latitude' );
106      $items_removed = true;
107    }
108
109    if ( ! empty( $longitude ) ) {
110      delete_comment_meta( $comment->comment_ID, 'longitude' );
111                        $items_removed = true;
112    }
113  }
114
115  // Tell core if we have more comments to work on still
116  $done = count( $comments ) < $number;
117
118  return array(
119    'items_removed' => $items_removed,
120    'items_retained' => false, // always false in this example
121    'messages' => array(), // no messages in this example
122    'done' => $done,
123  );
124}
125```
126
127The next thing the plugin needs to do is to register the callback by
128filtering the eraser array using the `wp_privacy_personal_data_erasers`
129filter.
130
131When registering you provide a friendly name for the eraser (to aid in
132debugging - this friendly name is not shown to anyone at this time)
133and the callback, e.g.
134
135```
136function register_my_plugin_eraser( $erasers ) {
137  $erasers['my-plugin-slug'] = array(
138    'eraser_friendly_name' => __( 'Comment Location Plugin' ),
139    'callback'             => 'my_plugin_eraser',
140    );
141  return $erasers;
142}
143
144add_filter(
145  'wp_privacy_personal_data_erasers',
146  'register_my_plugin_eraser',
147  10
148);
149```
150
151And that's all there is to it! Your plugin will now clean up its personal
152data!