Composr API documentation
Back to top  

Functions

Add a usergroup subscription.

add_usergroup_subscription(\SHORT_TEXT $title, \LONG_TEXT $description, \SHORT_TEXT $cost, integer $length, \SHORT_TEXT $length_units, \BINARY $auto_recur, \?GROUP $group_id, \BINARY $uses_primary, \BINARY $enabled, \?LONG_TEXT $mail_start, \?LONG_TEXT $mail_end, \?LONG_TEXT $mail_uhoh, array $mails) : \AUTO_LINK
package ecommerce
set y m d w

Parameters

$title

\SHORT_TEXT

The title

$description

\LONG_TEXT

The description

$cost

\SHORT_TEXT

The cost

$length

integer

The length

$length_units

\SHORT_TEXT

The units for the length

$auto_recur

\BINARY

Auto-recur

$group_id

\?GROUP

The usergroup that purchasing gains membership to (null: super members)

$uses_primary

\BINARY

Whether this is applied to primary usergroup membership

$enabled

\BINARY

Whether this is currently enabled

$mail_start

\?LONG_TEXT

The text of the e-mail to send out when a subscription is start (null: default)

$mail_end

\?LONG_TEXT

The text of the e-mail to send out when a subscription is ended (null: default)

$mail_uhoh

\?LONG_TEXT

The text of the e-mail to send out when a subscription cannot be renewed because the subproduct is gone (null: default)

$mails

array

Other e-mails to send

Returns

\AUTO_LINKThe ID

Convert a country code to a currency code.

country_to_currency(\ID_TEXT $country) : \ID_TEXT
package ecommerce

Parameters

$country

\ID_TEXT

The country code.

Returns

\ID_TEXTThe currency code.

Perform a currency conversion.

currency_convert(mixed $amount, \ID_TEXT $from_currency, \?ID_TEXT $to_currency = null, boolean $string = false) : \?mixed
package ecommerce

Parameters

$amount

mixed

The starting amount (integer or float).

$from_currency

\ID_TEXT

The start currency code.

$to_currency

\?ID_TEXT

The end currency code (null: unknown, guess it).

$string

boolean

Whether to get as a string.

Returns

\?mixedThe new amount as float, or if $string then as a string (null: failed to do it).

Delete a usergroup subscription.

delete_usergroup_subscription(\AUTO_LINK $id, \LONG_TEXT $uhoh_mail = '') 
package ecommerce

Parameters

$id

\AUTO_LINK

The ID

$uhoh_mail

\LONG_TEXT

The cancellation mail to send out (blank: none)

Send an IPN call to a remote host for debugging purposes.

dev__ipn_debug(\URLPATH $ipn_target, string $ipn_message) : string

Useful for making one Composr site (caller site) pretend to be PayPal, when talking to another (target site). Make sure the target site has the caller site listed as the backdoor_ip in the base config, or the verification will happen and fail.

package ecommerce

Parameters

$ipn_target

\URLPATH

URL to send IPN to

$ipn_message

string

Post parameters to send, in query string format

Returns

stringOutput

Get the symbol of the currency we're trading in.

ecommerce_get_currency_symbol(\?ID_TEXT $currency = null) : \ID_TEXT
package ecommerce

Parameters

$currency

\?ID_TEXT

The currency (null: configured).

Returns

\ID_TEXTThe currency symbol.

Check whether the system is in test mode (normally, not).

ecommerce_test_mode() : boolean
package ecommerce

Returns

booleanThe answer.

Edit a usergroup subscription.

edit_usergroup_subscription(\AUTO_LINK $id, \SHORT_TEXT $title, \LONG_TEXT $description, \SHORT_TEXT $cost, integer $length, \SHORT_TEXT $length_units, \BINARY $auto_recur, \?GROUP $group_id, \BINARY $uses_primary, \BINARY $enabled, \?LONG_TEXT $mail_start, \?LONG_TEXT $mail_end, \?LONG_TEXT $mail_uhoh, \?array $mails = null) 
package ecommerce
set y m d w

Parameters

$id

\AUTO_LINK

The ID

$title

\SHORT_TEXT

The title

$description

\LONG_TEXT

The description

$cost

\SHORT_TEXT

The cost

$length

integer

The length

$length_units

\SHORT_TEXT

The units for the length

$auto_recur

\BINARY

Auto-recur

$group_id

\?GROUP

The usergroup that purchasing gains membership to (null: super members)

$uses_primary

\BINARY

Whether this is applied to primary usergroup membership

$enabled

\BINARY

Whether this is currently enabled

$mail_start

\?LONG_TEXT

The text of the e-mail to send out when a subscription is start (null: default)

$mail_end

\?LONG_TEXT

The text of the e-mail to send out when a subscription is ended (null: default)

$mail_uhoh

\?LONG_TEXT

The text of the e-mail to send out when a subscription cannot be renewed because the subproduct is gone (null: default)

$mails

\?array

Other e-mails to send (null: do not change)

Exit Composr and write to the error log file.

fatal_ipn_exit(string $error, boolean $dont_trigger = false) : mixed
package ecommerce

Parameters

$error

string

The message.

