class Payment in Payment 7

A single payment. Contains all payment-specific data.

Hierarchy

class \PaymentCommon
- class \Payment

File

./payment.classes.inc, line 25: The API and related functions for executing and managing payments.

View source

class Payment extends PaymentCommon {

  /**
   * The machine name of the context that created this Payment, such as the
   * webshop module.
   *
   * @var string
   */
  public $context = '';

  /**
   * Information about this payment that is specific to the context that
   * created it, such as the webshop module.
   *
   * @var mixed[]
   */
  public $context_data = array();

  /**
   * The ISO 4217 currency code of the payment amount.
   *
   * @var string
   */
  public $currency_code = 'XXX';

  /**
   * The general description of this payment. Not to be confused with line item
   * descriptions.
   *
   * @var string
   */
  public $description = '';

  /**
   * Arguments to pass on to t() when translating $this->description.
   *
   * @var string[]
   */
  public $description_arguments = array();

  /**
   * The name of a function to call when payment execution is completed,
   * regardless of the payment status. It receives one argument:
   * - $payment Payment
   *   The Payment object.
   * The callback does not need to return anything and is free to redirect the
   * user or display something.
   * Use Payment::context_data to pass on arbitrary data to the finish callback.
   *
   * @var string
   */
  public $finish_callback = '';

  /**
   * An array with PaymentLineItem objects.
   *
   * @see Payment::setLineItem()
   *
   * @var PaymentLineItem[]
   */
  public $line_items = array();

  /**
   * The payment method used for this payment.
   *
   * @var PaymentMethod
   */
  public $method = NULL;

  /**
   * Information about this payment that is specific to its payment method.
   *
   * @var mixed[]
   */
  public $method_data = array();

  /**
   * The internal ID of this payment.
   *
   * @var integer
   */
  public $pid = 0;

  /**
   * The status log. Contains PaymentStatusItem objects ordered by datetime. Do
   * not set directly, but use Payment::setStatus() instead.
   *
   * @see Payment::setStatus()
   *
   * @var PaymentStatusItem[]
   */
  public $statuses = array();

  /**
   * The UID of the user this payment belongs to.
   *
   * @var integer
   */
  public $uid = NULL;

  /**
   * Constructor.
   *
   * @param mixed[] $properties
   *   An associative array. Keys are property names and values are property
   *   values.
   */
  function __construct(array $properties = array()) {
    global $user;
    parent::__construct($properties);
    if (is_null($this->uid)) {
      $this->uid = $user->uid;
    }
    if (!$this->statuses) {

      // We purposefully avoid Payment::setStatus(), because this is the
      // payment's first status.
      $this->statuses[] = new PaymentStatusItem(PAYMENT_STATUS_NEW);
    }
  }

  /**
   * Execute the actual payment.
   */
  function execute() {

    // Preprocess the payment.
    module_invoke_all('payment_pre_execute', $this);
    if (module_exists('rules')) {
      rules_invoke_event('payment_pre_execute', $this);
    }

    // Execute the payment.
    if ($this->method) {
      try {
        $this->method
          ->validate($this);
        $this
          ->setStatus(new PaymentStatusItem(PAYMENT_STATUS_PENDING));
        $this->method->controller
          ->execute($this);
      } catch (PaymentValidationException $e) {
        $this
          ->setStatus(new PaymentStatusItem(PAYMENT_STATUS_FAILED));
      }
    }
    else {
      $this
        ->setStatus(new PaymentStatusItem(PAYMENT_STATUS_FAILED));
    }

    // This is only called if the payment execution didn't redirect the user
    // offsite. Otherwise it's the payment method return page's responsibility.
    $this
      ->finish();
  }

  /**
   * Finish the payment after its execution.
   */
  function finish() {
    entity_save('payment', $this);
    module_invoke_all('payment_pre_finish', $this);
    if (module_exists('rules')) {
      rules_invoke_event('payment_pre_finish', $this);
    }
    call_user_func($this->finish_callback, $this);
  }

  /**
   * Set a line item.
   *
   * @see Payment::getLineItems()
   *
   * @param PaymentLineItem $line_item
   *
   * @return static
   */
  function setLineItem(PaymentLineItem $line_item) {
    $this->line_items[$line_item->name] = $line_item;
    return $this;
  }

