namespace WPForms\Db\Payments;
* Class for the Payments database table.
class Payment extends WPForms_DB {
* Primary class constructor.
public function __construct() {
$this->table_name = self::get_table_name();
$this->primary_key = 'id';
public static function get_table_name() {
return $wpdb->prefix . 'wpforms_payments';
public function get_columns() {
'subtotal_amount' => '%f',
'discount_amount' => '%f',
'transaction_id' => '%s',
'subscription_id' => '%s',
'subscription_status' => '%s',
'date_created_gmt' => '%s',
'date_updated_gmt' => '%s',
public function get_column_defaults() {
$date = gmdate( 'Y-m-d H:i:s' );
'subscription_status' => '',
'date_created_gmt' => $date,
'date_updated_gmt' => $date,
* Insert a new payment into the database.
* @param array $data Column data.
* @param string $type Optional. Data type context.
* @return int ID for the newly inserted payment. Zero otherwise.
public function add( $data, $type = '' ) {
// Return early if the status is not allowed.
// TODO: consider validating other properties as well or get rid of it.
if ( isset( $data['status'] ) && ! ValueValidator::is_valid( $data['status'], 'status' ) ) {
// Use database type identifier if a context is empty.
$type = empty( $type ) ? $this->type : $type;
return parent::add( $data, $type );
* Retrieve a payment from the database based on a given payment ID.
* @param int $payment_id Payment ID.
* @param array $args Additional arguments.
public function get( $payment_id, $args = [] ) {
if ( ! $this->current_user_can( $payment_id, $args ) && wpforms()->obj( 'access' )->init_allowed() ) {
$payment = parent::get( $payment_id );
return $payment ? $this->cast_amounts_to_float( $payment ) : null;
* Retrieve a row based on column value.
* @param string $column Column name.
* @param int|string $value Column value.
* @return object|null Database query result, object or null on failure.
public function get_by( $column, $value ) {
$payment = parent::get_by( $column, $value );
return $payment ? $this->cast_amounts_to_float( $payment ) : null;
* Cast amounts to float in the given payment data object.
* @param object $payment Payment ID.
private function cast_amounts_to_float( $payment ) {
if ( empty( $payment ) || ! is_object( $payment ) ) {
// Amounts is stored in DB as decimal(26,8), but appear here as strings.
// Therefore, they should be cast to float to avoid further multi-time currency conversion.
$payment->subtotal_amount = $payment->subtotal_amount ? (float) $payment->subtotal_amount : 0;
$payment->discount_amount = $payment->discount_amount ? (float) $payment->discount_amount : 0;
$payment->total_amount = $payment->total_amount ? (float) $payment->total_amount : 0;
* Update an existing payment in the database.
* @param string $payment_id Payment ID.
* @param array $data Array of columns and associated data to update.
* @param string $where Column to match against in the WHERE clause. If empty, $primary_key will be used.
* @param string $type Data type context.
* @param array $args Additional arguments.
public function update( $payment_id, $data = [], $where = '', $type = '', $args = [] ) {
if ( ! $this->current_user_can( $payment_id, $args ) ) {
// TODO: consider validating other properties as well or get rid of it.
if ( isset( $data['status'] ) && ! ValueValidator::is_valid( $data['status'], 'status' ) ) {
// Use database type identifier if a context is empty.
$type = empty( $type ) ? $this->type : $type;
return parent::update( $payment_id, $data, $where, $type );
* Delete a payment from the database, also removes payment meta.
* @param int $payment_id Payment ID.
* @param array $args Additional arguments.
* @return bool False if the payment and meta could not be deleted, true otherwise.
public function delete( $payment_id = 0, $args = [] ): bool {
if ( ! $this->current_user_can( $payment_id, $args ) ) {
$is_payment_deleted = parent::delete( $payment_id );
$is_meta_deleted = wpforms()->obj( 'payment_meta' )->delete_by( 'payment_id', $payment_id );
return $is_payment_deleted && $is_meta_deleted;
* Retrieve a list of payments.
* @param array $args Arguments.
public function get_payments( $args = [] ) {
$args = $this->sanitize_get_payments_args( $args );
if ( ! $this->current_user_can( 0, $args ) ) {
$query[] = "SELECT p.* FROM {$this->table_name} as p";
* Filter the query for get_payments method before the WHERE clause.
* @param string $where Before the WHERE clause in DB query.
* @param array $args Query arguments.
$query[] = apply_filters( 'wpforms_db_payments_payment_get_payments_query_before_where', '', $args );
$query[] = $this->add_columns_where_conditions( $args );
$query[] = $this->add_secondary_where_conditions( $args );
* Extend the query for the get_payments method after the WHERE clause.
* This hook provides the flexibility to modify the SQL query by appending custom conditions
* right after the WHERE clause.
* @param string $where After the WHERE clause in the database query.
* @param array $args Query arguments.
$query[] = apply_filters( 'wpforms_db_payments_payment_get_payments_query_after_where', '', $args );
$query[] = sprintf( 'ORDER BY %s', sanitize_sql_orderby( "{$args['orderby']} {$args['order']}" ) );
$query[] = $wpdb->prepare( 'LIMIT %d, %d', $args['offset'], $args['number'] );
// phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery, WordPress.DB.DirectDatabaseQuery.NoCaching, WordPress.DB.PreparedSQL.NotPrepared
$result = $wpdb->get_results( implode( ' ', $query ), ARRAY_A );
return ! $result ? [] : $result;
public function create_table() {
$charset_collate = $wpdb->get_charset_collate();
* To avoid any possible issues during migration from entries to payments' table,
* all data types are preserved.
* Note: there must be two spaces between the words PRIMARY KEY and the definition of primary key.
* @link https://codex.wordpress.org/Creating_Tables_with_Plugins#Creating_or_Updating_the_Table
$query = "CREATE TABLE $this->table_name (
id bigint(20) NOT NULL AUTO_INCREMENT,
form_id bigint(20) NOT NULL,
status varchar(10) NOT NULL DEFAULT '',
subtotal_amount decimal(26,8) NOT NULL DEFAULT 0,
discount_amount decimal(26,8) NOT NULL DEFAULT 0,
total_amount decimal(26,8) NOT NULL DEFAULT 0,
currency varchar(3) NOT NULL DEFAULT '',
entry_id bigint(20) NOT NULL DEFAULT 0,
gateway varchar(20) NOT NULL DEFAULT '',
type varchar(12) NOT NULL DEFAULT '',
mode varchar(4) NOT NULL DEFAULT '',
transaction_id varchar(40) NOT NULL DEFAULT '',
customer_id varchar(40) NOT NULL DEFAULT '',
subscription_id varchar(40) NOT NULL DEFAULT '',
subscription_status varchar(10) NOT NULL DEFAULT '',
title varchar(255) NOT NULL DEFAULT '',
date_created_gmt datetime NOT NULL,
date_updated_gmt datetime NOT NULL,
is_published tinyint(1) NOT NULL DEFAULT 1,
KEY total_amount (total_amount),
KEY transaction_id (transaction_id(32)),
KEY customer_id (customer_id(32)),
KEY subscription_id (subscription_id(32)),
KEY subscription_status (subscription_status(8)),
require_once ABSPATH . 'wp-admin/includes/upgrade.php';
* Check if the current user has capabilities to manage payments.
* @param int $payment_id Payment ID.
* @param array $args Additional arguments.
* @noinspection IfReturnReturnSimplificationInspection
private function current_user_can( $payment_id, $args = [] ) {
$manage_cap = wpforms_get_capability_manage_options();
if ( ! isset( $args['cap'] ) ) {
$args['cap'] = $manage_cap;
if ( ! empty( $args['cap'] ) && ! wpforms_current_user_can( $args['cap'], $payment_id ) ) {
* Construct where clauses for selected columns.
* @param array $args Query arguments.
public function add_columns_where_conditions( $args = [] ) {
// Allowed columns for filtering.
// Determine if this is a table query.
$is_table_query = ! empty( $args['table_query'] );
$keys_to_validate = [ 'status', 'subscription_status', 'type', 'gateway' ];
foreach ( $args as $key => $value ) {
if ( empty( $value ) || ! in_array( $key, $allowed_cols, true ) ) {
// Explode values if needed.
$values = explode( '|', $value );
// Run some keys through the "ValueValidator" class to make sure they are valid.
if ( in_array( $key, $keys_to_validate, true ) ) {
static function ( $v ) use ( $key ) {
return ValueValidator::is_valid( $v, $key );
// Skip if no valid values found.
if ( empty( $values ) ) {
// Merge "Partially Refunded" status with "Refunded" status.
if ( $is_table_query && $key === 'status' && in_array( 'refunded', $values, true ) ) {
$values[] = 'partrefund';
$placeholders = wpforms_wpdb_prepare_in( $values );
// Prepare and add to WHERE clause.
$where .= " AND {$key} IN ({$placeholders})";
* Construct secondary where clauses.
* @param array $args Query arguments.
public function add_secondary_where_conditions( $args = [] ) {
* Filter arguments needed for all query.
* @param array $args Query arguments.
$args = (array) apply_filters( 'wpforms_db_payments_payment_add_secondary_where_conditions_args', $args );
'currency' => wpforms_get_currency(),
// If it's a valid mode, add it to a WHERE clause.
if ( ValueValidator::is_valid( $args['mode'], 'mode' ) ) {
$where .= $wpdb->prepare( ' AND mode = %s', $args['mode'] );
$where .= $wpdb->prepare( ' AND currency = %s', $args['currency'] );
$where .= $wpdb->prepare( ' AND is_published = %d', $args['is_published'] );
* Sanitize query arguments for get_payments() method.