give.module

<?php

/**
 * @file
 * Enables the use of donation forms to give money on your site.
 */

use Drupal\Core\Routing\RouteMatchInterface;
use Drupal\Core\Entity\EntityInterface;
use Drupal\Core\Entity\EntityTypeInterface;
use Drupal\Core\Url;
use Drupal\Component\Utility\Xss;
use Drupal\filter\Entity\FilterFormat;

/**
 * Denotes that the donation is not completed.
 */
const DONATION_NOT_COMPLETED = 0;

/**
 * Denotes that the donation is completed.
 */
const DONATION_COMPLETED = 1;

/**
 * Process donation with Stripe.
 */
const GIVE_WITH_STRIPE = 1;

/**
 * Process donation with Dwolla.
 */
const GIVE_WITH_DWOLLA = 2;

/**
 * Accept a pledge to pay by check or other.
 */
const GIVE_WITH_CHECK = 3;

/**
 * Return array of donation method constants with human-readable, text names.
 *
 * @param bool $long
 */
function give_methods($long = FALSE) {
  if ($long !== TRUE) {
    $pairs = [
      GIVE_WITH_STRIPE => t('Card'),
      GIVE_WITH_CHECK => t('Check'),
      GIVE_WITH_DWOLLA => t('Bank transfer'),
    ];
  }
  else {
    $pairs = [
      GIVE_WITH_STRIPE => t('Payment card (Stripe)'),
      GIVE_WITH_CHECK => t('Check pledge'),
      GIVE_WITH_DWOLLA => t('Bank transfer (Dwolla)'),
    ];
  }
  return $pairs;
}

/**
 * Implements hook_help().
 */
function give_help($route_name, RouteMatchInterface $route_match) {

  switch ($route_name) {
    case 'help.page.give':
      $menu_page = \Drupal::moduleHandler()->moduleExists('menu_ui') ? \Drupal::url('entity.menu.collection') : '#';
      $block_page = \Drupal::moduleHandler()->moduleExists('block') ? \Drupal::url('block.admin_display') : '#';
      $give_page = \Drupal::url('entity.give_form.collection');
      $output = '';
      $output .= '<h3>' . t('About') . '</h3>';
      $output .= '<p>' . t('The Give module allows visitors to donate to you with credit/debit card or bank transfer using donation forms you can configure. For more information, see the <a href=":give">online documentation for the Give module</a>.', [':give' => 'https://www.drupal.org/project/give']) . '</p>';
      $output .= '<h3>' . t('Uses') . '</h3>';
      $output .= '<dl>';
      $output .= '<dt>' . t('Configuring give (donation) forms') . '</dt>';
      $output .= '<dd>' . t('On the <a href=":give_admin">Give forms page</a>, you can configure the fields and display of the donation forms. Each give form has a machine name, a label, and zero or more defined recipients to receive notification when someone donates (or tries to donate).', [':give_admin' => $give_page]) . '</dd>';
      $output .= '<dt>' . t('Linking to give (donation) forms') . '</dt>';
      $output .= '<dd>' . t('One give form can be designated as the default donation form. If you choose to designate a default form, the <em>Give</em> menu link in the <em>Main</em> menu will link to it. You can modify this link from the <a href=":menu-settings">Menus page</a> if you have the Menu UI module installed. You can also create links to other give forms; the URL for each form you have set up has format <em>give/machine_name_of_form</em>.', [':menu-settings' => $menu_page]) . '</p>';
      $output .= '<dt>' . t('Adding fields to give forms') . '</dt>';
      $output .= '<dd>' . t('From the <a href=":give_admin">Give forms page</a>, you can configure the fields to be shown on different give forms, including their labels and help text. If you would like other content (such as text or images) to appear on a donation form, use a block. You can create and edit blocks on the <a href=":blocks">Block layout page</a>, if the Block module is installed. Another possibility is to embed donation forms in content with an entity reference field, or in paragraphs with the contributed <a href=":paragraphs">Paragraphs module</a>.', [':blocks' => $block_page, ':give_admin' => $give_page, ':paragraphs' => 'https://www.drupal.org/project/paragraphs']) . '</dd>';
      $output .= '</dl>';
      return $output;

  }
}

