Types Laravel Package

Product Decisions This Supports

• Type Safety & Developer Experience (DX):

  • Enhanced Validation for Critical Data: The new EmailAddress type utility enables stricter validation for email-related logic, reducing runtime errors in user-facing flows (e.g., authentication, notifications). This aligns with security and compliance needs (e.g., GDPR, email deliverability).
  • Domain-Specific Typing: Expands the package’s utility beyond generic types to business-critical domains (e.g., user accounts, communication layers), making it a stronger candidate for build vs. buy in projects with heavy email workflows (e.g., SaaS platforms, marketing tools).
  • Laravel Ecosystem Integration: Complements Laravel’s built-in MustVerifyEmail trait and Illuminate\Validation\Rules\Email by offering runtime type enforcement (e.g., EmailAddress::validate($input)) alongside validation rules.

• Roadmap Acceleration:

  • Feature Flag for Email-Heavy Projects: Prioritize adoption in projects where email validation is a bottleneck (e.g., password reset flows, subscription confirmations). Example: Replace custom regex validation with EmailAddress::ensureValid().
  • Legacy Modernization: Gradually introduce types in user-related modules without breaking existing email logic. Example:

    // Before: Loose validation
    if (filter_var($email, FILTER_VALIDATE_EMAIL)) { ... }
    
    // After: Strong typing
    $email = EmailAddress::fromString($request->input('email'));
    

  • API Contracts: Use EmailAddress in OpenAPI/Swagger schemas or GraphQL input types to enforce consistency between frontend and backend.

• Use Cases (Expanded):

  • User Authentication: Validate email addresses during registration/login with zero false positives (e.g., catch user@example early).
  • Transactional Emails: Ensure from/to addresses in queues (e.g., Laravel’s Mailable) are typed correctly.
  • Third-Party Integrations: Sanitize emails from external APIs (e.g., Stripe webhooks, Mailchimp) before processing.

When to Consider This Package

• Adopt if:

  • Your project heavily relies on email validation (e.g., >50% of user flows involve emails) and you’re using PHP 8.0+.
  • You need both runtime validation and type safety (e.g., EmailAddress as a method return type in a User service).
  • You’re migrating from loose email checks (e.g., strpos($email, '@')) to modern PHP types.
  • Your team uses Laravel’s validation but wants additional type guarantees (e.g., in DTOs or domain services).

• Look elsewhere if:

  • You only need basic email validation (use Laravel’s built-in Email rule or filter_var).
  • Your stack is not PHP/Laravel (e.g., Node.js, Python; use language-specific libraries).
  • You require enterprise support (this package is community-maintained; pair with phpstan/extension-installer for static analysis).
  • Your emails are internationalized (e.g., non-ASCII addresses; consider egulias/email-validator for RFC compliance).

How to Pitch It (Stakeholders)

For Executives:

*"This update adds specialized email type safety to our PHP toolkit—critical for reducing errors in user flows like sign-ups and password resets. For example, it catches invalid emails like user@example before they hit our database, saving support costs and improving deliverability.

Impact:

• Fewer bugs in high-traffic email workflows (e.g., 10–20% reduction in validation edge cases).
• Faster onboarding for new devs by standardizing email handling.
• Low risk: MIT-licensed, zero dependencies, and backward-compatible.

Ask: ‘Would you prioritize cutting support tickets from bad email data over a small dev training investment?’

For Engineering:

*"Problem: Email validation is still a runtime wild west—even with Laravel’s rules, we get user@example slipping through. The new EmailAddress type adds:

• Runtime type enforcement (e.g., EmailAddress::validate() in services).
• Laravel-friendly integration (e.g., typed User model attributes).
• Zero overhead (just 1 new class; no config changes).

Why now?

• Fixes a top-3 bug source in [Project Y]’s auth flow.
• Future-proofs email-heavy features (e.g., multi-factor auth).
• Works with PHPStan for static checks.

Next steps:

1. Spike: Replace custom email validation in [Module Z] with EmailAddress for 1 sprint.
2. Adopt: Update User DTOs to use EmailAddress as a property type.
3. Document: Add examples to our type guidelines.

Risk: None—drop-in replacement for existing validation. If it’s not a fit, we can revert easily.*

Ask: ‘Can we test this in the auth service before the next release?’"*