eventespresso / event-espresso-core

core/db_models/EEM_Datetime.model.php

Doc Comments +2 added lines, -2 removed lines

@@ -463,7 +463,7 @@ 
      * @param int      $TKT_ID           ID of ticket to retrieve the datetimes for
      * @param boolean  $include_expired  whether to include expired datetimes or not
      * @param boolean  $include_deleted  whether to include trashed datetimes or not.
-     * @param int|null $limit            if null, no limit, if int then limit results by
+     * @param integer $limit            if null, no limit, if int then limit results by
      *                                   that number
      * @return EE_Datetime[]
      * @throws EE_Error
@@ -648,7 +648,7 @@ 
     /**
      * This returns an array of counts of datetimes in the database for each Datetime status that can be queried.
      *
-     * @param array $stati_to_include  If included you can restrict the statuses we return counts for by including the
+     * @param string[] $stati_to_include  If included you can restrict the statuses we return counts for by including the
      *                                 stati you want counts for as values in the array.  An empty array returns counts
      *                                 for all valid stati.
      * @param array $query_params      If included can be used to refine the conditions for returning the count (i.e.

Indentation +830 added lines, -830 removed lines

@@ -13,834 +13,834 @@
 class EEM_Datetime extends EEM_Soft_Delete_Base
 {
 
-    /**
-     * @var EEM_Datetime $_instance
-     */
-    protected static $_instance;
-
-
-    /**
-     * private constructor to prevent direct creation
-     *
-     * @param string $timezone A string representing the timezone we want to set for returned Date Time Strings
-     *                         (and any incoming timezone data that gets saved).
-     *                         Note this just sends the timezone info to the date time model field objects.
-     *                         Default is NULL
-     *                         (and will be assumed using the set timezone in the 'timezone_string' wp option)
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidArgumentException
-     */
-    protected function __construct($timezone)
-    {
-        $this->singular_item           = esc_html__('Datetime', 'event_espresso');
-        $this->plural_item             = esc_html__('Datetimes', 'event_espresso');
-        $this->_tables                 = [
-            'Datetime' => new EE_Primary_Table('esp_datetime', 'DTT_ID'),
-        ];
-        $this->_fields                 = [
-            'Datetime' => [
-                'DTT_ID'          => new EE_Primary_Key_Int_Field(
-                    'DTT_ID',
-                    esc_html__('Datetime ID', 'event_espresso')
-                ),
-                'EVT_ID'          => new EE_Foreign_Key_Int_Field(
-                    'EVT_ID',
-                    esc_html__('Event ID', 'event_espresso'),
-                    false,
-                    0,
-                    'Event'
-                ),
-                'DTT_name'        => new EE_Plain_Text_Field(
-                    'DTT_name',
-                    esc_html__('Datetime Name', 'event_espresso'),
-                    false,
-                    ''
-                ),
-                'DTT_description' => new EE_Post_Content_Field(
-                    'DTT_description',
-                    esc_html__('Description for Datetime', 'event_espresso'),
-                    false,
-                    ''
-                ),
-                'DTT_EVT_start'   => new EE_Datetime_Field(
-                    'DTT_EVT_start',
-                    esc_html__('Start time/date of Event', 'event_espresso'),
-                    false,
-                    EE_Datetime_Field::now,
-                    $timezone
-                ),
-                'DTT_EVT_end'     => new EE_Datetime_Field(
-                    'DTT_EVT_end',
-                    esc_html__('End time/date of Event', 'event_espresso'),
-                    false,
-                    EE_Datetime_Field::now,
-                    $timezone
-                ),
-                'DTT_reg_limit'   => new EE_Infinite_Integer_Field(
-                    'DTT_reg_limit',
-                    esc_html__('Registration Limit for this time', 'event_espresso'),
-                    true,
-                    EE_INF
-                ),
-                'DTT_sold'        => new EE_Integer_Field(
-                    'DTT_sold',
-                    esc_html__('How many sales for this Datetime that have occurred', 'event_espresso'),
-                    true,
-                    0
-                ),
-                'DTT_reserved'    => new EE_Integer_Field(
-                    'DTT_reserved',
-                    esc_html__('Quantity of tickets reserved, but not yet fully purchased', 'event_espresso'),
-                    false,
-                    0
-                ),
-                'DTT_is_primary'  => new EE_Boolean_Field(
-                    'DTT_is_primary',
-                    esc_html__('Flag indicating datetime is primary one for event', 'event_espresso'),
-                    false,
-                    false
-                ),
-                'DTT_order'       => new EE_Integer_Field(
-                    'DTT_order',
-                    esc_html__('The order in which the Datetime is displayed', 'event_espresso'),
-                    false,
-                    0
-                ),
-                'DTT_parent'      => new EE_Integer_Field(
-                    'DTT_parent',
-                    esc_html__('Indicates what DTT_ID is the parent of this DTT_ID', 'event_espresso'),
-                    true,
-                    0
-                ),
-                'DTT_deleted'     => new EE_Trashed_Flag_Field(
-                    'DTT_deleted',
-                    esc_html__('Flag indicating datetime is archived', 'event_espresso'),
-                    false,
-                    false
-                ),
-            ],
-        ];
-        $this->_model_relations        = [
-            'Ticket'          => new EE_HABTM_Relation('Datetime_Ticket'),
-            'Event'           => new EE_Belongs_To_Relation(),
-            'Checkin'         => new EE_Has_Many_Relation(),
-            'Datetime_Ticket' => new EE_Has_Many_Relation(),
-        ];
-        $path_to_event_model           = 'Event';
-        $this->model_chain_to_password = $path_to_event_model;
-        $this->_model_chain_to_wp_user = $path_to_event_model;
-        // this model is generally available for reading
-        $this->_cap_restriction_generators[ EEM_Base::caps_read ]       =
-            new EE_Restriction_Generator_Event_Related_Public(
-                $path_to_event_model
-            );
-        $this->_cap_restriction_generators[ EEM_Base::caps_read_admin ] =
-            new EE_Restriction_Generator_Event_Related_Protected(
-                $path_to_event_model
-            );
-        $this->_cap_restriction_generators[ EEM_Base::caps_edit ]       =
-            new EE_Restriction_Generator_Event_Related_Protected(
-                $path_to_event_model
-            );
-        $this->_cap_restriction_generators[ EEM_Base::caps_delete ]     =
-            new EE_Restriction_Generator_Event_Related_Protected(
-                $path_to_event_model,
-                EEM_Base::caps_edit
-            );
-        parent::__construct($timezone);
-    }
-
-
-    /**
-     * create new blank datetime
-     *
-     * @access public
-     * @return EE_Datetime[] array on success, FALSE on fail
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     * @throws ReflectionException
-     * @throws InvalidInterfaceException
-     */
-    public function create_new_blank_datetime()
-    {
-        // makes sure timezone is always set.
-        $timezone_string = $this->get_timezone();
-        /**
-         * Filters the initial start date for the new datetime.
-         * Any time included in this value will be overridden later so use additional filters to modify the time.
-         *
-         * @param int $start_date Unix timestamp representing now + 30 days in seconds.
-         * @return int Unix timestamp
-         */
-        $start_date = apply_filters(
-            'FHEE__EEM_Datetime__create_new_blank_datetime__start_date',
-            $this->current_time_for_query('DTT_EVT_start', true) + MONTH_IN_SECONDS
-        );
-        /**
-         * Filters the initial end date for the new datetime.
-         * Any time included in this value will be overridden later so use additional filters to modify the time.
-         *
-         * @param int $end_data Unix timestamp representing now + 30 days in seconds.
-         * @return int Unix timestamp
-         */
-        $end_date       = apply_filters(
-            'FHEE__EEM_Datetime__create_new_blank_datetime__end_date',
-            $this->current_time_for_query('DTT_EVT_end', true) + MONTH_IN_SECONDS
-        );
-        $blank_datetime = EE_Datetime::new_instance(
-            [
-                'DTT_EVT_start' => $start_date,
-                'DTT_EVT_end'   => $end_date,
-                'DTT_order'     => 1,
-                'DTT_reg_limit' => EE_INF,
-            ],
-            $timezone_string
-        );
-        /**
-         * Filters the initial start time and format for the new EE_Datetime instance.
-         *
-         * @param array $start_time An array having size 2.  First element is the time, second element is the time
-         *                          format.
-         * @return array
-         */
-        $start_time = apply_filters(
-            'FHEE__EEM_Datetime__create_new_blank_datetime__start_time',
-            ['8am', 'ga']
-        );
-        /**
-         * Filters the initial end time and format for the new EE_Datetime instance.
-         *
-         * @param array $end_time An array having size 2.  First element is the time, second element is the time
-         *                        format
-         * @return array
-         */
-        $end_time = apply_filters(
-            'FHEE__EEM_Datetime__create_new_blank_datetime__end_time',
-            ['5pm', 'ga']
-        );
-        $this->validateStartAndEndTimeForBlankDate($start_time, $end_time);
-        $blank_datetime->set_start_time(
-            $this->convert_datetime_for_query(
-                'DTT_EVT_start',
-                $start_time[0],
-                $start_time[1],
-                $timezone_string
-            )
-        );
-        $blank_datetime->set_end_time(
-            $this->convert_datetime_for_query(
-                'DTT_EVT_end',
-                $end_time[0],
-                $end_time[1],
-                $timezone_string
-            )
-        );
-        return [$blank_datetime];
-    }
-
-
-    /**
-     * Validates whether the start_time and end_time are in the expected format.
-     *
-     * @param array $start_time
-     * @param array $end_time
-     * @throws InvalidArgumentException
-     * @throws InvalidDataTypeException
-     */
-    private function validateStartAndEndTimeForBlankDate(array $start_time, array $end_time)
-    {
-        if (! is_array($start_time)) {
-            throw new InvalidDataTypeException('start_time', $start_time, 'array');
-        }
-        if (! is_array($end_time)) {
-            throw new InvalidDataTypeException('end_time', $end_time, 'array');
-        }
-        if (count($start_time) !== 2) {
-            throw new InvalidArgumentException(
-                sprintf(
-                    'The variable %1$s is expected to be an array with two elements.  The first item in the '
-                    . 'array should be a valid time string, the second item in the array should be a valid time format',
-                    '$start_time'
-                )
-            );
-        }
-        if (count($end_time) !== 2) {
-            throw new InvalidArgumentException(
-                sprintf(
-                    'The variable %1$s is expected to be an array with two elements.  The first item in the '
-                    . 'array should be a valid time string, the second item in the array should be a valid time format',
-                    '$end_time'
-                )
-            );
-        }
-    }
-
-
-    /**
-     * get event start date from db
-     *
-     * @access public
-     * @param int $EVT_ID
-     * @return EE_Datetime[] array on success, FALSE on fail
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function get_all_event_dates($EVT_ID = 0)
-    {
-        if (! $EVT_ID) { // on add_new_event event_id gets set to 0
-            return $this->create_new_blank_datetime();
-        }
-        $results = $this->get_datetimes_for_event_ordered_by_DTT_order($EVT_ID);
-        if (empty($results)) {
-            return $this->create_new_blank_datetime();
-        }
-        return $results;
-    }
-
-
-    /**
-     * get all datetimes attached to an event ordered by the DTT_order field
-     *
-     * @public
-     * @param int     $EVT_ID     event id
-     * @param boolean $include_expired
-     * @param boolean $include_deleted
-     * @param int     $limit      If included then limit the count of results by
-     *                            the given number
-     * @return EE_Datetime[]
-     * @throws EE_Error
-     */
-    public function get_datetimes_for_event_ordered_by_DTT_order(
-        int $EVT_ID,
-        bool $include_expired = true,
-        bool $include_deleted = true,
-        $limit = 0
-    ) {
-        $prev_data_prep_value = $this->prepModelForQuery();
-        $where_params         = ['Event.EVT_ID' => absint($EVT_ID)];
-        $query_params[0]      = $this->addDefaultWhereParams($where_params, $include_deleted, $include_expired);
-        $query_params         = $this->addDefaultWhereConditions($query_params);
-        $query_params         = $this->addDefaultQueryParams($query_params, $limit, 'DTT_order');
-        return $this->getDatetimesAndRestoreModel($query_params, $prev_data_prep_value);
-    }
-
-
-    /**
-     * Gets the datetimes for the event (with the given limit), and orders them by "importance".
-     * By importance, we mean that the primary datetimes are most important (DEPRECATED FOR NOW),
-     * and then the earlier datetimes are the most important.
-     * Maybe we'll want this to take into account datetimes that haven't already passed, but we don't yet.
-     *
-     * @param int $EVT_ID
-     * @param int $limit
-     * @return EE_Datetime[]|EE_Base_Class[]
-     * @throws EE_Error
-     */
-    public function get_datetimes_for_event_ordered_by_importance(int $EVT_ID, $limit = 0)
-    {
-        $query_params[0] = ['Event.EVT_ID' => absint($EVT_ID)];
-        $query_params    = $this->addDefaultWhereConditions($query_params);
-        $query_params    = $this->addDefaultQueryParams($query_params, $limit);
-        return $this->get_all($query_params);
-    }
-
-
-    /**
-     * @param int     $EVT_ID
-     * @param boolean $include_expired
-     * @param boolean $include_deleted
-     * @return EE_Datetime
-     * @throws EE_Error
-     */
-    public function get_oldest_datetime_for_event(
-        int $EVT_ID,
-        bool $include_expired = false,
-        bool $include_deleted = false
-    ) {
-        $results = $this->get_datetimes_for_event_ordered_by_start_time(
-            $EVT_ID,
-            $include_expired,
-            $include_deleted,
-            1
-        );
-        if ($results) {
-            return array_shift($results);
-        }
-        return null;
-    }
-
-
-    /**
-     * Gets the 'primary' datetime for an event.
-     *
-     * @param int  $EVT_ID
-     * @param bool $try_to_exclude_expired
-     * @param bool $try_to_exclude_deleted
-     * @return EE_Datetime
-     * @throws EE_Error
-     */
-    public function get_primary_datetime_for_event(
-        int $EVT_ID,
-        bool $try_to_exclude_expired = true,
-        bool $try_to_exclude_deleted = true
-    ) {
-        if ($try_to_exclude_expired) {
-            $non_expired = $this->get_oldest_datetime_for_event($EVT_ID, false, false);
-            if ($non_expired) {
-                return $non_expired;
-            }
-        }
-        if ($try_to_exclude_deleted) {
-            $expired_even = $this->get_oldest_datetime_for_event($EVT_ID, true);
-            if ($expired_even) {
-                return $expired_even;
-            }
-        }
-        return $this->get_oldest_datetime_for_event($EVT_ID, true, true);
-    }
-
-
-    /**
-     * Gets ALL the datetimes for an event (including trashed ones, for now), ordered
-     * only by start date
-     *
-     * @param int     $EVT_ID
-     * @param boolean $include_expired
-     * @param boolean $include_deleted
-     * @param int     $limit
-     * @return EE_Datetime[]
-     * @throws EE_Error
-     */
-    public function get_datetimes_for_event_ordered_by_start_time(
-        int $EVT_ID,
-        bool $include_expired = true,
-        bool $include_deleted = true,
-        $limit = 0
-    ) {
-        $prev_data_prep_value = $this->prepModelForQuery();
-        $where_params         = ['Event.EVT_ID' => absint($EVT_ID)];
-        $query_params[0]      = $this->addDefaultWhereParams($where_params, $include_deleted, $include_expired);
-        $query_params         = $this->addDefaultWhereConditions(
-            $query_params,
-            EEM_Base::default_where_conditions_this_only
-        );
-        $query_params         = $this->addDefaultQueryParams($query_params, $limit, 'DTT_order');
-        return $this->getDatetimesAndRestoreModel($query_params, $prev_data_prep_value);
-    }
-
-
-    /**
-     * Gets ALL the datetimes for an ticket (including trashed ones, for now), ordered
-     * only by start date
-     *
-     * @param int     $TKT_ID
-     * @param boolean $include_expired
-     * @param boolean $include_deleted
-     * @param int     $limit
-     * @return EE_Datetime[]
-     * @throws EE_Error
-     */
-    public function get_datetimes_for_ticket_ordered_by_start_time(
-        int $TKT_ID,
-        bool $include_expired = true,
-        bool $include_deleted = true,
-        $limit = 0
-    ) {
-        $prev_data_prep_value = $this->prepModelForQuery();
-        $where_params         = ['Ticket.TKT_ID' => absint($TKT_ID)];
-        $query_params[0]      = $this->addDefaultWhereParams($where_params, $include_deleted, $include_expired);
-        $query_params         = $this->addDefaultQueryParams($query_params, $limit);
-        return $this->getDatetimesAndRestoreModel($query_params, $prev_data_prep_value);
-    }
-
-
-    /**
-     * Gets all the datetimes for a ticket (including trashed ones, for now), ordered by the DTT_order for the
-     * datetimes.
-     *
-     * @param int      $TKT_ID           ID of ticket to retrieve the datetimes for
-     * @param boolean  $include_expired  whether to include expired datetimes or not
-     * @param boolean  $include_deleted  whether to include trashed datetimes or not.
-     * @param int|null $limit            if null, no limit, if int then limit results by
-     *                                   that number
-     * @return EE_Datetime[]
-     * @throws EE_Error
-     */
-    public function get_datetimes_for_ticket_ordered_by_DTT_order(
-        int $TKT_ID,
-        bool $include_expired = true,
-        bool $include_deleted = true,
-        $limit = 0
-    ) {
-        $prev_data_prep_value = $this->prepModelForQuery();
-        $where_params         = ['Ticket.TKT_ID' => absint($TKT_ID)];
-        $query_params[0]      = $this->addDefaultWhereParams($where_params, $include_deleted, $include_expired);
-        $query_params         = $this->addDefaultQueryParams($query_params, $limit, 'DTT_order');
-        return $this->getDatetimesAndRestoreModel($query_params, $prev_data_prep_value);
-    }
-
-
-    /**
-     * Gets the most important datetime for a particular event (ie, the primary event usually. But if for some WACK
-     * reason it doesn't exist, we consider the earliest event the most important)
-     *
-     * @param int $EVT_ID
-     * @return EE_Datetime
-     * @throws EE_Error
-     */
-    public function get_most_important_datetime_for_event(int $EVT_ID)
-    {
-        $results = $this->get_datetimes_for_event_ordered_by_importance($EVT_ID, 1);
-        if ($results) {
-            return array_shift($results);
-        }
-        return null;
-    }
-
-
-    /**
-     * This returns a wpdb->results        Array of all DTT month and years matching the incoming query params and
-     * grouped by month and year.
-     *
-     * @param array  $where_params       @see
-     *                                   https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md#0-where-conditions
-     * @param string $evt_active_status  A string representing the evt active status to filter the months by.
-     *                                   Can be:
-     *                                   - '' = no filter
-     *                                   - upcoming = Published events with at least one upcoming datetime.
-     *                                   - expired = Events with all datetimes expired.
-     *                                   - active = Events that are published and have at least one datetime that
-     *                                   starts before now and ends after now.
-     *                                   - inactive = Events that are either not published.
-     * @return EE_Base_Class[]
-     * @throws EE_Error
-     * @throws InvalidArgumentException
-     * @throws InvalidArgumentException
-     */
-    public function get_dtt_months_and_years(array $where_params, $evt_active_status = '')
-    {
-        $current_time_for_DTT_EVT_start = $this->current_time_for_query('DTT_EVT_start');
-        $current_time_for_DTT_EVT_end   = $this->current_time_for_query('DTT_EVT_end');
-        switch ($evt_active_status) {
-            case 'upcoming':
-                $where_params['Event.status'] = 'publish';
-                // if there are already query_params matching DTT_EVT_start then we need to modify that to add them.
-                if (isset($where_params['DTT_EVT_start'])) {
-                    $where_params['DTT_EVT_start*****'] = $where_params['DTT_EVT_start'];
-                }
-                $where_params['DTT_EVT_start'] = ['>', $current_time_for_DTT_EVT_start];
-                break;
-            case 'expired':
-                if (isset($where_params['Event.status'])) {
-                    unset($where_params['Event.status']);
-                }
-                // get events to exclude
-                $exclude_query[0] = array_merge(
-                    $where_params,
-                    ['DTT_EVT_end' => ['>', $current_time_for_DTT_EVT_end]]
-                );
-                // first get all events that have datetimes where its not expired.
-                $event_ids = $this->_get_all_wpdb_results(
-                    $exclude_query,
-                    OBJECT_K,
-                    'Datetime.EVT_ID'
-                );
-                $event_ids = array_keys($event_ids);
-                if (isset($where_params['DTT_EVT_end'])) {
-                    $where_params['DTT_EVT_end****'] = $where_params['DTT_EVT_end'];
-                }
-                $where_params['DTT_EVT_end']  = ['<', $current_time_for_DTT_EVT_end];
-                $where_params['Event.EVT_ID'] = ['NOT IN', $event_ids];
-                break;
-            case 'active':
-                $where_params['Event.status'] = 'publish';
-                if (isset($where_params['DTT_EVT_start'])) {
-                    $where_params['Datetime.DTT_EVT_start******'] = $where_params['DTT_EVT_start'];
-                }
-                if (isset($where_params['Datetime.DTT_EVT_end'])) {
-                    $where_params['Datetime.DTT_EVT_end*****'] = $where_params['DTT_EVT_end'];
-                }
-                $where_params['DTT_EVT_start'] = ['<', $current_time_for_DTT_EVT_start];
-                $where_params['DTT_EVT_end']   = ['>', $current_time_for_DTT_EVT_end];
-                break;
-            case 'inactive':
-                if (isset($where_params['Event.status'])) {
-                    unset($where_params['Event.status']);
-                }
-                if (isset($where_params['OR'])) {
-                    $where_params['AND']['OR'] = $where_params['OR'];
-                }
-                if (isset($where_params['DTT_EVT_end'])) {
-                    $where_params['AND']['DTT_EVT_end****'] = $where_params['DTT_EVT_end'];
-                    unset($where_params['DTT_EVT_end']);
-                }
-                if (isset($where_params['DTT_EVT_start'])) {
-                    $where_params['AND']['DTT_EVT_start'] = $where_params['DTT_EVT_start'];
-                    unset($where_params['DTT_EVT_start']);
-                }
-                $where_params['AND']['Event.status'] = ['!=', 'publish'];
-                break;
-        }
-        $query_params[0]          = $where_params;
-        $query_params['group_by'] = ['dtt_year', 'dtt_month'];
-        $query_params             = $this->addOrderByQueryParams($query_params, 'DTT_EVT_start', 'DESC');
-
-        $query_interval    = EEH_DTT_Helper::get_sql_query_interval_for_offset(
-            $this->get_timezone(),
-            'DTT_EVT_start'
-        );
-        $columns_to_select = [
-            'dtt_year'      => ['YEAR(' . $query_interval . ')', '%s'],
-            'dtt_month'     => ['MONTHNAME(' . $query_interval . ')', '%s'],
-            'dtt_month_num' => ['MONTH(' . $query_interval . ')', '%s'],
-        ];
-        return $this->_get_all_wpdb_results($query_params, OBJECT, $columns_to_select);
-    }
-
-
-    /**
-     * Updates the DTT_sold attribute on each datetime (based on the registrations
-     * for the tickets for each datetime)
-     *
-     * @param EE_Base_Class[]|EE_Datetime[] $datetimes
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function update_sold(array $datetimes)
-    {
-        EE_Error::doing_it_wrong(
-            __FUNCTION__,
-            esc_html__(
-                'Please use \EEM_Ticket::update_tickets_sold() instead which will in turn correctly update both the Ticket AND Datetime counts.',
-                'event_espresso'
-            ),
-            '4.9.32.rc.005'
-        );
-        foreach ($datetimes as $datetime) {
-            $datetime->update_sold();
-        }
-    }
-
-
-    /**
-     *    Gets the total number of tickets available at a particular datetime
-     *    (does NOT take into account the datetime's spaces available)
-     *
-     * @param int   $DTT_ID
-     * @param array $query_params
-     * @return int of tickets available. If sold out, return less than 1. If infinite, returns EE_INF,  IF there are NO
-     *             tickets attached to datetime then FALSE is returned.
-     * @throws EE_Error
-     * @throws ReflectionException
-     */
-    public function sum_tickets_currently_available_at_datetime(int $DTT_ID, array $query_params = [])
-    {
-        $datetime = $this->get_one_by_ID($DTT_ID);
-        if ($datetime instanceof EE_Datetime) {
-            return $datetime->tickets_remaining($query_params);
-        }
-        return 0;
-    }
-
-
-    /**
-     * This returns an array of counts of datetimes in the database for each Datetime status that can be queried.
-     *
-     * @param array $stati_to_include  If included you can restrict the statuses we return counts for by including the
-     *                                 stati you want counts for as values in the array.  An empty array returns counts
-     *                                 for all valid stati.
-     * @param array $query_params      If included can be used to refine the conditions for returning the count (i.e.
-     *                                 only for Datetimes connected to a specific event, or specific ticket.
-     * @return array  The value returned is an array indexed by Datetime Status and the values are the counts.  The
-     * @throws EE_Error
-     *                                 stati used as index keys are: EE_Datetime::active EE_Datetime::upcoming
-     *                                 EE_Datetime::expired
-     */
-    public function get_datetime_counts_by_status(array $stati_to_include = [], array $query_params = [])
-    {
-        // only accept where conditions for this query.
-        $_where            = isset($query_params[0]) ? $query_params[0] : [];
-        $status_query_args = [
-            EE_Datetime::active   => array_merge(
-                $_where,
-                ['DTT_EVT_start' => ['<', time()], 'DTT_EVT_end' => ['>', time()]]
-            ),
-            EE_Datetime::upcoming => array_merge(
-                $_where,
-                ['DTT_EVT_start' => ['>', time()]]
-            ),
-            EE_Datetime::expired  => array_merge(
-                $_where,
-                ['DTT_EVT_end' => ['<', time()]]
-            ),
-        ];
-        if (! empty($stati_to_include)) {
-            foreach (array_keys($status_query_args) as $status) {
-                if (! in_array($status, $stati_to_include, true)) {
-                    unset($status_query_args[ $status ]);
-                }
-            }
-        }
-        // loop through and query counts for each stati.
-        $status_query_results = [];
-        foreach ($status_query_args as $status => $status_where_conditions) {
-            $status_query_results[ $status ] = EEM_Datetime::count(
-                [$status_where_conditions],
-                'DTT_ID',
-                true
-            );
-        }
-        return $status_query_results;
-    }
-
-
-    /**
-     * Returns the specific count for a given Datetime status matching any given query_params.
-     *
-     * @param string $status Valid string representation for Datetime status requested. (Defaults to Active).
-     * @param array  $query_params
-     * @return int
-     * @throws EE_Error
-     */
-    public function get_datetime_count_for_status($status = EE_Datetime::active, array $query_params = [])
-    {
-        $count = $this->get_datetime_counts_by_status([$status], $query_params);
-        return ! empty($count[ $status ]) ? $count[ $status ] : 0;
-    }
-
-
-    /**
-     * @return bool|int
-     * @since   $VID:$
-     */
-    private function prepModelForQuery()
-    {
-        $prev_data_prep_value = $this->get_assumption_concerning_values_already_prepared_by_model_object();
-        $this->assume_values_already_prepared_by_model_object(EEM_Base::prepared_for_use_in_db);
-        return $prev_data_prep_value;
-    }
-
-
-    /**
-     * @param array    $query_params
-     * @param bool|int $prev_data_prep_value
-     * @return EE_Base_Class[]|EE_Datetime[]
-     * @throws EE_Error
-     * @since   $VID:$
-     */
-    private function getDatetimesAndRestoreModel(array $query_params, $prev_data_prep_value)
-    {
-        $result = $this->get_all($query_params);
-        $this->assume_values_already_prepared_by_model_object($prev_data_prep_value);
-        return $result;
-    }
-
-
-    /**
-     * @param array  $query_params
-     * @param int    $limit
-     * @param string $order_by
-     * @param string $order
-     * @return array
-     * @since   $VID:$
-     */
-    private function addDefaultQueryParams(array $query_params, $limit = 0, $order_by = 'DTT_EVT_start', $order = 'ASC')
-    {
-        $query_params = $this->addOrderByQueryParams($query_params, $order_by, $order);
-        $query_params = $this->addLimitQueryParams($query_params, $limit);
-        return $query_params;
-    }
-
-
-    /**
-     * @param array  $query_params
-     * @param string $default_where_conditions
-     * @return array
-     * @since   $VID:$
-     */
-    private function addDefaultWhereConditions(
-        array $query_params,
-        $default_where_conditions = EEM_Base::default_where_conditions_none
-    ) {
-        $query_params['default_where_conditions'] = $default_where_conditions;
-        return $query_params;
-    }
-
-
-    /**
-     * @param array $where_params
-     * @param bool  $include_deleted
-     * @param bool  $include_expired
-     * @return array
-     * @since   $VID:$
-     */
-    private function addDefaultWhereParams(array $where_params, bool $include_deleted = true, bool $include_expired = true)
-    {
-        $where_params = $this->addExpiredWhereParams($where_params, $include_expired);
-        $where_params = $this->addDeletedWhereParams($where_params, $include_deleted);
-        return $where_params;
-    }
-
-
-    /**
-     * @param array $where_params
-     * @param bool  $include_deleted
-     * @return array
-     * @since   $VID:$
-     */
-    private function addDeletedWhereParams(array $where_params, bool $include_deleted = true)
-    {
-        $deleted                     = $include_deleted ? [true, false] : [false];
-        $where_params['DTT_deleted'] = ['IN', $deleted];
-        return $where_params;
-    }
-
-
-    /**
-     * @param array $where_params
-     * @param bool  $include_expired
-     * @return array
-     * @since   $VID:$
-     */
-    private function addExpiredWhereParams(array $where_params, bool $include_expired = true)
-    {
-        if (! $include_expired) {
-            $where_params['DTT_EVT_end'] = ['>=', current_time('mysql', true)];
-        }
-        return $where_params;
-    }
-
-
-    /**
-     * @param array $query_params
-     * @param int   $limit
-     * @return array
-     * @since   $VID:$
-     */
-    private function addLimitQueryParams(array $query_params, $limit = 0)
-    {
-        if ($limit) {
-            $query_params['limit'] = $limit;
-        }
-        return $query_params;
-    }
-
-
-    /**
-     * @param array  $query_params
-     * @param string $order_by
-     * @param string $order
-     * @return array
-     * @since   $VID:$
-     */
-    private function addOrderByQueryParams(array $query_params, $order_by = 'DTT_EVT_start', $order = 'ASC')
-    {
-        $order                    = $order === 'ASC' ? 'ASC' : 'DESC';
-        $valid_order_columns      = ['DTT_ID', 'DTT_EVT_start', 'DTT_EVT_end', 'DTT_order'];
-        $order_by                 = in_array($order_by, $valid_order_columns, true) ? $order_by : 'DTT_EVT_start';
-        $query_params['order_by'] = [$order_by => $order];
-        return $query_params;
-    }
+	/**
+	 * @var EEM_Datetime $_instance
+	 */
+	protected static $_instance;
+
+
+	/**
+	 * private constructor to prevent direct creation
+	 *
+	 * @param string $timezone A string representing the timezone we want to set for returned Date Time Strings
+	 *                         (and any incoming timezone data that gets saved).
+	 *                         Note this just sends the timezone info to the date time model field objects.
+	 *                         Default is NULL
+	 *                         (and will be assumed using the set timezone in the 'timezone_string' wp option)
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidArgumentException
+	 */
+	protected function __construct($timezone)
+	{
+		$this->singular_item           = esc_html__('Datetime', 'event_espresso');
+		$this->plural_item             = esc_html__('Datetimes', 'event_espresso');
+		$this->_tables                 = [
+			'Datetime' => new EE_Primary_Table('esp_datetime', 'DTT_ID'),
+		];
+		$this->_fields                 = [
+			'Datetime' => [
+				'DTT_ID'          => new EE_Primary_Key_Int_Field(
+					'DTT_ID',
+					esc_html__('Datetime ID', 'event_espresso')
+				),
+				'EVT_ID'          => new EE_Foreign_Key_Int_Field(
+					'EVT_ID',
+					esc_html__('Event ID', 'event_espresso'),
+					false,
+					0,
+					'Event'
+				),
+				'DTT_name'        => new EE_Plain_Text_Field(
+					'DTT_name',
+					esc_html__('Datetime Name', 'event_espresso'),
+					false,
+					''
+				),
+				'DTT_description' => new EE_Post_Content_Field(
+					'DTT_description',
+					esc_html__('Description for Datetime', 'event_espresso'),
+					false,
+					''
+				),
+				'DTT_EVT_start'   => new EE_Datetime_Field(
+					'DTT_EVT_start',
+					esc_html__('Start time/date of Event', 'event_espresso'),
+					false,
+					EE_Datetime_Field::now,
+					$timezone
+				),
+				'DTT_EVT_end'     => new EE_Datetime_Field(
+					'DTT_EVT_end',
+					esc_html__('End time/date of Event', 'event_espresso'),
+					false,
+					EE_Datetime_Field::now,
+					$timezone
+				),
+				'DTT_reg_limit'   => new EE_Infinite_Integer_Field(
+					'DTT_reg_limit',
+					esc_html__('Registration Limit for this time', 'event_espresso'),
+					true,
+					EE_INF
+				),
+				'DTT_sold'        => new EE_Integer_Field(
+					'DTT_sold',
+					esc_html__('How many sales for this Datetime that have occurred', 'event_espresso'),
+					true,
+					0
+				),
+				'DTT_reserved'    => new EE_Integer_Field(
+					'DTT_reserved',
+					esc_html__('Quantity of tickets reserved, but not yet fully purchased', 'event_espresso'),
+					false,
+					0
+				),
+				'DTT_is_primary'  => new EE_Boolean_Field(
+					'DTT_is_primary',
+					esc_html__('Flag indicating datetime is primary one for event', 'event_espresso'),
+					false,
+					false
+				),
+				'DTT_order'       => new EE_Integer_Field(
+					'DTT_order',
+					esc_html__('The order in which the Datetime is displayed', 'event_espresso'),
+					false,
+					0
+				),
+				'DTT_parent'      => new EE_Integer_Field(
+					'DTT_parent',
+					esc_html__('Indicates what DTT_ID is the parent of this DTT_ID', 'event_espresso'),
+					true,
+					0
+				),
+				'DTT_deleted'     => new EE_Trashed_Flag_Field(
+					'DTT_deleted',
+					esc_html__('Flag indicating datetime is archived', 'event_espresso'),
+					false,
+					false
+				),
+			],
+		];
+		$this->_model_relations        = [
+			'Ticket'          => new EE_HABTM_Relation('Datetime_Ticket'),
+			'Event'           => new EE_Belongs_To_Relation(),
+			'Checkin'         => new EE_Has_Many_Relation(),
+			'Datetime_Ticket' => new EE_Has_Many_Relation(),
+		];
+		$path_to_event_model           = 'Event';
+		$this->model_chain_to_password = $path_to_event_model;
+		$this->_model_chain_to_wp_user = $path_to_event_model;
+		// this model is generally available for reading
+		$this->_cap_restriction_generators[ EEM_Base::caps_read ]       =
+			new EE_Restriction_Generator_Event_Related_Public(
+				$path_to_event_model
+			);
+		$this->_cap_restriction_generators[ EEM_Base::caps_read_admin ] =
+			new EE_Restriction_Generator_Event_Related_Protected(
+				$path_to_event_model
+			);
+		$this->_cap_restriction_generators[ EEM_Base::caps_edit ]       =
+			new EE_Restriction_Generator_Event_Related_Protected(
+				$path_to_event_model
+			);
+		$this->_cap_restriction_generators[ EEM_Base::caps_delete ]     =
+			new EE_Restriction_Generator_Event_Related_Protected(
+				$path_to_event_model,
+				EEM_Base::caps_edit
+			);
+		parent::__construct($timezone);
+	}
+
+
+	/**
+	 * create new blank datetime
+	 *
+	 * @access public
+	 * @return EE_Datetime[] array on success, FALSE on fail
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 * @throws ReflectionException
+	 * @throws InvalidInterfaceException
+	 */
+	public function create_new_blank_datetime()
+	{
+		// makes sure timezone is always set.
+		$timezone_string = $this->get_timezone();
+		/**
+		 * Filters the initial start date for the new datetime.
+		 * Any time included in this value will be overridden later so use additional filters to modify the time.
+		 *
+		 * @param int $start_date Unix timestamp representing now + 30 days in seconds.
+		 * @return int Unix timestamp
+		 */
+		$start_date = apply_filters(
+			'FHEE__EEM_Datetime__create_new_blank_datetime__start_date',
+			$this->current_time_for_query('DTT_EVT_start', true) + MONTH_IN_SECONDS
+		);
+		/**
+		 * Filters the initial end date for the new datetime.
+		 * Any time included in this value will be overridden later so use additional filters to modify the time.
+		 *
+		 * @param int $end_data Unix timestamp representing now + 30 days in seconds.
+		 * @return int Unix timestamp
+		 */
+		$end_date       = apply_filters(
+			'FHEE__EEM_Datetime__create_new_blank_datetime__end_date',
+			$this->current_time_for_query('DTT_EVT_end', true) + MONTH_IN_SECONDS
+		);
+		$blank_datetime = EE_Datetime::new_instance(
+			[
+				'DTT_EVT_start' => $start_date,
+				'DTT_EVT_end'   => $end_date,
+				'DTT_order'     => 1,
+				'DTT_reg_limit' => EE_INF,
+			],
+			$timezone_string
+		);
+		/**
+		 * Filters the initial start time and format for the new EE_Datetime instance.
+		 *
+		 * @param array $start_time An array having size 2.  First element is the time, second element is the time
+		 *                          format.
+		 * @return array
+		 */
+		$start_time = apply_filters(
+			'FHEE__EEM_Datetime__create_new_blank_datetime__start_time',
+			['8am', 'ga']
+		);
+		/**
+		 * Filters the initial end time and format for the new EE_Datetime instance.
+		 *
+		 * @param array $end_time An array having size 2.  First element is the time, second element is the time
+		 *                        format
+		 * @return array
+		 */
+		$end_time = apply_filters(
+			'FHEE__EEM_Datetime__create_new_blank_datetime__end_time',
+			['5pm', 'ga']
+		);
+		$this->validateStartAndEndTimeForBlankDate($start_time, $end_time);
+		$blank_datetime->set_start_time(
+			$this->convert_datetime_for_query(
+				'DTT_EVT_start',
+				$start_time[0],
+				$start_time[1],
+				$timezone_string
+			)
+		);
+		$blank_datetime->set_end_time(
+			$this->convert_datetime_for_query(
+				'DTT_EVT_end',
+				$end_time[0],
+				$end_time[1],
+				$timezone_string
+			)
+		);
+		return [$blank_datetime];
+	}
+
+
+	/**
+	 * Validates whether the start_time and end_time are in the expected format.
+	 *
+	 * @param array $start_time
+	 * @param array $end_time
+	 * @throws InvalidArgumentException
+	 * @throws InvalidDataTypeException
+	 */
+	private function validateStartAndEndTimeForBlankDate(array $start_time, array $end_time)
+	{
+		if (! is_array($start_time)) {
+			throw new InvalidDataTypeException('start_time', $start_time, 'array');
+		}
+		if (! is_array($end_time)) {
+			throw new InvalidDataTypeException('end_time', $end_time, 'array');
+		}
+		if (count($start_time) !== 2) {
+			throw new InvalidArgumentException(
+				sprintf(
+					'The variable %1$s is expected to be an array with two elements.  The first item in the '
+					. 'array should be a valid time string, the second item in the array should be a valid time format',
+					'$start_time'
+				)
+			);
+		}
+		if (count($end_time) !== 2) {
+			throw new InvalidArgumentException(
+				sprintf(
+					'The variable %1$s is expected to be an array with two elements.  The first item in the '
+					. 'array should be a valid time string, the second item in the array should be a valid time format',
+					'$end_time'
+				)
+			);
+		}
+	}
+
+
+	/**
+	 * get event start date from db
+	 *
+	 * @access public
+	 * @param int $EVT_ID
+	 * @return EE_Datetime[] array on success, FALSE on fail
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function get_all_event_dates($EVT_ID = 0)
+	{
+		if (! $EVT_ID) { // on add_new_event event_id gets set to 0
+			return $this->create_new_blank_datetime();
+		}
+		$results = $this->get_datetimes_for_event_ordered_by_DTT_order($EVT_ID);
+		if (empty($results)) {
+			return $this->create_new_blank_datetime();
+		}
+		return $results;
+	}
+
+
+	/**
+	 * get all datetimes attached to an event ordered by the DTT_order field
+	 *
+	 * @public
+	 * @param int     $EVT_ID     event id
+	 * @param boolean $include_expired
+	 * @param boolean $include_deleted
+	 * @param int     $limit      If included then limit the count of results by
+	 *                            the given number
+	 * @return EE_Datetime[]
+	 * @throws EE_Error
+	 */
+	public function get_datetimes_for_event_ordered_by_DTT_order(
+		int $EVT_ID,
+		bool $include_expired = true,
+		bool $include_deleted = true,
+		$limit = 0
+	) {
+		$prev_data_prep_value = $this->prepModelForQuery();
+		$where_params         = ['Event.EVT_ID' => absint($EVT_ID)];
+		$query_params[0]      = $this->addDefaultWhereParams($where_params, $include_deleted, $include_expired);
+		$query_params         = $this->addDefaultWhereConditions($query_params);
+		$query_params         = $this->addDefaultQueryParams($query_params, $limit, 'DTT_order');
+		return $this->getDatetimesAndRestoreModel($query_params, $prev_data_prep_value);
+	}
+
+
+	/**
+	 * Gets the datetimes for the event (with the given limit), and orders them by "importance".
+	 * By importance, we mean that the primary datetimes are most important (DEPRECATED FOR NOW),
+	 * and then the earlier datetimes are the most important.
+	 * Maybe we'll want this to take into account datetimes that haven't already passed, but we don't yet.
+	 *
+	 * @param int $EVT_ID
+	 * @param int $limit
+	 * @return EE_Datetime[]|EE_Base_Class[]
+	 * @throws EE_Error
+	 */
+	public function get_datetimes_for_event_ordered_by_importance(int $EVT_ID, $limit = 0)
+	{
+		$query_params[0] = ['Event.EVT_ID' => absint($EVT_ID)];
+		$query_params    = $this->addDefaultWhereConditions($query_params);
+		$query_params    = $this->addDefaultQueryParams($query_params, $limit);
+		return $this->get_all($query_params);
+	}
+
+
+	/**
+	 * @param int     $EVT_ID
+	 * @param boolean $include_expired
+	 * @param boolean $include_deleted
+	 * @return EE_Datetime
+	 * @throws EE_Error
+	 */
+	public function get_oldest_datetime_for_event(
+		int $EVT_ID,
+		bool $include_expired = false,
+		bool $include_deleted = false
+	) {
+		$results = $this->get_datetimes_for_event_ordered_by_start_time(
+			$EVT_ID,
+			$include_expired,
+			$include_deleted,
+			1
+		);
+		if ($results) {
+			return array_shift($results);
+		}
+		return null;
+	}
+
+
+	/**
+	 * Gets the 'primary' datetime for an event.
+	 *
+	 * @param int  $EVT_ID
+	 * @param bool $try_to_exclude_expired
+	 * @param bool $try_to_exclude_deleted
+	 * @return EE_Datetime
+	 * @throws EE_Error
+	 */
+	public function get_primary_datetime_for_event(
+		int $EVT_ID,
+		bool $try_to_exclude_expired = true,
+		bool $try_to_exclude_deleted = true
+	) {
+		if ($try_to_exclude_expired) {
+			$non_expired = $this->get_oldest_datetime_for_event($EVT_ID, false, false);
+			if ($non_expired) {
+				return $non_expired;
+			}
+		}
+		if ($try_to_exclude_deleted) {
+			$expired_even = $this->get_oldest_datetime_for_event($EVT_ID, true);
+			if ($expired_even) {
+				return $expired_even;
+			}
+		}
+		return $this->get_oldest_datetime_for_event($EVT_ID, true, true);
+	}
+
+
+	/**
+	 * Gets ALL the datetimes for an event (including trashed ones, for now), ordered
+	 * only by start date
+	 *
+	 * @param int     $EVT_ID
+	 * @param boolean $include_expired
+	 * @param boolean $include_deleted
+	 * @param int     $limit
+	 * @return EE_Datetime[]
+	 * @throws EE_Error
+	 */
+	public function get_datetimes_for_event_ordered_by_start_time(
+		int $EVT_ID,
+		bool $include_expired = true,
+		bool $include_deleted = true,
+		$limit = 0
+	) {
+		$prev_data_prep_value = $this->prepModelForQuery();
+		$where_params         = ['Event.EVT_ID' => absint($EVT_ID)];
+		$query_params[0]      = $this->addDefaultWhereParams($where_params, $include_deleted, $include_expired);
+		$query_params         = $this->addDefaultWhereConditions(
+			$query_params,
+			EEM_Base::default_where_conditions_this_only
+		);
+		$query_params         = $this->addDefaultQueryParams($query_params, $limit, 'DTT_order');
+		return $this->getDatetimesAndRestoreModel($query_params, $prev_data_prep_value);
+	}
+
+
+	/**
+	 * Gets ALL the datetimes for an ticket (including trashed ones, for now), ordered
+	 * only by start date
+	 *
+	 * @param int     $TKT_ID
+	 * @param boolean $include_expired
+	 * @param boolean $include_deleted
+	 * @param int     $limit
+	 * @return EE_Datetime[]
+	 * @throws EE_Error
+	 */
+	public function get_datetimes_for_ticket_ordered_by_start_time(
+		int $TKT_ID,
+		bool $include_expired = true,
+		bool $include_deleted = true,
+		$limit = 0
+	) {
+		$prev_data_prep_value = $this->prepModelForQuery();
+		$where_params         = ['Ticket.TKT_ID' => absint($TKT_ID)];
+		$query_params[0]      = $this->addDefaultWhereParams($where_params, $include_deleted, $include_expired);
+		$query_params         = $this->addDefaultQueryParams($query_params, $limit);
+		return $this->getDatetimesAndRestoreModel($query_params, $prev_data_prep_value);
+	}
+
+
+	/**
+	 * Gets all the datetimes for a ticket (including trashed ones, for now), ordered by the DTT_order for the
+	 * datetimes.
+	 *
+	 * @param int      $TKT_ID           ID of ticket to retrieve the datetimes for
+	 * @param boolean  $include_expired  whether to include expired datetimes or not
+	 * @param boolean  $include_deleted  whether to include trashed datetimes or not.
+	 * @param int|null $limit            if null, no limit, if int then limit results by
+	 *                                   that number
+	 * @return EE_Datetime[]
+	 * @throws EE_Error
+	 */
+	public function get_datetimes_for_ticket_ordered_by_DTT_order(
+		int $TKT_ID,
+		bool $include_expired = true,
+		bool $include_deleted = true,
+		$limit = 0
+	) {
+		$prev_data_prep_value = $this->prepModelForQuery();
+		$where_params         = ['Ticket.TKT_ID' => absint($TKT_ID)];
+		$query_params[0]      = $this->addDefaultWhereParams($where_params, $include_deleted, $include_expired);
+		$query_params         = $this->addDefaultQueryParams($query_params, $limit, 'DTT_order');
+		return $this->getDatetimesAndRestoreModel($query_params, $prev_data_prep_value);
+	}
+
+
+	/**
+	 * Gets the most important datetime for a particular event (ie, the primary event usually. But if for some WACK
+	 * reason it doesn't exist, we consider the earliest event the most important)
+	 *
+	 * @param int $EVT_ID
+	 * @return EE_Datetime
+	 * @throws EE_Error
+	 */
+	public function get_most_important_datetime_for_event(int $EVT_ID)
+	{
+		$results = $this->get_datetimes_for_event_ordered_by_importance($EVT_ID, 1);
+		if ($results) {
+			return array_shift($results);
+		}
+		return null;
+	}
+
+
+	/**
+	 * This returns a wpdb->results        Array of all DTT month and years matching the incoming query params and
+	 * grouped by month and year.
+	 *
+	 * @param array  $where_params       @see
+	 *                                   https://github.com/eventespresso/event-espresso-core/tree/master/docs/G--Model-System/model-query-params.md#0-where-conditions
+	 * @param string $evt_active_status  A string representing the evt active status to filter the months by.
+	 *                                   Can be:
+	 *                                   - '' = no filter
+	 *                                   - upcoming = Published events with at least one upcoming datetime.
+	 *                                   - expired = Events with all datetimes expired.
+	 *                                   - active = Events that are published and have at least one datetime that
+	 *                                   starts before now and ends after now.
+	 *                                   - inactive = Events that are either not published.
+	 * @return EE_Base_Class[]
+	 * @throws EE_Error
+	 * @throws InvalidArgumentException
+	 * @throws InvalidArgumentException
+	 */
+	public function get_dtt_months_and_years(array $where_params, $evt_active_status = '')
+	{
+		$current_time_for_DTT_EVT_start = $this->current_time_for_query('DTT_EVT_start');
+		$current_time_for_DTT_EVT_end   = $this->current_time_for_query('DTT_EVT_end');
+		switch ($evt_active_status) {
+			case 'upcoming':
+				$where_params['Event.status'] = 'publish';
+				// if there are already query_params matching DTT_EVT_start then we need to modify that to add them.
+				if (isset($where_params['DTT_EVT_start'])) {
+					$where_params['DTT_EVT_start*****'] = $where_params['DTT_EVT_start'];
+				}
+				$where_params['DTT_EVT_start'] = ['>', $current_time_for_DTT_EVT_start];
+				break;
+			case 'expired':
+				if (isset($where_params['Event.status'])) {
+					unset($where_params['Event.status']);
+				}
+				// get events to exclude
+				$exclude_query[0] = array_merge(
+					$where_params,
+					['DTT_EVT_end' => ['>', $current_time_for_DTT_EVT_end]]
+				);
+				// first get all events that have datetimes where its not expired.
+				$event_ids = $this->_get_all_wpdb_results(
+					$exclude_query,
+					OBJECT_K,
+					'Datetime.EVT_ID'
+				);
+				$event_ids = array_keys($event_ids);
+				if (isset($where_params['DTT_EVT_end'])) {
+					$where_params['DTT_EVT_end****'] = $where_params['DTT_EVT_end'];
+				}
+				$where_params['DTT_EVT_end']  = ['<', $current_time_for_DTT_EVT_end];
+				$where_params['Event.EVT_ID'] = ['NOT IN', $event_ids];
+				break;
+			case 'active':
+				$where_params['Event.status'] = 'publish';
+				if (isset($where_params['DTT_EVT_start'])) {
+					$where_params['Datetime.DTT_EVT_start******'] = $where_params['DTT_EVT_start'];
+				}
+				if (isset($where_params['Datetime.DTT_EVT_end'])) {
+					$where_params['Datetime.DTT_EVT_end*****'] = $where_params['DTT_EVT_end'];
+				}
+				$where_params['DTT_EVT_start'] = ['<', $current_time_for_DTT_EVT_start];
+				$where_params['DTT_EVT_end']   = ['>', $current_time_for_DTT_EVT_end];
+				break;
+			case 'inactive':
+				if (isset($where_params['Event.status'])) {
+					unset($where_params['Event.status']);
+				}
+				if (isset($where_params['OR'])) {
+					$where_params['AND']['OR'] = $where_params['OR'];
+				}
+				if (isset($where_params['DTT_EVT_end'])) {
+					$where_params['AND']['DTT_EVT_end****'] = $where_params['DTT_EVT_end'];
+					unset($where_params['DTT_EVT_end']);
+				}
+				if (isset($where_params['DTT_EVT_start'])) {
+					$where_params['AND']['DTT_EVT_start'] = $where_params['DTT_EVT_start'];
+					unset($where_params['DTT_EVT_start']);
+				}
+				$where_params['AND']['Event.status'] = ['!=', 'publish'];
+				break;
+		}
+		$query_params[0]          = $where_params;
+		$query_params['group_by'] = ['dtt_year', 'dtt_month'];
+		$query_params             = $this->addOrderByQueryParams($query_params, 'DTT_EVT_start', 'DESC');
+
+		$query_interval    = EEH_DTT_Helper::get_sql_query_interval_for_offset(
+			$this->get_timezone(),
+			'DTT_EVT_start'
+		);
+		$columns_to_select = [
+			'dtt_year'      => ['YEAR(' . $query_interval . ')', '%s'],
+			'dtt_month'     => ['MONTHNAME(' . $query_interval . ')', '%s'],
+			'dtt_month_num' => ['MONTH(' . $query_interval . ')', '%s'],
+		];
+		return $this->_get_all_wpdb_results($query_params, OBJECT, $columns_to_select);
+	}
+
+
+	/**
+	 * Updates the DTT_sold attribute on each datetime (based on the registrations
+	 * for the tickets for each datetime)
+	 *
+	 * @param EE_Base_Class[]|EE_Datetime[] $datetimes
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function update_sold(array $datetimes)
+	{
+		EE_Error::doing_it_wrong(
+			__FUNCTION__,
+			esc_html__(
+				'Please use \EEM_Ticket::update_tickets_sold() instead which will in turn correctly update both the Ticket AND Datetime counts.',
+				'event_espresso'
+			),
+			'4.9.32.rc.005'
+		);
+		foreach ($datetimes as $datetime) {
+			$datetime->update_sold();
+		}
+	}
+
+
+	/**
+	 *    Gets the total number of tickets available at a particular datetime
+	 *    (does NOT take into account the datetime's spaces available)
+	 *
+	 * @param int   $DTT_ID
+	 * @param array $query_params
+	 * @return int of tickets available. If sold out, return less than 1. If infinite, returns EE_INF,  IF there are NO
+	 *             tickets attached to datetime then FALSE is returned.
+	 * @throws EE_Error
+	 * @throws ReflectionException
+	 */
+	public function sum_tickets_currently_available_at_datetime(int $DTT_ID, array $query_params = [])
+	{
+		$datetime = $this->get_one_by_ID($DTT_ID);
+		if ($datetime instanceof EE_Datetime) {
+			return $datetime->tickets_remaining($query_params);
+		}
+		return 0;
+	}
+
+
+	/**
+	 * This returns an array of counts of datetimes in the database for each Datetime status that can be queried.
+	 *
+	 * @param array $stati_to_include  If included you can restrict the statuses we return counts for by including the
+	 *                                 stati you want counts for as values in the array.  An empty array returns counts
+	 *                                 for all valid stati.
+	 * @param array $query_params      If included can be used to refine the conditions for returning the count (i.e.
+	 *                                 only for Datetimes connected to a specific event, or specific ticket.
+	 * @return array  The value returned is an array indexed by Datetime Status and the values are the counts.  The
+	 * @throws EE_Error
+	 *                                 stati used as index keys are: EE_Datetime::active EE_Datetime::upcoming
+	 *                                 EE_Datetime::expired
+	 */
+	public function get_datetime_counts_by_status(array $stati_to_include = [], array $query_params = [])
+	{
+		// only accept where conditions for this query.
+		$_where            = isset($query_params[0]) ? $query_params[0] : [];
+		$status_query_args = [
+			EE_Datetime::active   => array_merge(
+				$_where,
+				['DTT_EVT_start' => ['<', time()], 'DTT_EVT_end' => ['>', time()]]
+			),
+			EE_Datetime::upcoming => array_merge(
+				$_where,
+				['DTT_EVT_start' => ['>', time()]]
+			),
+			EE_Datetime::expired  => array_merge(
+				$_where,
+				['DTT_EVT_end' => ['<', time()]]
+			),
+		];
+		if (! empty($stati_to_include)) {
+			foreach (array_keys($status_query_args) as $status) {
+				if (! in_array($status, $stati_to_include, true)) {
+					unset($status_query_args[ $status ]);
+				}
+			}
+		}
+		// loop through and query counts for each stati.
+		$status_query_results = [];
+		foreach ($status_query_args as $status => $status_where_conditions) {
+			$status_query_results[ $status ] = EEM_Datetime::count(
+				[$status_where_conditions],
+				'DTT_ID',
+				true
+			);
+		}
+		return $status_query_results;
+	}
+
+
+	/**
+	 * Returns the specific count for a given Datetime status matching any given query_params.
+	 *
+	 * @param string $status Valid string representation for Datetime status requested. (Defaults to Active).
+	 * @param array  $query_params
+	 * @return int
+	 * @throws EE_Error
+	 */
+	public function get_datetime_count_for_status($status = EE_Datetime::active, array $query_params = [])
+	{
+		$count = $this->get_datetime_counts_by_status([$status], $query_params);
+		return ! empty($count[ $status ]) ? $count[ $status ] : 0;
+	}
+
+
+	/**
+	 * @return bool|int
+	 * @since   $VID:$
+	 */
+	private function prepModelForQuery()
+	{
+		$prev_data_prep_value = $this->get_assumption_concerning_values_already_prepared_by_model_object();
+		$this->assume_values_already_prepared_by_model_object(EEM_Base::prepared_for_use_in_db);
+		return $prev_data_prep_value;
+	}
+
+
+	/**
+	 * @param array    $query_params
+	 * @param bool|int $prev_data_prep_value
+	 * @return EE_Base_Class[]|EE_Datetime[]
+	 * @throws EE_Error
+	 * @since   $VID:$
+	 */
+	private function getDatetimesAndRestoreModel(array $query_params, $prev_data_prep_value)
+	{
+		$result = $this->get_all($query_params);
+		$this->assume_values_already_prepared_by_model_object($prev_data_prep_value);
+		return $result;
+	}
+
+
+	/**
+	 * @param array  $query_params
+	 * @param int    $limit
+	 * @param string $order_by
+	 * @param string $order
+	 * @return array
+	 * @since   $VID:$
+	 */
+	private function addDefaultQueryParams(array $query_params, $limit = 0, $order_by = 'DTT_EVT_start', $order = 'ASC')
+	{
+		$query_params = $this->addOrderByQueryParams($query_params, $order_by, $order);
+		$query_params = $this->addLimitQueryParams($query_params, $limit);
+		return $query_params;
+	}
+
+
+	/**
+	 * @param array  $query_params
+	 * @param string $default_where_conditions
+	 * @return array
+	 * @since   $VID:$
+	 */
+	private function addDefaultWhereConditions(
+		array $query_params,
+		$default_where_conditions = EEM_Base::default_where_conditions_none
+	) {
+		$query_params['default_where_conditions'] = $default_where_conditions;
+		return $query_params;
+	}
+
+
+	/**
+	 * @param array $where_params
+	 * @param bool  $include_deleted
+	 * @param bool  $include_expired
+	 * @return array
+	 * @since   $VID:$
+	 */
+	private function addDefaultWhereParams(array $where_params, bool $include_deleted = true, bool $include_expired = true)
+	{
+		$where_params = $this->addExpiredWhereParams($where_params, $include_expired);
+		$where_params = $this->addDeletedWhereParams($where_params, $include_deleted);
+		return $where_params;
+	}
+
+
+	/**
+	 * @param array $where_params
+	 * @param bool  $include_deleted
+	 * @return array
+	 * @since   $VID:$
+	 */
+	private function addDeletedWhereParams(array $where_params, bool $include_deleted = true)
+	{
+		$deleted                     = $include_deleted ? [true, false] : [false];
+		$where_params['DTT_deleted'] = ['IN', $deleted];
+		return $where_params;
+	}
+
+
+	/**
+	 * @param array $where_params
+	 * @param bool  $include_expired
+	 * @return array
+	 * @since   $VID:$
+	 */
+	private function addExpiredWhereParams(array $where_params, bool $include_expired = true)
+	{
+		if (! $include_expired) {
+			$where_params['DTT_EVT_end'] = ['>=', current_time('mysql', true)];
+		}
+		return $where_params;
+	}
+
+
+	/**
+	 * @param array $query_params
+	 * @param int   $limit
+	 * @return array
+	 * @since   $VID:$
+	 */
+	private function addLimitQueryParams(array $query_params, $limit = 0)
+	{
+		if ($limit) {
+			$query_params['limit'] = $limit;
+		}
+		return $query_params;
+	}
+
+
+	/**
+	 * @param array  $query_params
+	 * @param string $order_by
+	 * @param string $order
+	 * @return array
+	 * @since   $VID:$
+	 */
+	private function addOrderByQueryParams(array $query_params, $order_by = 'DTT_EVT_start', $order = 'ASC')
+	{
+		$order                    = $order === 'ASC' ? 'ASC' : 'DESC';
+		$valid_order_columns      = ['DTT_ID', 'DTT_EVT_start', 'DTT_EVT_end', 'DTT_order'];
+		$order_by                 = in_array($order_by, $valid_order_columns, true) ? $order_by : 'DTT_EVT_start';
+		$query_params['order_by'] = [$order_by => $order];
+		return $query_params;
+	}
 }