/**
 * Implements hook_entity_extra_field_info().
 */
function give_entity_extra_field_info() {
  $fields = [];
  foreach (array_keys(\Drupal::service('entity_type.bundle.info')->getBundleInfo('give_donation')) as $bundle) {
    $fields['give_donation'][$bundle]['form']['name'] = [
      'label' => t('Donor name'),
      'description' => t('Text'),
      'weight' => -50,
    ];
    $fields['give_donation'][$bundle]['form']['mail'] = [
      'label' => t('Donor e-mail'),
      'description' => t('Email'),
      'weight' => -40,
    ];
    $fields['give_donation'][$bundle]['form']['recurring'] = [
      'label' => t('Recurring donation'),
      'description' => t('Option'),
      'weight' => 50,
    ];
  }
  return $fields;
}

/**
 * Implements hook_entity_base_field_info_alter().
 *
 * Makes fields on donations configurable.
 *
 * @TODO do this in the first place rather than as an alter hook.
 */
function give_entity_base_field_info_alter(&$fields, EntityTypeInterface $entity_type) {
  if ($entity_type->id() == 'give_donation') {
    foreach ([
      'name',
      'mail',
      'give_form',
      'label',
      'uuid',
      'id',
      'langcode',
      'amount',
      'recurring',
      'created',
      'method',
      'telephone',
      'check_or_other_information',
      'complete',
      'address_line1',
      'address_line2',
      'address_city',
      'address_state',
      'address_zip',
      'address_country',
      'stripe_token',
      'card_funding',
      'card_brand',
      'card_last4',
      'changed',
    ] as $field_name) {
      $fields[$field_name]->setDisplayConfigurable('view', TRUE);
    }
  }
}

/**
 * Implements hook_entity_operation().
 */
function give_entity_operation(EntityInterface $entity) {
  $operations = [];
  $info = $entity->getEntityType();
  // Add preview e-mails link to Give (donation) forms.
  if ($info->getBundleOf() == 'give_donation') {
    $account = \Drupal::currentUser();
    if ($account->hasPermission('create and edit give forms')) {
      $operations['preview-reply'] = [
        'title' => t('Preview e-mails'),
        'weight' => 15,
        'url' => Url::fromRoute("entity.give_form.preview_reply", [
          $entity->getEntityTypeId() => $entity->id(),
        ]),
      ];
    }
  }

  return $operations;
}

/**
 * Implements hook_mail().
 */
function give_mail($key, &$message, $params) {
  $give_donation = $params['give_donation'];
  /** @var $donor \Drupal\user\UserInterface */
  $donor = $params['donor'];
  $language = \Drupal::languageManager()->getLanguage($message['langcode']);

  $variables = [
    '@site-name' => \Drupal::config('system.site')->get('name'),
    '@label' => $give_donation->getLabel(),
    '@form' => !empty($params['give_form']) ? $params['give_form']->label() : NULL,
    '@form-url' => \Drupal::url('<current>', [], ['absolute' => TRUE, 'language' => $language]),
    '@donor-name' => $donor->getDisplayName(),
  ];
  if ($donor->isAuthenticated()) {
    $variables['@donor-url'] = $donor->url('canonical', ['absolute' => TRUE, 'language' => $language]);
  }
  else {
    $variables['@donor-url'] = $params['donor']->getEmail();
  }

  switch ($key) {
    case 'donation_notice':
      $options = ['langcode' => $language->getId()];
      $message['subject'] .= t('[@form] @label', $variables, $options);
      // $message['body'][] = t("", $variables, $options);
      $markup = entity_view($give_donation, 'notice');
      $message['body'][] = render($markup);
      break;

    case 'donation_receipt':

      $give_form = $params['give_form'];
      switch ($give_donation->getReplyType()) {
        case 'onetime':
          $params['reply'] = $give_form->get('reply');
          $params['subject'] = $give_form->get('subject');
          break;
        case 'recurring':
          $params['reply'] = $give_form->get('reply_recurring');
          $params['subject'] = $give_form->get('subject_recurring');
          break;
        case 'pledge':
          $params['reply'] = $give_form->get('reply_pledge');
          $params['subject'] = $give_form->get('subject_pledge');
          break;
        default:
          $this->logger->notice('Unknown reply type %type triggered for %donor-name (@donor-from) via %give_form; no message sent.', [
            '%donor-name' => $donor->getDisplayName(),
            '@donor-from' => $donor->getEmail(),
            '%give_form' => $give_form->label(),
            '%type' => $give_donation->getReplyType(),
          ]);
      }

      $message['subject'] .= give_replace_donation_tokens($params['subject'], $give_donation);

      $render_array = [
        "#type" => "processed_text",
        "#text" => give_replace_donation_tokens($params['reply'], $give_donation),
        "#format" => give_format(),
        "#langcode" => $language->getId(),
      ];
      $message['body'][] = render($render_array);

      $markup = entity_view($give_donation, 'receipt');
      $message['body'][] = render($markup);
      break;
  }
}

