unsupervised-scheduler/src/Payment/PaymentDueMailer.php

<?php
declare(strict_types=1);

namespace Unsupervised\Schedular\Payment;

/**
 * Emails a student a single itemised notice for every payment the daily billing
 * scan generated for them in one run, so a student billed for several lessons on
 * the same day receives one email with a line per item and a grand total — never
 * one email per lesson.
 */
class PaymentDueMailer {

	/**
	 * Send one student their consolidated due-payment notice for the current scan.
	 * The optional `$reference` is the shared notice-batch code the student can quote
	 * on a lump-sum e-transfer so the studio can reconcile it to these payments.
	 *
	 * @param list<array{label: string, amount: float, currency: string, due_date: ?string, etransfer_email: ?string}> $items
	 * @param float                                                                                                    $creditApplied Account credit deducted from the total this notice covers.
	 * @return bool False when there is no recipient or nothing to bill.
	 */
	public function send( \WP_User $student, array $items, string $reference = '', float $creditApplied = 0.0 ): bool {
		if ( '' === (string) $student->user_email || [] === $items ) {
			return false;
		}

		$currency = (string) $items[0]['currency'];
		$total    = 0.0;
		$lines    = [];
		$emails   = [];

		foreach ( $items as $item ) {
			$amount = (float) $item['amount'];
			$total += $amount;

			$lines[] = sprintf(
				/* translators: 1: item description, 2: due date, 3: currency, 4: amount */
				__( '- %1$s (due %2$s): %3$s %4$s', 'unsupervised-schedular' ),
				(string) $item['label'],
				$this->formatDate( $item['due_date'] ?? null ),
				$currency,
				number_format( $amount, 2 )
			);

			$etransfer = (string) ( $item['etransfer_email'] ?? '' );
			if ( '' !== $etransfer ) {
				$emails[ $etransfer ] = true;
			}
		}

		// Account credit (from an earlier cancelled paid lesson) offsets the total.
		$creditApplied = round( min( $creditApplied, $total ), 2 );
		$dueTotal      = round( $total - $creditApplied, 2 );

		$body = __( 'You have upcoming payments due:', 'unsupervised-schedular' ) . "\n\n"
			. implode( "\n", $lines );

		if ( $creditApplied > 0.0 ) {
			$body .= "\n\n" . sprintf(
				/* translators: 1: currency, 2: credit amount */
				__( 'Account credit applied: -%1$s %2$s', 'unsupervised-schedular' ),
				$currency,
				number_format( $creditApplied, 2 )
			);
		}

		$body .= "\n\n" . sprintf(
			/* translators: 1: currency, 2: total amount */
			__( 'Total due: %1$s %2$s', 'unsupervised-schedular' ),
			$currency,
			number_format( $dueTotal, 2 )
		);

		if ( $dueTotal > 0.0 && [] !== $emails ) {
			$body .= "\n\n" . sprintf(
				/* translators: %s: e-transfer destination email address(es) */
				__( 'Please send your e-transfer to: %s', 'unsupervised-schedular' ),
				implode( ', ', array_keys( $emails ) )
			);
		}

		if ( '' !== $reference ) {
			$body .= "\n\n" . sprintf(
				/* translators: %s: payment reference code */
				__( 'Please include this reference with your payment: %s', 'unsupervised-schedular' ),
				$reference
			);
		}

		return (bool) wp_mail( $student->user_email, __( 'Payment due', 'unsupervised-schedular' ), $body );
	}

	/**
	 * Present a stored `Y-m-d` due date in a friendlier form; falls back to the
	 * raw value (or an empty string) when it is not a parseable date.
	 */
	private function formatDate( ?string $date ): string {
		if ( null === $date || '' === $date ) {
			return '';
		}

		$parsed = \DateTimeImmutable::createFromFormat( '!Y-m-d', $date );

		return false !== $parsed ? $parsed->format( 'M j, Y' ) : $date;
	}
}