The Inx_Api_Recipient_RecipientContext is used to access and manipulate recipient data.
The Inx_Api_Recipient_RecipientContext is used to access and manipulate recipient data. The following operations can be performed using the RecipientContext:
$oRecipientContext = $oSession->createRecipientContext(); $oAttribute = $oRecipientContext->getMetaData()->getUserAttribute( "name" ); $oListContext = $oSession->getListContextManager()->findByName( "Desired list" ); $sNameFilter = 'Column("name") LIKE "m%"'; $oRecipientRowSet = $oRecipientContext->select( $oListContext, null, $sNameFilter, $oAttribute, Inx_Api_Order::ASC ); while( $oRecipientRowSet->next() ) { echo $oRecipientRowSet->getString( $oAttribute )."<br>"; } $oRecipientRowSet->close();To fetch only recipients which unsubscribed from a specific list, use the selectUnsubscriber() method which returns an Inx_Api_Recipient_UnsubscriptionRecipientRowSet.
Adding and removing recipients can be accomplished in two ways:
The following snippet shows how to add a new recipient using an empty Inx_Api_Recipient_RecipientRowSet:
$oRecipientContext = $oSession->createRecipientContext(); $oRecipientRowSet = $oRecipientContext->createRowSet(); $oAttribute = $oRecipientRowSet->getMetaData()->getEmailAttribute(); $oRecipientRowSet->moveToInsertRow(); $oRecipientRowSet->updateString( $oAttribute, "new@recipient.invalid" ); $oRecipientRowSet->commitRowUpdate(); $oRecipientRowSet->close();Removing a recipient using the Inx_Api_Recipient_RecipientRowSet can be accomplished by selecting only one specific recipient. To do so, use a filter expression on the email attribute. The following snippet shows how to do this:
$oRecipientContext = $oSession->createRecipientContext(); $oRecipientRowSet = $oRecipientContext->select( null, null, 'Column("email") = "abusive@recipient.invalid"' ); $oRecipientRowSet->next(); $oRecipientRowSet->deleteRow(); $oRecipientRowSet->close();Note: Both tasks are easier to perform using the Inx_Api_Recipient_BatchChannel.
The retrieval of recipient attributes using the Inx_Api_Recipient_RecipientMetaData was already shown in the fetching example. Creating new attributes is almost as easy, as shown in the following snippet which creates the previously used name attribute:
$oAttributeManager = $oSession->getAttributeManager(); $oAttributeManager->create( "name", Inx_Api_Recipient_Attribute::DATA_TYPE_STRING, 50 );For more information on the manipulation of recipient attributes, see the Inx_Api_Recipient_AttributeManager documentation.
A more common action than manipulating recipient attributes is to update their values. There are several ways in which this can be accomplished:
$oRecipientContext = $oSession->createRecipientContext(); $oAttribute = $oRecipientContext->getMetaData()->getUserAttribute( "defaultFormat" ); $value = new stdClass(); $value->value = "html"; $oRecipientContext->setAttributeValue( $oAttribute, $value );Setting the attribute value for all recipients in a specific Inx_Api_Recipient_RecipientRowSet works very much the same. Also, the RecipientRowSet can be used to change the attribute value for a selection of recipients in the set. The following snippet shows how to do this:
$oRecipientContext = $oSession->createRecipientContext(); $oAttribute = $oRecipientContext->getMetaData()->getUserAttribute( "top10" ); $oRecipientRowSet = $oRecipientContext->select(); // fetches all recipients $value = new stdClass(); $value->value = true; $oRecipientRowSet->setAttributeValue( $oAttribute, $value, new Inx_Api_IndexSelection( 0, 9 ) ); $oRecipientRowSet->close();The last available option is to change the attribute value of a single recipient. The recipient creation example further above used this method to update the email address of the newly created recipient.
For an example on how to resubscribe recipients to a list, see the Inx_Api_Recipient_UnsubscriptionRecipientRowSet documentation.
<strong>Note:</strong> Getting this context from the session will get a snapshot of the current attributes defined. This snapshot will be used for the lifetime of the context, changes in the underlying attribute configuration won't be reflected to it. This ensures that you can safely work with recipient data, even if other users possibly add or change attributes.
However, if a recipient attribute is deleted or the type is changed, this will also not be reflected to the RecipientContext. The attribute values may still be changed without any error, though this change will not be visible in Inxmail. The recipient attribute will not be undeleted. Therefore, it is not recommended to use the same recipient context during long operations as the possibility of changes in the recipient attributes will rise.
Instead of creating a new Inx_Api_Recipient_RecipientContext repeatedly (possibly without any need to do this), it is also possible to check whether some attributes have changed. This can be achieved using the isUpToDate() method. The following snippet shows hot to use this method:
$oRecipientContext = $oSession->createRecipientContext(); while( !$taskDone ) { if( !$oRecipientContext->isUpToDate() ) { $oRecipientContext = $oSession->createRecipientContext(); } // perform some operations on the recipient context }Of course this is a very simple example, though it illustrates how to update the RecipientContext only if needed. A more realistic example might be a triggered operation that checks if the RecipientContextis still up to date (possibly some time passed after the last trigger) before executing the operation.
<strong>Note:</strong> An Inx_Api_Recipient_RecipientContext object <strong>must</strong> be closed once it is not needed anymore to prevent memory leaks and other potentially harmful side effects.
Located in /Api/Recipient/RecipientContext.php (line 184)
Closes this recipient context and releases any resources associated with it.
Closes this recipient context and releases any resources associated with it. An Inx_Api_Recipient_RecipientContext object <strong>must</strong> be closed once it is not needed anymore to prevent memory leaks and other potentially harmful side effects.
Creates an Inx_Api_Recipient_BatchChannel for fast recipient data manipulation with an optional alternative 'key attribute' to select the recipient.
Creates an Inx_Api_Recipient_BatchChannel for fast recipient data manipulation with an optional alternative 'key attribute' to select the recipient. The type of the select attribute must be Inx_Api_Recipient_Attribute::DATA_TYPE_STRING or Inx_Api_Recipient_Attribute::DATA_TYPE_INTEGER. If the specified select value exists for multiple recipients, any of these recipients may be selected (undetermined).
Returns an empty Inx_Api_Recipient_RecipientRowSet.
Returns an empty Inx_Api_Recipient_RecipientRowSet. Use this to add new recipients to the system.
Returns an Inx_Api_Recipient_RecipientRowSet containing all recipients with the specified key.
Returns an Inx_Api_Recipient_RecipientRowSet containing all recipients with the specified key. If multiple recipients use that key, all of them will be retrieved. If you wish to retrieve only the first recipient with that key, use findByKey($sKey) instead.
Returns an Inx_Api_Recipient_RecipientRowSet containing all recipients with the specified keys.
Returns an Inx_Api_Recipient_RecipientRowSet containing all recipients with the specified keys. If multiple recipients use one of the keys, all of them will be retrieved. If you wish to retrieve only the first recipient with that key, use findByKeys($aKeys) instead.
Returns an Inx_Api_Recipient_RecipientRowSet containing all recipients specified by the given IDs.
Returns an Inx_Api_Recipient_RecipientRowSet containing all recipients specified by the given IDs. For each ID that cannot be mapped to an existing recipient ID, the returned RecipientRowSet contains a NULL entry.
Returns an Inx_Api_Recipient_RecipientRowSet containing exactly one recipient: the one with the specified key.
Returns an Inx_Api_Recipient_RecipientRowSet containing exactly one recipient: the one with the specified key. If multiple recipients use that key, only the first one will be retrieved. If you wish to retrieve all recipients with the given key, use findAllByKey($sKey) instead.
Returns an Inx_Api_Recipient_RecipientRowSet containing all recipients with the specified keys.
Returns an Inx_Api_Recipient_RecipientRowSet containing all recipients with the specified keys. If multiple recipients use one of the keys, only the first one will be retrieved. If you wish to retrieve all recipients with that key, use findAllByKeys($aKeys) instead.
Returns an Inx_Api_Recipient_RecipientRowSet containing all recipients associated with the specified sending.
Returns an Inx_Api_Recipient_RecipientRowSet containing all recipients associated with the specified sending. Be aware that any recipients which are not existing anymore (with respect to their ID) are not included in the result.
Retrieves an Inx_Api_Recipient_RecipientMetaData object that contains meta data about the recipients represented by this Inx_Api_Recipient_RecipientMetaData object.
Retrieves an Inx_Api_Recipient_RecipientMetaData object that contains meta data about the recipients represented by this Inx_Api_Recipient_RecipientMetaData object. The meta data includes information about the available attributes, though can not be used to retrieve the actual attribute values.
Determines if the key is unique. you need not worry about this method.
Determines if the key is unique. If you have not explicitly allowed the recipient key to have duplicate values, you need not worry about this method.
Checks whether or not this Inx_Api_Recipient_RecipientContext is up to date.
Checks whether or not this Inx_Api_Recipient_RecipientContext is up to date. If attributes were added, removed or manipulated (renamed, different type) since this RecipientContext was created, false will be returned. This information may be used to check whether the RecipientContext needs to be updated before executing the next operation.
Returns an Inx_Api_Recipient_RecipientRowSet containing all recipients that are members of the given list and match the given filter and additional filter statement, ordered by the given attribute and order type.
Returns an Inx_Api_Recipient_RecipientRowSet containing all recipients that are members of the given list and match the given filter and additional filter statement, ordered by the given attribute and order type. All of the parameters are optional and may be omitted. For further information on the filter statement syntax, see the Inx_Api_Filter_Filter::updateStatement($sStmt) documentation.
Returns an Inx_Api_Recipient_UnsubscriptionRecipientRowSet containing all recipients that have been unsubscribed from the given list and match the given filter and additional filter statement, ordered by the given attribute and order type.
Returns an Inx_Api_Recipient_UnsubscriptionRecipientRowSet containing all recipients that have been unsubscribed from the given list and match the given filter and additional filter statement, ordered by the given attribute and order type. All parameters except for the list are optional and may be omitted. For further information on the filter statement syntax, see the Inx_Api_Filter_Filter::updateStatement($sStmt) documentation.
Sets the specified attribute value to all recipients in the system.
Sets the specified attribute value to all recipients in the system. Note: $newValue must be of type stdClass. To set the actual value, use the value variable. The following snippet demonstrates this:
$value = new stdClass(); $value->value = "the new value of any type"; $oRecipientContext->setAttributeValue($oAttribute, $value);
Documentation generated on Thu, 17 Sep 2015 14:27:28 +0200 by phpDocumentor 1.3.2