sureforms / inc / abilities / entries / list-entries.php

list-entries.php in SureForms – Contact Form Builder, AI Forms, Payment Form, Survey & Quiz 2.12.8, at inc/abilities/entries/list-entries.php

200 lines 6.2 KB

Raw Download Zip

1	<?php
2	/**
3	* List Entries Ability.
4	*
5	* @package sureforms
6	* @since 2.5.2
7	*/
8
9	namespace SRFM\Inc\Abilities\Entries;
10
11	use SRFM\Inc\Abilities\Abstract_Ability;
12	use SRFM\Inc\Entries;
13	use SRFM\Inc\Helper;
14
15	if ( ! defined( 'ABSPATH' ) ) {
16	exit; // Exit if accessed directly.
17	}
18
19	/**
20	* List_Entries ability class.
21	*
22	* Lists form submission entries with filtering, sorting, and pagination.
23	*
24	* @since 2.5.2
25	*/
26	class List_Entries extends Abstract_Ability {
27	/**
28	* Constructor.
29	*
30	* @since 2.5.2
31	*/
32	public function __construct() {
33	$this->id = 'sureforms/list-entries';
34	$this->label = __( 'List Form Entries', 'sureforms' );
35	$this->description = __( 'List SureForms form submission entries with optional filtering by form, status, date range, and search. Supports pagination and sorting.', 'sureforms' );
36	$this->capability = 'manage_options';
37	}
38
39	/**
40	* {@inheritDoc}
41	*
42	* @since 2.5.2
43	*/
44	public function get_annotations() {
45	return [
46	'readonly' => true,
47	'destructive' => false,
48	'idempotent' => true,
49	'priority' => 1.0,
50	'openWorldHint' => false,
51	];
52	}
53
54	/**
55	* {@inheritDoc}
56	*
57	* @since 2.5.2
58	*/
59	public function get_input_schema() {
60	return [
61	'type' => 'object',
62	'additionalProperties' => false,
63	'properties' => [
64	'form_id' => [
65	'type' => 'integer',
66	'description' => __( 'Filter entries by form ID. Use 0 or omit for all forms.', 'sureforms' ),
67	'default' => 0,
68	],
69	'status' => [
70	'type' => 'string',
71	'description' => __( 'Filter entries by status.', 'sureforms' ),
72	'enum' => [ 'all', 'read', 'unread', 'trash' ],
73	'default' => 'all',
74	],
75	'search' => [
76	'type' => 'string',
77	'description' => __( 'Search entries by entry ID, form title, or submitted form data. Text search requires at least 3 characters; numeric terms match the entry ID exactly.', 'sureforms' ),
78	],
79	'date_from' => [
80	'type' => 'string',
81	'description' => __( 'Start date for filtering entries (YYYY-MM-DD format).', 'sureforms' ),
82	],
83	'date_to' => [
84	'type' => 'string',
85	'description' => __( 'End date for filtering entries (YYYY-MM-DD format).', 'sureforms' ),
86	],
87	'per_page' => [
88	'type' => 'integer',
89	'description' => __( 'Number of entries per page (1-100).', 'sureforms' ),
90	'default' => 20,
91	],
92	'page' => [
93	'type' => 'integer',
94	'description' => __( 'Page number for pagination.', 'sureforms' ),
95	'default' => 1,
96	],
97	'orderby' => [
98	'type' => 'string',
99	'description' => __( 'Column to order results by.', 'sureforms' ),
100	'enum' => [ 'created_at', 'ID', 'id', 'form_id', 'status' ],
101	'default' => 'created_at',
102	],
103	'order' => [
104	'type' => 'string',
105	'description' => __( 'Sort direction.', 'sureforms' ),
106	'enum' => [ 'ASC', 'DESC' ],
107	'default' => 'DESC',
108	],
109	],
110	];
111	}
112
113	/**
114	* {@inheritDoc}
115	*
116	* @since 2.5.2
117	*/
118	public function get_output_schema() {
119	return [
120	'type' => 'object',
121	'properties' => [
122	'entries' => [
123	'type' => 'array',
124	'items' => [
125	'type' => 'object',
126	'properties' => [
127	'id' => [ 'type' => 'integer' ],
128	'form_id' => [ 'type' => 'integer' ],
129	'form_title' => [ 'type' => 'string' ],
130	'status' => [ 'type' => 'string' ],
131	'created_at' => [ 'type' => 'string' ],
132	],
133	],
134	],
135	'total' => [ 'type' => 'integer' ],
136	'total_pages' => [ 'type' => 'integer' ],
137	'current_page' => [ 'type' => 'integer' ],
138	'per_page' => [ 'type' => 'integer' ],
139	],
140	];
141	}
142
143	/**
144	* Execute the list-entries ability.
145	*
146	* @param array<string,mixed> $input Validated input data.
147	* @since 2.5.2
148	* @return array<string,mixed>\|\WP_Error
149	*/
150	public function execute( $input ) {
151	$per_page = isset( $input['per_page'] ) ? Helper::get_integer_value( $input['per_page'] ) : 20;
152	$per_page = max( 1, min( 100, $per_page ) );
153
154	$args = [
155	'form_id' => Helper::get_integer_value( $input['form_id'] ?? 0 ),
156	'status' => ! empty( $input['status'] ) ? sanitize_text_field( Helper::get_string_value( $input['status'] ) ) : 'all',
157	// isset(), not ! empty(): a literal "0" search is a valid term and must not be
158	// dropped (which would return every entry). Mirrors the REST path.
159	'search' => isset( $input['search'] ) ? sanitize_text_field( Helper::get_string_value( $input['search'] ) ) : '',
160	'date_from' => ! empty( $input['date_from'] ) ? sanitize_text_field( Helper::get_string_value( $input['date_from'] ) ) : '',
161	'date_to' => ! empty( $input['date_to'] ) ? sanitize_text_field( Helper::get_string_value( $input['date_to'] ) ) : '',
162	'per_page' => $per_page,
163	'page' => isset( $input['page'] ) ? Helper::get_integer_value( $input['page'] ) : 1,
164	'orderby' => ! empty( $input['orderby'] ) ? sanitize_text_field( Helper::get_string_value( $input['orderby'] ) ) : 'created_at',
165	'order' => ! empty( $input['order'] ) ? sanitize_text_field( Helper::get_string_value( $input['order'] ) ) : 'DESC',
166	];
167
168	$result = Entries::get_entries( $args );
169
170	// Enrich entries with form title and strip heavyweight form_data.
171	$entries = [];
172	if ( ! empty( $result['entries'] ) && is_array( $result['entries'] ) ) {
173	foreach ( $result['entries'] as $entry ) {
174	if ( ! is_array( $entry ) ) {
175	continue;
176	}
177
178	$form_id = absint( $entry['form_id'] ?? 0 );
179	$form_title = $form_id > 0 ? get_the_title( $form_id ) : '';
180
181	$entries[] = [
182	'id' => absint( $entry['ID'] ?? 0 ),
183	'form_id' => $form_id,
184	'form_title' => $form_title,
185	'status' => $entry['status'] ?? '',
186	'created_at' => $entry['created_at'] ?? '',
187	];
188	}
189	}
190
191	return [
192	'entries' => $entries,
193	'total' => Helper::get_integer_value( $result['total'] ?? 0 ),
194	'total_pages' => Helper::get_integer_value( $result['total_pages'] ?? 0 ),
195	'current_page' => Helper::get_integer_value( $result['current_page'] ?? 1 ),
196	'per_page' => Helper::get_integer_value( $result['per_page'] ?? $per_page ),
197	];
198	}
199	}
200