Spacing +20 added lines, -20 removed lines

@@ -121,7 +121,7 @@ 
                 ),
             ],
         ];
-        $this->_model_relations        = [
+        $this->_model_relations = [
             'Ticket'          => new EE_HABTM_Relation('Datetime_Ticket'),
             'Event'           => new EE_Belongs_To_Relation(),
             'Checkin'         => new EE_Has_Many_Relation(),
@@ -131,19 +131,19 @@ 
         $this->model_chain_to_password = $path_to_event_model;
         $this->_model_chain_to_wp_user = $path_to_event_model;
         // this model is generally available for reading
-        $this->_cap_restriction_generators[ EEM_Base::caps_read ]       =
+        $this->_cap_restriction_generators[EEM_Base::caps_read] =
             new EE_Restriction_Generator_Event_Related_Public(
                 $path_to_event_model
             );
-        $this->_cap_restriction_generators[ EEM_Base::caps_read_admin ] =
+        $this->_cap_restriction_generators[EEM_Base::caps_read_admin] =
             new EE_Restriction_Generator_Event_Related_Protected(
                 $path_to_event_model
             );
-        $this->_cap_restriction_generators[ EEM_Base::caps_edit ]       =
+        $this->_cap_restriction_generators[EEM_Base::caps_edit] =
             new EE_Restriction_Generator_Event_Related_Protected(
                 $path_to_event_model
             );
-        $this->_cap_restriction_generators[ EEM_Base::caps_delete ]     =
+        $this->_cap_restriction_generators[EEM_Base::caps_delete] =
             new EE_Restriction_Generator_Event_Related_Protected(
                 $path_to_event_model,
                 EEM_Base::caps_edit
@@ -185,7 +185,7 @@ 
          * @param int $end_data Unix timestamp representing now + 30 days in seconds.
          * @return int Unix timestamp
          */
-        $end_date       = apply_filters(
+        $end_date = apply_filters(
             'FHEE__EEM_Datetime__create_new_blank_datetime__end_date',
             $this->current_time_for_query('DTT_EVT_end', true) + MONTH_IN_SECONDS
         );
@@ -251,10 +251,10 @@ 
      */
     private function validateStartAndEndTimeForBlankDate(array $start_time, array $end_time)
     {
-        if (! is_array($start_time)) {
+        if ( ! is_array($start_time)) {
             throw new InvalidDataTypeException('start_time', $start_time, 'array');
         }
-        if (! is_array($end_time)) {
+        if ( ! is_array($end_time)) {
             throw new InvalidDataTypeException('end_time', $end_time, 'array');
         }
         if (count($start_time) !== 2) {
@@ -289,7 +289,7 @@ 
      */
     public function get_all_event_dates($EVT_ID = 0)
     {
-        if (! $EVT_ID) { // on add_new_event event_id gets set to 0
+        if ( ! $EVT_ID) { // on add_new_event event_id gets set to 0
             return $this->create_new_blank_datetime();
         }
         $results = $this->get_datetimes_for_event_ordered_by_DTT_order($EVT_ID);
@@ -426,7 +426,7 @@ 
             $query_params,
             EEM_Base::default_where_conditions_this_only
         );
-        $query_params         = $this->addDefaultQueryParams($query_params, $limit, 'DTT_order');
+        $query_params = $this->addDefaultQueryParams($query_params, $limit, 'DTT_order');
         return $this->getDatetimesAndRestoreModel($query_params, $prev_data_prep_value);
     }
 
@@ -587,14 +587,14 @@ 
         $query_params['group_by'] = ['dtt_year', 'dtt_month'];
         $query_params             = $this->addOrderByQueryParams($query_params, 'DTT_EVT_start', 'DESC');
 
-        $query_interval    = EEH_DTT_Helper::get_sql_query_interval_for_offset(
+        $query_interval = EEH_DTT_Helper::get_sql_query_interval_for_offset(
             $this->get_timezone(),
             'DTT_EVT_start'
         );
         $columns_to_select = [
-            'dtt_year'      => ['YEAR(' . $query_interval . ')', '%s'],
-            'dtt_month'     => ['MONTHNAME(' . $query_interval . ')', '%s'],
-            'dtt_month_num' => ['MONTH(' . $query_interval . ')', '%s'],
+            'dtt_year'      => ['YEAR('.$query_interval.')', '%s'],
+            'dtt_month'     => ['MONTHNAME('.$query_interval.')', '%s'],
+            'dtt_month_num' => ['MONTH('.$query_interval.')', '%s'],
         ];
         return $this->_get_all_wpdb_results($query_params, OBJECT, $columns_to_select);
     }
@@ -676,17 +676,17 @@ 
                 ['DTT_EVT_end' => ['<', time()]]
             ),
         ];
-        if (! empty($stati_to_include)) {
+        if ( ! empty($stati_to_include)) {
             foreach (array_keys($status_query_args) as $status) {
-                if (! in_array($status, $stati_to_include, true)) {
-                    unset($status_query_args[ $status ]);
+                if ( ! in_array($status, $stati_to_include, true)) {
+                    unset($status_query_args[$status]);
                 }
             }
         }
         // loop through and query counts for each stati.
         $status_query_results = [];
         foreach ($status_query_args as $status => $status_where_conditions) {
-            $status_query_results[ $status ] = EEM_Datetime::count(
+            $status_query_results[$status] = EEM_Datetime::count(
                 [$status_where_conditions],
                 'DTT_ID',
                 true
@@ -707,7 +707,7 @@ 
     public function get_datetime_count_for_status($status = EE_Datetime::active, array $query_params = [])
     {
         $count = $this->get_datetime_counts_by_status([$status], $query_params);
-        return ! empty($count[ $status ]) ? $count[ $status ] : 0;
+        return ! empty($count[$status]) ? $count[$status] : 0;
     }
 
 
@@ -806,7 +806,7 @@ 
      */
     private function addExpiredWhereParams(array $where_params, bool $include_expired = true)
     {
-        if (! $include_expired) {
+        if ( ! $include_expired) {
             $where_params['DTT_EVT_end'] = ['>=', current_time('mysql', true)];
         }
         return $where_params;

core/helpers/EEH_File.helper.php

Indentation +901 added lines, -901 removed lines

@@ -25,905 +25,905 @@
 class EEH_File extends EEH_Base implements EEHI_File
 {
 
-    /**
-     * @var string $_credentials_form
-     */
-    private static $_credentials_form;
-
-    /**
-     * @var WP_Filesystem_Base $_wp_filesystem
-     */
-    protected static $_wp_filesystem;
-
-
-    /**
-     * @param string|null $filepath the filepath we want to work in. If its in the
-     *                              wp uploads directory, we'll want to just use the filesystem directly.
-     *                              If not provided, we have to assume its not in the uploads directory
-     * @return WP_Filesystem_Base
-     */
-    private static function _get_wp_filesystem($filepath = null)
-    {
-        if (apply_filters(
-            'FHEE__EEH_File___get_wp_filesystem__allow_using_filesystem_direct',
-            $filepath && EEH_File::is_in_uploads_folder($filepath),
-            $filepath
-        )) {
-            return EEH_File::loadAlternateWpFileSystem();
-        }
-        return EEH_File::loadWpFileSystem();
-    }
-
-
-    /**
-     * @return WP_Filesystem_Base
-     */
-    private static function loadAlternateWpFileSystem()
-    {
-        if (! EEH_File::$_wp_filesystem instanceof WP_Filesystem_Base) {
-            require_once(ABSPATH . 'wp-admin/includes/class-wp-filesystem-base.php');
-            $method             = 'direct';
-            $wp_filesystem_file =
-                apply_filters(
-                    'filesystem_method_file',
-                    ABSPATH . 'wp-admin/includes/class-wp-filesystem-' . $method . '.php',
-                    $method
-                );
-            // added the following validation logic
-            // because we allow the filesystem filepath to be filtered,
-            // and are loading whatever file the path pointed to,
-            // but we were not validating things in any way :scream_emoji:
-            $valid_wp_filesystem_types = [
-                'direct'     => 'WP_Filesystem_Direct',
-                'ftpext'     => 'WP_Filesystem_FTPext',
-                'ftpsockets' => 'WP_Filesystem_ftpsockets',
-                'ssh2'       => 'WP_Filesystem_SSH2',
-            ];
-            $valid                     = false;
-            $wp_filesystem_class       = '';
-            foreach ($valid_wp_filesystem_types as $method => $filesystem_class) {
-                // if file path matches for one of valid types, then toggle $valid to true
-                if (strpos($wp_filesystem_file, $method) > 0) {
-                    $valid               = true;
-                    $wp_filesystem_class = $filesystem_class;
-                }
-            }
-            if (! $valid || ! file_exists($wp_filesystem_file)) {
-                EE_Error::add_error(
-                    sprintf(
-                        __(
-                            'The supplied WP Filesystem filepath "%1$s" is either missing or invalid.',
-                            'event_espresso'
-                        ),
-                        $wp_filesystem_file
-                    ),
-                    __FILE__,
-                    __FUNCTION__,
-                    __LINE__
-                );
-            }
-            // check constants defined, just like in the wp-admin/includes/file.php WP_Filesystem()
-            if (! defined('FS_CHMOD_DIR')) {
-                define('FS_CHMOD_DIR', (fileperms(ABSPATH) & 0775 | 0755));
-            }
-            if (! defined('FS_CHMOD_FILE')) {
-                define('FS_CHMOD_FILE', (fileperms(ABSPATH . 'index.php') & 0775 | 0644));
-            }
-            require_once($wp_filesystem_file);
-            EEH_File::$_wp_filesystem = new $wp_filesystem_class([]);
-        }
-        return EEH_File::$_wp_filesystem;
-    }
-
-
-    /**
-     * @return WP_Filesystem_Base
-     */
-    private static function loadWpFileSystem()
-    {
-        global $wp_filesystem;
-        // no filesystem setup ???
-        if (! $wp_filesystem instanceof WP_Filesystem_Base) {
-            // if some eager beaver's just trying to get in there too early...
-            // let them do it, because we are one of those eager beavers! :P
-            /**
-             * more explanations are probably merited. http://codex.wordpress.org/Filesystem_API#Initializing_WP_Filesystem_Base
-             * says WP_Filesystem should be used after 'wp_loaded', but currently EE's activation process
-             * is setup to mostly happen on 'init', and refactoring to have it happen on
-             * 'wp_loaded' is too much work on a BETA milestone.
-             * So this fix is expected to work if the WP files are owned by the server user,
-             * but probably not if the user needs to enter their FTP credentials to modify files
-             * and there may be troubles if the WP files are owned by a different user
-             * than the server user. But both of these issues should exist in 4.4 and earlier too
-             */
-            if (false && ! did_action('wp_loaded')) {
-                $msg =
-                    __(
-                        'An attempt to access and/or write to a file on the server could not be completed due to a lack of sufficient credentials.',
-                        'event_espresso'
-                    );
-                if (WP_DEBUG) {
-                    $msg .= '<br />' . __(
-                        'The WP Filesystem can not be accessed until after the "wp_loaded" hook has run, so it\'s best not to attempt access until the "admin_init" hookpoint.',
-                        'event_espresso'
-                    );
-                }
-                EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
-            }
-            // should be loaded if we are past the wp_loaded hook...
-            if (! function_exists('WP_Filesystem') || ! function_exists('submit_button')) {
-                require_once(ABSPATH . 'wp-admin/includes/file.php');
-                require_once(ABSPATH . 'wp-admin/includes/template.php');
-            }
-            // turn on output buffering so that we can capture the credentials form
-            ob_start();
-            $credentials = request_filesystem_credentials(false);
-            // store credentials form for the time being
-            EEH_File::$_credentials_form = ob_get_clean();
-            // if credentials do NOT exist
-            if ($credentials === false) {
-                add_action('admin_notices', ['EEH_File', 'display_request_filesystem_credentials_form'], 999);
-                EE_Error::add_error(
-                    __(
-                        'An attempt to access and/or write to a file on the server could not be completed due to a lack of sufficient credentials.',
-                        'event_espresso'
-                    ),
-                    __FILE__,
-                    __FUNCTION__,
-                    __LINE__
-                );
-            }
-            // basically check for direct or previously configured access
-            if (! WP_Filesystem($credentials)
-                && is_wp_error($wp_filesystem->errors)
-                && $wp_filesystem->errors->get_error_code()
-            ) {
-                add_action('admin_notices', ['EEH_File', 'display_request_filesystem_credentials_form'], 999);
-                EE_Error::add_error(
-                    sprintf(
-                        __('WP Filesystem Error: $1%s', 'event_espresso'),
-                        $wp_filesystem->errors->get_error_message()
-                    ),
-                    __FILE__,
-                    __FUNCTION__,
-                    __LINE__
-                );
-            }
-        }
-        return $wp_filesystem;
-    }
-
-
-    /**
-     * display_request_filesystem_credentials_form
-     */
-    public static function display_request_filesystem_credentials_form()
-    {
-        if (! empty(EEH_File::$_credentials_form)) {
-            echo '<div class="updated espresso-notices-attention"><p>' . EEH_File::$_credentials_form . '</p></div>';
-        }
-    }
-
-
-    /**
-     *    verify_filepath_and_permissions
-     *    checks that a file is readable and has sufficient file permissions set to access
-     *
-     * @access public
-     * @param string $full_file_path - full server path to the folder or file
-     * @param string $file_name      - name of file if checking a file
-     * @param string $file_ext       - file extension (ie: "php") if checking a file
-     * @param string $type_of_file   - general type of file (ie: "module"), this is only used to improve error messages
-     * @return bool
-     */
-    public static function verify_filepath_and_permissions(
-        $full_file_path = '',
-        $file_name = '',
-        $file_ext = '',
-        $type_of_file = ''
-    ) {
-        // load WP_Filesystem and set file permissions
-        $wp_filesystem  = EEH_File::_get_wp_filesystem($full_file_path);
-        $full_file_path = EEH_File::standardise_directory_separators($full_file_path);
-        if (! $wp_filesystem->is_readable(EEH_File::convert_local_filepath_to_remote_filepath($full_file_path))) {
-            $file_name = ! empty($type_of_file) ? $file_name . ' ' . $type_of_file : $file_name;
-            $file_name .= ! empty($file_ext) ? ' file' : ' folder';
-            $msg       = sprintf(
-                __(
-                    'The requested %1$s could not be found or is not readable, possibly due to an incorrect filepath, or incorrect file permissions.%2$s',
-                    'event_espresso'
-                ),
-                $file_name,
-                '<br />'
-            );
-            if (EEH_File::exists($full_file_path)) {
-                $msg .= EEH_File::_permissions_error_for_unreadable_filepath($full_file_path, $type_of_file);
-            } else {
-                // no file permissions means the file was not found
-                $msg .= sprintf(
-                    __('Please ensure the following path is correct: "%s".', 'event_espresso'),
-                    $full_file_path
-                );
-            }
-            if (defined('WP_DEBUG') && WP_DEBUG) {
-                EE_Error::add_error($msg . '||' . $msg, __FILE__, __FUNCTION__, __LINE__);
-            }
-            return false;
-        }
-        return true;
-    }
-
-
-    /**
-     * _permissions_error_for_unreadable_filepath - attempts to determine why permissions are set incorrectly for a
-     * file or folder
-     *
-     * @access private
-     * @param string $full_file_path - full server path to the folder or file
-     * @param string $type_of_file   - general type of file (ie: "module"), this is only used to improve error messages
-     * @return string
-     */
-    private static function _permissions_error_for_unreadable_filepath($full_file_path = '', $type_of_file = '')
-    {
-        // load WP_Filesystem and set file permissions
-        $wp_filesystem = EEH_File::_get_wp_filesystem($full_file_path);
-        // check file permissions
-        $perms = $wp_filesystem->getchmod(EEH_File::convert_local_filepath_to_remote_filepath($full_file_path));
-        if ($perms) {
-            // file permissions exist, but way be set incorrectly
-            $type_of_file = ! empty($type_of_file) ? $type_of_file . ' ' : '';
-            $type_of_file .= ! empty($type_of_file) ? 'file' : 'folder';
-            return ' ' . sprintf(
-                __(
-                    'File permissions for the requested %1$s are currently set at "%2$s". The recommended permissions are 644 for files and 755 for folders.',
-                    'event_espresso'
-                ),
-                $type_of_file,
-                $perms
-            );
-        } else {
-            // file exists but file permissions could not be read ?!?!
-            return ' ' . sprintf(
-                __(
-                    'Please ensure that the server and/or PHP configuration allows the current process to access the following file: "%s".',
-                    'event_espresso'
-                ),
-                $full_file_path
-            );
-        }
-    }
-
-
-    /**
-     * ensure_folder_exists_and_is_writable
-     * ensures that a folder exists and is writable, will attempt to create folder if it does not exist
-     * Also ensures all the parent folders exist, and if not tries to create them.
-     * Also, if this function creates the folder, adds a .htaccess file and index.html file
-     *
-     * @param string $folder
-     * @return bool false if folder isn't writable; true if it exists and is writeable,
-     */
-    public static function ensure_folder_exists_and_is_writable($folder = '')
-    {
-        if (empty($folder)) {
-            return false;
-        }
-        // remove ending /
-        $folder        = EEH_File::standardise_directory_separators(rtrim($folder, '/\\'));
-        $parent_folder = EEH_File::get_parent_folder($folder);
-        // add / to folder
-        $folder        = EEH_File::end_with_directory_separator($folder);
-        $wp_filesystem = EEH_File::_get_wp_filesystem($folder);
-        $remote_dir    = EEH_File::convert_local_filepath_to_remote_filepath($folder);
-        if (! $wp_filesystem->is_dir($remote_dir)) {
-            // ok so it doesn't exist. Does its parent? Can we write to it?
-            if (! EEH_File::ensure_folder_exists_and_is_writable($parent_folder)) {
-                return false;
-            }
-            if (! EEH_File::verify_is_writable($parent_folder, 'folder')) {
-                return false;
-            }
-            if (! $wp_filesystem->mkdir(EEH_File::convert_local_filepath_to_remote_filepath($folder))) {
-                if (defined('WP_DEBUG') && WP_DEBUG) {
-                    $msg = sprintf(__('"%s" could not be created.', 'event_espresso'), $folder);
-                    $msg .= EEH_File::_permissions_error_for_unreadable_filepath($folder);
-                    EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
-                }
-                return false;
-            }
-            EEH_File::add_index_file($folder);
-        } elseif (! EEH_File::verify_is_writable($folder, 'folder')) {
-            return false;
-        }
-        return true;
-    }
-
-
-    /**
-     * verify_is_writable - checks if a file or folder is writable
-     *
-     * @param string $full_path      - full server path to file or folder
-     * @param string $file_or_folder - whether checking a file or folder
-     * @return bool
-     */
-    public static function verify_is_writable($full_path = '', $file_or_folder = 'folder')
-    {
-        // load WP_Filesystem and set file permissions
-        $wp_filesystem = EEH_File::_get_wp_filesystem($full_path);
-        $full_path     = EEH_File::standardise_directory_separators($full_path);
-        $remote_path   = EEH_File::convert_local_filepath_to_remote_filepath($full_path);
-        $remote_path   = rtrim($remote_path, '/\\');
-        if (! $wp_filesystem->is_writable($remote_path)) {
-            if (defined('WP_DEBUG') && WP_DEBUG) {
-                $msg = sprintf(__('The "%1$s" %2$s is not writable.', 'event_espresso'), $full_path, $file_or_folder);
-                $msg .= EEH_File::_permissions_error_for_unreadable_filepath($full_path);
-                EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
-            }
-            return false;
-        }
-        return true;
-    }
-
-
-    /**
-     * ensure_file_exists_and_is_writable
-     * ensures that a file exists and is writable, will attempt to create file if it does not exist.
-     * Also ensures all the parent folders exist, and if not tries to create them.
-     *
-     * @param string $full_file_path
-     * @return bool
-     */
-    public static function ensure_file_exists_and_is_writable($full_file_path = '')
-    {
-        // load WP_Filesystem and set file permissions
-        $wp_filesystem  = EEH_File::_get_wp_filesystem($full_file_path);
-        $full_file_path = EEH_File::standardise_directory_separators($full_file_path);
-        $parent_folder  = EEH_File::get_parent_folder($full_file_path);
-        if (! EEH_File::exists($full_file_path)) {
-            if (! EEH_File::ensure_folder_exists_and_is_writable($parent_folder)) {
-                return false;
-            }
-            if (! $wp_filesystem->touch(EEH_File::convert_local_filepath_to_remote_filepath($full_file_path))) {
-                if (defined('WP_DEBUG') && WP_DEBUG) {
-                    $msg = sprintf(__('The "%s" file could not be created.', 'event_espresso'), $full_file_path);
-                    $msg .= EEH_File::_permissions_error_for_unreadable_filepath($full_file_path);
-                    EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
-                }
-                return false;
-            }
-        }
-        if (! EEH_File::verify_is_writable($full_file_path, 'file')) {
-            return false;
-        }
-        return true;
-    }
-
-
-    /**
-     * Gets the parent folder. If provided with file, gets the folder that contains it.
-     * If provided a folder, gets its parent folder.
-     *
-     * @param string $file_or_folder_path
-     * @return string parent folder, ENDING with a directory separator
-     */
-    public static function get_parent_folder($file_or_folder_path)
-    {
-        // find the last /, ignoring a / on the very end
-        // eg if given "/var/something/somewhere/", we want to get "somewhere"'s
-        // parent folder, "/var/something/"
-        $ds = strlen($file_or_folder_path) > 1
-            ? strrpos($file_or_folder_path, '/', -2)
-            : strlen($file_or_folder_path);
-        return substr($file_or_folder_path, 0, $ds + 1);
-    }
-
-
-    /**
-     * get_file_contents
-     *
-     * @param string $full_file_path
-     * @return string
-     */
-    public static function get_file_contents($full_file_path = '')
-    {
-        $full_file_path = EEH_File::standardise_directory_separators($full_file_path);
-        if (EEH_File::verify_filepath_and_permissions(
-            $full_file_path,
-            EEH_File::get_filename_from_filepath($full_file_path),
-            EEH_File::get_file_extension($full_file_path)
-        )) {
-            // load WP_Filesystem and set file permissions
-            $wp_filesystem = EEH_File::_get_wp_filesystem($full_file_path);
-            return $wp_filesystem->get_contents(EEH_File::convert_local_filepath_to_remote_filepath($full_file_path));
-        }
-        return '';
-    }
-
-
-    /**
-     * write_file
-     *
-     * @param string $full_file_path
-     * @param string $file_contents - the content to be written to the file
-     * @param string $file_type
-     * @return bool
-     */
-    public static function write_to_file($full_file_path = '', $file_contents = '', $file_type = '')
-    {
-        $full_file_path = EEH_File::standardise_directory_separators($full_file_path);
-        $file_type      = ! empty($file_type) ? rtrim($file_type, ' ') . ' ' : '';
-        $folder         = EEH_File::remove_filename_from_filepath($full_file_path);
-        if (! EEH_File::verify_is_writable($folder, 'folder')) {
-            if (defined('WP_DEBUG') && WP_DEBUG) {
-                $msg =
-                    sprintf(
-                        __('The %1$sfile located at "%2$s" is not writable.', 'event_espresso'),
-                        $file_type,
-                        $full_file_path
-                    );
-                $msg .= EEH_File::_permissions_error_for_unreadable_filepath($full_file_path);
-                EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
-            }
-            return false;
-        }
-        // load WP_Filesystem and set file permissions
-        $wp_filesystem = EEH_File::_get_wp_filesystem($full_file_path);
-        // write the file
-        if (! $wp_filesystem->put_contents(
-            EEH_File::convert_local_filepath_to_remote_filepath($full_file_path),
-            $file_contents
-        )) {
-            if (defined('WP_DEBUG') && WP_DEBUG) {
-                $msg =
-                    sprintf(
-                        __('The %1$sfile located at "%2$s" could not be written to.', 'event_espresso'),
-                        $file_type,
-                        $full_file_path
-                    );
-                $msg .= EEH_File::_permissions_error_for_unreadable_filepath($full_file_path, 'f');
-                EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
-            }
-            return false;
-        }
-        return true;
-    }
-
-
-    /**
-     * Wrapper for WP_Filesystem_Base::delete
-     *
-     * @param string         $filepath
-     * @param boolean        $recursive
-     * @param boolean|string $type 'd' for directory, 'f' for file
-     * @return boolean
-     */
-    public static function delete($filepath, $recursive = false, $type = false)
-    {
-        $wp_filesystem = EEH_File::_get_wp_filesystem();
-        return $wp_filesystem->delete($filepath, $recursive, $type);
-    }
-
-
-    /**
-     * exists
-     * checks if a file exists using the WP filesystem
-     *
-     * @param string $full_file_path
-     * @return bool
-     */
-    public static function exists($full_file_path = '')
-    {
-        $wp_filesystem = EEH_File::_get_wp_filesystem($full_file_path);
-        return $wp_filesystem->exists(EEH_File::convert_local_filepath_to_remote_filepath($full_file_path));
-    }
-
-
-    /**
-     * is_readable
-     * checks if a file is_readable using the WP filesystem
-     *
-     * @param string $full_file_path
-     * @return bool
-     */
-    public static function is_readable($full_file_path = '')
-    {
-        $wp_filesystem = EEH_File::_get_wp_filesystem($full_file_path);
-        return $wp_filesystem->is_readable(EEH_File::convert_local_filepath_to_remote_filepath($full_file_path));
-    }
-
-
-    /**
-     * remove_filename_from_filepath
-     * given a full path to a file including the filename itself, this removes  the filename and returns the path, up
-     * to, but NOT including the filename OR slash
-     *
-     * @param string $full_file_path
-     * @return string
-     */
-    public static function remove_filename_from_filepath($full_file_path = '')
-    {
-        return pathinfo($full_file_path, PATHINFO_DIRNAME);
-    }
-
-
-    /**
-     * get_filename_from_filepath. Arguably the same as basename()
-     *
-     * @param string $full_file_path
-     * @return string
-     */
-    public static function get_filename_from_filepath($full_file_path = '')
-    {
-        return pathinfo($full_file_path, PATHINFO_BASENAME);
-    }
-
-
-    /**
-     * get_file_extension
-     *
-     * @param string $full_file_path
-     * @return string
-     */
-    public static function get_file_extension($full_file_path = '')
-    {
-        return pathinfo($full_file_path, PATHINFO_EXTENSION);
-    }
-
-
-    /**
-     * add_htaccess_deny_from_all so the web server cannot access this folder
-     *
-     * @param string $folder
-     * @return bool
-     */
-    public static function add_htaccess_deny_from_all($folder = '')
-    {
-        $folder = EEH_File::standardise_and_end_with_directory_separator($folder);
-        if (! EEH_File::exists($folder . '.htaccess')) {
-            if (! EEH_File::write_to_file($folder . '.htaccess', 'deny from all', '.htaccess')) {
-                return false;
-            }
-        }
-
-        return true;
-    }
-
-
-    /**
-     * Adds an index file to this folder, so folks can't list all the file's contents
-     *
-     * @param string $folder
-     * @return boolean
-     */
-    public static function add_index_file($folder)
-    {
-        $folder = EEH_File::standardise_and_end_with_directory_separator($folder);
-        if (! EEH_File::exists($folder . 'index.php')) {
-            if (! EEH_File::write_to_file(
-                $folder . 'index.php',
-                'You are not permitted to read from this folder',
-                '.php'
-            )) {
-                return false;
-            }
-        }
-        return true;
-    }
-
-
-    /**
-     * Given that the file in $file_path has the normal name, (ie, CLASSNAME.whatever.php),
-     * extract that classname.
-     *
-     * @param string $file_path
-     * @return string
-     */
-    public static function get_classname_from_filepath_with_standard_filename($file_path)
-    {
-        // extract file from path
-        $filename = basename($file_path);
-        // now remove the first period and everything after
-        $pos_of_first_period = strpos($filename, '.');
-        return substr($filename, 0, $pos_of_first_period);
-    }
-
-
-    /**
-     * standardise_directory_separators
-     *  convert all directory separators in a file path.
-     *
-     * @param string $file_path
-     * @param bool   $rtrim will remove trailing backslash
-     * @return string
-     */
-    public static function standardise_directory_separators($file_path, $rtrim = false)
-    {
-        $file_path = $rtrim ? rtrim($file_path, '/\\') : $file_path;
-        return str_replace(['\\', '/'], '/', $file_path);
-    }
-
-
-    /**
-     * end_with_directory_separator
-     *  ensures that file path ends with '/'
-     *
-     * @param string $file_path
-     * @return string
-     */
-    public static function end_with_directory_separator($file_path)
-    {
-        return rtrim($file_path, '/\\') . '/';
-    }
-
-
-    /**
-     * shorthand for both EEH_FIle::end_with_directory_separator AND EEH_File::standardise_directory_separators
-     *
-     * @param $file_path
-     * @return string
-     */
-    public static function standardise_and_end_with_directory_separator($file_path)
-    {
-        return self::end_with_directory_separator(self::standardise_directory_separators($file_path));
-    }
-
-
-    /**
-     * takes the folder name (with or without trailing slash) and finds the files it in,
-     * and what the class's name inside of each should be.
-     *
-     * @param array   $folder_paths
-     * @param boolean $index_numerically if TRUE, the returned array will be indexed numerically;
-     *                                   if FALSE (Default), returned array will be indexed by the filenames minus
-     *                                   extensions. Set it TRUE if you know there are files in the directory with the
-     *                                   same name but different extensions
-     * @return array if $index_numerically == TRUE keys are numeric ,
-     *                                   if $index_numerically == FALSE (Default) keys are what the class names SHOULD
-     *                                   be; and values are their file paths
-     */
-    public static function get_contents_of_folders($folder_paths = [], $index_numerically = false)
-    {
-        $class_to_folder_path = [];
-        foreach ($folder_paths as $folder_path) {
-            $folder_path = self::standardise_and_end_with_directory_separator($folder_path);
-            // load WP_Filesystem and set file permissions
-            $files_in_folder = glob($folder_path . '*.php');
-            $class_to_folder_path = [];
-            if ($files_in_folder) {
-                foreach ($files_in_folder as $file_path) {
-                    // only add files, not folders
-                    if (! is_dir($file_path)) {
-                        if ($index_numerically) {
-                            $class_to_folder_path[] = $file_path;
-                        } else {
-                            $classname =
-                                self::get_classname_from_filepath_with_standard_filename($file_path);
-                            $class_to_folder_path[ $classname ] = $file_path;
-                        }
-                    }
-                }
-            }
-        }
-        return $class_to_folder_path;
-    }
-
-
-    /**
-     * Copies a file. Mostly a wrapper of WP_Filesystem::copy
-     *
-     * @param string  $source_file
-     * @param string  $destination_file
-     * @param boolean $overwrite
-     * @return boolean success
-     */
-    public static function copy($source_file, $destination_file, $overwrite = false)
-    {
-        $source_file      = EEH_File::validateFileForCopyOrMove($source_file);
-        $destination_file = EEH_File::validateFolderForCopyOrMove($destination_file);
-        if (! $source_file || ! $destination_file) {
-            return false;
-        }
-        // load WP_Filesystem and set file permissions
-        $wp_filesystem = EEH_File::_get_wp_filesystem($destination_file);
-        // write the file
-        $copied = $wp_filesystem->copy(
-            EEH_File::convert_local_filepath_to_remote_filepath($source_file),
-            EEH_File::convert_local_filepath_to_remote_filepath($destination_file),
-            $overwrite
-        );
-        if (! $copied) {
-            if (defined('WP_DEBUG') && WP_DEBUG) {
-                $msg = sprintf(
-                    __(
-                        'Attempted writing to file %1$s, but could not, probably because of permissions issues',
-                        'event_espresso'
-                    ),
-                    $source_file
-                );
-                $msg .= EEH_File::_permissions_error_for_unreadable_filepath($source_file, 'f');
-                EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
-            }
-            return false;
-        }
-        return true;
-    }
-
-
-    /**
-     * Reports whether or not the filepath is in the EE uploads folder or not
-     *
-     * @param string $filepath
-     * @return boolean
-     */
-    public static function is_in_uploads_folder($filepath)
-    {
-        $uploads = wp_upload_dir();
-        return strpos($filepath, $uploads['basedir']) === 0;
-    }
-
-
-    /**
-     * Given a "local" filepath (what you probably thought was the only filepath),
-     * converts it into a "remote" filepath (the filepath the currently-in-use
-     * $wp_filesystem needs to use access the folder or file).
-     * See http://wordpress.stackexchange.com/questions/124900/using-wp-filesystem-in-plugins
-     *
-     * @param string $local_filepath the filepath to the folder/file locally
-     * @return string the remote filepath (eg the filepath the filesystem method, eg
-     *                               ftp or ssh, will use to access the folder
-     */
-    public static function convert_local_filepath_to_remote_filepath($local_filepath)
-    {
-        $wp_filesystem = EEH_File::_get_wp_filesystem($local_filepath);
-        return str_replace(WP_CONTENT_DIR . '/', $wp_filesystem->wp_content_dir(), $local_filepath);
-    }
-
-
-    /**
-     * wrapper for WP_Filesystem::chmod()
-     *
-     * @param string    $file      Path to the file.
-     * @param int|false $mode      Optional. The permissions as octal number, usually 0644 for files,
-     *                             0755 for directories. Default false.
-     * @param bool      $recursive Optional. If set to true, changes file permissions recursively.
-     *                             Default false.
-     * @return bool True on success, false on failure.
-     */
-    public static function chmod($file, $mode = false, $recursive = false)
-    {
-        $wp_filesystem = EEH_File::_get_wp_filesystem($file);
-        return $wp_filesystem->chmod($file, $mode, $recursive);
-    }
-
-
-    /**
-     * wrapper for WP_Filesystem::getchmod()
-     *
-     * @param string $file Path to the file.
-     * @return string Mode of the file (the last 3 digits).
-     */
-    public static function permissions($file)
-    {
-        $wp_filesystem = EEH_File::_get_wp_filesystem($file);
-        return $wp_filesystem->getchmod($file);
-    }
-
-
-    /**
-     * wrapper for WP_Filesystem::owner()
-     *
-     * @param string $file Path to the file.
-     * @return string|false Username of the owner on success, false on failure.
-     */
-    public static function owner($file)
-    {
-        $wp_filesystem = EEH_File::_get_wp_filesystem($file);
-        return $wp_filesystem->owner($file);
-    }
-
-
-    /**
-     * wrapper for WP_Filesystem::group()
-     *
-     * @param string $file Path to the file.
-     * @return string|false The group on success, false on failure.
-     */
-    public static function group($file)
-    {
-        $wp_filesystem = EEH_File::_get_wp_filesystem($file);
-        return $wp_filesystem->group($file);
-    }
-
-
-    /**
-     * wrapper for WP_Filesystem::move()
-     *
-     * @param string $source      Path to the source file.
-     * @param string $destination Path to the destination file.
-     * @param bool   $overwrite   Optional. Whether to overwrite the destination file if it exists.
-     *                            Default false.
-     * @return bool True on success, false on failure.
-     */
-    public static function move($source, $destination, $overwrite = false)
-    {
-        // throw new RuntimeException("source: {$source} && destination: {$destination}");
-        $source      = EEH_File::validateFileForCopyOrMove($source);
-        $destination = EEH_File::validateFolderForCopyOrMove($destination);
-        if (! $source || ! $destination) {
-            return false;
-        }
-        $wp_filesystem = EEH_File::_get_wp_filesystem($source);
-        if ($wp_filesystem->move($source, $destination, $overwrite)) {
-            return true;
-        }
-        if (defined('WP_DEBUG') && WP_DEBUG) {
-            $file        = EEH_File::convert_local_filepath_to_remote_filepath($source);
-            $owner       = EEH_File::owner($file);
-            $group       = EEH_File::group($file);
-            $permissions = EEH_File::permissions($file);
-            EE_Error::add_error(
-                sprintf(
-                    esc_html__(
-                        'Unable to move the file "%1$s" to new location (possible permissions errors). The existing "owner:group permissions" for the file are: "%2$s"',
-                        'event_espresso'
-                    ),
-                    $destination,
-                    "{$owner}:{$group} $permissions"
-                ),
-                __FILE__,
-                __FUNCTION__,
-                __LINE__
-            );
-        }
-        return false;
-    }
-
-
-    /**
-     * @param string $source_file
-     * @return string
-     */
-    private static function validateFileForCopyOrMove($source_file)
-    {
-        $full_source_path = EEH_File::standardise_directory_separators($source_file);
-        if (! EEH_File::exists($full_source_path)) {
-            if (defined('WP_DEBUG') && WP_DEBUG) {
-                $msg =
-                    sprintf(
-                        __('The file located at "%2$s" is not readable or doesn\'t exist.', 'event_espresso'),
-                        '',
-                        $full_source_path
-                    );
-                $msg .= EEH_File::_permissions_error_for_unreadable_filepath($full_source_path);
-                EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
-            }
-            return '';
-        }
-        return $full_source_path;
-    }
-
-
-    /**
-     * @param string $destination_file
-     * @return string
-     */
-    private static function validateFolderForCopyOrMove($destination_file)
-    {
-        $full_dest_path = EEH_File::standardise_directory_separators($destination_file);
-        $folder         = EEH_File::remove_filename_from_filepath($full_dest_path);
-        EEH_File::ensure_folder_exists_and_is_writable($folder);
-        if (! EEH_File::verify_is_writable($folder, 'folder')) {
-            if (defined('WP_DEBUG') && WP_DEBUG) {
-                $msg = sprintf(
-                    __('The file located at "%2$s" is not writable.', 'event_espresso'),
-                    '',
-                    $full_dest_path
-                );
-                $msg .= EEH_File::_permissions_error_for_unreadable_filepath($full_dest_path);
-                EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
-            }
-            return '';
-        }
-        return $full_dest_path;
-    }
+	/**
+	 * @var string $_credentials_form
+	 */
+	private static $_credentials_form;
+
+	/**
+	 * @var WP_Filesystem_Base $_wp_filesystem
+	 */
+	protected static $_wp_filesystem;
+
+
+	/**
+	 * @param string|null $filepath the filepath we want to work in. If its in the
+	 *                              wp uploads directory, we'll want to just use the filesystem directly.
+	 *                              If not provided, we have to assume its not in the uploads directory
+	 * @return WP_Filesystem_Base
+	 */
+	private static function _get_wp_filesystem($filepath = null)
+	{
+		if (apply_filters(
+			'FHEE__EEH_File___get_wp_filesystem__allow_using_filesystem_direct',
+			$filepath && EEH_File::is_in_uploads_folder($filepath),
+			$filepath
+		)) {
+			return EEH_File::loadAlternateWpFileSystem();
+		}
+		return EEH_File::loadWpFileSystem();
+	}
+
+
+	/**
+	 * @return WP_Filesystem_Base
+	 */
+	private static function loadAlternateWpFileSystem()
+	{
+		if (! EEH_File::$_wp_filesystem instanceof WP_Filesystem_Base) {
+			require_once(ABSPATH . 'wp-admin/includes/class-wp-filesystem-base.php');
+			$method             = 'direct';
+			$wp_filesystem_file =
+				apply_filters(
+					'filesystem_method_file',
+					ABSPATH . 'wp-admin/includes/class-wp-filesystem-' . $method . '.php',
+					$method
+				);
+			// added the following validation logic
+			// because we allow the filesystem filepath to be filtered,
+			// and are loading whatever file the path pointed to,
+			// but we were not validating things in any way :scream_emoji:
+			$valid_wp_filesystem_types = [
+				'direct'     => 'WP_Filesystem_Direct',
+				'ftpext'     => 'WP_Filesystem_FTPext',
+				'ftpsockets' => 'WP_Filesystem_ftpsockets',
+				'ssh2'       => 'WP_Filesystem_SSH2',
+			];
+			$valid                     = false;
+			$wp_filesystem_class       = '';
+			foreach ($valid_wp_filesystem_types as $method => $filesystem_class) {
+				// if file path matches for one of valid types, then toggle $valid to true
+				if (strpos($wp_filesystem_file, $method) > 0) {
+					$valid               = true;
+					$wp_filesystem_class = $filesystem_class;
+				}
+			}
+			if (! $valid || ! file_exists($wp_filesystem_file)) {
+				EE_Error::add_error(
+					sprintf(
+						__(
+							'The supplied WP Filesystem filepath "%1$s" is either missing or invalid.',
+							'event_espresso'
+						),
+						$wp_filesystem_file
+					),
+					__FILE__,
+					__FUNCTION__,
+					__LINE__
+				);
+			}
+			// check constants defined, just like in the wp-admin/includes/file.php WP_Filesystem()
+			if (! defined('FS_CHMOD_DIR')) {
+				define('FS_CHMOD_DIR', (fileperms(ABSPATH) & 0775 | 0755));
+			}
+			if (! defined('FS_CHMOD_FILE')) {
+				define('FS_CHMOD_FILE', (fileperms(ABSPATH . 'index.php') & 0775 | 0644));
+			}
+			require_once($wp_filesystem_file);
+			EEH_File::$_wp_filesystem = new $wp_filesystem_class([]);
+		}
+		return EEH_File::$_wp_filesystem;
+	}
+
+
+	/**
+	 * @return WP_Filesystem_Base
+	 */
+	private static function loadWpFileSystem()
+	{
+		global $wp_filesystem;
+		// no filesystem setup ???
+		if (! $wp_filesystem instanceof WP_Filesystem_Base) {
+			// if some eager beaver's just trying to get in there too early...
+			// let them do it, because we are one of those eager beavers! :P
+			/**
+			 * more explanations are probably merited. http://codex.wordpress.org/Filesystem_API#Initializing_WP_Filesystem_Base
+			 * says WP_Filesystem should be used after 'wp_loaded', but currently EE's activation process
+			 * is setup to mostly happen on 'init', and refactoring to have it happen on
+			 * 'wp_loaded' is too much work on a BETA milestone.
+			 * So this fix is expected to work if the WP files are owned by the server user,
+			 * but probably not if the user needs to enter their FTP credentials to modify files
+			 * and there may be troubles if the WP files are owned by a different user
+			 * than the server user. But both of these issues should exist in 4.4 and earlier too
+			 */
+			if (false && ! did_action('wp_loaded')) {
+				$msg =
+					__(
+						'An attempt to access and/or write to a file on the server could not be completed due to a lack of sufficient credentials.',
+						'event_espresso'
+					);
+				if (WP_DEBUG) {
+					$msg .= '<br />' . __(
+						'The WP Filesystem can not be accessed until after the "wp_loaded" hook has run, so it\'s best not to attempt access until the "admin_init" hookpoint.',
+						'event_espresso'
+					);
+				}
+				EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
+			}
+			// should be loaded if we are past the wp_loaded hook...
+			if (! function_exists('WP_Filesystem') || ! function_exists('submit_button')) {
+				require_once(ABSPATH . 'wp-admin/includes/file.php');
+				require_once(ABSPATH . 'wp-admin/includes/template.php');
+			}
+			// turn on output buffering so that we can capture the credentials form
+			ob_start();
+			$credentials = request_filesystem_credentials(false);
+			// store credentials form for the time being
+			EEH_File::$_credentials_form = ob_get_clean();
+			// if credentials do NOT exist
+			if ($credentials === false) {
+				add_action('admin_notices', ['EEH_File', 'display_request_filesystem_credentials_form'], 999);
+				EE_Error::add_error(
+					__(
+						'An attempt to access and/or write to a file on the server could not be completed due to a lack of sufficient credentials.',
+						'event_espresso'
+					),
+					__FILE__,
+					__FUNCTION__,
+					__LINE__
+				);
+			}
+			// basically check for direct or previously configured access
+			if (! WP_Filesystem($credentials)
+				&& is_wp_error($wp_filesystem->errors)
+				&& $wp_filesystem->errors->get_error_code()
+			) {
+				add_action('admin_notices', ['EEH_File', 'display_request_filesystem_credentials_form'], 999);
+				EE_Error::add_error(
+					sprintf(
+						__('WP Filesystem Error: $1%s', 'event_espresso'),
+						$wp_filesystem->errors->get_error_message()
+					),
+					__FILE__,
+					__FUNCTION__,
+					__LINE__
+				);
+			}
+		}
+		return $wp_filesystem;
+	}
+
+
+	/**
+	 * display_request_filesystem_credentials_form
+	 */
+	public static function display_request_filesystem_credentials_form()
+	{
+		if (! empty(EEH_File::$_credentials_form)) {
+			echo '<div class="updated espresso-notices-attention"><p>' . EEH_File::$_credentials_form . '</p></div>';
+		}
+	}
+
+
+	/**
+	 *    verify_filepath_and_permissions
+	 *    checks that a file is readable and has sufficient file permissions set to access
+	 *
+	 * @access public
+	 * @param string $full_file_path - full server path to the folder or file
+	 * @param string $file_name      - name of file if checking a file
+	 * @param string $file_ext       - file extension (ie: "php") if checking a file
+	 * @param string $type_of_file   - general type of file (ie: "module"), this is only used to improve error messages
+	 * @return bool
+	 */
+	public static function verify_filepath_and_permissions(
+		$full_file_path = '',
+		$file_name = '',
+		$file_ext = '',
+		$type_of_file = ''
+	) {
+		// load WP_Filesystem and set file permissions
+		$wp_filesystem  = EEH_File::_get_wp_filesystem($full_file_path);
+		$full_file_path = EEH_File::standardise_directory_separators($full_file_path);
+		if (! $wp_filesystem->is_readable(EEH_File::convert_local_filepath_to_remote_filepath($full_file_path))) {
+			$file_name = ! empty($type_of_file) ? $file_name . ' ' . $type_of_file : $file_name;
+			$file_name .= ! empty($file_ext) ? ' file' : ' folder';
+			$msg       = sprintf(
+				__(
+					'The requested %1$s could not be found or is not readable, possibly due to an incorrect filepath, or incorrect file permissions.%2$s',
+					'event_espresso'
+				),
+				$file_name,
+				'<br />'
+			);
+			if (EEH_File::exists($full_file_path)) {
+				$msg .= EEH_File::_permissions_error_for_unreadable_filepath($full_file_path, $type_of_file);
+			} else {
+				// no file permissions means the file was not found
+				$msg .= sprintf(
+					__('Please ensure the following path is correct: "%s".', 'event_espresso'),
+					$full_file_path
+				);
+			}
+			if (defined('WP_DEBUG') && WP_DEBUG) {
+				EE_Error::add_error($msg . '||' . $msg, __FILE__, __FUNCTION__, __LINE__);
+			}
+			return false;
+		}
+		return true;
+	}
+
+
+	/**
+	 * _permissions_error_for_unreadable_filepath - attempts to determine why permissions are set incorrectly for a
+	 * file or folder
+	 *
+	 * @access private
+	 * @param string $full_file_path - full server path to the folder or file
+	 * @param string $type_of_file   - general type of file (ie: "module"), this is only used to improve error messages
+	 * @return string
+	 */
+	private static function _permissions_error_for_unreadable_filepath($full_file_path = '', $type_of_file = '')
+	{
+		// load WP_Filesystem and set file permissions
+		$wp_filesystem = EEH_File::_get_wp_filesystem($full_file_path);
+		// check file permissions
+		$perms = $wp_filesystem->getchmod(EEH_File::convert_local_filepath_to_remote_filepath($full_file_path));
+		if ($perms) {
+			// file permissions exist, but way be set incorrectly
+			$type_of_file = ! empty($type_of_file) ? $type_of_file . ' ' : '';
+			$type_of_file .= ! empty($type_of_file) ? 'file' : 'folder';
+			return ' ' . sprintf(
+				__(
+					'File permissions for the requested %1$s are currently set at "%2$s". The recommended permissions are 644 for files and 755 for folders.',
+					'event_espresso'
+				),
+				$type_of_file,
+				$perms
+			);
+		} else {
+			// file exists but file permissions could not be read ?!?!
+			return ' ' . sprintf(
+				__(
+					'Please ensure that the server and/or PHP configuration allows the current process to access the following file: "%s".',
+					'event_espresso'
+				),
+				$full_file_path
+			);
+		}
+	}
+
+
+	/**
+	 * ensure_folder_exists_and_is_writable
+	 * ensures that a folder exists and is writable, will attempt to create folder if it does not exist
+	 * Also ensures all the parent folders exist, and if not tries to create them.
+	 * Also, if this function creates the folder, adds a .htaccess file and index.html file
+	 *
+	 * @param string $folder
+	 * @return bool false if folder isn't writable; true if it exists and is writeable,
+	 */
+	public static function ensure_folder_exists_and_is_writable($folder = '')
+	{
+		if (empty($folder)) {
+			return false;
+		}
+		// remove ending /
+		$folder        = EEH_File::standardise_directory_separators(rtrim($folder, '/\\'));
+		$parent_folder = EEH_File::get_parent_folder($folder);
+		// add / to folder
+		$folder        = EEH_File::end_with_directory_separator($folder);
+		$wp_filesystem = EEH_File::_get_wp_filesystem($folder);
+		$remote_dir    = EEH_File::convert_local_filepath_to_remote_filepath($folder);
+		if (! $wp_filesystem->is_dir($remote_dir)) {
+			// ok so it doesn't exist. Does its parent? Can we write to it?
+			if (! EEH_File::ensure_folder_exists_and_is_writable($parent_folder)) {
+				return false;
+			}
+			if (! EEH_File::verify_is_writable($parent_folder, 'folder')) {
+				return false;
+			}
+			if (! $wp_filesystem->mkdir(EEH_File::convert_local_filepath_to_remote_filepath($folder))) {
+				if (defined('WP_DEBUG') && WP_DEBUG) {
+					$msg = sprintf(__('"%s" could not be created.', 'event_espresso'), $folder);
+					$msg .= EEH_File::_permissions_error_for_unreadable_filepath($folder);
+					EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
+				}
+				return false;
+			}
+			EEH_File::add_index_file($folder);
+		} elseif (! EEH_File::verify_is_writable($folder, 'folder')) {
+			return false;
+		}
+		return true;
+	}
+
+
+	/**
+	 * verify_is_writable - checks if a file or folder is writable
+	 *
+	 * @param string $full_path      - full server path to file or folder
+	 * @param string $file_or_folder - whether checking a file or folder
+	 * @return bool
+	 */
+	public static function verify_is_writable($full_path = '', $file_or_folder = 'folder')
+	{
+		// load WP_Filesystem and set file permissions
+		$wp_filesystem = EEH_File::_get_wp_filesystem($full_path);
+		$full_path     = EEH_File::standardise_directory_separators($full_path);
+		$remote_path   = EEH_File::convert_local_filepath_to_remote_filepath($full_path);
+		$remote_path   = rtrim($remote_path, '/\\');
+		if (! $wp_filesystem->is_writable($remote_path)) {
+			if (defined('WP_DEBUG') && WP_DEBUG) {
+				$msg = sprintf(__('The "%1$s" %2$s is not writable.', 'event_espresso'), $full_path, $file_or_folder);
+				$msg .= EEH_File::_permissions_error_for_unreadable_filepath($full_path);
+				EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
+			}
+			return false;
+		}
+		return true;
+	}
+
+
+	/**
+	 * ensure_file_exists_and_is_writable
+	 * ensures that a file exists and is writable, will attempt to create file if it does not exist.
+	 * Also ensures all the parent folders exist, and if not tries to create them.
+	 *
+	 * @param string $full_file_path
+	 * @return bool
+	 */
+	public static function ensure_file_exists_and_is_writable($full_file_path = '')
+	{
+		// load WP_Filesystem and set file permissions
+		$wp_filesystem  = EEH_File::_get_wp_filesystem($full_file_path);
+		$full_file_path = EEH_File::standardise_directory_separators($full_file_path);
+		$parent_folder  = EEH_File::get_parent_folder($full_file_path);
+		if (! EEH_File::exists($full_file_path)) {
+			if (! EEH_File::ensure_folder_exists_and_is_writable($parent_folder)) {
+				return false;
+			}
+			if (! $wp_filesystem->touch(EEH_File::convert_local_filepath_to_remote_filepath($full_file_path))) {
+				if (defined('WP_DEBUG') && WP_DEBUG) {
+					$msg = sprintf(__('The "%s" file could not be created.', 'event_espresso'), $full_file_path);
+					$msg .= EEH_File::_permissions_error_for_unreadable_filepath($full_file_path);
+					EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
+				}
+				return false;
+			}
+		}
+		if (! EEH_File::verify_is_writable($full_file_path, 'file')) {
+			return false;
+		}
+		return true;
+	}
+
+
+	/**
+	 * Gets the parent folder. If provided with file, gets the folder that contains it.
+	 * If provided a folder, gets its parent folder.
+	 *
+	 * @param string $file_or_folder_path
+	 * @return string parent folder, ENDING with a directory separator
+	 */
+	public static function get_parent_folder($file_or_folder_path)
+	{
+		// find the last /, ignoring a / on the very end
+		// eg if given "/var/something/somewhere/", we want to get "somewhere"'s
+		// parent folder, "/var/something/"
+		$ds = strlen($file_or_folder_path) > 1
+			? strrpos($file_or_folder_path, '/', -2)
+			: strlen($file_or_folder_path);
+		return substr($file_or_folder_path, 0, $ds + 1);
+	}
+
+
+	/**
+	 * get_file_contents
+	 *
+	 * @param string $full_file_path
+	 * @return string
+	 */
+	public static function get_file_contents($full_file_path = '')
+	{
+		$full_file_path = EEH_File::standardise_directory_separators($full_file_path);
+		if (EEH_File::verify_filepath_and_permissions(
+			$full_file_path,
+			EEH_File::get_filename_from_filepath($full_file_path),
+			EEH_File::get_file_extension($full_file_path)
+		)) {
+			// load WP_Filesystem and set file permissions
+			$wp_filesystem = EEH_File::_get_wp_filesystem($full_file_path);
+			return $wp_filesystem->get_contents(EEH_File::convert_local_filepath_to_remote_filepath($full_file_path));
+		}
+		return '';
+	}
+
+
+	/**
+	 * write_file
+	 *
+	 * @param string $full_file_path
+	 * @param string $file_contents - the content to be written to the file
+	 * @param string $file_type
+	 * @return bool
+	 */
+	public static function write_to_file($full_file_path = '', $file_contents = '', $file_type = '')
+	{
+		$full_file_path = EEH_File::standardise_directory_separators($full_file_path);
+		$file_type      = ! empty($file_type) ? rtrim($file_type, ' ') . ' ' : '';
+		$folder         = EEH_File::remove_filename_from_filepath($full_file_path);
+		if (! EEH_File::verify_is_writable($folder, 'folder')) {
+			if (defined('WP_DEBUG') && WP_DEBUG) {
+				$msg =
+					sprintf(
+						__('The %1$sfile located at "%2$s" is not writable.', 'event_espresso'),
+						$file_type,
+						$full_file_path
+					);
+				$msg .= EEH_File::_permissions_error_for_unreadable_filepath($full_file_path);
+				EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
+			}
+			return false;
+		}
+		// load WP_Filesystem and set file permissions
+		$wp_filesystem = EEH_File::_get_wp_filesystem($full_file_path);
+		// write the file
+		if (! $wp_filesystem->put_contents(
+			EEH_File::convert_local_filepath_to_remote_filepath($full_file_path),
+			$file_contents
+		)) {
+			if (defined('WP_DEBUG') && WP_DEBUG) {
+				$msg =
+					sprintf(
+						__('The %1$sfile located at "%2$s" could not be written to.', 'event_espresso'),
+						$file_type,
+						$full_file_path
+					);
+				$msg .= EEH_File::_permissions_error_for_unreadable_filepath($full_file_path, 'f');
+				EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
+			}
+			return false;
+		}
+		return true;
+	}
+
+
+	/**
+	 * Wrapper for WP_Filesystem_Base::delete
+	 *
+	 * @param string         $filepath
+	 * @param boolean        $recursive
+	 * @param boolean|string $type 'd' for directory, 'f' for file
+	 * @return boolean
+	 */
+	public static function delete($filepath, $recursive = false, $type = false)
+	{
+		$wp_filesystem = EEH_File::_get_wp_filesystem();
+		return $wp_filesystem->delete($filepath, $recursive, $type);
+	}
+
+
+	/**
+	 * exists
+	 * checks if a file exists using the WP filesystem
+	 *
+	 * @param string $full_file_path
+	 * @return bool
+	 */
+	public static function exists($full_file_path = '')
+	{
+		$wp_filesystem = EEH_File::_get_wp_filesystem($full_file_path);
+		return $wp_filesystem->exists(EEH_File::convert_local_filepath_to_remote_filepath($full_file_path));
+	}
+
+
+	/**
+	 * is_readable
+	 * checks if a file is_readable using the WP filesystem
+	 *
+	 * @param string $full_file_path
+	 * @return bool
+	 */
+	public static function is_readable($full_file_path = '')
+	{
+		$wp_filesystem = EEH_File::_get_wp_filesystem($full_file_path);
+		return $wp_filesystem->is_readable(EEH_File::convert_local_filepath_to_remote_filepath($full_file_path));
+	}
+
+
+	/**
+	 * remove_filename_from_filepath
+	 * given a full path to a file including the filename itself, this removes  the filename and returns the path, up
+	 * to, but NOT including the filename OR slash
+	 *
+	 * @param string $full_file_path
+	 * @return string
+	 */
+	public static function remove_filename_from_filepath($full_file_path = '')
+	{
+		return pathinfo($full_file_path, PATHINFO_DIRNAME);
+	}
+
+
+	/**
+	 * get_filename_from_filepath. Arguably the same as basename()
+	 *
+	 * @param string $full_file_path
+	 * @return string
+	 */
+	public static function get_filename_from_filepath($full_file_path = '')
+	{
+		return pathinfo($full_file_path, PATHINFO_BASENAME);
+	}
+
+
+	/**
+	 * get_file_extension
+	 *
+	 * @param string $full_file_path
+	 * @return string
+	 */
+	public static function get_file_extension($full_file_path = '')
+	{
+		return pathinfo($full_file_path, PATHINFO_EXTENSION);
+	}
+
+
+	/**
+	 * add_htaccess_deny_from_all so the web server cannot access this folder
+	 *
+	 * @param string $folder
+	 * @return bool
+	 */
+	public static function add_htaccess_deny_from_all($folder = '')
+	{
+		$folder = EEH_File::standardise_and_end_with_directory_separator($folder);
+		if (! EEH_File::exists($folder . '.htaccess')) {
+			if (! EEH_File::write_to_file($folder . '.htaccess', 'deny from all', '.htaccess')) {
+				return false;
+			}
+		}
+
+		return true;
+	}
+
+
+	/**
+	 * Adds an index file to this folder, so folks can't list all the file's contents
+	 *
+	 * @param string $folder
+	 * @return boolean
+	 */
+	public static function add_index_file($folder)
+	{
+		$folder = EEH_File::standardise_and_end_with_directory_separator($folder);
+		if (! EEH_File::exists($folder . 'index.php')) {
+			if (! EEH_File::write_to_file(
+				$folder . 'index.php',
+				'You are not permitted to read from this folder',
+				'.php'
+			)) {
+				return false;
+			}
+		}
+		return true;
+	}
+
+
+	/**
+	 * Given that the file in $file_path has the normal name, (ie, CLASSNAME.whatever.php),
+	 * extract that classname.
+	 *
+	 * @param string $file_path
+	 * @return string
+	 */
+	public static function get_classname_from_filepath_with_standard_filename($file_path)
+	{
+		// extract file from path
+		$filename = basename($file_path);
+		// now remove the first period and everything after
+		$pos_of_first_period = strpos($filename, '.');
+		return substr($filename, 0, $pos_of_first_period);
+	}
+
+
+	/**
+	 * standardise_directory_separators
+	 *  convert all directory separators in a file path.
+	 *
+	 * @param string $file_path
+	 * @param bool   $rtrim will remove trailing backslash
+	 * @return string
+	 */
+	public static function standardise_directory_separators($file_path, $rtrim = false)
+	{
+		$file_path = $rtrim ? rtrim($file_path, '/\\') : $file_path;
+		return str_replace(['\\', '/'], '/', $file_path);
+	}
+
+
+	/**
+	 * end_with_directory_separator
+	 *  ensures that file path ends with '/'
+	 *
+	 * @param string $file_path
+	 * @return string
+	 */
+	public static function end_with_directory_separator($file_path)
+	{
+		return rtrim($file_path, '/\\') . '/';
+	}
+
+
+	/**
+	 * shorthand for both EEH_FIle::end_with_directory_separator AND EEH_File::standardise_directory_separators
+	 *
+	 * @param $file_path
+	 * @return string
+	 */
+	public static function standardise_and_end_with_directory_separator($file_path)
+	{
+		return self::end_with_directory_separator(self::standardise_directory_separators($file_path));
+	}
+
+
+	/**
+	 * takes the folder name (with or without trailing slash) and finds the files it in,
+	 * and what the class's name inside of each should be.
+	 *
+	 * @param array   $folder_paths
+	 * @param boolean $index_numerically if TRUE, the returned array will be indexed numerically;
+	 *                                   if FALSE (Default), returned array will be indexed by the filenames minus
+	 *                                   extensions. Set it TRUE if you know there are files in the directory with the
+	 *                                   same name but different extensions
+	 * @return array if $index_numerically == TRUE keys are numeric ,
+	 *                                   if $index_numerically == FALSE (Default) keys are what the class names SHOULD
+	 *                                   be; and values are their file paths
+	 */
+	public static function get_contents_of_folders($folder_paths = [], $index_numerically = false)
+	{
+		$class_to_folder_path = [];
+		foreach ($folder_paths as $folder_path) {
+			$folder_path = self::standardise_and_end_with_directory_separator($folder_path);
+			// load WP_Filesystem and set file permissions
+			$files_in_folder = glob($folder_path . '*.php');
+			$class_to_folder_path = [];
+			if ($files_in_folder) {
+				foreach ($files_in_folder as $file_path) {
+					// only add files, not folders
+					if (! is_dir($file_path)) {
+						if ($index_numerically) {
+							$class_to_folder_path[] = $file_path;
+						} else {
+							$classname =
+								self::get_classname_from_filepath_with_standard_filename($file_path);
+							$class_to_folder_path[ $classname ] = $file_path;
+						}
+					}
+				}
+			}
+		}
+		return $class_to_folder_path;
+	}
+
+
+	/**
+	 * Copies a file. Mostly a wrapper of WP_Filesystem::copy
+	 *
+	 * @param string  $source_file
+	 * @param string  $destination_file
+	 * @param boolean $overwrite
+	 * @return boolean success
+	 */
+	public static function copy($source_file, $destination_file, $overwrite = false)
+	{
+		$source_file      = EEH_File::validateFileForCopyOrMove($source_file);
+		$destination_file = EEH_File::validateFolderForCopyOrMove($destination_file);
+		if (! $source_file || ! $destination_file) {
+			return false;
+		}
+		// load WP_Filesystem and set file permissions
+		$wp_filesystem = EEH_File::_get_wp_filesystem($destination_file);
+		// write the file
+		$copied = $wp_filesystem->copy(
+			EEH_File::convert_local_filepath_to_remote_filepath($source_file),
+			EEH_File::convert_local_filepath_to_remote_filepath($destination_file),
+			$overwrite
+		);
+		if (! $copied) {
+			if (defined('WP_DEBUG') && WP_DEBUG) {
+				$msg = sprintf(
+					__(
+						'Attempted writing to file %1$s, but could not, probably because of permissions issues',
+						'event_espresso'
+					),
+					$source_file
+				);
+				$msg .= EEH_File::_permissions_error_for_unreadable_filepath($source_file, 'f');
+				EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
+			}
+			return false;
+		}
+		return true;
+	}
+
+
+	/**
+	 * Reports whether or not the filepath is in the EE uploads folder or not
+	 *
+	 * @param string $filepath
+	 * @return boolean
+	 */
+	public static function is_in_uploads_folder($filepath)
+	{
+		$uploads = wp_upload_dir();
+		return strpos($filepath, $uploads['basedir']) === 0;
+	}
+
+
+	/**
+	 * Given a "local" filepath (what you probably thought was the only filepath),
+	 * converts it into a "remote" filepath (the filepath the currently-in-use
+	 * $wp_filesystem needs to use access the folder or file).
+	 * See http://wordpress.stackexchange.com/questions/124900/using-wp-filesystem-in-plugins
+	 *
+	 * @param string $local_filepath the filepath to the folder/file locally
+	 * @return string the remote filepath (eg the filepath the filesystem method, eg
+	 *                               ftp or ssh, will use to access the folder
+	 */
+	public static function convert_local_filepath_to_remote_filepath($local_filepath)
+	{
+		$wp_filesystem = EEH_File::_get_wp_filesystem($local_filepath);
+		return str_replace(WP_CONTENT_DIR . '/', $wp_filesystem->wp_content_dir(), $local_filepath);
+	}
+
+
+	/**
+	 * wrapper for WP_Filesystem::chmod()
+	 *
+	 * @param string    $file      Path to the file.
+	 * @param int|false $mode      Optional. The permissions as octal number, usually 0644 for files,
+	 *                             0755 for directories. Default false.
+	 * @param bool      $recursive Optional. If set to true, changes file permissions recursively.
+	 *                             Default false.
+	 * @return bool True on success, false on failure.
+	 */
+	public static function chmod($file, $mode = false, $recursive = false)
+	{
+		$wp_filesystem = EEH_File::_get_wp_filesystem($file);
+		return $wp_filesystem->chmod($file, $mode, $recursive);
+	}
+
+
+	/**
+	 * wrapper for WP_Filesystem::getchmod()
+	 *
+	 * @param string $file Path to the file.
+	 * @return string Mode of the file (the last 3 digits).
+	 */
+	public static function permissions($file)
+	{
+		$wp_filesystem = EEH_File::_get_wp_filesystem($file);
+		return $wp_filesystem->getchmod($file);
+	}
+
+
+	/**
+	 * wrapper for WP_Filesystem::owner()
+	 *
+	 * @param string $file Path to the file.
+	 * @return string|false Username of the owner on success, false on failure.
+	 */
+	public static function owner($file)
+	{
+		$wp_filesystem = EEH_File::_get_wp_filesystem($file);
+		return $wp_filesystem->owner($file);
+	}
+
+
+	/**
+	 * wrapper for WP_Filesystem::group()
+	 *
+	 * @param string $file Path to the file.
+	 * @return string|false The group on success, false on failure.
+	 */
+	public static function group($file)
+	{
+		$wp_filesystem = EEH_File::_get_wp_filesystem($file);
+		return $wp_filesystem->group($file);
+	}
+
+
+	/**
+	 * wrapper for WP_Filesystem::move()
+	 *
+	 * @param string $source      Path to the source file.
+	 * @param string $destination Path to the destination file.
+	 * @param bool   $overwrite   Optional. Whether to overwrite the destination file if it exists.
+	 *                            Default false.
+	 * @return bool True on success, false on failure.
+	 */
+	public static function move($source, $destination, $overwrite = false)
+	{
+		// throw new RuntimeException("source: {$source} && destination: {$destination}");
+		$source      = EEH_File::validateFileForCopyOrMove($source);
+		$destination = EEH_File::validateFolderForCopyOrMove($destination);
+		if (! $source || ! $destination) {
+			return false;
+		}
+		$wp_filesystem = EEH_File::_get_wp_filesystem($source);
+		if ($wp_filesystem->move($source, $destination, $overwrite)) {
+			return true;
+		}
+		if (defined('WP_DEBUG') && WP_DEBUG) {
+			$file        = EEH_File::convert_local_filepath_to_remote_filepath($source);
+			$owner       = EEH_File::owner($file);
+			$group       = EEH_File::group($file);
+			$permissions = EEH_File::permissions($file);
+			EE_Error::add_error(
+				sprintf(
+					esc_html__(
+						'Unable to move the file "%1$s" to new location (possible permissions errors). The existing "owner:group permissions" for the file are: "%2$s"',
+						'event_espresso'
+					),
+					$destination,
+					"{$owner}:{$group} $permissions"
+				),
+				__FILE__,
+				__FUNCTION__,
+				__LINE__
+			);
+		}
+		return false;
+	}
+
+
+	/**
+	 * @param string $source_file
+	 * @return string
+	 */
+	private static function validateFileForCopyOrMove($source_file)
+	{
+		$full_source_path = EEH_File::standardise_directory_separators($source_file);
+		if (! EEH_File::exists($full_source_path)) {
+			if (defined('WP_DEBUG') && WP_DEBUG) {
+				$msg =
+					sprintf(
+						__('The file located at "%2$s" is not readable or doesn\'t exist.', 'event_espresso'),
+						'',
+						$full_source_path
+					);
+				$msg .= EEH_File::_permissions_error_for_unreadable_filepath($full_source_path);
+				EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
+			}
+			return '';
+		}
+		return $full_source_path;
+	}
+
+
+	/**
+	 * @param string $destination_file
+	 * @return string
+	 */
+	private static function validateFolderForCopyOrMove($destination_file)
+	{
+		$full_dest_path = EEH_File::standardise_directory_separators($destination_file);
+		$folder         = EEH_File::remove_filename_from_filepath($full_dest_path);
+		EEH_File::ensure_folder_exists_and_is_writable($folder);
+		if (! EEH_File::verify_is_writable($folder, 'folder')) {
+			if (defined('WP_DEBUG') && WP_DEBUG) {
+				$msg = sprintf(
+					__('The file located at "%2$s" is not writable.', 'event_espresso'),
+					'',
+					$full_dest_path
+				);
+				$msg .= EEH_File::_permissions_error_for_unreadable_filepath($full_dest_path);
+				EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
+			}
+			return '';
+		}
+		return $full_dest_path;
+	}
 }

Spacing +49 added lines, -49 removed lines

@@ -60,13 +60,13 @@ 
      */
     private static function loadAlternateWpFileSystem()
     {
-        if (! EEH_File::$_wp_filesystem instanceof WP_Filesystem_Base) {
-            require_once(ABSPATH . 'wp-admin/includes/class-wp-filesystem-base.php');
+        if ( ! EEH_File::$_wp_filesystem instanceof WP_Filesystem_Base) {
+            require_once(ABSPATH.'wp-admin/includes/class-wp-filesystem-base.php');
             $method             = 'direct';
             $wp_filesystem_file =
                 apply_filters(
                     'filesystem_method_file',
-                    ABSPATH . 'wp-admin/includes/class-wp-filesystem-' . $method . '.php',
+                    ABSPATH.'wp-admin/includes/class-wp-filesystem-'.$method.'.php',
                     $method
                 );
             // added the following validation logic
@@ -88,7 +88,7 @@ 
                     $wp_filesystem_class = $filesystem_class;
                 }
             }
-            if (! $valid || ! file_exists($wp_filesystem_file)) {
+            if ( ! $valid || ! file_exists($wp_filesystem_file)) {
                 EE_Error::add_error(
                     sprintf(
                         __(
@@ -103,11 +103,11 @@ 
                 );
             }
             // check constants defined, just like in the wp-admin/includes/file.php WP_Filesystem()
-            if (! defined('FS_CHMOD_DIR')) {
+            if ( ! defined('FS_CHMOD_DIR')) {
                 define('FS_CHMOD_DIR', (fileperms(ABSPATH) & 0775 | 0755));
             }
-            if (! defined('FS_CHMOD_FILE')) {
-                define('FS_CHMOD_FILE', (fileperms(ABSPATH . 'index.php') & 0775 | 0644));
+            if ( ! defined('FS_CHMOD_FILE')) {
+                define('FS_CHMOD_FILE', (fileperms(ABSPATH.'index.php') & 0775 | 0644));
             }
             require_once($wp_filesystem_file);
             EEH_File::$_wp_filesystem = new $wp_filesystem_class([]);
@@ -123,7 +123,7 @@ 
     {
         global $wp_filesystem;
         // no filesystem setup ???
-        if (! $wp_filesystem instanceof WP_Filesystem_Base) {
+        if ( ! $wp_filesystem instanceof WP_Filesystem_Base) {
             // if some eager beaver's just trying to get in there too early...
             // let them do it, because we are one of those eager beavers! :P
             /**
@@ -143,7 +143,7 @@ 
                         'event_espresso'
                     );
                 if (WP_DEBUG) {
-                    $msg .= '<br />' . __(
+                    $msg .= '<br />'.__(
                         'The WP Filesystem can not be accessed until after the "wp_loaded" hook has run, so it\'s best not to attempt access until the "admin_init" hookpoint.',
                         'event_espresso'
                     );
@@ -151,9 +151,9 @@ 
                 EE_Error::add_error($msg, __FILE__, __FUNCTION__, __LINE__);
             }
             // should be loaded if we are past the wp_loaded hook...
-            if (! function_exists('WP_Filesystem') || ! function_exists('submit_button')) {
-                require_once(ABSPATH . 'wp-admin/includes/file.php');
-                require_once(ABSPATH . 'wp-admin/includes/template.php');
+            if ( ! function_exists('WP_Filesystem') || ! function_exists('submit_button')) {
+                require_once(ABSPATH.'wp-admin/includes/file.php');
+                require_once(ABSPATH.'wp-admin/includes/template.php');
             }
             // turn on output buffering so that we can capture the credentials form
             ob_start();
@@ -174,7 +174,7 @@ 
                 );
             }
             // basically check for direct or previously configured access
-            if (! WP_Filesystem($credentials)
+            if ( ! WP_Filesystem($credentials)
                 && is_wp_error($wp_filesystem->errors)
                 && $wp_filesystem->errors->get_error_code()
             ) {
@@ -199,8 +199,8 @@ 
      */
     public static function display_request_filesystem_credentials_form()
     {
-        if (! empty(EEH_File::$_credentials_form)) {
-            echo '<div class="updated espresso-notices-attention"><p>' . EEH_File::$_credentials_form . '</p></div>';
+        if ( ! empty(EEH_File::$_credentials_form)) {
+            echo '<div class="updated espresso-notices-attention"><p>'.EEH_File::$_credentials_form.'</p></div>';
         }
     }
 
@@ -225,8 +225,8 @@ 
         // load WP_Filesystem and set file permissions
         $wp_filesystem  = EEH_File::_get_wp_filesystem($full_file_path);
         $full_file_path = EEH_File::standardise_directory_separators($full_file_path);
-        if (! $wp_filesystem->is_readable(EEH_File::convert_local_filepath_to_remote_filepath($full_file_path))) {
-            $file_name = ! empty($type_of_file) ? $file_name . ' ' . $type_of_file : $file_name;
+        if ( ! $wp_filesystem->is_readable(EEH_File::convert_local_filepath_to_remote_filepath($full_file_path))) {
+            $file_name = ! empty($type_of_file) ? $file_name.' '.$type_of_file : $file_name;
             $file_name .= ! empty($file_ext) ? ' file' : ' folder';
             $msg       = sprintf(
                 __(
@@ -246,7 +246,7 @@ 
                 );
             }
             if (defined('WP_DEBUG') && WP_DEBUG) {
-                EE_Error::add_error($msg . '||' . $msg, __FILE__, __FUNCTION__, __LINE__);
+                EE_Error::add_error($msg.'||'.$msg, __FILE__, __FUNCTION__, __LINE__);
             }
             return false;
         }
@@ -271,9 +271,9 @@ 
         $perms = $wp_filesystem->getchmod(EEH_File::convert_local_filepath_to_remote_filepath($full_file_path));
         if ($perms) {
             // file permissions exist, but way be set incorrectly
-            $type_of_file = ! empty($type_of_file) ? $type_of_file . ' ' : '';
+            $type_of_file = ! empty($type_of_file) ? $type_of_file.' ' : '';
             $type_of_file .= ! empty($type_of_file) ? 'file' : 'folder';
-            return ' ' . sprintf(
+            return ' '.sprintf(
                 __(
                     'File permissions for the requested %1$s are currently set at "%2$s". The recommended permissions are 644 for files and 755 for folders.',
                     'event_espresso'
@@ -283,7 +283,7 @@ 
             );
         } else {
             // file exists but file permissions could not be read ?!?!
-            return ' ' . sprintf(
+            return ' '.sprintf(
                 __(
                     'Please ensure that the server and/or PHP configuration allows the current process to access the following file: "%s".',
                     'event_espresso'
@@ -315,15 +315,15 @@ 
         $folder        = EEH_File::end_with_directory_separator($folder);
         $wp_filesystem = EEH_File::_get_wp_filesystem($folder);
         $remote_dir    = EEH_File::convert_local_filepath_to_remote_filepath($folder);
-        if (! $wp_filesystem->is_dir($remote_dir)) {
+        if ( ! $wp_filesystem->is_dir($remote_dir)) {
             // ok so it doesn't exist. Does its parent? Can we write to it?
-            if (! EEH_File::ensure_folder_exists_and_is_writable($parent_folder)) {
+            if ( ! EEH_File::ensure_folder_exists_and_is_writable($parent_folder)) {
                 return false;
             }
-            if (! EEH_File::verify_is_writable($parent_folder, 'folder')) {
+            if ( ! EEH_File::verify_is_writable($parent_folder, 'folder')) {
                 return false;
             }
-            if (! $wp_filesystem->mkdir(EEH_File::convert_local_filepath_to_remote_filepath($folder))) {
+            if ( ! $wp_filesystem->mkdir(EEH_File::convert_local_filepath_to_remote_filepath($folder))) {
                 if (defined('WP_DEBUG') && WP_DEBUG) {
                     $msg = sprintf(__('"%s" could not be created.', 'event_espresso'), $folder);
                     $msg .= EEH_File::_permissions_error_for_unreadable_filepath($folder);
@@ -332,7 +332,7 @@ 
                 return false;
             }
             EEH_File::add_index_file($folder);
-        } elseif (! EEH_File::verify_is_writable($folder, 'folder')) {
+        } elseif ( ! EEH_File::verify_is_writable($folder, 'folder')) {
             return false;
         }
         return true;
@@ -353,7 +353,7 @@ 
         $full_path     = EEH_File::standardise_directory_separators($full_path);
         $remote_path   = EEH_File::convert_local_filepath_to_remote_filepath($full_path);
         $remote_path   = rtrim($remote_path, '/\\');
-        if (! $wp_filesystem->is_writable($remote_path)) {
+        if ( ! $wp_filesystem->is_writable($remote_path)) {
             if (defined('WP_DEBUG') && WP_DEBUG) {
                 $msg = sprintf(__('The "%1$s" %2$s is not writable.', 'event_espresso'), $full_path, $file_or_folder);
                 $msg .= EEH_File::_permissions_error_for_unreadable_filepath($full_path);
@@ -379,11 +379,11 @@ 
         $wp_filesystem  = EEH_File::_get_wp_filesystem($full_file_path);
         $full_file_path = EEH_File::standardise_directory_separators($full_file_path);
         $parent_folder  = EEH_File::get_parent_folder($full_file_path);
-        if (! EEH_File::exists($full_file_path)) {
-            if (! EEH_File::ensure_folder_exists_and_is_writable($parent_folder)) {
+        if ( ! EEH_File::exists($full_file_path)) {
+            if ( ! EEH_File::ensure_folder_exists_and_is_writable($parent_folder)) {
                 return false;
             }
-            if (! $wp_filesystem->touch(EEH_File::convert_local_filepath_to_remote_filepath($full_file_path))) {
+            if ( ! $wp_filesystem->touch(EEH_File::convert_local_filepath_to_remote_filepath($full_file_path))) {
                 if (defined('WP_DEBUG') && WP_DEBUG) {
                     $msg = sprintf(__('The "%s" file could not be created.', 'event_espresso'), $full_file_path);
                     $msg .= EEH_File::_permissions_error_for_unreadable_filepath($full_file_path);
@@ -392,7 +392,7 @@ 
                 return false;
             }
         }
-        if (! EEH_File::verify_is_writable($full_file_path, 'file')) {
+        if ( ! EEH_File::verify_is_writable($full_file_path, 'file')) {
             return false;
         }
         return true;
@@ -451,9 +451,9 @@ 
     public static function write_to_file($full_file_path = '', $file_contents = '', $file_type = '')
     {
         $full_file_path = EEH_File::standardise_directory_separators($full_file_path);
-        $file_type      = ! empty($file_type) ? rtrim($file_type, ' ') . ' ' : '';
+        $file_type      = ! empty($file_type) ? rtrim($file_type, ' ').' ' : '';
         $folder         = EEH_File::remove_filename_from_filepath($full_file_path);
-        if (! EEH_File::verify_is_writable($folder, 'folder')) {
+        if ( ! EEH_File::verify_is_writable($folder, 'folder')) {
             if (defined('WP_DEBUG') && WP_DEBUG) {
                 $msg =
                     sprintf(
@@ -469,7 +469,7 @@ 
         // load WP_Filesystem and set file permissions
         $wp_filesystem = EEH_File::_get_wp_filesystem($full_file_path);
         // write the file
-        if (! $wp_filesystem->put_contents(
+        if ( ! $wp_filesystem->put_contents(
             EEH_File::convert_local_filepath_to_remote_filepath($full_file_path),
             $file_contents
         )) {
@@ -579,8 +579,8 @@ 
     public static function add_htaccess_deny_from_all($folder = '')
     {
         $folder = EEH_File::standardise_and_end_with_directory_separator($folder);
-        if (! EEH_File::exists($folder . '.htaccess')) {
-            if (! EEH_File::write_to_file($folder . '.htaccess', 'deny from all', '.htaccess')) {
+        if ( ! EEH_File::exists($folder.'.htaccess')) {
+            if ( ! EEH_File::write_to_file($folder.'.htaccess', 'deny from all', '.htaccess')) {
                 return false;
             }
         }
@@ -598,9 +598,9 @@ 
     public static function add_index_file($folder)
     {
         $folder = EEH_File::standardise_and_end_with_directory_separator($folder);
-        if (! EEH_File::exists($folder . 'index.php')) {
-            if (! EEH_File::write_to_file(
-                $folder . 'index.php',
+        if ( ! EEH_File::exists($folder.'index.php')) {
+            if ( ! EEH_File::write_to_file(
+                $folder.'index.php',
                 'You are not permitted to read from this folder',
                 '.php'
             )) {
@@ -652,7 +652,7 @@ 
      */
     public static function end_with_directory_separator($file_path)
     {
-        return rtrim($file_path, '/\\') . '/';
+        return rtrim($file_path, '/\\').'/';
     }
 
 
@@ -687,18 +687,18 @@ 
         foreach ($folder_paths as $folder_path) {
             $folder_path = self::standardise_and_end_with_directory_separator($folder_path);
             // load WP_Filesystem and set file permissions
-            $files_in_folder = glob($folder_path . '*.php');
+            $files_in_folder = glob($folder_path.'*.php');
             $class_to_folder_path = [];
             if ($files_in_folder) {
                 foreach ($files_in_folder as $file_path) {
                     // only add files, not folders
-                    if (! is_dir($file_path)) {
+                    if ( ! is_dir($file_path)) {
                         if ($index_numerically) {
                             $class_to_folder_path[] = $file_path;
                         } else {
                             $classname =
                                 self::get_classname_from_filepath_with_standard_filename($file_path);
-                            $class_to_folder_path[ $classname ] = $file_path;
+                            $class_to_folder_path[$classname] = $file_path;
                         }
                     }
                 }
@@ -720,7 +720,7 @@ 
     {
         $source_file      = EEH_File::validateFileForCopyOrMove($source_file);
         $destination_file = EEH_File::validateFolderForCopyOrMove($destination_file);
-        if (! $source_file || ! $destination_file) {
+        if ( ! $source_file || ! $destination_file) {
             return false;
         }
         // load WP_Filesystem and set file permissions
@@ -731,7 +731,7 @@ 
             EEH_File::convert_local_filepath_to_remote_filepath($destination_file),
             $overwrite
         );
-        if (! $copied) {
+        if ( ! $copied) {
             if (defined('WP_DEBUG') && WP_DEBUG) {
                 $msg = sprintf(
                     __(
@@ -775,7 +775,7 @@ 
     public static function convert_local_filepath_to_remote_filepath($local_filepath)
     {
         $wp_filesystem = EEH_File::_get_wp_filesystem($local_filepath);
-        return str_replace(WP_CONTENT_DIR . '/', $wp_filesystem->wp_content_dir(), $local_filepath);
+        return str_replace(WP_CONTENT_DIR.'/', $wp_filesystem->wp_content_dir(), $local_filepath);
     }
 
 
@@ -849,7 +849,7 @@ 
         // throw new RuntimeException("source: {$source} && destination: {$destination}");
         $source      = EEH_File::validateFileForCopyOrMove($source);
         $destination = EEH_File::validateFolderForCopyOrMove($destination);
-        if (! $source || ! $destination) {
+        if ( ! $source || ! $destination) {
             return false;
         }
         $wp_filesystem = EEH_File::_get_wp_filesystem($source);
@@ -886,7 +886,7 @@ 
     private static function validateFileForCopyOrMove($source_file)
     {
         $full_source_path = EEH_File::standardise_directory_separators($source_file);
-        if (! EEH_File::exists($full_source_path)) {
+        if ( ! EEH_File::exists($full_source_path)) {
             if (defined('WP_DEBUG') && WP_DEBUG) {
                 $msg =
                     sprintf(
@@ -912,7 +912,7 @@ 
         $full_dest_path = EEH_File::standardise_directory_separators($destination_file);
         $folder         = EEH_File::remove_filename_from_filepath($full_dest_path);
         EEH_File::ensure_folder_exists_and_is_writable($folder);
-        if (! EEH_File::verify_is_writable($folder, 'folder')) {
+        if ( ! EEH_File::verify_is_writable($folder, 'folder')) {
             if (defined('WP_DEBUG') && WP_DEBUG) {
                 $msg = sprintf(
                     __('The file located at "%2$s" is not writable.', 'event_espresso'),