  /**
   * Get line items.
   *
   * @param string|null $name (optional)
   *   The requested line item(s)'s machine name, as possibly defined in
   *   hook_payment_line_item_info(). If $name is NULL, then all line items
   *   will be returned.
   *
   * @return PaymentLineItem[]
   *   An array with matching PaymentLineItem objects.
   */
  function getLineItems($name = NULL) {
    if (is_null($name)) {
      return payment_line_item_get_all($name, $this);
    }
    elseif ($line_item_info = payment_line_item_info($name)) {
      return call_user_func($line_item_info->callback, $name, $this);
    }
    else {
      return payment_line_item_get_specific($name, $this);
    }
  }

  /**
   * Get the total payment amount.
   *
   * @param boolean $tax
   *   Whether to include taxes or not.
   * @param PaymentLineItem[]|null $line_items
   *   An array with PaymentLineItem objects to calculate the total from.
   *   Leave empty to use $this->line_items.
   *
   * @return float
   */
  function totalAmount($tax, array $line_items = NULl) {
    $total = 0;
    if (is_null($line_items)) {
      $line_items = $this->line_items;
    }
    foreach ($line_items as $line_item) {
      $total += $line_item
        ->totalAmount($tax);
    }
    return $total;
  }

  /**
   * Set the payment status.
   *
   * @param PaymentStatusItem $status_item
   *
   * @return static
   */
  function setStatus(PaymentStatusItem $status_item) {
    $previous_status_item = $this
      ->getStatus();
    $status_item->pid = $this->pid;
    $this->statuses[] = $status_item;
    foreach (module_implements('payment_status_change') as $module_name) {
      call_user_func($module_name . '_payment_status_change', $this, $previous_status_item);

      // If a hook invocation has added another log item, a new loop with
      // invocations has already been executed and we don't need to continue
      // with this one.
      if ($this
        ->getStatus() !== $status_item) {
        return $this;
      }
    }
    if (module_exists('rules')) {
      rules_invoke_event('payment_status_change', $this, $previous_status_item);
    }
    return $this;
  }

  /**
   * Get the current payment status.
   *
   * @return PaymentStatusItem
   */
  function getStatus() {
    return end($this->statuses);
  }

  /**
   * Get available/valid payment methods for this payment.
   *
   * @param PaymentMethod[] $payment_methods
   *   Use an empty array to check the availability of all payment methods.
   *
   * @return PaymentMethod[]
   *   An array with payment methods usable for Payment in its current state,
   *   keyed by PMID.
   */
  function availablePaymentMethods(array $payment_methods = array()) {
    if (!$payment_methods) {
      $payment_methods = entity_load('payment_method', FALSE);
    }
    $available = array();
    foreach ($payment_methods as $payment_method) {
      try {
        $payment_method
          ->validate($this, FALSE);
        $available[$payment_method->pmid] = $payment_method;
      } catch (PaymentValidationException $e) {
      }
    }
    return $available;
  }

}

Members

Name	Modifiers	Type	Description
Payment::$context	public	property	The machine name of the context that created this Payment, such as the webshop module.
Payment::$context_data	public	property	Information about this payment that is specific to the context that created it, such as the webshop module.
Payment::$currency_code	public	property	The ISO 4217 currency code of the payment amount.
Payment::$description	public	property	The general description of this payment. Not to be confused with line item descriptions.
Payment::$description_arguments	public	property	Arguments to pass on to t() when translating $this->description.
Payment::$finish_callback	public	property	The name of a function to call when payment execution is completed, regardless of the payment status. It receives one argument:
Payment::$line_items	public	property	An array with PaymentLineItem objects.
Payment::$method	public	property	The payment method used for this payment.
Payment::$method_data	public	property	Information about this payment that is specific to its payment method.
Payment::$pid	public	property	The internal ID of this payment.
Payment::$statuses	public	property	The status log. Contains PaymentStatusItem objects ordered by datetime. Do not set directly, but use Payment::setStatus() instead.
Payment::$uid	public	property	The UID of the user this payment belongs to.
Payment::availablePaymentMethods		function	Get available/valid payment methods for this payment.
Payment::execute		function	Execute the actual payment.
Payment::finish		function	Finish the payment after its execution.
Payment::getLineItems		function	Get line items.
Payment::getStatus		function	Get the current payment status.
Payment::setLineItem		function	Set a line item.
Payment::setStatus		function	Set the payment status.
Payment::totalAmount		function	Get the total payment amount.
Payment::__construct		function	Constructor. Overrides PaymentCommon::__construct

You are here

class Payment in Payment 7

Hierarchy

See also

File

Members

API Navigation