Simple Commerce Laravel Package

Getting Started

This is a patch release on the 7.8 line (v7.8.10). It contains a single hardening change to email address validation (#1287) plus the usual dependency bumps — no new APIs, no deprecations, no migration steps. Upgrade with a normal composer update pinned to the same constraint you already have:

composer require vendor/package:"^7.8"   # already satisfied if you're on 7.8.x
composer update vendor/package --with-dependencies

Where to look first, in order:

1. composer.json of the package — confirm the PHP and Laravel constraints for the 7.x line before you assume the patch is free. If you're coming from v6, the major bump is the real work; 7.8.10 itself is not.
2. The package's config file — publish it if you haven't (php artisan vendor:publish --tag=<package>-config) and read it end to end. In mature packages at this version, most day-to-day behaviour is toggled there rather than in code.
3. The changelog entry for 7.8.10 — one line, but it tells you the validation surface changed, which is the thing most likely to bite you.

First use case: put the package's email validation in front of any user-supplied address — registration, profile update, invite flows, newsletter capture, webhook payloads from third parties. The hardening in 7.8.10 is exactly the kind of change that makes it safer to trust a single rule instead of hand-rolled regex: patterns scattered across form requests.

Implementation Patterns

Keep validation in Form Requests, not controllers. Wrap the package rule in a request class so the rule set is testable in isolation and reusable across HTTP, Livewire, and console/import paths:

public function rules(): array
{
    return [
        'email' => ['required', 'string', 'max:255', $this->emailRule()],
        // ...
    ];
}

Compose the rule with the standard Laravel constraints (required, nullable, max, unique) rather than letting the package rule stand alone — it validates shape, not uniqueness or length policy.

Normalise before you persist. Validation and storage are separate concerns. Validate the raw input, then store a normalised form (trim whitespace, lowercase the domain, preserve the local part's case unless your product says otherwise). Keeping the raw value alongside the normalised one costs one column and saves you an afternoon when someone disputes an address.

Test the edge cases explicitly. This is the highest-value habit with a package that just changed its email validation. Use a data provider:

public static function addresses(): array
{
    return [
        'plus tag'        => ['[email protected]', true],
        'subdomain'       => ['[email protected]', true],
        'unicode domain'  => ['user@exämple.com', true],
        'trailing dot'    => ['[email protected].', false],
        'double at'       => ['user@@example.com', false],
        'display name'    => ['"User" <[email protected]>', false],
        'no tld'          => ['user@localhost', false],
    ];
}

Run this against 7.8.9 and 7.8.10 in CI once, so you can see exactly which inputs the hardening rejects that it previously accepted. That diff is your risk assessment.

Integration tips:

• Map ValidationException to a 422 in API controllers via the default handler; don't catch and swallow it, or clients lose the field-level errors.
• For imports and queued jobs, run Validator::make() explicitly rather than relying on HTTP-layer validation — the same rule set, but you control the failure path (skip row, log, or fail the job).
• In tests, prefer Config::set('package.key', $value) over editing the published config file, and assertInvalid() / assertValid() over reaching into the rule internals.
• If you need product-specific policy (block disposable domains, require corporate TLDs), layer a custom Rule object after the package rule instead of forking it.

Gotchas and Tips

Stricter validation can lock out existing users. The most common failure mode after a hardening patch: records in your database that were accepted under looser rules now fail on the profile-update form. Before deploying, run the new rule against your existing users.email column in a read-only script and count the rejections. If it's non-zero, decide the policy deliberately — grandfathered rows, forced re-verification, or a softer rule on update paths.

Don't mirror the rule client-side. A JS regex that approximates the server rule will drift with every patch and produce "the form said it was fine" bug reports. Submit and render the 422 instead.

email:rfc,dns in tests is a trap. DNS-dependent validation is slow and flaky in CI and fails entirely in sandboxed environments. Keep the strict/DNS variant for production config and use the syntax-only variant (or a mocked resolver) in testing. Same applies to any verification or deliverability call the package exposes behind a config flag.

Debugging a rejection: drop to php artisan tinker and run Validator::make(['email' => $value], ['email' => $rule])->errors() to see the actual message, rather than bisecting your request class. Enable the package's debug/logging config switch if it has one — many at this version log outbound calls and rule failures.

Extension points worth knowing: custom rule objects and Validator::extend() for policy on top of the package, published lang/ files for message wording (translate the email message if you support non-English locales — it's the one users see most), and the config toggles for turning strictness down per-environment.

Version discipline: pin to ^7.8 in composer.json, commit composer.lock, and read the changelog for every 7.x minor. Patch releases like 7.8.10 are safe to take within the line; the risk is entirely in behaviour your tests don't cover, not in the upgrade mechanics.

Validation is not verification. A passing email rule means the address is well-formed, not that it exists or is deliverable. Keep that boundary explicit in your architecture — the package validates, your verification step (double opt-in, provider API) confirms.