format( $format ) === $value && ( false === $errors || ( 0 === $errors['warning_count'] && 0 === $errors['error_count'] ) ) ) { return true; } } return false; } /** * Accept only an administrator. An empty value clears the assignment. * * @param mixed $assigned_to_param Raw assignee value. * @return int|null|WP_Error */ private function sanitize_assignee( $assigned_to_param ) { if ( null === $assigned_to_param || '' === $assigned_to_param ) { return null; } $assigned_to = (int) $assigned_to_param; if ( $assigned_to <= 0 || ! user_can( $assigned_to, 'manage_options' ) ) { return new WP_Error( 'invalid_assigned_to', __( 'The specified user does not exist or is not an administrator.', 'devnotes' ), array( 'status' => 400 ) ); } return $assigned_to; } /** * @param array $item Stored row. * @param int $previous_assignee Previous assignee, or 0. */ private function maybe_notify_assignee( $item, $previous_assignee ) { $assignee = isset( $item['assigned_to'] ) ? (int) $item['assigned_to'] : 0; $previous = (int) $previous_assignee; if ( $assignee <= 0 || $assignee === $previous || $assignee === get_current_user_id() ) { return; } $user = get_userdata( $assignee ); if ( ! $user || ! user_can( $user, 'manage_options' ) || empty( $user->user_email ) ) { return; } $notices_key = DevNotes_DB::notices_meta_key(); $notices = get_user_meta( $assignee, $notices_key, true ); if ( ! is_array( $notices ) ) { $notices = array(); } $notices[] = array( 'id' => isset( $item['id'] ) ? (int) $item['id'] : 0, 'title' => isset( $item['title'] ) ? sanitize_text_field( $item['title'] ) : '', 'from' => get_current_user_id(), 'blog_id' => get_current_blog_id(), ); if ( count( $notices ) > 20 ) { $notices = array_slice( $notices, -20 ); } update_user_meta( $assignee, $notices_key, $notices ); if ( '0' === get_option( 'devnotes_email_assignees', '1' ) ) { return; } $assigner = wp_get_current_user(); $subject = sprintf( /* translators: %s: site name */ __( '[%s] A DevNotes item was assigned to you', 'devnotes' ), wp_specialchars_decode( get_bloginfo( 'name' ), ENT_QUOTES ) ); $body = sprintf( /* translators: 1: assignee name, 2: assigner name, 3: item title, 4: DevNotes URL */ __( "Hi %1\$s,\n\n%2\$s assigned you a DevNotes item:\n\n%3\$s\n\nOpen DevNotes: %4\$s\n", 'devnotes' ), $user->display_name, $assigner->exists() ? $assigner->display_name : __( 'Someone', 'devnotes' ), isset( $item['title'] ) ? sanitize_text_field( $item['title'] ) : '', admin_url( 'admin.php?page=devnotes&tab=tasks' ) ); wp_mail( $user->user_email, $subject, $body ); } /** * Add the linked post title and edit URL for the response. * * @param array> $rows Database rows. * @return array> */ private function enrich_items( $rows ) { $post_ids = array(); foreach ( $rows as $row ) { if ( ! empty( $row['post_id'] ) ) { $post_ids[] = (int) $row['post_id']; } } $post_ids = array_values( array_unique( $post_ids ) ); $posts = array(); if ( ! empty( $post_ids ) ) { $found = get_posts( array( 'post__in' => $post_ids, 'post_type' => 'any', 'post_status' => 'any', 'posts_per_page' => count( $post_ids ), 'orderby' => 'post__in', 'suppress_filters' => false, 'ignore_sticky_posts' => true, ) ); foreach ( $found as $post ) { $posts[ $post->ID ] = $post; } } foreach ( $rows as $index => $row ) { $post_id = ! empty( $row['post_id'] ) ? (int) $row['post_id'] : 0; $rows[ $index ]['id'] = isset( $row['id'] ) ? (int) $row['id'] : 0; $rows[ $index ]['pinned'] = ! empty( $row['pinned'] ) ? 1 : 0; $rows[ $index ]['post_id'] = $post_id > 0 ? $post_id : null; $rows[ $index ]['assigned_to'] = ! empty( $row['assigned_to'] ) ? (int) $row['assigned_to'] : null; $rows[ $index ]['post_title'] = ''; $rows[ $index ]['post_edit_url'] = ''; if ( $post_id > 0 && isset( $posts[ $post_id ] ) ) { $rows[ $index ]['post_title'] = html_entity_decode( get_the_title( $posts[ $post_id ] ), ENT_QUOTES, get_bloginfo( 'charset' ) ); $edit = get_edit_post_link( $post_id, 'raw' ); $rows[ $index ]['post_edit_url'] = $edit ? $edit : admin_url( 'post.php?post=' . $post_id . '&action=edit' ); } } return $rows; } /** * @param array $row Database row. * @return array */ private function enrich_item( $row ) { $items = $this->enrich_items( array( $row ) ); return $items[0]; } public function register_routes() { $namespace = 'devnotes/v1'; register_rest_route( $namespace, '/items', array( array( 'methods' => WP_REST_Server::READABLE, 'callback' => array( $this, 'get_items' ), 'permission_callback' => array( $this, 'check_permission' ), 'args' => array( 'item_type' => array( 'type' => 'string', 'description' => 'Filter by item type', 'enum' => array( 'note', 'task' ), ), 'status' => array( 'type' => 'string', 'description' => 'Filter by status', 'enum' => array( 'active', 'archived', 'finished' ), ), 'limit' => array( 'type' => 'integer', 'description' => 'Number of items to return (max 500)', 'default' => 100, 'minimum' => 1, 'maximum' => 500, ), 'offset' => array( 'type' => 'integer', 'description' => 'Number of items to skip', 'default' => 0, 'minimum' => 0, 'maximum' => 100000, ), 'search' => array( 'type' => 'string', 'description' => 'Search titles and content', ), 'post_id' => array( 'type' => 'integer', 'description' => 'Only items linked to this post', 'minimum' => 1, ), 'assigned_to' => array( 'type' => 'integer', 'description' => 'Only items assigned to this user', 'minimum' => 1, ), 'unassigned' => array( 'type' => 'boolean', 'description' => 'Only items with no assignee', ), 'pinned' => array( 'type' => 'integer', 'description' => '1 for pinned items, 0 for unpinned items', ), ), ), array( 'methods' => WP_REST_Server::CREATABLE, 'callback' => array( $this, 'create_item' ), 'permission_callback' => array( $this, 'check_permission' ), 'args' => array( 'item_type' => array( 'type' => 'string', 'required' => true, 'description' => 'Type of item (note or task)', 'enum' => array( 'note', 'task' ), ), 'title' => array( 'type' => 'string', 'required' => true, 'description' => 'Title of the item', ), 'content' => array( 'type' => 'string', 'description' => 'Content of the item', ), 'status' => array( 'type' => 'string', 'description' => 'Status of the item', 'enum' => array( 'active', 'archived', 'finished' ), ), 'due_date' => array( 'type' => 'string', 'description' => 'Due date in Y-m-d or Y-m-d H:i:s format', ), 'assigned_to' => array( 'type' => array( 'integer', 'null' ), 'description' => 'User ID to assign the item to', ), 'post_id' => array( 'type' => array( 'integer', 'null' ), 'description' => 'Post ID this item is linked to', ), 'context_url' => array( 'type' => 'string', 'description' => 'Admin or front-end URL where the item was created', ), 'pinned' => array( 'type' => 'integer', 'description' => '1 to pin the item to the top of the list', ), ), ), ) ); register_rest_route( $namespace, '/items/(?P\d+)', array( array( 'methods' => WP_REST_Server::EDITABLE, 'callback' => array( $this, 'update_item' ), 'permission_callback' => array( $this, 'check_permission' ), 'args' => array( 'id' => array( 'type' => 'integer', 'description' => 'ID of the item', ), 'title' => array( 'type' => 'string', 'description' => 'Title of the item', ), 'content' => array( 'type' => 'string', 'description' => 'Content of the item', ), 'status' => array( 'type' => 'string', 'description' => 'Status of the item', 'enum' => array( 'active', 'archived', 'finished' ), ), 'due_date' => array( 'type' => 'string', 'description' => 'Due date in Y-m-d or Y-m-d H:i:s format', ), 'assigned_to' => array( 'type' => array( 'integer', 'null' ), 'description' => 'User ID to assign the item to', ), 'post_id' => array( 'type' => array( 'integer', 'null' ), 'description' => 'Post ID this item is linked to', ), 'context_url' => array( 'type' => 'string', 'description' => 'Admin or front-end URL where the item was created', ), 'pinned' => array( 'type' => 'integer', 'description' => '1 to pin the item to the top of the list', ), ), ), array( 'methods' => WP_REST_Server::DELETABLE, 'callback' => array( $this, 'delete_item' ), 'permission_callback' => array( $this, 'check_permission' ), 'args' => array( 'id' => array( 'type' => 'integer', 'description' => 'ID of the item to delete', ), ), ), ) ); } public function check_permission() { if ( ! current_user_can( 'manage_options' ) ) { return new WP_Error( 'rest_forbidden', __( 'You do not have permission to access this resource.', 'devnotes' ), array( 'status' => 403 ) ); } return true; } public function get_items( $request ) { global $wpdb; $valid_item_types = array( 'note', 'task' ); $valid_statuses = array( 'active', 'archived', 'finished' ); $item_type = $request->get_param( 'item_type' ); $status = $request->get_param( 'status' ); $limit = $request->get_param( 'limit' ) ? intval( $request->get_param( 'limit' ) ) : 100; $limit = min( max( $limit, 1 ), 500 ); $offset = absint( $request->get_param( 'offset' ) ); $search = $request->get_param( 'search' ); $search = is_string( $search ) ? sanitize_text_field( $search ) : ''; if ( function_exists( 'mb_substr' ) ) { $search = mb_substr( $search, 0, 200 ); } else { $search = substr( $search, 0, 200 ); } if ( ! empty( $item_type ) && ! in_array( $item_type, $valid_item_types, true ) ) { return new WP_Error( 'invalid_item_type', __( 'Invalid item_type.', 'devnotes' ), array( 'status' => 400 ) ); } if ( ! empty( $status ) && ! in_array( $status, $valid_statuses, true ) ) { return new WP_Error( 'invalid_status', __( 'Invalid status.', 'devnotes' ), array( 'status' => 400 ) ); } $filter_type = ! empty( $item_type ) ? 1 : 0; $type_value = is_string( $item_type ) ? $item_type : ''; $filter_status = ! empty( $status ) ? 1 : 0; $status_value = is_string( $status ) ? $status : ''; $filter_search = '' !== $search ? 1 : 0; $like = '%' . $wpdb->esc_like( $search ) . '%'; $post_id = absint( $request->get_param( 'post_id' ) ); $filter_post = $post_id > 0 ? 1 : 0; $assignee_mode = 0; $assignee_id = 0; if ( rest_sanitize_boolean( $request->get_param( 'unassigned' ) ) ) { $assignee_mode = 1; } elseif ( absint( $request->get_param( 'assigned_to' ) ) > 0 ) { $assignee_mode = 2; $assignee_id = absint( $request->get_param( 'assigned_to' ) ); } $pinned_param = $request->get_param( 'pinned' ); $filter_pinned = ( null !== $pinned_param && '' !== $pinned_param ) ? 1 : 0; $pinned = $filter_pinned ? DevNotes_DB::sanitize_pinned( $pinned_param ) : 0; // Unused filters stay in the statement and are turned off with a placeholder, so the SQL text is fixed. $order_by_due = ( 'task' === $item_type && ( empty( $status ) || 'active' === $status ) ); // phpcs:disable WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching if ( $order_by_due ) { $results = $wpdb->get_results( $wpdb->prepare( 'SELECT * FROM %i WHERE ( %d = 0 OR item_type = %s ) AND ( %d = 0 OR status = %s ) AND ( %d = 0 OR title LIKE %s OR content LIKE %s ) AND ( %d = 0 OR post_id = %d ) AND ( %d = 0 OR ( %d = 1 AND assigned_to IS NULL ) OR ( %d = 2 AND assigned_to = %d ) ) AND ( %d = 0 OR pinned = %d ) ORDER BY pinned DESC, (due_date IS NULL) ASC, due_date ASC, id ASC LIMIT %d OFFSET %d', DevNotes_DB::get_table_name(), $filter_type, $type_value, $filter_status, $status_value, $filter_search, $like, $like, $filter_post, $post_id, $assignee_mode, $assignee_mode, $assignee_mode, $assignee_id, $filter_pinned, $pinned, $limit, $offset ), ARRAY_A ); } else { $results = $wpdb->get_results( $wpdb->prepare( 'SELECT * FROM %i WHERE ( %d = 0 OR item_type = %s ) AND ( %d = 0 OR status = %s ) AND ( %d = 0 OR title LIKE %s OR content LIKE %s ) AND ( %d = 0 OR post_id = %d ) AND ( %d = 0 OR ( %d = 1 AND assigned_to IS NULL ) OR ( %d = 2 AND assigned_to = %d ) ) AND ( %d = 0 OR pinned = %d ) ORDER BY pinned DESC, created_at DESC, id DESC LIMIT %d OFFSET %d', DevNotes_DB::get_table_name(), $filter_type, $type_value, $filter_status, $status_value, $filter_search, $like, $like, $filter_post, $post_id, $assignee_mode, $assignee_mode, $assignee_mode, $assignee_id, $filter_pinned, $pinned, $limit, $offset ), ARRAY_A ); } // phpcs:enable if ( null === $results && ! empty( $wpdb->last_error ) ) { return new WP_Error( 'db_error', __( 'Could not retrieve items.', 'devnotes' ), array( 'status' => 500 ) ); } $results = is_array( $results ) ? $results : array(); $results = $this->enrich_items( $results ); $response = rest_ensure_response( $results ); $response->header( 'Cache-Control', 'no-cache, must-revalidate, max-age=0' ); return $response; } public function create_item( $request ) { global $wpdb; $valid_item_types = array( 'note', 'task' ); $valid_statuses = array( 'active', 'archived', 'finished' ); $item_type = sanitize_text_field( $request->get_param( 'item_type' ) ); if ( empty( $item_type ) ) { return new WP_Error( 'invalid_item_type', __( 'item_type is required and must be either note or task.', 'devnotes' ), array( 'status' => 400 ) ); } if ( ! in_array( $item_type, $valid_item_types, true ) ) { return new WP_Error( 'invalid_item_type', __( 'Invalid item_type. Must be note or task.', 'devnotes' ), array( 'status' => 400 ) ); } $status_param = $request->get_param( 'status' ); $status = $status_param ? sanitize_text_field( $status_param ) : 'active'; if ( ! in_array( $status, $valid_statuses, true ) ) { return new WP_Error( 'invalid_status', __( 'Invalid status. Must be active, archived, or finished.', 'devnotes' ), array( 'status' => 400 ) ); } $title = sanitize_text_field( $request->get_param( 'title' ) ); if ( empty( $title ) ) { return new WP_Error( 'invalid_title', __( 'Title is required and cannot be empty.', 'devnotes' ), array( 'status' => 400 ) ); } $due_date_raw = $request->get_param( 'due_date' ); if ( ! empty( $due_date_raw ) && ! $this->is_valid_date_value( $due_date_raw ) ) { return new WP_Error( 'invalid_due_date', __( 'due_date must be a real date in Y-m-d or Y-m-d H:i:s format.', 'devnotes' ), array( 'status' => 400 ) ); } $assigned_to = $this->sanitize_assignee( $request->get_param( 'assigned_to' ) ); if ( is_wp_error( $assigned_to ) ) { return $assigned_to; } $post_id = DevNotes_DB::sanitize_post_id( $request->get_param( 'post_id' ) ); if ( is_wp_error( $post_id ) ) { return $post_id; } $data = array( 'item_type' => $item_type, 'title' => $title, 'content' => sanitize_textarea_field( $request->get_param( 'content' ) ), 'status' => $status, 'due_date' => sanitize_text_field( $request->get_param( 'due_date' ) ), 'assigned_to' => $assigned_to, 'post_id' => $post_id, 'context_url' => DevNotes_DB::sanitize_context_url( $request->get_param( 'context_url' ) ), 'pinned' => DevNotes_DB::sanitize_pinned( $request->get_param( 'pinned' ) ), 'finished_date' => ( 'finished' === $status ) ? current_time( 'mysql' ) : null, 'created_at' => current_time( 'mysql' ), 'updated_at' => current_time( 'mysql' ), ); // Ensure due_date is null if empty. if ( empty( $data['due_date'] ) ) { $data['due_date'] = null; } $inserted = $wpdb->insert( DevNotes_DB::get_table_name(), $data ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery -- write operation, caching not applicable if ( ! $inserted ) { return new WP_Error( 'db_error', __( 'Could not insert item.', 'devnotes' ), array( 'status' => 500 ) ); } $data['id'] = $wpdb->insert_id; $this->maybe_notify_assignee( $data, 0 ); return rest_ensure_response( $this->enrich_item( $data ) ); } public function update_item( $request ) { global $wpdb; $table = DevNotes_DB::get_table_name(); $id = intval( $request->get_param( 'id' ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- read the current row before an update so assignment changes can be detected $existing = $wpdb->get_row( $wpdb->prepare( 'SELECT * FROM %i WHERE id = %d', $table, $id ), ARRAY_A ); if ( ! is_array( $existing ) ) { return new WP_Error( 'not_found', __( 'Item not found.', 'devnotes' ), array( 'status' => 404 ) ); } $previous_assignee = ! empty( $existing['assigned_to'] ) ? (int) $existing['assigned_to'] : 0; $data = array( 'updated_at' => current_time( 'mysql' ), ); if ( $request->has_param( 'title' ) ) { $title_update = sanitize_text_field( $request->get_param( 'title' ) ); if ( empty( $title_update ) ) { return new WP_Error( 'invalid_title', __( 'Title is required and cannot be empty.', 'devnotes' ), array( 'status' => 400 ) ); } $data['title'] = $title_update; } if ( $request->has_param( 'content' ) ) { $data['content'] = sanitize_textarea_field( $request->get_param( 'content' ) ); } if ( $request->has_param( 'status' ) ) { $new_status = sanitize_text_field( $request->get_param( 'status' ) ); $valid_statuses = array( 'active', 'archived', 'finished' ); if ( ! in_array( $new_status, $valid_statuses, true ) ) { return new WP_Error( 'invalid_status', __( 'Invalid status. Must be active, archived, or finished.', 'devnotes' ), array( 'status' => 400 ) ); } $data['status'] = $new_status; if ( 'finished' === $data['status'] ) { $data['finished_date'] = current_time( 'mysql' ); } elseif ( 'active' === $data['status'] ) { $data['finished_date'] = null; } } if ( $request->has_param( 'due_date' ) ) { $due_date = $request->get_param( 'due_date' ); if ( ! empty( $due_date ) ) { if ( ! $this->is_valid_date_value( $due_date ) ) { return new WP_Error( 'invalid_due_date', __( 'due_date must be a real date in Y-m-d or Y-m-d H:i:s format.', 'devnotes' ), array( 'status' => 400 ) ); } $data['due_date'] = sanitize_text_field( $due_date ); } else { $data['due_date'] = null; } } if ( $request->has_param( 'assigned_to' ) ) { $assigned_to = $this->sanitize_assignee( $request->get_param( 'assigned_to' ) ); if ( is_wp_error( $assigned_to ) ) { return $assigned_to; } $data['assigned_to'] = $assigned_to; } if ( $request->has_param( 'post_id' ) ) { $post_id = DevNotes_DB::sanitize_post_id( $request->get_param( 'post_id' ) ); if ( is_wp_error( $post_id ) ) { return $post_id; } $data['post_id'] = $post_id; } if ( $request->has_param( 'context_url' ) ) { $data['context_url'] = DevNotes_DB::sanitize_context_url( $request->get_param( 'context_url' ) ); } if ( $request->has_param( 'pinned' ) ) { $data['pinned'] = DevNotes_DB::sanitize_pinned( $request->get_param( 'pinned' ) ); } $updated = $wpdb->update( $table, $data, array( 'id' => $id ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- write operation, caching not applicable if ( false === $updated ) { return new WP_Error( 'db_error', __( 'Could not update item.', 'devnotes' ), array( 'status' => 500 ) ); } $item = $wpdb->get_row( $wpdb->prepare( 'SELECT * FROM %i WHERE id = %d', $table, $id ), ARRAY_A ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- fetches freshly updated row immediately after write if ( ! is_array( $item ) ) { return new WP_Error( 'not_found', __( 'Item not found.', 'devnotes' ), array( 'status' => 404 ) ); } $this->maybe_notify_assignee( $item, $previous_assignee ); return rest_ensure_response( $this->enrich_item( $item ) ); } public function delete_item( $request ) { global $wpdb; $table = DevNotes_DB::get_table_name(); $id = intval( $request->get_param( 'id' ) ); $deleted = $wpdb->delete( $table, array( 'id' => $id ) ); // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching -- write operation, caching not applicable if ( false === $deleted ) { return new WP_Error( 'db_error', __( 'Could not delete item.', 'devnotes' ), array( 'status' => 500 ) ); } if ( 0 === $deleted ) { return new WP_Error( 'not_found', __( 'Item not found.', 'devnotes' ), array( 'status' => 404 ) ); } return rest_ensure_response( array( 'deleted' => true ) ); } }