@fleetbase/fleetops-engine 0.6.64 → 0.6.66

package/server/src/Support/InspectionFileStore.php

@@ -0,0 +1,268 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Fleetbase\FleetOps\Models\InspectionSubmission;
+use Fleetbase\Models\File;
+use Illuminate\Support\Str;
+use Illuminate\Validation\ValidationException;
+
+/**
+ * Turns what a driver sends for a photo or a signature into a platform file.
+ *
+ * The app is offline-first: it cannot upload a photo and then reference it,
+ * so a photo arrives inside the submit body as base64. The platform's own
+ * convention for a file held in a custom-field value is `file:<uuid>`, which
+ * is what every value leaves here as — a URL, or a reference to a file that
+ * already exists, is kept as it came.
+ *
+ * A reference is only ever kept for a file the submission may use: one that
+ * belongs to the submission's own company. A submission through a public
+ * link may go further than that only in one direction — it may reference
+ * nothing but files uploaded through that same link, and it may not use an
+ * outside URL as a photo at all.
+ */
+class InspectionFileStore
+{
+    public const TYPE_PHOTO     = 'inspection_photo';
+    public const TYPE_SIGNATURE = 'inspection_signature';
+
+    /**
+     * Normalizes one file value. Returns the value unchanged when it is not a
+     * string, is empty, or is something other than base64 or a file reference.
+     */
+    public static function normalize(mixed $value, InspectionSubmission $submission, string $type = self::TYPE_PHOTO, ?string $uploaderUuid = null): mixed
+    {
+        if (!is_string($value) || trim($value) === '') {
+            return $value;
+        }
+
+        $value = trim($value);
+
+        $linkUuid = static::linkUuidOf($submission);
+
+        // A reference to a file that already exists — `file:<uuid>`, a bare
+        // uuid, or the public id an upload answers with — is kept only for a
+        // file the submission may use.
+        if (Str::startsWith($value, 'file:') || Str::isUuid($value) || Str::startsWith($value, 'file_')) {
+            return static::ownedReference($value, $submission, $linkUuid);
+        }
+
+        if (static::isUrl($value)) {
+            if ($linkUuid) {
+                throw ValidationException::withMessages(['photos' => 'A photo on an inspection link must be uploaded through the link.']);
+            }
+
+            return $value;
+        }
+
+        if (static::isBase64($value)) {
+            $file = static::store($value, $submission, $type, $uploaderUuid);
+
+            return $file ? 'file:' . $file->uuid : $value;
+        }
+
+        return $value;
+    }
+
+    /**
+     * Stores a base64 payload — bare or as a data URI — as a file that belongs
+     * to the submission, under `inspections/<submission uuid>/`.
+     */
+    public static function store(string $base64, InspectionSubmission $submission, string $type = self::TYPE_PHOTO, ?string $uploaderUuid = null): ?File
+    {
+        $contentType = null;
+        $data        = $base64;
+
+        if (preg_match('/^data:(?<content_type>[^;]+);base64,(?<data>.+)$/s', $base64, $matches)) {
+            $contentType = $matches['content_type'];
+            $data        = $matches['data'];
+        }
+
+        $data        = preg_replace('/\s+/', '', $data);
+        $contentType = $contentType ?? static::sniffContentType($data);
+        $extension   = static::extensionFor($contentType);
+        $fileName    = Str::lower(Str::random(20)) . '.' . $extension;
+
+        $file = File::createFromBase64($data, $fileName, 'inspections/' . $submission->uuid, $type, $contentType);
+        if (!$file instanceof File) {
+            return null;
+        }
+
+        $file->company_uuid  = $submission->company_uuid;
+        $file->uploader_uuid = $uploaderUuid ?? $submission->submitted_by_uuid ?? $file->uploader_uuid;
+        $file->setSubject($submission, $type);
+
+        return $file;
+    }
+
+    /**
+     * Files referenced by `file:<uuid>` values that were uploaded before the
+     * submission existed — the console uploads a photo as soon as it is picked
+     * — are claimed by the submission so its Photos panel lists them.
+     *
+     * @param string[] $uuids
+     */
+    public static function attachReferenced(InspectionSubmission $submission, array $uuids): int
+    {
+        $uuids = array_values(array_unique(array_filter($uuids, 'is_string')));
+        if (empty($uuids)) {
+            return 0;
+        }
+
+        // Only the submission's own company's files, and — for a submission
+        // through a public link — only files uploaded through that link. This
+        // claim was unscoped: any unattached file anywhere whose uuid appeared
+        // in an answer was taken.
+        $query = File::query()
+            ->whereIn('uuid', $uuids)
+            ->where('company_uuid', $submission->company_uuid)
+            ->whereNull('subject_uuid');
+
+        if ($linkUuid = static::linkUuidOf($submission)) {
+            $query->where('meta->inspection_link_uuid', $linkUuid);
+        }
+
+        return $query->update(['subject_uuid' => $submission->uuid, 'subject_type' => $submission->getMorphClass()]);
+    }
+
+    /**
+     * The inspection link a submission came through, or null when it came
+     * through the console or the driver app.
+     */
+    protected static function linkUuidOf(InspectionSubmission $submission): ?string
+    {
+        if ($submission->source !== 'public_link') {
+            return null;
+        }
+
+        $uuid = data_get($submission->meta, 'inspection_link_uuid');
+
+        return is_string($uuid) && $uuid !== '' ? $uuid : null;
+    }
+
+    /**
+     * A reference to an existing file, as `file:<uuid>`, kept only when the
+     * file is the submission's to use.
+     *
+     * The lookup used to be unscoped, so a submission that named another
+     * company's file — by uuid or public id — kept the reference, the file was
+     * attached to it, and the submission resource then handed out that file's
+     * URL. It is now scoped to the submission's company; a submission through
+     * a public link must also have uploaded the file through that link, and is
+     * refused outright rather than silently losing a photo it named.
+     */
+    protected static function ownedReference(string $value, InspectionSubmission $submission, ?string $linkUuid): ?string
+    {
+        $reference = Str::startsWith($value, 'file:') ? substr($value, 5) : $value;
+
+        $file = File::query()
+            ->where('company_uuid', $submission->company_uuid)
+            ->where(Str::isUuid($reference) ? 'uuid' : 'public_id', $reference)
+            ->first();
+
+        if ($file && (!$linkUuid || data_get($file->meta, 'inspection_link_uuid') === $linkUuid)) {
+            return 'file:' . $file->uuid;
+        }
+
+        if ($linkUuid) {
+            throw ValidationException::withMessages(['photos' => 'A photo on an inspection link must be uploaded through the link.']);
+        }
+
+        return null;
+    }
+
+    /** The uuid a `file:<uuid>` value points at, or null for anything else. */
+    public static function referencedUuid(mixed $value): ?string
+    {
+        if (!is_string($value) || !Str::startsWith($value, 'file:')) {
+            return null;
+        }
+
+        $uuid = substr($value, 5);
+
+        return Str::isUuid($uuid) ? $uuid : null;
+    }
+
+    /** Resolves a `file:<uuid>` value to its file, or null. */
+    public static function resolve(mixed $value): ?File
+    {
+        $uuid = static::referencedUuid($value);
+
+        return $uuid ? File::query()->where('uuid', $uuid)->first() : null;
+    }
+
+    /**
+     * What the driver API answers for a file value: the file's id and where to
+     * fetch it, or the value as it was stored when it is a URL.
+     */
+    public static function project(mixed $value): mixed
+    {
+        $file = static::resolve($value);
+        if (!$file) {
+            return $value;
+        }
+
+        return [
+            'id'           => $file->public_id,
+            'url'          => $file->url,
+            'filename'     => $file->original_filename,
+            'content_type' => $file->content_type,
+        ];
+    }
+
+    public static function isUrl(string $value): bool
+    {
+        return (bool) preg_match('#^https?://#i', $value);
+    }
+
+    /** Bare base64 of at least a few bytes: long enough not to be a word, and only base64 characters. */
+    public static function isBase64(string $value): bool
+    {
+        if (Str::startsWith($value, 'data:')) {
+            return (bool) preg_match('/^data:[^;]+;base64,[A-Za-z0-9+\/=\s]+$/s', $value);
+        }
+
+        $stripped = preg_replace('/\s+/', '', $value);
+
+        return strlen($stripped) >= 16
+            && strlen($stripped) % 4 === 0
+            && (bool) preg_match('/^[A-Za-z0-9+\/]+={0,2}$/', $stripped);
+    }
+
+    /** The image type from the decoded bytes' signature; PNG when it is not a known image. */
+    public static function sniffContentType(string $base64): string
+    {
+        $bytes = (string) base64_decode(substr($base64, 0, 32), true);
+
+        if (str_starts_with($bytes, "\xFF\xD8\xFF")) {
+            return 'image/jpeg';
+        }
+
+        if (str_starts_with($bytes, 'GIF8')) {
+            return 'image/gif';
+        }
+
+        if (str_starts_with($bytes, 'RIFF') && substr($bytes, 8, 4) === 'WEBP') {
+            return 'image/webp';
+        }
+
+        if (str_starts_with($bytes, '%PDF')) {
+            return 'application/pdf';
+        }
+
+        return 'image/png';
+    }
+
+    public static function extensionFor(string $contentType): string
+    {
+        return match (strtolower($contentType)) {
+            'image/jpeg', 'image/jpg' => 'jpg',
+            'image/gif'               => 'gif',
+            'image/webp'              => 'webp',
+            'application/pdf'         => 'pdf',
+            'image/svg+xml'           => 'svg',
+            default                   => 'png',
+        };
+    }
+}

