Allow other module's to alter Recurly Account object before saving

Another, similar issue that I'm running into is the need to make use of the $subscription object created in recurlyjs_subscribe_form_submit() after the form is submitted. My use-case is wanting to log an event/transaction in Google Analytics. In previous versions of the module I added a submit handler to the form, and used the $form_state['recurly_status'] object that was added when validating the JS token. That code doesn't exist anymore though.

My suggestion in this case is to add something like the following:

// Allow other modules the chance to alter the new Recurly_Subscription object
// before it is saved.
drupal_alter('recurlyjs_subscription', $subscription, $entity, $plan_code);

$subscription->create();

// Allow other modules to react to the new subscription being created.
module_invoke_all('recurlyjs_new_subscription', $subscription, $entity);

If you remove the not necessary call to $recurly_account->create() (See #2854667: Display error message for declined credit cards) this will allow someone to modify the Recurly_Account, and Recurly_Subscription objects prior to saving them.

In my version I ended up re-writing this to use hook_recurlyjs_subscription_alter(), and hook_recurlyjs_new_subscription().

I've attached my updated recurlyjs.api.php file.

And here's what I've got for the submit handler at the moment. This also includes some code that's not really related to this issue, like catching some validation errors for example. However, what it does do is remove the extra call to $recurly_account->create() which isn't necessary, so we can have a single point to alter the entire subscription object before it's saved. And then invoke the alter, and new_subscription hooks. Hopefully this is helpful.

/**
 * Submit handler for recurlyjs_subscribe_form().
 */
function recurlyjs_subscribe_form_submit($form, &$form_state) {
  $entity_type = $form['#entity_type'];
  $entity = $form['#entity'];
  $plan_code = $form['#plan_code'];
  $currency = $form['#currency'];
  $recurly_token = isset($form_state['values']['recurly-token']) ? $form_state['values']['recurly-token'] : NULL;
  $coupon_code = isset($form_state['values']['coupon_code']) ? $form_state['values']['coupon_code'] : NULL;

  list($entity_id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
  $recurly_account = recurly_account_load(array('entity_type' => $entity_type, 'entity_id' => $entity_id));

  if (!$recurly_account) {
    $recurly_account = new Recurly_Account();

    $recurly_account->first_name = check_plain($form_state['values']['first_name']);
    $recurly_account->last_name = check_plain($form_state['values']['last_name']);

    if ($entity_type == 'user') {
      $recurly_account->email = $entity->mail;
      $recurly_account->username = $entity->name;
    }

    // Account code is the only property required for Recurly account creation.
    // https://dev.recurly.com/docs/create-an-account.
    $recurly_account->account_code = $entity_type . '-' . $entity_id;
  }

  $subscription = new Recurly_Subscription();
  $subscription->account = $recurly_account;
  $subscription->plan_code = $plan_code;
  $subscription->currency = $currency;
  $subscription->coupon_code = $coupon_code;

  // Allow other modules the chance to alter the new Recurly Subscription object
  // before it is saved.
  drupal_alter('recurlyjs_subscription', $subscription, $entity, $plan_code);

  // Billing info is based on the token we retrieved from the Recurly JS API
  // and should only contain the token in this case. We add this after the above
  // alter hook to ensure it's not modified.
  $subscription->account->billing_info = new Recurly_BillingInfo();
  $subscription->account->billing_info->token_id = $recurly_token;

  try {
    // This saves all of the data assembled above in addition to creating a new
    // subscription record.
    $subscription->create();
  }
  catch (Recurly_ValidationError $e) {
    // There was an error validating information in the form. For example,
    // credit card was declined. We don't need to log these in Drupal, you can
    // find the errors logged within Recurly.
    drupal_set_message(t('<strong>Unable to create subscription:</strong><br/>@error', array('@error' => $e->getMessage())), 'error');
    $form_state['rebuild'] = TRUE;
    return;
  }
  catch (Recurly_Error $e) {
    // Catch any non-validation errors. This will be things like unable to
    // contact Recurly API, or lower level errors. Display a generic message to
    // the user letting them know there was an error and then log the detailed
    // version. There's probably nothing a user can do to correct these errors
    // so we don't need to display the details.
    watchdog('recurlyjs', 'Unable to create subscription: @error', array('@error' => $e->getMessage()));
    drupal_set_message(t('An error occured while trying to create your subscription. Please contact a site administrator.'));
    $form_state['rebuild'] = TRUE;
    return;
  }

  // Allow other modules to react to the new subscription being created.
  module_invoke_all('recurlyjs_new_subscription', $subscription, $entity);

  drupal_set_message(t('Account upgraded to @plan!', array('@plan' => $subscription->plan->name)));

  // Save the account locally immediately so that subscriber information may
  // be retrieved when the user is directed back to the /subscription tab.
  try {
    $account = $subscription->account->get();
    recurly_account_save($account, $entity_type, $entity_id);
  }
  catch (Recurly_Error $e) {
    watchdog('recurly', 'New subscriber account could not be retreived from Recurly. Received the following error: @error', array('@error' => $e->getMessage()));
  }

  $form_state['redirect'] = $entity_type . '/' . $entity_id . '/subscription';
}