mirror of
https://github.com/itflow-org/itflow
synced 2026-11-11 15:07:24 +00:00
718 lines
36 KiB
PHP
718 lines
36 KiB
PHP
<?php
|
|
|
|
/*
|
|
* Billing emails - one look for every email a client gets about money: an
|
|
* invoice, a receipt for one paid, a quote, a payment reminder, a payment
|
|
* received and a statement.
|
|
*
|
|
* Each is drawn by emailHtml() (functions/email.php), as every email is: the
|
|
* company's logo (or name), what it is about, a summary box with what it
|
|
* comes to, any note from the agent, a button to open it online - to pay an
|
|
* invoice when online payments are on, or answer a quote - and the company's
|
|
* details at the foot. The PDF can go with it.
|
|
*
|
|
* Reminders follow a schedule from the invoice settings: days before and
|
|
* after the due date, then every so many days while it is owed. Statements
|
|
* can go out each month to every client with a balance, and a client can be
|
|
* left out of both.
|
|
*/
|
|
|
|
/* ------------------------------------------------------------ The rules */
|
|
|
|
/**
|
|
* Reminders and statements, from the invoice settings - with the old
|
|
* behaviour until 2.9.8 is applied:
|
|
* enabled send reminders at all
|
|
* days days from the due date to send on, negative before it, sorted
|
|
* repeat then every so many days after the last of them, 0 for no more
|
|
* statement_monthly email a statement each month to clients with a balance
|
|
* statement_day on this day of the month (1 to 28)
|
|
* attach_pdf put the PDF on invoice, quote, reminder and statement emails
|
|
*/
|
|
function billingReminderRules($fresh = false) {
|
|
global $mysqli;
|
|
static $rules = null;
|
|
if ($rules !== null && !$fresh) {
|
|
return $rules;
|
|
}
|
|
$rules = ['enabled' => false, 'days' => [1, 30], 'repeat' => 30, 'statement_monthly' => false, 'statement_day' => 1, 'attach_pdf' => true];
|
|
try {
|
|
$row = mysqli_fetch_assoc(mysqli_query($mysqli, "SELECT config_send_invoice_reminders, config_invoice_reminder_days, config_invoice_reminder_repeat,
|
|
config_statement_monthly, config_statement_day, config_billing_email_attach_pdf FROM settings WHERE company_id = 1"));
|
|
} catch (mysqli_sql_exception $e) {
|
|
$row = mysqli_fetch_assoc(mysqli_query($mysqli, "SELECT config_send_invoice_reminders FROM settings WHERE company_id = 1"));
|
|
}
|
|
if ($row) {
|
|
$rules['enabled'] = intval($row['config_send_invoice_reminders'] ?? 0) === 1;
|
|
if (array_key_exists('config_invoice_reminder_days', $row)) {
|
|
$rules['days'] = billingReminderDaysParse($row['config_invoice_reminder_days']);
|
|
$rules['repeat'] = max(0, min(365, intval($row['config_invoice_reminder_repeat'])));
|
|
$rules['statement_monthly'] = intval($row['config_statement_monthly']) === 1;
|
|
$rules['statement_day'] = max(1, min(28, intval($row['config_statement_day'])));
|
|
$rules['attach_pdf'] = intval($row['config_billing_email_attach_pdf']) === 1;
|
|
}
|
|
}
|
|
return $rules;
|
|
}
|
|
|
|
/** Days from a list - "-3, 0, 7 14" - as whole days from 60 before to a year after, sorted, each once. */
|
|
function billingReminderDaysParse($text) {
|
|
$days = [];
|
|
foreach (preg_split('/[\s,;]+/', trim((string) $text)) as $part) {
|
|
if (preg_match('/^[+-]?\d{1,3}$/', $part)) {
|
|
$day = intval($part);
|
|
if ($day >= -60 && $day <= 365) {
|
|
$days[$day] = $day;
|
|
}
|
|
}
|
|
}
|
|
sort($days);
|
|
return array_values($days);
|
|
}
|
|
|
|
/** Is a reminder due for an invoice $days after its due date (negative before it)? */
|
|
function billingReminderOnDay($days, ?array $rules = null) {
|
|
$rules = $rules ?? billingReminderRules();
|
|
$days = intval($days);
|
|
if (in_array($days, $rules['days'], true)) {
|
|
return true;
|
|
}
|
|
$last = $rules['days'] ? max(max($rules['days']), 0) : 0;
|
|
return $rules['repeat'] > 0 && $days > $last && ($days - $last) % $rules['repeat'] === 0;
|
|
}
|
|
|
|
/** The schedule in words - "3 days before it is due, on the day, 7 and 30 days late, then every 30 days". */
|
|
function billingReminderScheduleText(?array $rules = null) {
|
|
$rules = $rules ?? billingReminderRules();
|
|
$parts = [];
|
|
$before = array_reverse(array_map('abs', array_filter($rules['days'], function ($day) {
|
|
return $day < 0;
|
|
})));
|
|
$after = array_values(array_filter($rules['days'], function ($day) {
|
|
return $day > 0;
|
|
}));
|
|
$list = function ($days) {
|
|
return count($days) > 1 ? implode(', ', array_slice($days, 0, -1)) . ' and ' . end($days) : (string) reset($days);
|
|
};
|
|
if ($before) {
|
|
$parts[] = $list($before) . ' day' . (end($before) === 1 && count($before) === 1 ? '' : 's') . ' before it is due';
|
|
}
|
|
if (in_array(0, $rules['days'], true)) {
|
|
$parts[] = 'on the due date';
|
|
}
|
|
if ($after) {
|
|
$parts[] = $list($after) . ' day' . (end($after) === 1 && count($after) === 1 ? '' : 's') . ' late';
|
|
}
|
|
if ($rules['repeat'] > 0) {
|
|
$parts[] = ($parts ? 'then ' : '') . 'every ' . $rules['repeat'] . ' day' . ($rules['repeat'] === 1 ? '' : 's') . ($after || in_array(0, $rules['days'], true) ? '' : ' after it is due') . ' until it is paid';
|
|
}
|
|
return $parts ? implode(', ', $parts) : 'never';
|
|
}
|
|
|
|
/**
|
|
* When an invoice's next reminder goes, from tomorrow on: ['date' => Y-m-d,
|
|
* 'days' => days from its due date], or null - none on the schedule, or
|
|
* reminders are off. With $late_only, none before it is late - autopay
|
|
* charges it on the day.
|
|
*/
|
|
function billingReminderNext(array $invoice, ?array $rules = null, $late_only = false) {
|
|
$rules = $rules ?? billingReminderRules();
|
|
$due = substr((string) ($invoice['invoice_due'] ?? ''), 0, 10);
|
|
if (!$rules['enabled'] || !preg_match('/^\d{4}-\d{2}-\d{2}$/', $due)) {
|
|
return null;
|
|
}
|
|
$today = new DateTime('today');
|
|
$due_date = new DateTime($due);
|
|
$from = (int) $due_date->diff($today)->format('%r%a') + 1;
|
|
if ($late_only) {
|
|
$from = max($from, 1);
|
|
}
|
|
for ($days = $from; $days <= $from + 400; $days++) {
|
|
if (billingReminderOnDay($days, $rules)) {
|
|
$date = (clone $due_date)->modify(($days >= 0 ? '+' : '') . $days . ' days');
|
|
return ['date' => $date->format('Y-m-d'), 'days' => $days];
|
|
}
|
|
}
|
|
return null;
|
|
}
|
|
|
|
/** Will a recurring autopay charge this invoice on its due date? Then it isn't reminded before. */
|
|
function billingReminderAutopay(array $invoice) {
|
|
global $mysqli;
|
|
$recurring_id = intval($invoice['invoice_recurring_invoice_id'] ?? 0);
|
|
return $recurring_id > 0 && mysqli_num_rows(mysqli_query($mysqli, "SELECT 1 FROM recurring_payments WHERE recurring_payment_recurring_invoice_id = $recurring_id LIMIT 1")) > 0;
|
|
}
|
|
|
|
/** How late an invoice is, in words - "due in 3 days", "due today", "7 days late". */
|
|
function billingReminderWhen($days) {
|
|
$days = intval($days);
|
|
if ($days < 0) {
|
|
return 'due in ' . (-$days) . ' day' . ($days === -1 ? '' : 's');
|
|
}
|
|
return $days === 0 ? 'due today' : $days . ' day' . ($days === 1 ? '' : 's') . ' late';
|
|
}
|
|
|
|
/* ------------------------------------------------------------ The email */
|
|
|
|
/** A date for an email - "Oct 20, 2026". */
|
|
function billingEmailDate($date) {
|
|
$time = strtotime((string) $date);
|
|
return $time ? date('M j, Y', $time) : (string) $date;
|
|
}
|
|
|
|
/**
|
|
* One billing email as HTML - emailHtml() (functions/email.php), greeting
|
|
* nobody when it has no name, as an internal one has none.
|
|
*/
|
|
function billingEmailHtml(array $email) {
|
|
if (empty($email['name'])) {
|
|
$email['name'] = null;
|
|
}
|
|
return emailHtml($email);
|
|
}
|
|
|
|
/** Who billing emails come from - invoices and quotes each have their own address. */
|
|
function billingEmailFrom($which = 'invoice') {
|
|
global $mysqli;
|
|
static $from = null;
|
|
if ($from === null) {
|
|
$from = mysqli_fetch_assoc(mysqli_query($mysqli, "SELECT config_invoice_from_email, config_invoice_from_name, config_quote_from_email, config_quote_from_name,
|
|
config_invoice_paid_notification_email, config_smtp_provider FROM settings WHERE company_id = 1")) ?: [];
|
|
}
|
|
if ($which === 'quote' && !empty($from['config_quote_from_email'])) {
|
|
return ['email' => (string) $from['config_quote_from_email'], 'name' => (string) $from['config_quote_from_name']];
|
|
}
|
|
if ($which === 'notify') {
|
|
return ['email' => (string) ($from['config_invoice_paid_notification_email'] ?? ''), 'name' => ''];
|
|
}
|
|
if ($which === 'ready') {
|
|
return ['email' => (string) ($from['config_smtp_provider'] ?? ''), 'name' => ''];
|
|
}
|
|
return ['email' => (string) ($from['config_invoice_from_email'] ?? ''), 'name' => (string) ($from['config_invoice_from_name'] ?? '')];
|
|
}
|
|
|
|
/** Can billing emails go out at all - mail is set up? */
|
|
function billingEmailReady() {
|
|
return billingEmailFrom('ready')['email'] !== '' && billingEmailFrom()['email'] !== '';
|
|
}
|
|
|
|
/**
|
|
* A client's contacts to email: the ones picked (any of the client's with an
|
|
* email address), or with none picked the defaults for $type - the primary
|
|
* and billing contacts, or for a quote the primary contact.
|
|
* [['id', 'name', 'email'], ...], each address once.
|
|
*/
|
|
function billingEmailRecipients($client_id, ?array $contact_ids = null, $type = 'invoice') {
|
|
global $mysqli;
|
|
$client_id = intval($client_id);
|
|
if ($contact_ids !== null) {
|
|
$contact_ids = array_filter(array_map('intval', $contact_ids));
|
|
if (!$contact_ids) {
|
|
return [];
|
|
}
|
|
$filter = 'AND contact_id IN (' . implode(', ', $contact_ids) . ')';
|
|
} else {
|
|
$filter = documentDefaultContactFilterSql($type === 'quote' ? 'quote' : 'invoice');
|
|
}
|
|
$recipients = [];
|
|
$sql = mysqli_query($mysqli, "SELECT contact_id, contact_name, contact_email FROM contacts
|
|
WHERE contact_client_id = $client_id AND contact_archived_at IS NULL AND contact_email IS NOT NULL AND contact_email != '' $filter
|
|
ORDER BY contact_primary DESC, contact_billing DESC, contact_name ASC");
|
|
while ($row = mysqli_fetch_assoc($sql)) {
|
|
$key = strtolower(trim($row['contact_email']));
|
|
if (!filter_var(trim($row['contact_email']), FILTER_VALIDATE_EMAIL) || isset($recipients[$key])) {
|
|
continue;
|
|
}
|
|
$recipients[$key] = ['id' => intval($row['contact_id']), 'name' => (string) $row['contact_name'], 'email' => trim($row['contact_email'])];
|
|
}
|
|
return array_values($recipients);
|
|
}
|
|
|
|
/**
|
|
* Queue a billing email to each recipient, greeting each by name - nobody
|
|
* without one - through emailQueue(), whether or not mail is set up yet, as
|
|
* the Send windows always have. $opts: from ('invoice' or 'quote' -
|
|
* whose address it comes from) and attach (a list of billingEmailPdf()
|
|
* files). Who it was queued to, "Name (email)".
|
|
*/
|
|
function billingEmailQueue(array $recipients, $subject, array $email, array $opts = []) {
|
|
$recipients = array_map(function ($recipient) {
|
|
$greet = array_key_exists('greet', $recipient) ? $recipient['greet'] : ($recipient['name'] ?? '');
|
|
return ['greet' => trim((string) $greet) !== '' ? (string) $greet : null] + $recipient;
|
|
}, $recipients);
|
|
return emailQueue($recipients, $subject, $email, ['from' => billingEmailFrom($opts['from'] ?? 'invoice'), 'attachments' => (array) ($opts['attach'] ?? []), 'always' => true]);
|
|
}
|
|
|
|
/**
|
|
* A document's PDF, saved where the mail queue can attach it - ['path' =>
|
|
* app-relative path, 'name' => file name], or null when it can't be made.
|
|
* They go in uploads/tmp/billing_mail, which the web can't reach, and the
|
|
* nightly run clears them out after a week. $pdf is a billingPdf() or
|
|
* billingStatementPdf() result.
|
|
*/
|
|
function billingEmailPdf(array $pdf) {
|
|
$dir = 'uploads/tmp/billing_mail/' . bin2hex(random_bytes(12));
|
|
$full = dirname(__DIR__) . '/' . $dir;
|
|
if (!is_dir($full) && !@mkdir($full, 0775, true)) {
|
|
return null;
|
|
}
|
|
$name = preg_replace('/[^A-Za-z0-9._-]+/', '-', (string) $pdf['name']);
|
|
if (@file_put_contents("$full/$name", $pdf['data']) === false) {
|
|
return null;
|
|
}
|
|
return ['path' => "$dir/$name", 'name' => $name];
|
|
}
|
|
|
|
/** Clear PDFs made for emails more than $days days ago. How many went. */
|
|
function billingEmailPdfCleanup($days = 7) {
|
|
$base = dirname(__DIR__) . '/uploads/tmp/billing_mail';
|
|
if (!is_dir($base)) {
|
|
return 0;
|
|
}
|
|
$cutoff = time() - max(1, intval($days)) * 86400;
|
|
$removed = 0;
|
|
foreach (glob("$base/*", GLOB_ONLYDIR) ?: [] as $dir) {
|
|
if (filemtime($dir) >= $cutoff) {
|
|
continue;
|
|
}
|
|
foreach (glob("$dir/*") ?: [] as $file) {
|
|
@unlink($file);
|
|
}
|
|
if (@rmdir($dir)) {
|
|
$removed++;
|
|
}
|
|
}
|
|
return $removed;
|
|
}
|
|
|
|
/* ----------------------------------------------- What each one says */
|
|
|
|
/** The footnote for a client's billing contact. */
|
|
function billingEmailFootnote($client_name) {
|
|
$company = billingCompany();
|
|
return "You received this email as a billing contact for $client_name with " . ($company['company_name'] ?? 'us') . '.';
|
|
}
|
|
|
|
/**
|
|
* An invoice email - [subject, email]. $opts:
|
|
* kind invoice (the default), or reminder
|
|
* note the agent's own words
|
|
* Paid, it is a receipt. A reminder says when it is or was due and what is
|
|
* still owed - firmer once it is late.
|
|
*/
|
|
function billingInvoiceEmail(array $invoice, array $opts = []) {
|
|
$number = billingNumber('invoice', $invoice);
|
|
$currency = (string) $invoice['invoice_currency_code'];
|
|
$paid = invoicePaid($invoice['invoice_id']);
|
|
$state = invoiceState($invoice, $paid);
|
|
$company = billingCompany();
|
|
$company_name = (string) ($company['company_name'] ?? '');
|
|
$scope = trim((string) $invoice['invoice_scope']);
|
|
$url = billingGuestUrl('invoice', $invoice);
|
|
$owed = $state['balance'] > 0 && !in_array($invoice['invoice_status'], ['Paid', 'Cancelled', 'Non-Billable'], true);
|
|
$pay = $owed && billingOnlinePayments();
|
|
$kind = ($opts['kind'] ?? 'invoice') === 'reminder' && $owed ? 'reminder' : 'invoice';
|
|
$contact_line = 'Questions? Reply to this email' . (!empty($company['phone_display']) ? ' or call us on ' . $company['phone_display'] : '') . '.';
|
|
|
|
$summary = ['Invoice' => $number];
|
|
if ($scope !== '') {
|
|
$summary['For'] = $scope;
|
|
}
|
|
$summary['Issued'] = billingEmailDate($invoice['invoice_date']);
|
|
if ($owed) {
|
|
$summary['Due'] = billingEmailDate($invoice['invoice_due']);
|
|
}
|
|
$summary['Total'] = billingMoney($invoice['invoice_amount'], $currency);
|
|
if ($paid > 0) {
|
|
$summary['Paid'] = billingMoney($paid, $currency);
|
|
}
|
|
$email = [
|
|
'note' => $opts['note'] ?? '',
|
|
'button' => ['label' => $pay ? 'View and pay invoice' : 'View invoice', 'url' => $url],
|
|
'footnote' => billingEmailFootnote($invoice['client_name']),
|
|
];
|
|
|
|
if (!$owed && $invoice['invoice_status'] === 'Paid') {
|
|
return ["Receipt for invoice $number from $company_name", $email + [
|
|
'kind' => 'Receipt', 'tone' => 'success', 'title' => "Invoice $number is paid",
|
|
'intro' => ['Thank you - invoice ' . $number . ($scope !== '' ? " for \"$scope\"" : '') . ' is paid in full.'],
|
|
'summary' => $summary, 'strong' => 'Paid',
|
|
'after' => ['Please keep this email for your records. You can download the invoice as a PDF from its page.'],
|
|
]];
|
|
}
|
|
|
|
if ($kind === 'reminder') {
|
|
$days = $state['days'] !== null ? -intval($state['days']) : 0;
|
|
$balance = billingMoney($state['balance'], $currency);
|
|
$summary['Balance due'] = $balance;
|
|
if ($days < 0) {
|
|
$subject = "Reminder: invoice $number is due " . billingEmailDate($invoice['invoice_due']);
|
|
$intro = ["A friendly reminder that invoice $number" . ($scope !== '' ? " for \"$scope\"" : '') . " is due on " . billingEmailDate($invoice['invoice_due']) . ", with $balance to pay."];
|
|
$tone = 'primary';
|
|
$title = 'Due ' . billingEmailDate($invoice['invoice_due']);
|
|
} elseif ($days === 0) {
|
|
$subject = "Reminder: invoice $number is due today";
|
|
$intro = ["A friendly reminder that invoice $number" . ($scope !== '' ? " for \"$scope\"" : '') . " is due today, with $balance to pay."];
|
|
$tone = 'warning';
|
|
$title = 'Due today';
|
|
} else {
|
|
$subject = "Overdue: invoice $number is $days day" . ($days === 1 ? '' : 's') . ' past due';
|
|
$intro = ["Invoice $number" . ($scope !== '' ? " for \"$scope\"" : '') . ' was due on ' . billingEmailDate($invoice['invoice_due']) . " and $balance is still outstanding. Please arrange payment as soon as you can."];
|
|
$tone = 'danger';
|
|
$title = "$days day" . ($days === 1 ? '' : 's') . ' past due';
|
|
}
|
|
return [$subject, $email + [
|
|
'kind' => 'Payment reminder', 'tone' => $tone, 'title' => "Invoice $number - $title",
|
|
'intro' => $intro, 'summary' => $summary, 'strong' => 'Balance due',
|
|
'after' => ["If you have already paid, thank you, and please disregard this reminder. $contact_line"],
|
|
]];
|
|
}
|
|
|
|
$summary[$owed ? 'Balance due' : 'Balance'] = billingMoney($state['balance'], $currency);
|
|
return ["Invoice $number from $company_name", $email + [
|
|
'kind' => 'Invoice', 'tone' => 'primary', 'title' => "Invoice $number",
|
|
'intro' => ['Here is your invoice' . ($scope !== '' ? " for \"$scope\"" : '') . '.' . ($owed ? ' Payment is due by ' . billingEmailDate($invoice['invoice_due']) . '.' : '')],
|
|
'summary' => $summary, 'strong' => $owed ? 'Balance due' : 'Balance',
|
|
'after' => [($pay ? 'You can pay online by card from the invoice page, and download it as a PDF. ' : 'You can download it as a PDF from the invoice page. ') . $contact_line],
|
|
]];
|
|
}
|
|
|
|
/** A quote email - [subject, email]. $opts: note. */
|
|
function billingQuoteEmail(array $quote, array $opts = []) {
|
|
$number = billingNumber('quote', $quote);
|
|
$currency = (string) $quote['quote_currency_code'];
|
|
$company = billingCompany();
|
|
$scope = trim((string) $quote['quote_scope']);
|
|
$groups = quoteGroups($quote);
|
|
$summary = ['Quote' => $number];
|
|
if ($scope !== '') {
|
|
$summary['For'] = $scope;
|
|
}
|
|
$summary['Date'] = billingEmailDate($quote['quote_date']);
|
|
$summary['Valid until'] = billingEmailDate($quote['quote_expire']);
|
|
$strong = 'Total';
|
|
if (quoteHasRecurring($groups)) {
|
|
foreach ($groups as $group) {
|
|
if ($group['items'] || $group['frequency'] === '') {
|
|
$label = $group['frequency'] === '' ? 'Up front' : $group['label'];
|
|
$summary[$label] = billingMoney($group['total'], $currency);
|
|
if ($group['frequency'] === '') {
|
|
$strong = $label;
|
|
}
|
|
}
|
|
}
|
|
} else {
|
|
$summary['Total'] = billingMoney($quote['quote_amount'], $currency);
|
|
}
|
|
return ["Quote $number from " . ($company['company_name'] ?? '') . ($scope !== '' ? " - $scope" : ''), [
|
|
'kind' => 'Quote', 'tone' => 'primary', 'title' => "Quote $number",
|
|
'intro' => ['Thank you for the opportunity. Here is our quote' . ($scope !== '' ? " for \"$scope\"" : '') . ', valid until ' . billingEmailDate($quote['quote_expire']) . '.'],
|
|
'note' => $opts['note'] ?? '',
|
|
'summary' => $summary, 'strong' => $strong,
|
|
'button' => ['label' => 'View and accept quote', 'url' => billingGuestUrl('quote', $quote)],
|
|
'after' => ['You can accept or decline it online, and download it as a PDF. Questions? Reply to this email.'],
|
|
'footnote' => billingEmailFootnote($quote['client_name']),
|
|
]];
|
|
}
|
|
|
|
/**
|
|
* A payment received - [subject, email]. $applied: what went on each
|
|
* invoice, [['invoice' => billingRow(), 'amount' => ...], ...]. $payment:
|
|
* date, method, reference, currency.
|
|
*/
|
|
function billingPaymentEmail(array $applied, array $payment) {
|
|
$currency = (string) ($payment['currency'] ?? ($applied[0]['invoice']['invoice_currency_code'] ?? ''));
|
|
$total = array_sum(array_column($applied, 'amount'));
|
|
$first = $applied[0]['invoice'];
|
|
$summary = ['Amount paid' => billingMoney($total, $currency), 'Date' => billingEmailDate($payment['date'] ?? date('Y-m-d'))];
|
|
if (!empty($payment['method'])) {
|
|
$summary['Method'] = $payment['method'];
|
|
}
|
|
if (!empty($payment['reference'])) {
|
|
$summary['Reference'] = $payment['reference'];
|
|
}
|
|
$email = ['kind' => 'Payment received', 'tone' => 'success', 'footnote' => billingEmailFootnote($first['client_name'])];
|
|
if (count($applied) === 1) {
|
|
$number = billingNumber('invoice', $first);
|
|
$balance = invoiceState($first, invoicePaid($first['invoice_id']))['balance'];
|
|
$summary['Invoice'] = $number;
|
|
$summary[$balance > 0 ? 'Still to pay' : 'Invoice balance'] = $balance > 0 ? billingMoney($balance, $currency) : 'Paid in full';
|
|
return ["Payment received for invoice $number", $email + [
|
|
'title' => 'Thank you for your payment',
|
|
'intro' => ['We have received your payment of ' . billingMoney($total, $currency) . " for invoice $number."],
|
|
'summary' => $summary, 'strong' => 'Amount paid',
|
|
'button' => ['label' => 'View invoice', 'url' => billingGuestUrl('invoice', $first)],
|
|
'after' => ['Please keep this email as your receipt.'],
|
|
]];
|
|
}
|
|
$rows = [];
|
|
foreach ($applied as $entry) {
|
|
$balance = invoiceState($entry['invoice'], invoicePaid($entry['invoice']['invoice_id']))['balance'];
|
|
$rows[] = [['text' => billingNumber('invoice', $entry['invoice']), 'url' => billingGuestUrl('invoice', $entry['invoice'])],
|
|
billingMoney($entry['amount'], $currency), $balance > 0 ? billingMoney($balance, $currency) : 'Paid'];
|
|
}
|
|
return ['Payment received - ' . count($applied) . ' invoices', $email + [
|
|
'title' => 'Thank you for your payment',
|
|
'intro' => ['We have received your payment of ' . billingMoney($total, $currency) . ' and applied it to these invoices.'],
|
|
'summary' => $summary, 'strong' => 'Amount paid',
|
|
'lines' => ['head' => ['Invoice', 'Applied', 'Balance'], 'align' => ['left', 'right', 'right'], 'rows' => $rows],
|
|
'after' => ['Please keep this email as your receipt.'],
|
|
]];
|
|
}
|
|
|
|
/** Confirm a card a contact saved in the client portal - its brand, last four digits and expiry. Who it went to. */
|
|
function billingMailCardSaved($email, $name, $client_name, $brand, $last4, $exp_month, $exp_year) {
|
|
return billingEmailQueue([['email' => (string) $email, 'name' => (string) $name]], 'Payment method saved', [
|
|
'kind' => 'Payment method', 'tone' => 'success', 'preview' => 'Your card is saved for future invoices',
|
|
'title' => 'Your payment method is saved',
|
|
'intro' => ['Your payment details are stored securely with Stripe, our payment processor, and you authorized us to bill this card automatically for future invoices.'],
|
|
'summary' => ['Card' => ucfirst((string) $brand) . ' ending ' . $last4, 'Expires' => sprintf('%02d/%d', intval($exp_month), intval($exp_year))],
|
|
'after' => ['You can change or remove it at any time in the client portal.', 'Thank you for your business!'],
|
|
'footnote' => billingEmailFootnote((string) $client_name),
|
|
]);
|
|
}
|
|
|
|
/** An email to one of our own addresses - no greeting, from the invoice or quote address. Who it went to. */
|
|
function billingNotifyEmail($to, $subject, array $email, $from = 'invoice') {
|
|
$to = trim((string) $to);
|
|
if (!filter_var($to, FILTER_VALIDATE_EMAIL)) {
|
|
return [];
|
|
}
|
|
return billingEmailQueue([['email' => $to, 'name' => '', 'greet' => '']], $subject, $email, ['from' => $from]);
|
|
}
|
|
|
|
/**
|
|
* Tell our team a client answered a quote online - to the quote notification
|
|
* address in the quote settings. $accepted or declined; $by, who answered
|
|
* in the client portal, and the note they left with it.
|
|
*/
|
|
function billingQuoteAnsweredNotify($quote_id, $accepted, $by = '', $note = '') {
|
|
global $mysqli, $config_base_url;
|
|
$quote = billingRow('quote', $quote_id, false);
|
|
$to = (string) (mysqli_fetch_row(mysqli_query($mysqli, "SELECT config_quote_notification_email FROM settings WHERE company_id = 1"))[0] ?? '');
|
|
if (!$quote || $to === '') {
|
|
return [];
|
|
}
|
|
$number = billingNumber('quote', $quote);
|
|
$word = $accepted ? 'accepted' : 'declined';
|
|
$by = trim((string) $by);
|
|
$summary = ['Client' => $quote['client_name'], 'Quote' => $number, 'Total' => billingMoney($quote['quote_amount'], $quote['quote_currency_code'])];
|
|
if ($by !== '') {
|
|
$summary = ['Client' => $quote['client_name'], ucfirst($word) . ' by' => $by] + $summary;
|
|
}
|
|
return billingNotifyEmail($to, 'Quote ' . ucfirst($word) . " - {$quote['client_name']} - Quote $number", [
|
|
'kind' => 'Quote ' . $word, 'tone' => $accepted ? 'success' : 'danger', 'title' => "{$quote['client_name']} $word $number",
|
|
'intro' => ["{$quote['client_name']} $word quote $number " . ($by !== '' ? 'in the client portal' : 'online') . (trim((string) $quote['quote_scope']) !== '' ? " - \"{$quote['quote_scope']}\"" : '') . '.'
|
|
. (trim((string) $note) !== '' ? ' They left a note:' : '')],
|
|
'note' => trim((string) $note),
|
|
'summary' => $summary,
|
|
'button' => ['label' => 'Open in ITFlow', 'url' => "https://$config_base_url/agent/quote.php?quote_id=" . intval($quote['quote_id'])],
|
|
], 'quote');
|
|
}
|
|
|
|
/**
|
|
* Tell the paid notification address (Invoice settings) that an invoice was
|
|
* paid - for online and automatic payments. Nothing when none is set.
|
|
*/
|
|
function billingPaymentNotify(array $invoice, $amount, $how) {
|
|
global $config_base_url;
|
|
$to = billingEmailFrom('notify')['email'];
|
|
if ($to === '') {
|
|
return;
|
|
}
|
|
$number = billingNumber('invoice', $invoice);
|
|
$currency = (string) $invoice['invoice_currency_code'];
|
|
$balance = invoiceState($invoice, invoicePaid($invoice['invoice_id']))['balance'];
|
|
billingNotifyEmail($to, "Payment received - {$invoice['client_name']} - invoice $number", [
|
|
'kind' => 'Payment received', 'tone' => 'success', 'title' => "{$invoice['client_name']} paid $number",
|
|
'intro' => ["$how payment of " . billingMoney($amount, $currency) . " on invoice $number for {$invoice['client_name']}."],
|
|
'summary' => ['Client' => $invoice['client_name'], 'Invoice' => $number, 'Amount paid' => billingMoney($amount, $currency), 'Balance' => $balance > 0 ? billingMoney($balance, $currency) : 'Paid in full'],
|
|
'strong' => 'Amount paid',
|
|
'button' => ['label' => 'Open in ITFlow', 'url' => "https://$config_base_url/agent/invoice.php?invoice_id=" . intval($invoice['invoice_id'])],
|
|
]);
|
|
}
|
|
|
|
/**
|
|
* Tell the paid notification address about one payment over several
|
|
* invoices - the online payments the client portal takes.
|
|
*/
|
|
function billingPaymentNotifyMany(array $applied, $how) {
|
|
global $config_base_url;
|
|
$to = billingEmailFrom('notify')['email'];
|
|
if ($to === '' || !$applied) {
|
|
return;
|
|
}
|
|
$first = $applied[0]['invoice'];
|
|
$currency = (string) $first['invoice_currency_code'];
|
|
$total = array_sum(array_column($applied, 'amount'));
|
|
$rows = [];
|
|
foreach ($applied as $entry) {
|
|
$balance = invoiceState($entry['invoice'], invoicePaid($entry['invoice']['invoice_id']))['balance'];
|
|
$rows[] = [['text' => billingNumber('invoice', $entry['invoice']), 'url' => "https://$config_base_url/agent/invoice.php?invoice_id=" . intval($entry['invoice']['invoice_id'])],
|
|
billingMoney($entry['amount'], $currency), $balance > 0 ? billingMoney($balance, $currency) : 'Paid'];
|
|
}
|
|
billingNotifyEmail($to, "Payment received - {$first['client_name']} - " . count($applied) . ' invoices', [
|
|
'kind' => 'Payment received', 'tone' => 'success', 'title' => "{$first['client_name']} paid " . count($applied) . ' invoices',
|
|
'intro' => ["$how payment of " . billingMoney($total, $currency) . " for {$first['client_name']}, over these invoices."],
|
|
'summary' => ['Client' => $first['client_name'], 'Invoices' => (string) count($applied), 'Amount paid' => billingMoney($total, $currency)],
|
|
'strong' => 'Amount paid',
|
|
'lines' => ['head' => ['Invoice', 'Applied', 'Balance'], 'align' => ['left', 'right', 'right'], 'rows' => $rows],
|
|
]);
|
|
}
|
|
|
|
/**
|
|
* Send the receipt for a payment on one invoice or several - $applied as
|
|
* billingPaymentEmail() takes it - to the client's primary and billing
|
|
* contacts, and log it on each invoice. $notify also tells the paid
|
|
* notification address. The addresses it went to.
|
|
*/
|
|
function billingPaymentReceiptSend(array $applied, array $payment, $notify = false) {
|
|
if (!$applied) {
|
|
return [];
|
|
}
|
|
$first = $applied[0]['invoice'];
|
|
[$subject, $email] = billingPaymentEmail($applied, $payment + ['currency' => $first['invoice_currency_code']]);
|
|
$sent = billingEmailQueue(billingEmailRecipients($first['client_id']), $subject, $email);
|
|
if ($sent) {
|
|
foreach ($applied as $entry) {
|
|
billingLog('invoice', $entry['invoice']['invoice_id'], 'Sent', 'Payment receipt emailed to ' . implode(', ', $sent));
|
|
}
|
|
}
|
|
if ($notify && count($applied) === 1) {
|
|
billingPaymentNotify($first, $applied[0]['amount'], $payment['how'] ?? 'Online');
|
|
} elseif ($notify) {
|
|
billingPaymentNotifyMany($applied, $payment['how'] ?? 'Online');
|
|
}
|
|
return $sent;
|
|
}
|
|
|
|
/**
|
|
* Send a payment received email for a payment on one invoice - to its
|
|
* client's primary and billing contacts - and log it on the invoice.
|
|
* $notify also tells the paid notification address. The addresses it went to.
|
|
*/
|
|
function billingPaymentSend($invoice_id, $amount, array $payment, $notify = false) {
|
|
$invoice = billingRow('invoice', $invoice_id, false);
|
|
if (!$invoice) {
|
|
return [];
|
|
}
|
|
return billingPaymentReceiptSend([['invoice' => $invoice, 'amount' => $amount]], $payment, $notify);
|
|
}
|
|
|
|
/* ------------------------------------------------------------ Statements */
|
|
|
|
/**
|
|
* A client's statement - their invoices sent and not cancelled, dated up to
|
|
* $to (and from $from), the open ones only unless $include_paid, with what
|
|
* has been paid on each:
|
|
* client the client, with its currency
|
|
* from, to the period
|
|
* invoices each with paid, balance and days (late, negative while not due)
|
|
* total what is owed on them
|
|
* overdue what of it is past due
|
|
* aging current, 1-30, 31-60, 61-90 and 90+ days late
|
|
*/
|
|
function billingStatement($client_id, $from = '', $to = '', $include_paid = false) {
|
|
global $mysqli, $session_company_currency;
|
|
$client_id = intval($client_id);
|
|
$to = preg_match('/^\d{4}-\d{2}-\d{2}$/', (string) $to) ? $to : date('Y-m-d');
|
|
$from = preg_match('/^\d{4}-\d{2}-\d{2}$/', (string) $from) ? $from : '';
|
|
$client = mysqli_fetch_assoc(mysqli_query($mysqli, "SELECT client_id, client_name, client_currency_code, client_reminders FROM clients WHERE client_id = $client_id")) ?: null;
|
|
$statement = ['client' => $client, 'from' => $from, 'to' => $to, 'include_paid' => (bool) $include_paid, 'invoices' => [], 'total' => 0.0, 'overdue' => 0.0,
|
|
'aging' => ['Current' => 0.0, '1-30 days' => 0.0, '31-60 days' => 0.0, '61-90 days' => 0.0, 'Over 90 days' => 0.0],
|
|
'currency' => (string) (($client['client_currency_code'] ?? '') ?: ($session_company_currency ?? '') ?: (billingCompany()['company_currency'] ?? ''))];
|
|
if (!$client) {
|
|
return $statement;
|
|
}
|
|
$sql = mysqli_query($mysqli, "SELECT invoice_id, invoice_prefix, invoice_number, invoice_scope, invoice_date, invoice_due, invoice_status, invoice_amount,
|
|
invoice_currency_code, invoice_url_key, COALESCE(paid.amount, 0) AS paid
|
|
FROM invoices
|
|
LEFT JOIN (SELECT payment_invoice_id, SUM(payment_amount) AS amount FROM payments WHERE payment_archived_at IS NULL GROUP BY payment_invoice_id) AS paid
|
|
ON paid.payment_invoice_id = invoice_id
|
|
WHERE invoice_client_id = $client_id AND invoice_status NOT IN ('Draft', 'Cancelled', 'Non-Billable')
|
|
AND invoice_date <= '$to'" . ($from !== '' ? " AND invoice_date >= '$from'" : '') . "
|
|
ORDER BY invoice_date ASC, invoice_number ASC");
|
|
$today = strtotime(date('Y-m-d'));
|
|
while ($row = mysqli_fetch_assoc($sql)) {
|
|
$row['balance'] = round(floatval($row['invoice_amount']) - floatval($row['paid']), 2);
|
|
if ($row['balance'] <= 0 && !$include_paid) {
|
|
continue;
|
|
}
|
|
$row['days'] = intval(round(($today - strtotime($row['invoice_due'])) / 86400));
|
|
$row['client_name'] = $client['client_name'];
|
|
if ($row['balance'] > 0) {
|
|
$statement['total'] += $row['balance'];
|
|
$days = $row['days'];
|
|
$bucket = $days <= 0 ? 'Current' : ($days <= 30 ? '1-30 days' : ($days <= 60 ? '31-60 days' : ($days <= 90 ? '61-90 days' : 'Over 90 days')));
|
|
$statement['aging'][$bucket] += $row['balance'];
|
|
if ($days > 0) {
|
|
$statement['overdue'] += $row['balance'];
|
|
}
|
|
}
|
|
$statement['invoices'][] = $row;
|
|
}
|
|
$statement['total'] = round($statement['total'], 2);
|
|
$statement['overdue'] = round($statement['overdue'], 2);
|
|
return $statement;
|
|
}
|
|
|
|
/** A statement's period in words - "up to Oct 16, 2026", "Jul 1, 2026 to Oct 16, 2026". */
|
|
function billingStatementPeriod(array $statement) {
|
|
return ($statement['from'] !== '' ? billingEmailDate($statement['from']) . ' to ' : 'up to ') . billingEmailDate($statement['to']);
|
|
}
|
|
|
|
/** A statement as a PDF - ['name', 'data']. See functions/billing_pdf.php. */
|
|
function billingStatementPdf(array $statement) {
|
|
require_once __DIR__ . '/../libs/TCPDF/tcpdf.php';
|
|
require_once __DIR__ . '/billing_pdf.php';
|
|
return billingStatementPdfRender($statement);
|
|
}
|
|
|
|
/** A statement email - [subject, email]. $opts: note. */
|
|
function billingStatementEmail(array $statement, array $opts = []) {
|
|
$currency = $statement['currency'];
|
|
$company = billingCompany();
|
|
$rows = [];
|
|
foreach ($statement['invoices'] as $invoice) {
|
|
$late = $invoice['balance'] > 0 && $invoice['days'] > 0;
|
|
$rows[] = [
|
|
['text' => billingNumber('invoice', $invoice), 'url' => billingGuestUrl('invoice', $invoice)],
|
|
billingEmailDate($invoice['invoice_date']),
|
|
['text' => billingEmailDate($invoice['invoice_due']) . ($late ? ' (' . $invoice['days'] . 'd late)' : ''), 'tone' => $late ? 'danger' : ''],
|
|
['text' => $invoice['balance'] > 0 ? billingMoney($invoice['balance'], $currency) : 'Paid', 'tone' => $invoice['balance'] > 0 ? '' : 'success'],
|
|
];
|
|
}
|
|
$summary = ['Statement date' => billingEmailDate(date('Y-m-d')), 'Period' => ucfirst(billingStatementPeriod($statement)), 'Open invoices' => (string) count(array_filter($statement['invoices'], function ($invoice) {
|
|
return $invoice['balance'] > 0;
|
|
}))];
|
|
if ($statement['overdue'] > 0) {
|
|
$summary['Overdue'] = billingMoney($statement['overdue'], $currency);
|
|
}
|
|
$summary['Total due'] = billingMoney($statement['total'], $currency);
|
|
return ['Statement from ' . ($company['company_name'] ?? '') . ' - ' . billingEmailDate($statement['to']), [
|
|
'kind' => 'Statement', 'tone' => $statement['overdue'] > 0 ? 'warning' : 'primary', 'title' => 'Your account statement',
|
|
'intro' => ['Here is your statement for ' . $statement['client']['client_name'] . ', ' . billingStatementPeriod($statement) . '.' . ($statement['total'] > 0 ? ' Open an invoice to view' . (billingOnlinePayments() ? ' or pay' : '') . ' it.' : ' Nothing is owed - thank you.')],
|
|
'note' => $opts['note'] ?? '',
|
|
'summary' => $summary, 'strong' => 'Total due',
|
|
'lines' => ['head' => ['Invoice', 'Date', 'Due', 'Balance'], 'align' => ['left', 'left', 'left', 'right'], 'rows' => $rows],
|
|
'after' => ['Questions about your account? Reply to this email' . (!empty($company['phone_display']) ? ' or call us on ' . $company['phone_display'] : '') . '.'],
|
|
'footnote' => billingEmailFootnote($statement['client']['client_name']),
|
|
]];
|
|
}
|
|
|
|
/**
|
|
* Email a statement to a client's contacts (the defaults when $contact_ids
|
|
* is null), with its PDF when $attach. The addresses it went to.
|
|
*/
|
|
function billingStatementSend(array $statement, ?array $contact_ids = null, array $opts = []) {
|
|
[$subject, $email] = billingStatementEmail($statement, $opts);
|
|
$attach = [];
|
|
if (!empty($opts['attach'])) {
|
|
$file = billingEmailPdf(billingStatementPdf($statement));
|
|
if ($file) {
|
|
$attach[] = $file;
|
|
}
|
|
}
|
|
return billingEmailQueue(billingEmailRecipients($statement['client']['client_id'], $contact_ids), $subject, $email, ['attach' => $attach]);
|
|
}
|