$dont_trigger

boolean

Dont trigger an error

Returns

mixedNever returns (i.e. exits)

Find all products, except ones from hooks that might have too many to list (so don't rely on this for important backend tasks).

find_all_products(boolean $site_lang = false) : array
package ecommerce

Parameters

$site_lang

boolean

Whether to make sure the language for item_name is the site default language (crucial for when we read/go to third-party sales systems and use the item_name as a key).

Returns

arrayA list of maps of product details.

Find member subscriptions.

find_member_subscriptions(\MEMBER $member_id, boolean $usergroup_subscriptions_only = false) : array
package ecommerce

Parameters

$member_id

\MEMBER

The member.

$usergroup_subscriptions_only

boolean

Whether to limit us to usergroup subscriptions.

Returns

arrayA list of subscriptions and subscription lifetime positions.

Find product.

find_product(\ID_TEXT $search, boolean $site_lang = false, boolean $search_item_names = false) : \?object
package ecommerce

Parameters

$search

\ID_TEXT

The item name/product_id

$site_lang

boolean

Whether to make sure the language for item_name is the site default language (crucial for when we read/go to third-party sales systems and use the item_name as a key).

$search_item_names

boolean

Whether $search refers to the item name rather than the product codename

Returns

\?objectThe product-class object (null: not found).

Find product info row.

find_product_row(\ID_TEXT $search, boolean $site_lang = false, boolean $search_item_names = false) : array
package ecommerce

Parameters

$search

\ID_TEXT

The product codename/item name

$site_lang

boolean

Whether to make sure the language for item_name is the site default language (crucial for when we read/go to third-party sales systems and use the item_name as a key).

$search_item_names

boolean

Whether $search refers to the item name rather than the product codename

Returns

arrayA pair: The product-class map, and the formal product name (both will be NULL if not found).

Get the currency map.

get_currency_map() : array
package ecommerce

Returns

arrayThe currency map, currency code, to an array of country codes.

Get the symbol for a currency.

get_currency_symbol(\ID_TEXT $currency) : array
package ecommerce

Parameters

$currency

\ID_TEXT

The currency.

Returns

arrayA pair: The symbol, and whether the symbol is okay to use on it's own (as it is the accepted default for the symbol).

Find a transaction fee from a transaction amount. Regular fees aren't taken into account.

get_transaction_fee(float $amount, \ID_TEXT $via) : float
package ecommerce

Parameters

$amount

float

A transaction amount.

$via

\ID_TEXT

The service the payment went via.

Returns

floatThe fee

Find a transaction fee from a transaction amount. Regular fees aren't taken into account.

get_transaction_form_fields(\?ID_TEXT $trans_id, \ID_TEXT $purchase_id, \SHORT_TEXT $item_name, \SHORT_TEXT $amount, \?integer $length, \ID_TEXT $length_units, \?ID_TEXT $via = null) : array
package ecommerce

Parameters

$trans_id

\?ID_TEXT

The transaction ID (null: auto-generate)

$purchase_id

\ID_TEXT

The purchase ID

$item_name

\SHORT_TEXT

The item name

$amount

\SHORT_TEXT

The amount

$length

\?integer

The length (null: not a subscription)

$length_units

\ID_TEXT

The length units

$via

\?ID_TEXT

The service the payment will go via via (null: autodetect).

Returns

arrayA pair: The form fields, Hidden fields

Handle IPN's that have been confirmed as backed up by real money.

handle_confirmed_transaction(\ID_TEXT $purchase_id, \SHORT_TEXT $item_name, \ID_TEXT $payment_status, \SHORT_TEXT $reason_code, \SHORT_TEXT $pending_reason, \SHORT_TEXT $memo, \SHORT_TEXT $mc_gross, \SHORT_TEXT $mc_currency, \SHORT_TEXT $txn_id, \SHORT_TEXT $parent_txn_id, string $period, \ID_TEXT $via) : \ID_TEXT
package ecommerce
set Pending Completed SModified SCancelled

Parameters

$purchase_id

\ID_TEXT

The ID of the purchase-type (meaning depends on item_name)

$item_name

\SHORT_TEXT

The item being purchased (aka the product) (blank: subscription, so we need to look it up). One might wonder why we use $item_name instead of $type_code. This is because we pass human-readable-names (hopefully unique!!!) through payment gateways because they are visually shown to the user. (blank: it's a subscription, so look up via a key map across the subscriptions table)

$payment_status

\ID_TEXT

The status this transaction is telling of

$reason_code

\SHORT_TEXT

The code that gives reason to the status

$pending_reason

\SHORT_TEXT

The reason it is in pending status (if it is)

$memo

\SHORT_TEXT

A note attached to the transaction

$mc_gross

\SHORT_TEXT

The amount of money

$mc_currency

\SHORT_TEXT

The currency the amount is in

$txn_id

\SHORT_TEXT

The transaction ID

$parent_txn_id

\SHORT_TEXT

The ID of the parent transaction

$period

string

The subscription period (blank: N/A / unknown: trust is correct on the gateway)

$via

\ID_TEXT

The payment gateway

Returns

\ID_TEXTThe product purchased

Handle IPN's.

handle_transaction_script() : \ID_TEXT
package ecommerce

Returns

\ID_TEXTThe ID of the purchase-type (meaning depends on item_name)

Convert an IP address to a currency code.

ip_to_currency(\?IP $ip = null) : \ID_TEXT
package ecommerce

Parameters

$ip

\?IP

IP address (null: that of current member).

Returns

\ID_TEXTThe currency code.

Make a subscription cancellation button.

make_cancel_button(\AUTO_LINK $purchase_id, \ID_TEXT $via) : \?Tempcode
package ecommerce

Parameters

$purchase_id

\AUTO_LINK

The purchase ID.

$via

\ID_TEXT

The service the payment will go via via.

Returns

\?TempcodeThe button (null: no special cancellation -- just delete the subscription row to stop Composr regularly re-charging)

Make a shopping cart payment button.

make_cart_payment_button(\AUTO_LINK $order_id, \ID_TEXT $currency) : \Tempcode
package ecommerce

Parameters

$order_id

\AUTO_LINK

Order ID

$currency

\ID_TEXT

The currency to use.

Returns

\TempcodeThe button

Make a subscription (payment) button.

make_subscription_button(\ID_TEXT $type_code, \SHORT_TEXT $item_name, \ID_TEXT $purchase_id, float $amount, integer $length, \ID_TEXT $length_units, \ID_TEXT $currency, \?ID_TEXT $via = null) : \Tempcode
package ecommerce
set d w m y

Parameters

$type_code

\ID_TEXT

The product codename.

$item_name

\SHORT_TEXT

The human-readable product title.

$purchase_id

\ID_TEXT

The purchase ID.

$amount

float

A transaction amount.

$length

integer

The subscription length in the units.

$length_units

\ID_TEXT

The length units.

$currency

\ID_TEXT

The currency to use.

$via

\?ID_TEXT

The service the payment will go via via (null: autodetect).

Returns

\TempcodeThe button

Make a transaction (payment) button.

make_transaction_button(\ID_TEXT $type_code, \SHORT_TEXT $item_name, \ID_TEXT $purchase_id, float $amount, \ID_TEXT $currency, \?ID_TEXT $via = null) : \Tempcode
package ecommerce

Parameters

$type_code

\ID_TEXT

The product codename.

$item_name

\SHORT_TEXT

The human-readable product title.

$purchase_id

\ID_TEXT

The purchase ID.

$amount

float

A transaction amount.

$currency

\ID_TEXT

The currency to use.

$via

\?ID_TEXT

The service the payment will go via via (null: autodetect).

Returns

\TempcodeThe button

Find whether local payment will be performed.

perform_local_payment() : boolean
package ecommerce

Returns

booleanWhether local payment will be performed.

Get template-ready parameters for displaying a subscription.

prepare_templated_subscription(array $subscription) : array
package ecommerce

Parameters

$subscription

array

Subscription details.

Returns

arrayTemplate-ready parameters.

Send an invoice notification to a member.

send_invoice_notification(\MEMBER $member_id, \AUTO_LINK $id) 
package ecommerce

Parameters

$member_id

\MEMBER

The member to send to.

$id

\AUTO_LINK

The invoice ID.

Constants

 

ECOMMERCE_PRODUCT_ALREADY_HAS

ECOMMERCE_PRODUCT_ALREADY_HAS = 2 
package ecommerce
 

ECOMMERCE_PRODUCT_AVAILABLE

ECOMMERCE_PRODUCT_AVAILABLE = 0 
package ecommerce
 

ECOMMERCE_PRODUCT_DISABLED

ECOMMERCE_PRODUCT_DISABLED = 3 
package ecommerce
 

ECOMMERCE_PRODUCT_INTERNAL_ERROR

ECOMMERCE_PRODUCT_INTERNAL_ERROR = 7 
package ecommerce
 

ECOMMERCE_PRODUCT_MISSING

ECOMMERCE_PRODUCT_MISSING = 6 
package ecommerce
 

ECOMMERCE_PRODUCT_NO_GUESTS

ECOMMERCE_PRODUCT_NO_GUESTS = 1 
package ecommerce
 

ECOMMERCE_PRODUCT_OUT_OF_STOCK

ECOMMERCE_PRODUCT_OUT_OF_STOCK = 5 
package ecommerce
 

ECOMMERCE_PRODUCT_PROHIBITED

ECOMMERCE_PRODUCT_PROHIBITED = 4 
package ecommerce
 

PRODUCT_CATALOGUE

PRODUCT_CATALOGUE = 4 
package ecommerce
 

PRODUCT_INVOICE

PRODUCT_INVOICE = 1 
package ecommerce
 

PRODUCT_ORDERS

PRODUCT_ORDERS = 5 
package ecommerce
 

PRODUCT_OTHER

PRODUCT_OTHER = 3 
package ecommerce
 

PRODUCT_PURCHASE_WIZARD

PRODUCT_PURCHASE_WIZARD = 0 
package ecommerce
 

PRODUCT_SUBSCRIPTION

PRODUCT_SUBSCRIPTION = 2 
package ecommerce