package/server/src/Support/InspectionFormSync.php

@@ -0,0 +1,231 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Fleetbase\FleetOps\Models\InspectionForm;
+use Fleetbase\Models\Category;
+use Fleetbase\Models\CustomField;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Collection;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
+
+/**
+ * Writes a form's structure — groups of typed fields — from the shape the
+ * console builder holds it in, and converts the first cut's checklist into
+ * that structure.
+ *
+ * The console builder lets a form be laid out before the form record exists,
+ * so the whole draft arrives with the first save and has to be written in one
+ * go: groups become platform categories owned by the form, fields become
+ * platform custom fields whose subject is the form. Rows are matched on their
+ * uuid so a second post updates rather than duplicates; rows the post no
+ * longer mentions are pruned only when asked, because a partial post is the
+ * common case and losing fields is not.
+ */
+class InspectionFormSync
+{
+    /** The group columns the builder is allowed to write. */
+    public const GROUP_COLUMNS = ['name', 'description', 'meta', 'order', 'icon', 'icon_color', 'translations', 'tags'];
+
+    /** The field columns the builder is allowed to write. */
+    public const FIELD_COLUMNS = ['name', 'label', 'type', 'component', 'options', 'required', 'editable', 'default_value', 'validation_rules', 'meta', 'description', 'help_text', 'order', 'for'];
+
+    /**
+     * @param InspectionForm $form         the form the structure belongs to
+     * @param array          $draft        groups, each with its fields under `fields` or `customFields`
+     * @param bool           $pruneMissing drop groups and fields the draft no longer lists
+     * @param string         $primaryKey   the key rows are matched on, `uuid` or `id`
+     *
+     * @return array{groups: Category[], fields: CustomField[]}
+     */
+    public static function sync(InspectionForm $form, array $draft, bool $pruneMissing = false, string $primaryKey = 'uuid'): array
+    {
+        $existingGroups = Category::query()
+            ->where(['owner_uuid' => $form->uuid, 'for' => InspectionForm::GROUP_FOR])
+            ->get()
+            ->keyBy('uuid');
+        // Only the fields a driver answers. A custom field the console's
+        // generic panel added to the form *record* has the same subject and
+        // would otherwise be pruned as a field the builder no longer lists.
+        $existingFields = CustomField::query()
+            ->where(['subject_uuid' => $form->uuid, 'for' => InspectionForm::FIELD_FOR])
+            ->get()
+            ->keyBy('uuid');
+
+        $keptGroups = [];
+        $keptFields = [];
+        $now        = now();
+
+        foreach (array_values($draft) as $groupIndex => $groupData) {
+            $groupUuid  = Arr::get($groupData, $primaryKey);
+            $group      = $groupUuid ? $existingGroups->get($groupUuid) : null;
+            $groupUuid  = $group?->uuid ?? ($groupUuid ?: (string) Str::uuid());
+            $groupAttrs = static::normalizeRow(Arr::only($groupData, static::GROUP_COLUMNS), $groupIndex);
+
+            if ($group) {
+                DB::table('categories')->where('uuid', $groupUuid)->update(array_merge($groupAttrs, ['updated_at' => $now]));
+            } else {
+                DB::table('categories')->insert(array_merge($groupAttrs, [
+                    'uuid'         => $groupUuid,
+                    'public_id'    => 'category_' . Str::lower(Str::random(14)),
+                    'company_uuid' => $form->company_uuid,
+                    'owner_uuid'   => $form->uuid,
+                    'owner_type'   => $form->getMorphClass(),
+                    'for'          => InspectionForm::GROUP_FOR,
+                    'slug'         => Str::slug((string) ($groupAttrs['name'] ?? 'group')),
+                    'created_at'   => $now,
+                    'updated_at'   => $now,
+                ]));
+            }
+
+            $keptGroups[] = $groupUuid;
+
+            $fields = Arr::get($groupData, 'fields', Arr::get($groupData, 'customFields', []));
+            foreach (array_values(is_array($fields) ? $fields : []) as $fieldIndex => $fieldData) {
+                $fieldUuid  = Arr::get($fieldData, $primaryKey);
+                $field      = $fieldUuid ? $existingFields->get($fieldUuid) : null;
+                $fieldUuid  = $field?->uuid ?? ($fieldUuid ?: (string) Str::uuid());
+                $fieldAttrs = static::normalizeField(Arr::only($fieldData, static::FIELD_COLUMNS), $fieldIndex);
+
+                if ($field) {
+                    DB::table('custom_fields')->where('uuid', $fieldUuid)->update(array_merge($fieldAttrs, ['category_uuid' => $groupUuid, 'updated_at' => $now]));
+                } else {
+                    DB::table('custom_fields')->insert(array_merge($fieldAttrs, [
+                        'uuid'          => $fieldUuid,
+                        'company_uuid'  => $form->company_uuid,
+                        'category_uuid' => $groupUuid,
+                        'subject_uuid'  => $form->uuid,
+                        'subject_type'  => $form->getMorphClass(),
+                        'created_at'    => $now,
+                        'updated_at'    => $now,
+                    ]));
+                }
+
+                $keptFields[] = $fieldUuid;
+            }
+        }
+
+        if ($pruneMissing) {
+            static::prune($form, $existingGroups, $keptGroups, $existingFields, $keptFields);
+        }
+
+        $form->unsetRelation('fieldGroups');
+        $form->unsetRelation('fields');
+        $form->load(['fieldGroups', 'fields']);
+
+        return ['groups' => $form->fieldGroups->all(), 'fields' => $form->fields->all()];
+    }
+
+    /**
+     * Converts the first cut's `items` checklist into a "Checklist" group of
+     * pass-fail fields. Skips forms that have already been built with fields,
+     * and forms with nothing to convert, so it can be run any number of times.
+     *
+     * @return int the number of fields written
+     */
+    public static function convertLegacyItems(InspectionForm $form): int
+    {
+        $items = array_values(array_filter(is_array($form->items) ? $form->items : [], 'is_array'));
+        if (empty($items) || $form->fields()->count() > 0) {
+            return 0;
+        }
+
+        $fields = [];
+        foreach ($items as $index => $item) {
+            $label    = trim((string) ($item['label'] ?? $item['title'] ?? ''));
+            $label    = $label === '' ? 'Item ' . ($index + 1) : $label;
+            $fields[] = [
+                'label'       => $label,
+                'name'        => Str::slug((string) ($item['key'] ?? $label)),
+                'type'        => 'pass-fail',
+                'required'    => (bool) ($item['required'] ?? true),
+                'description' => $item['description'] ?? null,
+                'order'       => $index + 1,
+                'meta'        => [
+                    'severity'                => $item['severity'] ?? 'medium',
+                    'category'                => $item['category'] ?? null,
+                    'require_photo_on_fail'   => false,
+                    'require_comment_on_fail' => false,
+                    'unsafe_on_fail'          => ($item['severity'] ?? null) === 'critical',
+                ],
+            ];
+        }
+
+        $synced = static::sync($form, [[
+            'name'   => 'Checklist',
+            'order'  => 1,
+            'meta'   => ['grid_size' => 1, 'converted_from_items' => true],
+            'fields' => $fields,
+        ]]);
+
+        return count($synced['fields']);
+    }
+
+    /** Group attributes as the categories table stores them. */
+    protected static function normalizeRow(array $attributes, int $index): array
+    {
+        if (!array_key_exists('order', $attributes) || $attributes['order'] === null) {
+            $attributes['order'] = $index + 1;
+        }
+
+        foreach ($attributes as $key => $value) {
+            if (is_array($value) || is_object($value)) {
+                $attributes[$key] = json_encode($value, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
+            }
+        }
+
+        return $attributes;
+    }
+
+    /** Field attributes as the custom_fields table stores them. */
+    protected static function normalizeField(array $attributes, int $index): array
+    {
+        $label = trim((string) ($attributes['label'] ?? ''));
+        if ($label === '') {
+            $label = 'Untitled field';
+        }
+
+        $attributes['label'] = $label;
+        $attributes['name']  = Str::slug((string) (($attributes['name'] ?? '') ?: $label));
+        $attributes['type']  = in_array($attributes['type'] ?? null, InspectionForm::FIELD_TYPES, true) ? $attributes['type'] : 'input';
+        $attributes['for']   = InspectionForm::FIELD_FOR;
+
+        if (empty($attributes['component'])) {
+            $attributes['component'] = static::componentFor($attributes['type']);
+        }
+
+        foreach (['required', 'editable'] as $flag) {
+            $attributes[$flag] = (int) filter_var($attributes[$flag] ?? ($flag === 'editable'), FILTER_VALIDATE_BOOLEAN);
+        }
+
+        return static::normalizeRow($attributes, $index);
+    }
+
+    /**
+     * The console component that edits a field type. The platform's own
+     * types keep the platform's components; the inspection-only types are
+     * rendered by FleetOps and named after themselves.
+     */
+    public static function componentFor(string $type): string
+    {
+        return $type === 'radio-button' ? 'radio-button-select' : $type;
+    }
+
+    protected static function prune(InspectionForm $form, Collection $existingGroups, array $keptGroups, Collection $existingFields, array $keptFields): void
+    {
+        $groupsToDelete = $existingGroups->keys()->diff($keptGroups)->values();
+        if ($groupsToDelete->isNotEmpty()) {
+            CustomField::query()
+                ->where(['subject_uuid' => $form->uuid, 'for' => InspectionForm::FIELD_FOR])
+                ->whereIn('category_uuid', $groupsToDelete)
+                ->delete();
+            Category::query()->whereIn('uuid', $groupsToDelete)->delete();
+        }
+
+        $fieldsToDelete = $existingFields->keys()->diff($keptFields)->values();
+        if ($fieldsToDelete->isNotEmpty()) {
+            CustomField::query()->whereIn('uuid', $fieldsToDelete)->delete();
+        }
+    }
+}

package/server/src/Support/InspectionLinkPin.php

@@ -0,0 +1,150 @@
+<?php
+
+namespace Fleetbase\FleetOps\Support;
+
+use Fleetbase\FleetOps\Mail\InspectionLinkPinMail;
+use Fleetbase\FleetOps\Models\InspectionLink;
+use Fleetbase\Models\Company;
+use Fleetbase\Models\User;
+use Fleetbase\Services\SmsService;
+use Fleetbase\Support\Utils;
+use Illuminate\Support\Facades\Mail;
+
+/**
+ * Sends an inspection link and its PIN to whoever the link is for.
+ *
+ * The message carries both, so the recipient can open the inspection straight
+ * from it. The PIN still stops anyone who has only the link, such as a link
+ * copied or forwarded on its own, and it locks the link after a few wrong
+ * guesses.
+ */
+class InspectionLinkPin
+{
+    public const VIA = ['email', 'sms'];
+
+    /** Who a link's PIN goes to: the assignee, or failing that the driver's account. */
+    public static function recipientFor(InspectionLink $link): ?User
+    {
+        return $link->assignee ?? $link->driver?->user;
+    }
+
+    /** Why a PIN cannot go to this person this way, or null when it can. */
+    public static function unavailableReason(?User $recipient, string $via): ?string
+    {
+        if (!$recipient) {
+            return 'Assign the link to someone, or pick a driver, to send the PIN to.';
+        }
+
+        if ($via === 'sms' && !filled($recipient->phone)) {
+            return ($recipient->name ?: 'This person') . ' has no phone number to text the PIN to.';
+        }
+
+        if ($via === 'email' && !filled($recipient->email)) {
+            return ($recipient->name ?: 'This person') . ' has no email address to send the PIN to.';
+        }
+
+        return null;
+    }
+
+    /**
+     * Send the link's PIN. Never throws: a failed delivery is reported in the
+     * result, so minting a link does not fail because a mailer is misconfigured.
+     *
+     * @return array{sent: bool, via: string, to: ?string, error: ?string}
+     */
+    public static function send(InspectionLink $link, string $via): array
+    {
+        $recipient = static::recipientFor($link);
+        $reason    = static::unavailableReason($recipient, $via);
+
+        if (!$link->pin) {
+            $reason = 'This link has no PIN to send.';
+        }
+
+        if ($reason) {
+            return ['sent' => false, 'via' => $via, 'to' => null, 'error' => $reason];
+        }
+
+        try {
+            if ($via === 'sms') {
+                // Resolved from the container rather than built here, so the
+                // provider can be swapped out without touching this class.
+                $result = app(SmsService::class)->send($recipient->phone, static::smsText($link, $link->pin, static::urlFor($link)), static::smsOptions($link));
+
+                if (is_array($result) && array_key_exists('success', $result) && !$result['success']) {
+                    return ['sent' => false, 'via' => $via, 'to' => null, 'error' => 'The PIN could not be texted: ' . ($result['error'] ?? $result['message'] ?? 'the SMS provider refused it.')];
+                }
+
+                $to = static::maskPhone($recipient->phone);
+            } else {
+                Mail::to($recipient)->send(new InspectionLinkPinMail($link, $link->pin, $recipient, static::urlFor($link)));
+                $to = static::maskEmail($recipient->email);
+            }
+        } catch (\Throwable $e) {
+            report($e);
+
+            return ['sent' => false, 'via' => $via, 'to' => null, 'error' => 'The PIN could not be sent: ' . $e->getMessage()];
+        }
+
+        $link->forceFill(['pin_sent_via' => $via, 'pin_sent_at' => now()])->save();
+
+        return ['sent' => true, 'via' => $via, 'to' => $to, 'error' => null];
+    }
+
+    /**
+     * The link as the recipient opens it, on the console's own host. Null for a
+     * link minted before tokens were kept, whose URL cannot be rebuilt.
+     */
+    public static function urlFor(InspectionLink $link): ?string
+    {
+        $path = $link->path;
+
+        return $path ? Utils::consoleUrl($path) : null;
+    }
+
+    /** Naming the organisation so it is recognised, and short enough to read at a glance. */
+    public static function smsText(InspectionLink $link, string $pin, ?string $url = null): string
+    {
+        $company = Company::select(['uuid', 'name'])->find($link->company_uuid)?->name ?? config('app.name');
+        $form    = $link->form?->name ?? 'inspection';
+
+        if ($url) {
+            return "{$company}: complete the {$form} inspection at {$url} using PIN {$pin}. Do not share this PIN.";
+        }
+
+        return "{$company}: your PIN for the {$form} inspection is {$pin}. Do not share this PIN.";
+    }
+
+    /**
+     * The organisation's alphanumeric sender ID, when it has one, the same way
+     * the platform's own verification texts use it: as a Twilio-only option,
+     * so other providers are not handed a sender they would reject.
+     */
+    protected static function smsOptions(InspectionLink $link): array
+    {
+        $company = Company::select(['uuid', 'options'])->find($link->company_uuid);
+
+        if (!$company) {
+            return [];
+        }
+
+        $enabled  = Utils::castBoolean($company->getOption('alpha_numeric_sender_id_enabled'));
+        $senderId = $company->getOption('alpha_numeric_sender_id');
+
+        return $enabled && $senderId ? ['twilioParams' => ['from' => $senderId]] : [];
+    }
+
+    /** "r•••@fleetbase.io": enough to recognise, not enough to copy. */
+    public static function maskEmail(string $email): string
+    {
+        [$local, $domain] = array_pad(explode('@', $email, 2), 2, '');
+
+        return mb_substr($local, 0, 1) . '•••@' . $domain;
+    }
+
+    /** "•••1969": the last four digits. */
+    public static function maskPhone(string $phone): string
+    {
+        return '•••' . substr(preg_replace('/\D/', '', $phone), -4);
+    }
+}