Payment and shipping status
Every order has a payment status and a shipping status. EXT:cart registers these status:
| Service | Status in their order |
|---|---|
| payment | open, pending, paid, canceled |
| shipping | open, on_, in_, shipped |
The identifiers of these status are available as constants of
\Extcode\ and
\Extcode\, e.g.
Payment. The constants only name the status of EXT:cart.
The status are no enum, so your own extension can register further status,
e.g. refunded for the payment or delivered for the shipping. The
registered status are used in the backend module (the filter of the order
list, the label in the order list and the select in the order details), in
the order details in the frontend and in the TCA of the payment and the
shipping.
Register own status
Add a file Configuration/ to your extension. It
returns the status by service type (payment or shipping) and
identifier. The identifier is stored in the database, it consists of lower
case letters, digits and underscores and starts with a letter.
<?php
use Extcode\Cart\OrderStatus\PaymentStatus;
use Extcode\Cart\OrderStatus\ShippingStatus;
return [
'payment' => [
'refunded' => [
'label' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:payment.status.refunded',
'after' => [PaymentStatus::PAID],
'before' => [PaymentStatus::CANCELED],
],
],
'shipping' => [
'delivered' => [
'label' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:shipping.status.delivered',
'after' => [ShippingStatus::SHIPPED],
],
],
];
A status has these keys:
label- The label of the status, a
LLL:reference or a plain text. Required. before- A list of status identifiers this status is ordered before.
after- A list of status identifiers this status is ordered after.
The status are ordered by before and after like the middlewares in
Configuration/RequestMiddlewares.php. Give both to place a status
between two others; with only after the position relative to the other
following status is not defined. A status may refer to the status of other
extensions, a reference to a status which is not registered is ignored.
Unknown keys, service types and invalid values throw an exception.
The status of EXT:cart are loaded first, the ones of the other extensions in
the order of the extensions. An extension may change a status of EXT:cart or
of an extension loaded before by using the same identifier: the given keys
replace the ones registered before, e.g. 'pending' =>
only changes the label of pending.
The registered status are cached in the core cache, flush the caches after
changing a Configuration/.
Use the registered status
The service \Extcode\
returns the registered status in their order:
use Extcode\Cart\OrderStatus\OrderStatusRegistry;
use Extcode\Cart\OrderStatus\ServiceType;
final readonly class MyService
{
public function __construct(
private OrderStatusRegistry $orderStatusRegistry,
) {}
public function isKnownPaymentStatus(string $status): bool
{
return $this->orderStatusRegistry->hasStatus(ServiceType::Payment, $status);
}
}
get returns the \Extcode\
objects, get the translated labels by identifier, e.g. for
the options of a select.
In Fluid templates the ViewHelper cart: renders the
label of a status. A status which is not registered (anymore) is rendered as
its identifier:
<cart:order.statusLabel serviceType="payment" status="{orderItem.payment.status}"/>
Change the status
Change the status of an order with
\Extcode\ instead of setting it and
persisting the payment or the shipping, e.g. in the notification of a payment
provider:
use Extcode\Cart\OrderHistory\OrderChangeSource;
use Extcode\Cart\OrderStatus\PaymentStatus;
use Extcode\Cart\OrderStatus\StatusChangeResult;
use Extcode\Cart\OrderStatus\StatusChangeService;
// the notification of the payment provider, sent by its server
$result = $this->statusChangeService->change(
$orderItem->getPayment(),
PaymentStatus::PAID,
$orderItem->getPayment()->getStatus(),
initiator: 'my_payment_provider',
source: OrderChangeSource::Api
);
The optional initiator tells who or what triggered the change if it is not
a backend user, e.g. your extension, an ERP synchronisation or a scheduler
task.
The source is the channel of the change, the enum
\Extcode\:
Backend- An editor in the backend.
Frontend- The browser of a customer, e.g. redirected back from a payment provider.
Api- A server-to-server request, e.g. the notification (IPN, webhook) of a payment provider or a request of an ERP.
Cli- A command or a scheduler task.
Without a given source it is determined from the request (Backend,
Frontend or Cli), by default from $GLOBALS.
TYPO3 handles a server-to-server request as frontend request, so pass
Order for notifications and webhooks. Then the history
tells whether the customer or the server of the payment provider changed the
status.
The service
- only sets registered status,
- only changes the status if the order still has the expected status (the third argument), so an outdated form or a repeated notification does not overwrite a newer status,
- updates the status atomically, so of several requests with the same expected status only one changes it,
- writes the change to the order history.
It returns a \Extcode\ with the
outcome: Changed, Unchanged (the order has the status already),
Stale (the order has not the expected status anymore), Unknown
or Vetoed (a listener prevented the change, see veto). After a
change order contains the stored change.
Events
\Extcode\Cart\ Event\ Order\ Before Status Change Event -
Dispatched before the status is changed, with the order, the payment or the shipping, the old and the new status, the source, the initiator and the backend user. A listener can prevent the change with
veto; the reason is shown to the editor in the backend. The first veto stops the other listeners.('reason') Use it for checks only. The change can still fail after this event, e.g. if another request changed the status in the meantime.
\Extcode\Cart\ Event\ Order\ After Status Change Event -
Dispatched after the status was changed and written to the order history, the place for side effects like emails or shipping labels. The uid of the stored change (
get) identifies the change; use it to execute an action only once.Order Change ()->uid A listener which fails adds a message with
add. The status stays changed; the errors are returned inError () Statusand shown to the editor in the backend.Change Result::$errors EXT:cart registers the listener
\Extcode\with the identifierCart\ Event Listener\ Order\ Status Change\ Mail cart--, which sends the emails configured in TypoScript, see Emails on status changes. It is experimental and only active with the feature toggleorder-- status- change-- mail cart..experimental. status Change Mails
Both events are only dispatched by the Status, not for an
unknown or unchanged status.
use Extcode\Cart\Event\Order\BeforeStatusChangeEvent;
use Extcode\Cart\OrderStatus\ServiceType;
use Extcode\Cart\OrderStatus\ShippingStatus;
use TYPO3\CMS\Core\Attribute\AsEventListener;
#[AsEventListener('my-extension--order--require-delivery-number')]
final readonly class RequireDeliveryNumber
{
public function __invoke(BeforeStatusChangeEvent $event): void
{
if ($event->getServiceType() === ServiceType::Shipping
&& $event->getToStatus() === ShippingStatus::SHIPPED
&& (string) $event->getOrderItem()->getDeliveryNumber() === ''
) {
$event->veto('Generate the delivery number first.');
}
}
}
use Extcode\Cart\Event\Order\AfterStatusChangeEvent;
use Extcode\Cart\OrderStatus\PaymentStatus;
use Extcode\Cart\OrderStatus\ServiceType;
use TYPO3\CMS\Core\Attribute\AsEventListener;
#[AsEventListener('my-extension--order--send-paid-email')]
final readonly class SendPaidEmail
{
public function __invoke(AfterStatusChangeEvent $event): void
{
if ($event->getServiceType() !== ServiceType::Payment
|| $event->getToStatus() !== PaymentStatus::PAID
) {
return;
}
// send the email, e.g. remember $event->getOrderChange()->uid
// to send it only once
}
}
Order history
Every change is written to the table tx_ and
shown as order history in the order details of the backend module. A change
has a type (e.g. Order), the old and the new
value, the date, the source, the backend user, if there is one, and the
initiator. The history shows the backend user, otherwise the initiator with
the source, e.g. "my_payment_provider (API)", otherwise the source.
The table is not limited to status changes. Your extension can write its own
changes of an order with
\Extcode\, using
an own type, a subject (e.g. product:) and details in data.
Warning
The order history is new and its structure may still change in minor
versions. If a change cannot be migrated, the existing entries of
tx_ may have to be removed. Do not rely
on the order history as the only record of status changes yet.
Emails
The emails to the buyer and the seller use a template per payment status. If an order can have your own payment status when it is finished, add the email templates for it, see Templates per payment status.