/**
 * Implements hook_theme().
 */
function give_theme($existing, $type, $theme, $path) {
  return [
    // Make Drupal aware of our field template for our view mode.
    // @see give_theme_suggestions_field_alter().
    'field__give_donation__mail' => [
      'base hook' => 'field',
    ],
  ];
}

/**
 * Implement hook_theme_suggestions_HOOK_alter() for fields.
 *
 * Provide an alternate suggestion for fields in our donation e-mail view modes.
 */
function give_theme_suggestions_field_alter(array &$suggestions, array $variables) {
  // If it's not from our module, don't mess with it.
  if ($variables['element']['#entity_type'] !== 'give_donation' || $variables['element']['#bundle'] !== 'donate') {
    return;
  }

  if (in_array($variables['element']['#view_mode'], ['notice', 'receipt'], TRUE)) {
    $suggestions[] = 'field__give_donation__mail';
  }
}

/**
 * Simple no-dependency token replacement.  More robust would be better.
 */
function give_replace_donation_tokens($message, \Drupal\give\DonationInterface $donation) {
  $search_replace = [
    '[donor_name]' => $donation->getDonorName(),
    '[donor_email]' => $donation->getDonorMail(),
    '[give_label]' => $donation->getGiveForm()->label(),
    '[dollar_amount]' => $donation->getDollarAmount(),
    '[recurring]' => $donation->recurring() ? 'recurring ' : '',
    '[recurrence]' => strtolower($donation->getRecurrence()),
    '[today_date]' => strftime('%B %e, %Y'),
    '[date]' => strftime('%B %e, %Y', $donation->getUpdatedTime()),
  ];
  return str_replace(give_donation_tokens(), array_values($search_replace), $message);
}

/**
 * Tokens used in simple search-replace for donation messages.
 */
function give_donation_tokens() {
  return [
    '[donor_name]',
    '[donor_email]',
    '[give_label]',
    '[dollar_amount]',
    '[recurring]',
    '[recurrence]',
    '[today_date]',
    '[date]',
  ];
}

/**
 * Default pre-created frequencies.
 */
function give_get_default_frequencies() {
  return [
    0 => ['interval' => 'month', 'interval_count' => '1', 'description' => 'Every month'],
    1 => ['interval' => 'month', 'interval_count' => '3', 'description' => 'Every 3 months (quarterly)'],
    2 => ['interval' => 'month', 'interval_count' => '6', 'description' => 'Every 6 months (semi-annually)'],
    3 => ['interval' => 'month', 'interval_count' => '12', 'description' => 'Every year (annually)'],
  ];
}

/**
 * Get the text format used for processing administrator-entered messages.
 *
 * Give module requires Minimal HTML module, which sets up the minimalhtml text
 * format, but there's no guarantee in Drupal that a text format won't have its
 * name changed or be deleted, so if necessary complain and use a fallback.
 */
function give_format() {
  if (FilterFormat::load('minimalhtml')) {
    return 'minimalhtml';
  }
  else {
     \Drupal::logger('give')->error('Missing format <em>minimalhtml</em>; administrator-defined messages on the donation form and receipts may lack formatting. Make sure <a href="https://www.drupal.org/project/minimalhtml">Minimal HTML</a> module is enabled and an appropriate format called <em>minimalhtml</em> is present.');
    return filter_fallback_format();
  }
}