Acumulus::create()->getAcumulusContainer()
*
* @return \Siel\Acumulus\Helpers\Container
*/
public function getAcumulusContainer(): Container
{
$this->init();
return $this->acumulusContainer;
}
/**
* Adds our pages to the admin menu.
*
* We load the translations for each form to be able to show the translated
* form titles and headers.
*/
public function addMenuLinks(): void
{
// Initialise translations.
$this->getAcumulusContainer()->getTranslator()->add(new ConfigFormTranslations());
add_submenu_page(
'options-general.php',
$this->t('settings_form_title'),
$this->t('settings_form_header'),
'manage_options',
'acumulus_settings',
[$this, 'processSettingsForm']
);
add_submenu_page(
'options-general.php',
$this->t('mappings_form_title'),
$this->t('mappings_form_header'),
'manage_options',
'acumulus_mappings',
[$this, 'processMappingsForm']
);
$this->getAcumulusContainer()->getTranslator()->add(new ActivateSupportFormTranslations());
add_submenu_page(
'options-general.php',
$this->t('activate_form_title'),
$this->t('activate_form_header'),
'manage_options',
'acumulus_activate',
[$this, 'processActivateForm']
);
// Do not show the registration form if we have valid account settings. In WP you
// do so by using another page as the parent.
$accountStatus = $this->getAcumulusContainer()->getCheckAccount()->getAccountStatus();
$parent = $accountStatus === true ? 'acumulus_activate' : 'options-general.php';
$this->getAcumulusContainer()->getTranslator()->add(new RegisterFormTranslations());
add_submenu_page(
$parent,
$this->t('register_form_title'),
$this->t('register_form_header'),
'manage_options',
'acumulus_register',
[$this, 'processRegisterForm']
);
$this->getAcumulusContainer()->getTranslator()->add(new BatchFormTranslations());
add_submenu_page(
'woocommerce',
$this->t('batch_form_title'),
$this->t('batch_form_header'),
'manage_woocommerce',
'acumulus_batch',
[$this, 'processBatchForm']
);
}
/**
* Shows admin notices.
*
* Due to the order of execution and the habit of redirecting at the end of
* an action, just adding a notice may not work. Therefore, we work with
* transients.
*
* @throws \Throwable
*/
public function showAdminNotices(): void
{
// These notices should only show on the main dashboard and our own screens.
if ($this->isDashboard() || $this->isOwnPage()) {
// Notice about the new version.
if (time() >= $this->getAcumulusContainer()->getConfig()->get('showPluginV84Message')) {
echo $this->processMessageForm();
}
// Notice about rating our plugin.
if (time() >= $this->getAcumulusContainer()->getConfig()->getShowRatePluginMessage()) {
echo $this->processRatePluginForm();
}
}
}
/**
* Handles ajax requests for this plugin.
*
* Uses of ajax:
* - Invoice status overview.
* - Rate plugin message.
* - plugin new version message.
* - Mail invoice/packing slip from the order list. This use is not a real ajax
* request but uses admin-ajax.php as the entry point like WooCommerce does:
* no need to define a proper admin page and finish with a redirect back to
* the order list.
*
* @throws \Throwable
*/
public function handleAjaxRequest(): void
{
check_ajax_referer('acumulus_ajax_action', 'acumulus_nonce');
// Check where the ajax call came from.
if (isset($_POST['area'])) {
$content = match ($_POST['area']) {
'acumulus-invoice' => $this->processInvoiceStatusForm(),
'acumulus-rate' => $this->processRatePluginForm(),
'acumulus-message' => $this->processMessageForm(),
default => $this->renderNotice('Area parameter of ajax request unknown to Acumulus.', 'error'),
};
} elseif (isset($_REQUEST['acumulus_action'])) {
// @nth: should we have some visual feedback here, in case of both
// error and success. Given the redirect at the end, this needs
// transient flags or messages. See e.g:
// - https://wordpress.stackexchange.com/questions/261167/getting-admin-notices-to-appear-after-page-refresh
// - https://github.com/wpscholar/wp-transient-admin-notices
switch ($_REQUEST['acumulus_action']) {
case 'acumulus-document-invoice-mail':
case 'acumulus-document-packing-slip-mail':
$result = $this->mailPdf($_REQUEST['acumulus_action'], $_REQUEST['order_id']);
/** @noinspection PhpUnusedLocalVariableInspection @todo: do something with this content. */
$content = !$result->hasError() ? '✓' : '❌';
break;
default:
/** @noinspection PhpUnusedLocalVariableInspection */
$content = $this->renderNotice('Acumulus_action parameter of ajax request unknown to Acumulus.', 'error');
}
wp_safe_redirect(wp_get_referer() ?: admin_url($this->getOrderListPage()));
exit;
} else {
$content = $this->renderNotice('No recognised Acumulus ajax request.', 'error');
}
wp_send_json(['content' => $content]);
}
/**
* Mails an Acumulus invoice or packing slip PDF.
*
* @param string $acumulusAction
* Either 'acumulus-invoice' or 'acumulus-packing-slip' (already checked
* for).
* @param int $order_id
* The order id. The parameter type conversion will throw an error if
* someone played with the order_id parameter.
*
* @return \Siel\Acumulus\ApiClient\AcumulusResult
*/
public function mailPdf(string $acumulusAction, int $order_id): AcumulusResult
{
$source = $this->getAcumulusContainer()->createSource(Source::Order, $order_id);
return $acumulusAction === 'acumulus-document-invoice-mail'
? $this->getAcumulusContainer()->getInvoiceManager()->emailInvoiceAsPdf($source)
: $this->getAcumulusContainer()->getInvoiceManager()->emailPackingSlipAsPdf($source);
}
/**
* Action handler for the add_meta_boxes_{order-type-or-screen-id} actions.
*
* @param \WP_Post|\WC_Order $shopOrderOrPost
* This will be a:
* - WP_POST: on the legacy screen.
* - WC_Order: on the HPOS screen.
*
* @throws \Throwable
*/
public function addShopOrderMetaBox(WP_Post|WC_Abstract_Order $shopOrderOrPost): void
{
$orderId = ($shopOrderOrPost instanceof WP_Post) ? $shopOrderOrPost->ID : $shopOrderOrPost->get_id();
$invoiceStatusSettings = $this->getAcumulusContainer()->getConfig()->getInvoiceStatusSettings();
if ($invoiceStatusSettings['showInvoiceStatus']) {
// Create the form to load the form translations and set its Source.
/** @var \Siel\Acumulus\Shop\InvoiceStatusForm $form */
try {
$form = $this->getForm('invoice');
$source = $this->getAcumulusContainer()->createSource(Source::Order, $orderId);
$form->setSource($source);
add_meta_box(
'acumulus-invoice-status-overview',
$this->t('invoice_form_title'),
[$this, 'outputInvoiceStatusInfoBox'],
get_current_screen()?->id,
'side'
);
} catch (Throwable $e) {
// We do not show the meta-box, not even a message (though we
// could add an action for admin_notices), the mail should
// suffice to inform the user.
try {
$crashReporter = $this->getAcumulusContainer()->getCrashReporter();
$crashReporter->logAndMail($e);
} catch (Throwable) {
// We don't know if we have informed the user per mail or
// screen, so assume we didn't, and rethrow the original exception.
throw $e;
}
}
}
}
/**
* Callback that renders the contents of the Acumulus invoice info box.
*
* @\param WP_Post $shopOrderPost
* The post for the current order.
*
* @throws \Throwable
*/
public function outputInvoiceStatusInfoBox(/*WP_Post $shopOrderPost*/): void
{
echo $this->processInvoiceStatusForm();
}
/**
* Callback that renders the Acumulus actions on the order list page.
*
* @param array $actions
* @param \WC_Order $order
*
* @return array
* The $actions array with the (enabled) Acumulus actions added to it.
*/
public function adminOrderActions(array $actions, WC_Order $order): array
{
$documentsSettings = $this->getAcumulusContainer()->getConfig()->getDocumentsSettings();
if ($documentsSettings['showInvoiceList']
|| $documentsSettings['mailInvoiceList']
|| $documentsSettings['showPackingSlipList']
|| $documentsSettings['mailPackingSlipList']
) {
$source = $this->getAcumulusContainer()->createSource(Source::Order, $order);
$acumulusEntry = $this->getAcumulusContainer()->getAcumulusEntryManager()->getByInvoiceSource($source);
if ($acumulusEntry !== null) {
$token = $acumulusEntry->getToken();
// If sent as concept, token will be null.
if ($token !== null) {
$subActions = [];
$ajaxAction = 'acumulus_ajax_action';
$document = ucfirst($this->t('document_invoice'));
if ($documentsSettings['showInvoiceList']) {
$action = 'acumulus-document-invoice-show';
$uri = $this->getAcumulusContainer()->getAcumulusApiClient()->getInvoicePdfUri($token);
$subActions[$action] = [
'url' => $uri,
'action' => $action,
'name' => sprintf($this->t('document_show'), $document),
'title' => sprintf($this->t('document_show_title'), $document),
];
}
if ($documentsSettings['mailInvoiceList']) {
$action = 'acumulus-document-invoice-mail';
$uri = sprintf('admin-ajax.php?action=%s&acumulus_action=%s&order_id=%d', $ajaxAction, $action, $order->get_id());
$subActions[$action] = [
'url' => wp_nonce_url(admin_url($uri), $ajaxAction, 'acumulus_nonce'),
'action' => $action,
'name' => sprintf($this->t('document_mail'), $document),
'title' => sprintf($this->t('document_mail_title'), $document),
];
}
$document = ucfirst($this->t('document_packing_slip'));
if ($documentsSettings['showPackingSlipList']) {
$action = 'acumulus-document-packing-slip-show';
$uri = $this->getAcumulusContainer()->getAcumulusApiClient()->getPackingSlipPdfUri($token);
$subActions[$action] = [
'url' => $uri,
'action' => $action,
'name' => sprintf($this->t('document_show'), $document),
'title' => sprintf($this->t('document_show_title'), $document),
];
}
if ($documentsSettings['mailPackingSlipList']) {
$action = 'acumulus-document-packing-slip-mail';
$uri = sprintf('admin-ajax.php?action=%s&acumulus_action=%s&order_id=%d', $ajaxAction, $action, $order->get_id());
$subActions[$action] = [
'url' => wp_nonce_url(admin_url($uri), $ajaxAction, 'acumulus_nonce'),
'action' => $action,
'name' => sprintf($this->t('document_mail'), $document),
'title' => sprintf($this->t('document_mail_title'), $document),
];
}
// Add the actions and our own CSS.
$actions += $subActions;
$pluginUrl = plugins_url('/acumulus');
wp_enqueue_style('acumulus_css_admin', $pluginUrl . '/acumulus.css');
}
}
}
return $actions;
}
/**
* Getter for the form object.
*
* @param string $type
*
* @return \Siel\Acumulus\Helpers\Form
*/
private function getForm(string $type): Form
{
return $this->getAcumulusContainer()->getForm($type);
}
/**
* Implements the admin_post_acumulus_register action.
*
* Processes and renders the batch form.
*
* @throws \Throwable
*/
public function processRegisterForm(): void
{
$this->checkCapability('manage_options');
$this->checkCapability('manage_woocommerce');
echo $this->processForm('register');
}
/**
* Implements the admin_post_acumulus_settings action.
*
* Processes and renders the settings form.
*
* @throws \Throwable
*/
public function processSettingsForm(): void
{
$this->checkCapability('manage_options');
$this->checkCapability('manage_woocommerce');
echo $this->processForm('settings');
}
/**
* Implements the admin_post_acumulus_mappings action.
*
* Processes and renders the 'mappings' form.
*
* @throws \Throwable
*/
public function processMappingsForm(): void
{
$this->checkCapability('manage_options');
$this->checkCapability('manage_woocommerce');
echo $this->processForm('mappings');
}
/**
* Implements the admin_post_acumulus_activate action.
*
* Processes and renders the "activate pro-support" form.
*
* @throws \Throwable
*/
public function processActivateForm(): void
{
$this->checkCapability('manage_options');
$this->checkCapability('manage_woocommerce');
echo $this->processForm('activate');
}
/**
* Implements the admin_post_acumulus_batch action.
*
* Processes and renders the batch form.
*
* @throws \Throwable
*/
public function processBatchForm(): void
{
$this->checkCapability('manage_woocommerce');
echo $this->processForm('batch');
}
/**
* Processes and renders the Acumulus invoice status overview form.
*
* Either called via:
* - Callback that renders the contents of the Acumulus invoice info box.
* - Ajax request handler.
*
* @return string
* The rendered form (embedded in any necessary HTML).
*
* @throws \Throwable
*/
public function processInvoiceStatusForm(): string
{
return $this->processForm('invoice');
}
/**
* Processes and renders the Rate Acumulus plugin form.
*
* Either called via:
* - Render admin notice.
* - Ajax request handler.
*
* @return string
* The rendered form (embedded in any necessary HTML).
*
* @throws \Throwable
*/
public function processRatePluginForm(): string
{
return $this->processForm('rate');
}
/**
* Processes and renders the Acumulus message form.
*
* Called via:
* - Render admin notice.
*
* @return string
* The rendered form (embedded in any necessary HTML).
*
* @throws \Throwable
*/
public function processMessageForm(): string
{
return $this->processForm('message');
}
/**
* Processes and renders the form of the given type.
*
* @param string $type
* The form type: 'settings', 'mappings', 'batch' or one of the other forms.
*
* @return string
* the form HTML to output.
*
* @throws \Throwable
*/
protected function processForm(string $type): string
{
$form = $this->getForm($type);
try {
$this->preProcessForm($form);
$form->process();
$this->preRenderForm($form);
// Render the form first before wrapping it in its final format so that any
// messages added during rendering can be shown on top.
$formOutput = $this->getAcumulusContainer()->getFormRenderer()->render($form);
} catch (Throwable $e) {
// We handle our "own" exceptions but only when we can process them
// as we want, i.e. show it as an error at the beginning of the
// form. That's why we start catching only after we have a form and
// stop catching just before postRenderForm().
try {
$crashReporter = $this->getAcumulusContainer()->getCrashReporter();
$message = $crashReporter->logAndMail($e);
$form->createAndAddMessage($message, Severity::Exception);
} catch (Throwable) {
// We don't know if we have informed the user per mail or
// screen, so assume we didn't and rethrow the original exception.
throw $e;
}
}
$output = $this->postRenderForm($form, $formOutput ?? 'ERROR');
$this->postProcessForm($form);
return $output;
}
/**
* Performs form type-specific actions before processing a form.
*
* @param \Siel\Acumulus\Helpers\Form $form
* The form that is going to be processed.
*/
private function preProcessForm(Form $form): void
{
$type = $form->getType();
// Check nonce.
if (!wp_doing_ajax() && $form->isSubmitted()) {
check_admin_referer("acumulus_{$type}_nonce");
}
// Form processing may depend on determining the payment status, but the
// default states as returned by wc_get_is_paid_statuses() are not how
// we would define "is paid".
if (in_array($type, ['batch', 'invoice'])) {
// We use WC_Order::is_paid()
add_action('woocommerce_order_is_paid_statuses', [$this, 'woocommerceOrderIsPaidStatuses'], 10, 2);
}
}
/**
* Performs form type-specific actions after a form has been processed.
*
* @param \Siel\Acumulus\Helpers\Form $form
* The form that has been processed.
*/
private function postProcessForm(Form $form): void
{
$type = $form->getType();
// Remove our actions that redefine "is paid".
if (in_array($type, ['batch', 'invoice'])) {
remove_action('woocommerce_order_is_paid_statuses', [$this, 'woocommerceOrderIsPaidStatuses']);
}
}
/**
* Performs form type-specific actions before rendering a form.
*
* @param \Siel\Acumulus\Helpers\Form $form
* The form that is going to be rendered.
*/
private function preRenderForm(Form $form): void
{
// Get a new FormRenderer as the rate plugin message may be shown inside our
// pages, and that one has different settings.
$formRenderer = $this->getAcumulusContainer()->getFormRenderer(true);
// Add our own js.
$type = $form->getType();
$pluginUrl = plugins_url('/acumulus');
switch ($type) {
case 'invoice':
// Add some js.
wp_enqueue_script('jquery-ui-datepicker');
wp_enqueue_script('acumulus-ajax.js', $pluginUrl . '/' . 'acumulus-ajax.js');
// The invoice status overview is not rendered as other forms.
// Therefore, we change some properties of the form renderer.
$formRenderer
->setProperty('usePopupDescription', true)
->setProperty('fieldsetContentWrapperClass', 'data')
->setProperty('detailsWrapperClass', '')
->setProperty('labelWrapperClass', 'label')
->setProperty('inputDescriptionWrapperClass', 'value')
->setProperty('markupWrapperTag', '');
break;
case 'rate':
case 'message':
// Add some js.
wp_enqueue_script('acumulus-ajax.js', $pluginUrl . '/' . 'acumulus-ajax.js');
// The rate plugin message is not rendered as other forms.
// Therefore, we change some properties of the form renderer.
$formRenderer
->setProperty('fieldsetContentWrapperTag', 'div')
->setProperty('fieldsetContentWrapperClass', '')
->setProperty('elementWrapperTag', '')
->setProperty('inputDescriptionWrapperTag', '')
->setProperty('renderEmptyLabel', false)
->setProperty('markupWrapperTag', '');
break;
}
// Add our own CSS.
wp_enqueue_style('acumulus_css_admin', $pluginUrl . '/acumulus.css');
}
/**
* Performs form type-specific actions after a form has been rendered.
*
* @param \Siel\Acumulus\Helpers\Form $form
* The form that has been rendered.
* @param string $formOutput
* The HTML of the rendered form.
*
* @return string
* The rendered form with any wrapping around it.
*/
private function postRenderForm(Form $form, string $formOutput): string
{
$output = '';
$type = $form->getType();
$id = "acumulus-$type";
$wait = $this->t('wait');
$nonce = wp_create_nonce('acumulus_ajax_action');
$url = admin_url("admin.php?page=acumulus_$type");
$output .= $this->showNotices($form);
switch ($type) {
case 'register':
case 'settings':
case 'mappings':
case 'activate':
case 'batch':
case 'invoice':
$wrap = $form->isFullPage();
if ($wrap) {
$output .= '';
}
break;
case 'rate':
case 'message':
$extraAttributes = [
'class' => 'acumulus acumulus-area',
'data-acumulus-wait' => $wait,
'data-acumulus-nonce' => $nonce,
];
if ($this->isOwnPage()) {
$extraAttributes['class'] .= ' inline';
}
$noticeType = $type === 'rate' ? 'success' : 'info';
$output .= $this->renderNotice($formOutput, $noticeType, $id, $extraAttributes, true);
break;
}
return $output;
}
/**
* Action method that renders any notices coming from the form(s).
*
* @param \Siel\Acumulus\Helpers\Form|null $form
*
* @return string
*/
private function showNotices(?Form $form): string
{
$output = '';
if (isset($form)) {
foreach ($form->getMessages() as $message) {
$output .= $this->renderNotice(
$message->format(Message::Format_PlainWithSeverity),
$this->SeverityToNoticeClass($message->getSeverity()),
$message->getField()
);
}
}
return $output;
}
/**
* Converts a Severity constant into a WP notice class.
*
* @param int $severity
*
* @return string
*
*/
private function SeverityToNoticeClass(int $severity): string
{
return match ($severity) {
Severity::Success => 'success',
Severity::Info, Severity::Notice => 'info',
Severity::Warning => 'warning',
Severity::Error, Severity::Exception => 'error',
default => '',
};
}
/**
* Renders a notice.
*
* @param string $message
* @param string $type
* The type of notice. This is used to construct CSS classes to distinguish the
* different types of messages: 'error', 'warning', 'info', etc.
* @param string $id
* An optional id to use for the outer tag OR the name (id) of the field the
* form error message is meant for.
* @param array $extraAttributes
* Optional attributes, including additional CSS classes, to add to the
* surrounding div.
* @param bool $isHtml
* Indicates whether $message is HTML or plain text. Plain text will be
* embedded in a .
*
* @return string
* The rendered notice.
*/
private function renderNotice(string $message, string $type, string $id = '', array $extraAttributes = [], bool $isHtml = false): string
{
$for = '';
if (!empty($id) && func_num_args() === 3) {
// Form field message (because: 3 arguments (I know: this sucks)):
// make it a clickable label.
$for = $id;
$id = '';
}
if (!empty($id)) {
$id = ' id="' . $id . '"';
}
$class = '';
if (!empty($extraAttributes['class'])) {
$class = ' ' . $extraAttributes['class'];
unset($extraAttributes['class']);
}
$extraAttributesString = '';
foreach ($extraAttributes as $attribute => $value) {
$extraAttributesString .= " $attribute='$value'";
}
$result = " ';
}
if ($for) {
$result .= "';
}
if (!$isHtml) {
$result .= '