charitable / includes / abstracts / abstract-class-charitable-query.php

abstract-class-charitable-query.php in Charitable – Donation & Fundraising Platform (Donation Forms, Recurring Donations & Fundraising Campaigns) 1.7.0.5, at includes/abstracts/abstract-class-charitable-query.php

1,015 lines 22.2 KB

Raw Download Zip

1	<?php
2	/**
3	* An abstract base class defining common methods used by Charitable queries.
4	*
5	* @package Charitable/Classes/Charitable_Query
6	* @author David Bisset
7	* @copyright Copyright (c) 2022, WP Charitable LLC
8	* @license http://opensource.org/licenses/gpl-2.0.php GNU Public License
9	* @since 1.0.0
10	* @version 1.6.8
11	*/
12
13	// Exit if accessed directly.
14	if ( ! defined( 'ABSPATH' ) ) {
15	exit;
16	}
17
18	if ( ! class_exists( 'Charitable_Query' ) ) :
19
20	/**
21	* Charitable_Query
22	*
23	* @since 1.0.0
24	*/
25	abstract class Charitable_Query implements Iterator {
26
27	/**
28	* User-defined arguments.
29	*
30	* @var array
31	*/
32	protected $args;
33
34	/**
35	* Internal iterator position.
36	*
37	* @var int
38	*/
39	protected $position = 0;
40
41	/**
42	* The raw query results.
43	*
44	* @var array
45	*/
46	protected $query;
47
48	/**
49	* Number of items found.
50	*
51	* @var int\|null
52	*/
53	protected $found_items;
54
55	/**
56	* Result set.
57	*
58	* @var array
59	*/
60	protected $results;
61
62	/**
63	* Parameters to pass to the query.
64	*
65	* @var mixed[]
66	*/
67	protected $parameters = array();
68
69	/**
70	* Meta SQL query.
71	*
72	* @since 1.6.5
73	*
74	* @var array\|false
75	*/
76	protected $meta_sql;
77
78	/**
79	* Return the query argument value for the given key.
80	*
81	* @since 1.0.0
82	*
83	* @param string $key The key of the argument.
84	* @param mixed $fallback Default value to fall back to.
85	* @return mixed\|false Returns fallback if the argument is not found.
86	*/
87	public function get( $key, $fallback = false ) {
88	return isset( $this->args[ $key ] ) ? $this->args[ $key ] : $fallback;
89	}
90
91	/**
92	* Set the query argument for the given key.
93	*
94	* @since 1.0.0
95	*
96	* @param string $key Key of argument to set.
97	* @param mixed $value Value to be set.
98	* @return void
99	*/
100	public function set( $key, $value ) {
101	$this->args[ $key ] = apply_filters( 'charitable_query_sanitize_argument_' . $key, $value, $this );
102	}
103
104	/**
105	* Remove the given query argument.
106	*
107	* @since 1.0.0
108	*
109	* @param string $key Key of argument to remove.
110	* @return void
111	*/
112	public function remove( $key ) {
113	unset( $this->args[ $key ] );
114	}
115
116	/**
117	* Return the results of the query.
118	*
119	* @global WPDB $wpdb
120	*
121	* @since 1.6.8
122	*
123	* @return object[]
124	*/
125	public function get_query() {
126	if ( ! isset( $this->query ) ) {
127	/**
128	* Fires right before the query is executed.
129	*
130	* @since 1.0.0
131	*
132	* @param Charitable_Query The `Charitable_Query` instance.
133	*/
134	do_action( 'charitable_pre_query', $this );
135
136	$this->query = $this->run_query( $this->get( 'output' ) );
137	$this->found_items = $this->get_found_items();
138
139	/**
140	* Fires right after the query is executed.
141	*
142	* @since 1.0.0
143	*
144	* @param Charitable_Query The `Charitable_Query` instance.
145	*/
146	do_action( 'charitable_post_query', $this );
147
148	}//end if
149
150	return $this->query;
151	}
152
153	/**
154	* Return the results.
155	*
156	* @since 1.6.8
157	*
158	* @return object[]
159	*/
160	public function get_results() {
161	return $this->results;
162	}
163
164	/**
165	* Return the results of the query.
166	*
167	* @global WPDB $wpdb
168	*
169	* @since 1.0.0
170	*
171	* @return object[]
172	*/
173	public function query() {
174	return $this->get_query();
175	}
176
177	/**
178	* Run query, returning the results.
179	*
180	* @global WPDB $wpdb
181	*
182	* @since 1.5.0
183	*
184	* @param string $output The output type.
185	* @return array
186	*/
187	public function run_query( $output ) {
188	if ( method_exists( $this, 'run_query_' . $output ) ) {
189	return call_user_func( array( $this, 'run_query_' . $output ) );
190	}
191
192	global $wpdb;
193
194	$sql = "SELECT {$this->fields()} {$this->from()} {$this->join()} {$this->where()} {$this->groupby()} {$this->orderby()} {$this->order()} {$this->limit()} {$this->offset()};";
195
196	return $wpdb->get_results( $this->get_prepared_sql( $sql ) );
197	}
198
199	/**
200	* Run count query, returning the results.
201	*
202	* @global WPDB $wpdb
203	*
204	* @since 1.5.0
205	*
206	* @return array
207	*/
208	public function run_query_count() {
209	global $wpdb;
210
211	$sql = "SELECT {$this->select_count()} {$this->from()} {$this->join()} {$this->where()};";
212
213	return array( $wpdb->get_var( $this->get_prepared_sql( $sql ) ) );
214	}
215
216	/**
217	* Prepare a query with any passed parameters.
218	*
219	* @global WPDB $wpdb
220	*
221	* @since 1.5.0
222	*
223	* @param string $sql The SQL query with placeholders.
224	* @return string
225	*/
226	public function get_prepared_sql( $sql ) {
227	global $wpdb;
228
229	if ( empty( $this->parameters ) ) {
230	return $sql;
231	}
232
233	return $wpdb->prepare( $sql, $this->parameters );
234	}
235
236	/**
237	* After a query has been executed, check how many found rows there are.
238	*
239	* @global WPDB $wpdb
240	*
241	* @since 1.5.0
242	*
243	* @return int
244	*/
245	public function get_found_items() {
246	global $wpdb;
247
248	if ( empty( $this->query ) ) {
249	return 0;
250	}
251
252	if ( 'count' == $this->get( 'output' ) ) {
253	return current( $this->query );
254	}
255
256	if ( $this->show_all() ) {
257	return count( $this->query );
258	}
259
260	/**
261	* Filters the query used to retrieve the query result count.
262	*
263	* @since 1.5.0
264	*
265	* @param string $found_customers_query SQL query. Default 'SELECT FOUND_ROWS()'.
266	* @param Charitable_Query $query The `Charitable_Query` instance.
267	*/
268	$found_items_query = apply_filters( 'charitable_found_items_query', 'SELECT FOUND_ROWS()', $this );
269
270	return (int) $wpdb->get_var( $found_items_query );
271	}
272
273	/**
274	* Return the count query right after the SELECT part of the query.
275	*
276	* This is used instead of Charitable_Query::fields and is only appropriate
277	* when all you want to do with a query is get the number of something.
278	*
279	* @global WPBD $wpdb
280	*
281	* @since 1.5.0
282	*
283	* @return string
284	*/
285	public function select_count() {
286	global $wpdb;
287
288	/**
289	* Filter the `SELECT COUNT` statement.
290	*
291	* @since 1.5.0
292	*
293	* @param string $sql The `SELECT COUNT` statement.
294	* @param Charitable_Query $query The `Charitable_Query` instance.
295	*/
296	return apply_filters( 'charitable_select_count_fields', "COUNT(DISTINCT {$wpdb->posts}.ID)", $this );
297	}
298
299	/**
300	* Return the fields right after the SELECT part of the query.
301	*
302	* @global WPBD $wpdb
303	*
304	* @since 1.0.0
305	*
306	* @return string
307	*/
308	public function fields() {
309	global $wpdb;
310
311	$found_rows = $this->show_all() ? '' : 'SQL_CALC_FOUND_ROWS';
312
313	/**
314	* Filter the `SELECT` statement.
315	*
316	* @since 1.0.0
317	*
318	* @param string $sql The `SELECT` statement.
319	* @param Charitable_Query $query The `Charitable_Query` instance.
320	*/
321	return apply_filters( 'charitable_query_fields', "$found_rows {$wpdb->posts}.ID", $this );
322	}
323
324	/**
325	* Return the FROM part of the query.
326	*
327	* @global WPBD $wpdb
328	*
329	* @since 1.0.0
330	*
331	* @return string
332	*/
333	public function from() {
334	global $wpdb;
335
336	/**
337	* Filter the `FROM` statement.
338	*
339	* @since 1.0.0
340	*
341	* @param string $sql The `FROM` statement.
342	* @param Charitable_Query $query The `Charitable_Query` instance.
343	*/
344	return apply_filters( 'charitable_query_from', "FROM $wpdb->posts", $this );
345	}
346
347	/**
348	* Return the JOIN part of the query.
349	*
350	* @since 1.0.0
351	*
352	* @return string
353	*/
354	public function join() {
355	/**
356	* Filter the `JOIN` statement.
357	*
358	* @since 1.0.0
359	*
360	* @param string $sql The `JOIN` statement. Empty by default.
361	* @param Charitable_Query $query The `Charitable_Query` instance.
362	*/
363	return apply_filters( 'charitable_query_join', '', $this );
364	}
365
366	/**
367	* Return the WHERE part of the query.
368	*
369	* @since 1.0.0
370	*
371	* @return string
372	*/
373	public function where() {
374	/**
375	* Filter the `WHERE` statement.
376	*
377	* @since 1.0.0
378	*
379	* @param string $sql The `WHERE` statement.
380	* @param Charitable_Query $query This query object.
381	*/
382	return apply_filters( 'charitable_query_where', 'WHERE 1=1 ', $this );
383	}
384
385	/**
386	* Return the GROUPBY part of the query.
387	*
388	* @since 1.0.0
389	*
390	* @return string
391	*/
392	public function groupby() {
393	/**
394	* Filter the `GROUP BY` statement.
395	*
396	* @since 1.0.0
397	*
398	* @param string $sql The `GROUP BY` statement. Empty by default.
399	* @param Charitable_Query $query This query object.
400	*/
401	return apply_filters( 'charitable_query_groupby', '', $this );
402	}
403
404	/**
405	* Return the ORDER BY part of the query.
406	*
407	* @global WPBD $wpdb
408	*
409	* @since 1.0.0
410	*
411	* @return string
412	*/
413	public function orderby() {
414	global $wpdb;
415
416	/**
417	* Filter the `ORDER BY` statement.
418	*
419	* @since 1.0.0
420	*
421	* @param string $sql The `ORDER BY` statement.
422	* @param Charitable_Query $query The `Charitable_Query` instance.
423	*/
424	return apply_filters( 'charitable_query_orderby', "ORDER BY {$wpdb->posts}.ID", $this );
425	}
426
427	/**
428	* Return the ORDER part of the query.
429	*
430	* @since 1.0.0
431	*
432	* @return string
433	*/
434	public function order() {
435	/**
436	* Filter the `ORDER` statement.
437	*
438	* @since 1.0.0
439	*
440	* @param string $sql The `ORDER` statement. DESC by default.
441	* @param Charitable_Query $query The `Charitable_Query` instance.
442	*/
443	return apply_filters( 'charitable_query_order', $this->get( 'order', 'DESC' ), $this );
444	}
445
446	/**
447	* Return the LIMIT part of the query.
448	*
449	* @since 1.0.0
450	*
451	* @return string
452	*/
453	public function limit() {
454	if ( $this->show_all() ) {
455	return '';
456	}
457
458	/**
459	* Filter the `LIMIT` statement.
460	*
461	* @since 1.0.0
462	*
463	* @param string $sql The `LIMIT` statement.
464	* @param Charitable_Query $query The `Charitable_Query` instance.
465	*/
466	return apply_filters( 'charitable_query_limit', sprintf( 'LIMIT %d', $this->get( 'number', 20 ) ), $this );
467	}
468
469	/**
470	* Return the OFFSET part of the query.
471	*
472	* @since 1.0.0
473	*
474	* @return string
475	*/
476	public function offset() {
477	if ( $this->show_all() ) {
478	return '';
479	}
480
481	$offset = $this->get( 'number' ) * ( $this->get( 'paged', 1 ) - 1 );
482
483	/**
484	* Filter the `OFFSET` statement.
485	*
486	* @since 1.0.0
487	*
488	* @param string $sql The `OFFSET` statement.
489	* @param Charitable_Query $query The `Charitable_Query` instance.
490	*/
491	return apply_filters( 'charitable_query_offset', sprintf( 'OFFSET %d', $offset ), $this );
492	}
493
494	/**
495	* Select donor-specific fields.
496	*
497	* @since 1.0.0
498	*
499	* @param string $select_statement The default select statement.
500	* @return string
501	*/
502	public function donor_fields( $select_statement ) {
503	return $select_statement . ', d.donor_id, d.user_id, d.first_name, d.last_name, d.email, d.date_joined';
504	}
505
506	/**
507	* Retrieve the donation ID and campaigns.
508	*
509	* @since 1.0.0
510	*
511	* @param string $select_statement The default select statement.
512	* @return string
513	*/
514	public function donation_fields( $select_statement ) {
515	return $select_statement . ", cd.donation_id, GROUP_CONCAT(cd.campaign_name SEPARATOR ', ') AS campaigns, GROUP_CONCAT(cd.campaign_id SEPARATOR ',') AS campaign_ids, cd.donor_id";
516	}
517
518	/**
519	* Select donation-specific fields.
520	*
521	* @since 1.0.0
522	*
523	* @param string $select_statement The default select statement.
524	* @return string
525	*/
526	public function donation_calc_fields( $select_statement ) {
527	return $select_statement . ', COUNT(cd.campaign_donation_id) AS donations, SUM(cd.amount) AS amount';
528	}
529
530	/**
531	* Select total amount field.
532	*
533	* @since 1.2.0
534	*
535	* @param string $select_statement The default select statement.
536	* @return string
537	*/
538	public function donation_amount_sum_field( $select_statement ) {
539	return $select_statement . ', SUM(cd.amount) AS amount';
540	}
541
542	/**
543	* Return the SQL to be used for meta queries.
544	*
545	* @since 1.6.5
546	*
547	* @global WPDB $wpdb
548	*
549	* @return false\|array {
550	* Array containing JOIN and WHERE SQL clauses to append to the main query.
551	*
552	* @type string $join SQL fragment to append to the main JOIN clause.
553	* @type string $where SQL fragment to append to the main WHERE clause.
554	* }
555	*/
556	public function get_meta_sql() {
557	if ( ! isset( $this->meta_sql ) ) {
558	global $wpdb;
559
560	$meta_args = $this->get( 'meta_query' );
561
562	if ( empty( $meta_args ) ) {
563	return false;
564	}
565
566	$meta_query = new WP_Meta_Query( $meta_args );
567
568	$this->meta_sql = $meta_query->get_sql( 'post', $wpdb->posts, 'ID' );
569	}
570
571	return $this->meta_sql;
572	}
573
574	/**
575	* A helper function used to populate the query parameters ith an item and a return a string
576	* of placeholders that can be used in a MySQL `IN` statement.
577	*
578	* @since 1.5.0
579	*
580	* @param mixed $item The item.
581	* @param callable $filter_callback A callback to use to filter out invalid items.
582	* @param string $placeholder_type The type of placeholder to use. May be %s, %d or %f.
583	* @return string A string containing the correct number of placeholders.
584	*/
585	public function get_where_in_placeholders( $item, $filter_callback, $placeholder_type ) {
586	if ( ! is_array( $item ) ) {
587	$item = array( $item );
588	}
589
590	$item = array_filter( $item, $filter_callback );
591
592	$this->add_parameters( $item );
593
594	return $this->get_placeholders( count( $item ), $placeholder_type );
595	}
596
597	/**
598	* Filter query by donation_plan ID.
599	*
600	* @since 1.6.8
601	*
602	* @global WPBD $wpdb
603	* @param string $where_statement The default where statement.
604	* @return string
605	*/
606	public function where_donation_plan_is_in( $where_statement ) {
607	global $wpdb;
608
609	$donation_plan = $this->get( 'donation_plan', false );
610
611	if ( ! $donation_plan ) {
612	return $where_statement;
613	}
614
615	$placeholders = $this->get_where_in_placeholders( $donation_plan, 'charitable_validate_absint', '%d' );
616
617	return $where_statement . " AND {$wpdb->posts}.post_parent IN ({$placeholders})";
618	}
619
620	/**
621	* Filter query by campaign receiving the donation.
622	*
623	* @since 1.0.0
624	*
625	* @param string $where_statement The default where statement.
626	* @return string
627	*/
628	public function where_campaign_is_in( $where_statement ) {
629	$campaign = $this->get( 'campaign', 0 );
630
631	if ( ! $campaign ) {
632	return $where_statement;
633	}
634
635	$placeholders = $this->get_where_in_placeholders( $this->get( 'campaign', 0 ), 'charitable_validate_absint', '%d' );
636
637	return $where_statement . " AND cd.campaign_id IN ({$placeholders})";
638	}
639
640	/**
641	* Filter query by status of the post.
642	*
643	* @global WPBD $wpdb
644	*
645	* @since 1.0.0
646	*
647	* @param string $where_statement The default where statement.
648	* @return string
649	*/
650	public function where_status_is_in( $where_statement ) {
651	global $wpdb;
652
653	$status = $this->get( 'status', false );
654
655	if ( ! $status ) {
656	return $where_statement;
657	}
658
659	$placeholders = $this->get_where_in_placeholders( $status, 'charitable_is_valid_donation_status', '%s' );
660
661	return $where_statement . " AND {$wpdb->posts}.post_status IN ({$placeholders})";
662	}
663
664	/**
665	* Filter query by donor ID.
666	*
667	* @global WPBD $wpdb
668	* @since 1.0.0
669	*
670	* @param string $where_statement The default where statement.
671	* @return string
672	*/
673	public function where_donor_id_is_in( $where_statement ) {
674	$donor_id = $this->get( 'donor_id', false );
675
676	if ( ! $donor_id ) {
677	return $where_statement;
678	}
679
680	$placeholders = $this->get_where_in_placeholders( $donor_id, 'charitable_validate_absint', '%d' );
681
682	return $where_statement . " AND cd.donor_id IN ({$placeholders})";
683	}
684
685	/**
686	* Filter query by user ID.
687	*
688	* @since 1.5.0
689	*
690	* @global WPBD $wpdb
691	* @param string $where_statement The default where statement.
692	* @return string
693	*/
694	public function where_user_id_is_in( $where_statement ) {
695	global $wpdb;
696
697	$user_id = $this->get( 'user_id', false );
698
699	if ( ! $user_id ) {
700	return $where_statement;
701	}
702
703	$placeholders = $this->get_where_in_placeholders( $user_id, 'charitable_validate_absint', '%d' );
704
705	return $where_statement . " AND {$wpdb->posts}.post_author IN ({$placeholders})";
706	}
707
708	/**
709	* Filter a query by date.
710	*
711	* @uses WP_Date_Query
712	*
713	* @since 1.5.0
714	*
715	* @param string $where_statement The where query.
716	* @return string
717	*/
718	public function where_date( $where_statement ) {
719	$date_args = $this->get( 'date_query' );
720
721	if ( empty( $date_args ) ) {
722	return $where_statement;
723	}
724
725	$date_query = new WP_Date_Query( $date_args );
726
727	return $where_statement . $date_query->get_sql();
728	}
729
730	/**
731	* Filter a query by meta data.
732	*
733	* @uses WP_Meta_Query
734	*
735	* @since 1.6.5
736	*
737	* @param string $where_statement The where query.
738	* @return string
739	*/
740	public function where_meta( $where_statement ) {
741	$meta_sql = $this->get_meta_sql();
742
743	if ( ! $meta_sql \|\| empty( $meta_sql['where'] ) ) {
744	return $where_statement;
745	}
746
747	return $where_statement . $meta_sql['where'];
748	}
749
750	/**
751	* A method used to join the campaign donations table on the campaigns query.
752	*
753	* @global WPBD $wpdb
754	*
755	* @since 1.0.0
756	*
757	* @param string $join_statement The default join statement.
758	* @return string
759	*/
760	public function join_campaign_donations_table_on_campaign( $join_statement ) {
761	global $wpdb;
762	return $join_statement . " INNER JOIN {$wpdb->prefix}charitable_campaign_donations cd ON cd.campaign_id = $wpdb->posts.ID ";
763	}
764
765	/**
766	* Add one or more joins to the post meta table.
767	*
768	* @uses WP_Meta_Query
769	*
770	* @since 1.6.5
771	*
772	* @param string $join_statement The where query.
773	* @return string
774	*/
775	public function join_meta( $join_statement ) {
776	$meta_sql = $this->get_meta_sql();
777
778	if ( ! $meta_sql \|\| empty( $meta_sql['join'] ) ) {
779	return $join_statement;
780	}
781
782	return $join_statement . $meta_sql['join'];
783	}
784
785	/**
786	* A method used to join the campaign donations table on the campaigns query.
787	*
788	* @global WPBD $wpdb
789	*
790	* @since 1.0.0
791	*
792	* @param string $join_statement The default join statement.
793	* @return string
794	*/
795	public function join_campaign_donations_table_on_donation( $join_statement ) {
796	global $wpdb;
797	return $join_statement . " INNER JOIN {$wpdb->prefix}charitable_campaign_donations cd ON cd.donation_id = $wpdb->posts.ID ";
798	}
799
800	/**
801	* A method used to join the donors table on the query.
802	*
803	* @global WPBD $wpdb
804	* @since 1.5.0
805	*
806	* @param string $join_statement The default join statement.
807	* @return string
808	*/
809	public function join_post_meta_table_on_donation( $join_statement ) {
810	global $wpdb;
811	return $join_statement . " INNER JOIN $wpdb->postmeta pm ON pm.post_id = $wpdb->posts.ID ";
812	}
813
814	/**
815	* A method used to join the donors table on the query.
816	*
817	* @global WPBD $wpdb
818	* @since 1.0.0
819	*
820	* @param string $join_statement The default join statement.
821	* @return string
822	*/
823	public function join_donors_table( $join_statement ) {
824	global $wpdb;
825	return $join_statement . " INNER JOIN {$wpdb->prefix}charitable_donors d ON d.donor_id = cd.donor_id ";
826	}
827
828	/**
829	* Group results by the ID.
830	*
831	* @global WPBD $wpdb
832	* @since 1.0.0
833	*
834	* @return string
835	*/
836	public function groupby_ID() {
837	global $wpdb;
838	return "GROUP BY {$wpdb->posts}.ID";
839	}
840
841	/**
842	* Group a query by the donor ID.
843	*
844	* @since 1.0.0
845	*
846	* @return string
847	*/
848	public function groupby_donor_id() {
849	return 'GROUP BY cd.donor_id';
850	}
851
852	/**
853	* Group a query by the donation ID.
854	*
855	* @since 1.4.0
856	*
857	* @return string
858	*/
859	public function groupby_donation_id() {
860	return 'GROUP BY cd.donation_id';
861	}
862
863	/**
864	* Order by the date of the post.
865	*
866	* @global WPBD $wpdb
867	* @since 1.0.0
868	*
869	* @return string
870	*/
871	public function orderby_date() {
872	global $wpdb;
873	return "ORDER BY {$wpdb->posts}.post_date";
874	}
875
876	/**
877	* Order by the results count of the ID column.
878	*
879	* This is useful when used in combination with a group statement.
880	*
881	* @since 1.0.0
882	*
883	* @return string
884	*/
885	public function orderby_count() {
886	return 'ORDER BY COUNT(*)';
887	}
888
889	/**
890	* A method used to change the ordering of the campaigns query, to order by the amount donated.
891	*
892	* @since 1.0.0
893	*
894	* @return string
895	*/
896	public function orderby_donation_amount() {
897	return 'ORDER BY COALESCE(SUM(cd.amount), 0)';
898	}
899
900	/**
901	* Return number of results.
902	*
903	* @since 1.0.0
904	*
905	* @return int
906	*/
907	public function count() {
908	return 'count' == $this->get( 'output' ) ? $this->found_items : count( $this->results );
909	}
910
911	/**
912	* Return total result count.
913	*
914	* @since 1.5.0
915	*
916	* @return int
917	*/
918	public function found_items() {
919	return $this->found_items;
920	}
921
922	/**
923	* Rewind to first result.
924	*
925	* @since 1.0.0
926	*
927	* @return void
928	*/
929	public function rewind() {
930	$this->position = 0;
931	}
932
933	/**
934	* Return current element.
935	*
936	* @since 1.0.0
937	*
938	* @return object
939	*/
940	public function current() {
941	return $this->results[ $this->position ];
942	}
943
944	/**
945	* Return current key.
946	*
947	* @since 1.0.0
948	*
949	* @return int
950	*/
951	public function key() {
952	return $this->position;
953	}
954
955	/**
956	* Advance to next item.
957	*
958	* @since 1.0.0
959	*
960	* @return void
961	*/
962	public function next() {
963	++$this->position;
964	}
965
966	/**
967	* Ensure that current position is valid.
968	*
969	* @since 1.0.0
970	*
971	* @return boolean
972	*/
973	public function valid() {
974	return isset( $this->results[ $this->position ] );
975	}
976
977	/**
978	* Add parameters to pass to the prepared query.
979	*
980	* @since 1.0.0
981	*
982	* @param mixed $parameters Parameters to be set for the query.
983	* @return void
984	*/
985	public function add_parameters( $parameters ) {
986	$this->parameters = array_merge( $this->parameters, $parameters );
987	}
988
989	/**
990	* Whether to show all results.
991	*
992	* @since 1.1.0
993	*
994	* @return boolean
995	*/
996	public function show_all() {
997	return -1 == $this->get( 'number' );
998	}
999
1000	/**
1001	* Return the correct number of placeholders given a symbol and count.
1002	*
1003	* @since 1.0.0
1004	*
1005	* @param int $count Number of placeholders.
1006	* @param string $placeholder Placeholder symbol.
1007	* @return string
1008	*/
1009	protected function get_placeholders( $count = 1, $placeholder = '%s' ) {
1010	return charitable_get_query_placeholders( $count, $placeholder );
1011	}
1012	}
1013
1014	endif;
1015