csrest_segments.php

<?php
require_once dirname(__FILE__).'/class/base_classes.php';

/**
 * Class to access a segments resources from the create send API.
 * This class includes functions to create and edits segments
 * along with accessing the subscribers of a specific segment
 * @author tobyb
 *
 */
class CS_REST_Segments extends CS_REST_Wrapper_Base {

    /**
     * The base route of the lists resource.
     * @var string
     * @access private
     */
    var $_segments_base_route;

    /**
     * Constructor.
     * @param $segment_id string The segment id to access (Ignored for create requests)
     * @param $api_key string Your api key (Ignored for get_apikey requests)
     * @param $protocol string The protocol to use for requests (http|https)
     * @param $debug_level int The level of debugging required CS_REST_LOG_NONE | CS_REST_LOG_ERROR | CS_REST_LOG_WARNING | CS_REST_LOG_VERBOSE
     * @param $host string The host to send API requests to. There is no need to change this
     * @param $log CS_REST_Log The logger to use. Used for dependency injection
     * @param $serialiser The serialiser to use. Used for dependency injection
     * @param $transport The transport to use. Used for dependency injection
     * @access public
     */
    function CS_REST_Segments (
    $segment_id,
    $api_key,
    $protocol = 'https',
    $debug_level = CS_REST_LOG_NONE,
    $host = 'api.createsend.com',
    $log = NULL,
    $serialiser = NULL,
    $transport = NULL) {
            
        $this->CS_REST_Wrapper_Base($api_key, $protocol, $debug_level, $host, $log, $serialiser, $transport);
        $this->set_segment_id($segment_id);
    }

    /**
     * Change the segment id used for calls after construction
     * @param $segment_id
     * @access public
     */
    function set_segment_id($segment_id) {
        $this->_segments_base_route = $this->_base_route.'segments/'.$segment_id;
    }
    
    /**
     * Creates a new segment on the given list with the provided details
     * @param int $list_id The list on which to create the segment
     * @param $segment_details The details of the new segment
     *     This should be an array of the form 
     *         array(
     *             'Title' => The title of the new segment
     *             'Rules' => array(
     *                 array(
     *                     'Subject' => The subject of this rule
     *                     'Clauses' => array<string> The specific clauses for this rule
     *                 )
     *             )
     *         )
     * @return CS_REST_Wrapper_Result A successful response will be the ID of the newly created segment
     */
    function create($list_id, $segment_details) {
        return $this->post_request($this->_base_route.'segments/'.$list_id.'.json', $segment_details);
    }    
    
    /**
     * Updates the current segment with the provided details. Calls to this route will clear any existing rules
     * @param $segment_details The new details for the segment
     *     This should be an array of the form 
     *         array(
     *             'Title' => The new title for the segment
     *             'Rules' => array(
     *                 array(
     *                     'Subject' => The subject of this rule
     *                     'Clauses' => array<string> The specific clauses for this rule
     *                 )
     *             )
     *         )
     * @return CS_REST_Wrapper_Result A successful response will be empty
     */
    function update($segment_details) {
        return $this->put_request($this->_segments_base_route.'.json', $segment_details);
    }    
    
    /**
     * Adds the given rule to the current segment
     * @param $rule The rule to add to the segment
     *     This should be an array of the form
     *         array(
     *             'Subject' => The subject of this rule
     *             'Clauses' => array<string> The specific clauses for this rule
     *         )
     * @return CS_REST_Wrapper_Result A successful response will be empty
     */
    function add_rule($rule) {
        return $this->post_request($this->_segments_base_route.'/rules.json', $rule);
    }
    
    /**
     * Gets the details of the current segment
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be an object of the form
     * {
     *     'ActiveSubscribers' => The number of active subscribers in this segment
     *     'Rules' => array(
     *         {
     *             'Subject' => The subject of the rule
     *             'Clauses' => array<string> The clauses making up this segment rule
     *         }
     *     ),
     *     'ListID' => The ID of the list on which this segment is applied
     *     'SegmentID' => The ID of this segment
     *     'Title' => The title of this segment
     * }
     */
    function get() {
        return $this->get_request($this->_segments_base_route.'.json');
    }

    /**
     * Deletes an existing segment from the system
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be empty
     */
    function delete() {
        return $this->delete_request($this->_segments_base_route.'.json');
    }

    /**
     * Deletes all rules for the current segment
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be empty
     */
    function clear_rules() {
        return $this->delete_request($this->_segments_base_route.'/rules.json');
    }
    
    /**
     * Gets a paged collection of subscribers which fall into the given segment
     * @param string $subscribed_since The date to start getting subscribers from 
     * @param int $page_number The page number to get
     * @param int $page_size The number of records per page
     * @param string $order_field The field to order the record set by ('EMAIL', 'NAME', 'DATE')
     * @param string $order_direction The direction to order the record set ('ASC', 'DESC')
     * @access public
     * @return CS_REST_Wrapper_Result A successful response will be an object of the form
     * {
     *     'ResultsOrderedBy' => The field the results are ordered by
     *     'OrderDirection' => The order direction
     *     'PageNumber' => The page number for the result set
     *     'PageSize' => The page size used
     *     'RecordsOnThisPage' => The number of records returned
     *     'TotalNumberOfRecords' => The total number of records available
     *     'NumberOfPages' => The total number of pages for this collection
     *     'Results' => array(
     *         {
     *             'EmailAddress' => The email address of the subscriber
     *             'Name' => The name of the subscriber
     *             'Date' => The date that the subscriber was added to the list
     *             'State' => The current state of the subscriber, will be 'Active'
     *             'CustomFields' => array (
     *                 {
     *                     'Key' => The personalisation tag of the custom field
     *                     'Value' => The value of the custom field for this subscriber
     *                 }
     *             )
     *         }
     *     )
     * }
     */
    function get_subscribers($subscribed_since, $page_number = NULL, 
        $page_size = NULL, $order_field = NULL, $order_direction = NULL) {
            
        return $this->get_request_paged($this->_segments_base_route.'/active.json?date='.urlencode($subscribed_since), 
            $page_number, $page_size, $order_field, $order_direction);
    }
}