[11.x] Document the fluent email Rule validation #10112

SanderMuller · 2025-01-14T21:58:09Z

Documentation for laravel/framework#54067

validation.md

DanielSpravtsev · 2025-01-15T19:42:16Z

Would be great to see some use cases/examples for methods

taylorotwell · 2025-01-15T19:56:36Z

Yeah, explanation of what "strict" compliance means, or what spoofing means would be great! Please mark as ready for review when the requested changes have been made.

shaedrich · 2025-01-15T20:11:37Z

Yeah, explanation of what "strict" compliance means, or what spoofing means would be great! Please mark as ready for review when the requested changes have been made.

A good place might be here, where it's already mentioned:

docs/validation.md

Lines 1213 to 1224 in 8c527b5

    
           The example above will apply the `RFCValidation` and `DNSCheckValidation` validations. Here's a full list of validation styles you can apply: 
        
           <div class="content-list" markdown="1"> 
        
           - `rfc`: `RFCValidation` 
        
           - `strict`: `NoRFCWarningsValidation` 
        
           - `dns`: `DNSCheckValidation` 
        
           - `spoof`: `SpoofCheckValidation` 
        
           - `filter`: `FilterEmailValidation` 
        
           - `filter_unicode`: `FilterEmailValidation::unicode()` 
        
           </div>

shaedrich · 2025-01-15T20:10:50Z

validation.md

@@ -1240,6 +1241,8 @@ The `filter` validator, which uses PHP's `filter_var` function, ships with Larav
 > [!WARNING]  


You might want to link this:

- The `filter` validator, which uses PHP's `filter_var` function, ships with Laravel and was Laravel's default email validation behavior prior to Laravel version 5.8. + The `filter` validator, which uses PHP's [`filter_var` function](https://www.php.net/manual/en/filter.constants.php#constant.filter-validate-email), ships with Laravel and was Laravel's default email validation behavior prior to Laravel version 5.8. [!WARNING]

shaedrich · 2025-01-15T20:14:18Z

validation.md

@@ -1240,6 +1241,8 @@ The `filter` validator, which uses PHP's `filter_var` function, ships with Larav
 > [!WARNING]  
 > The `dns` and `spoof` validators require the PHP `intl` extension.


You could link this:

Suggested change

> The `dns` and `spoof` validators require the PHP `intl` extension.

> The `dns` and `spoof` validators require the [PHP `intl` extension](https://www.php.net/manual/de/book.intl.php).

shaedrich · 2025-01-15T21:11:17Z

Doesn't have #### Defining Default Email Rules an heading level too high? 🤔

SanderMuller · 2025-01-15T22:35:41Z

Would be great to see some use cases/examples for methods

@DanielSpravtsev I've been working on some improvements, could you have a look?

validation.md

shaedrich · 2025-01-16T06:16:54Z

validation.md

  Rule::email()->rfcCompliant(true);
 ```

+- **Addresses that pass `rfcCompliant()` but fail `rfcCompliant(true)`:**


You might have added the - accidentally here:

Suggested change

- **Addresses that pass `rfcCompliant()` but fail `rfcCompliant(true)`:**

**Addresses that pass `rfcCompliant()` but fail `rfcCompliant(true)`:**

shaedrich · 2025-01-16T06:22:38Z

validation.md

@@ -2324,99 +2323,102 @@ Email::defaults(function () {

 ### Use Cases & Examples


This might alternatively be a table:

Method Description Use case example

rfcCompliant(strict: bool) Validates the email according to RFC 5322.
Passing true enforces stricter RFC checks (e.g., rejects [email protected]). Use rfcCompliant() if you need standard RFC validation while allowing some unusual formats.
Use rfcCompliant(true) if you want to reject less typical but technically valid addresses. Basic RFC validation
Rule::email()->rfcCompliant();
Strict RFC validation
Rule::email()->rfcCompliant(true);

…

DanielSpravtsev · 2025-01-16T07:46:17Z

validation.md

+public function boot(): void
+{
+    Email::defaults(function () {
+        $rule = (new Email())->rfcCompliant(strict: true)->preventSpoofing(),


Should be ; instead of , at the end

DanielSpravtsev · 2025-01-16T07:51:33Z

Hey @SanderMuller, thanks for adding more detailed docs! I have a few points of feedback after reviewing the latest updates:

Clarifying rfcCompliant(true) vs. rfcCompliant(false)
- The examples show addresses that pass rfcCompliant() but fail rfcCompliant(true). Could you add just one example that explicitly passes or fails both, showing clearly what “less strict” does vs. “strict”? Right now, the bullet points are good, but a quick “this one fails them both” or “this one passes them both” might help clarify even further.
Extra Emphasis on validateMxRecord()
- The doc says “Requires valid MX record,” but some might not realize that DNS lookups can add latency or external calls—maybe add a small note or footnote like “(this relies on DNS lookups and could fail if domain DNS is temporarily down)”. Just an idea so folks understand potential trade-offs.
withNativeValidation(true) vs. rfcCompliant(true)
- You mention withNativeValidation(true) is less strict than RFC. Maybe add an explicit example showing something like "quoted [email protected]" or “[email protected]” that one method would allow or block. That’ll make it super clear to devs which to choose.

Other than that, everything looks good! Let me know what you think!

validation.md

shaedrich · 2025-01-16T15:11:10Z

validation.md

+});
+```
+
+### Use Cases & Examples


You might want to add a link up there, where the string rule is explained:
#10112 (comment)

SanderMuller · 2025-01-16T22:55:32Z

Hey @SanderMuller, thanks for adding more detailed docs! I have a few points of feedback after reviewing the latest updates:

Clarifying rfcCompliant(true) vs. rfcCompliant(false)

The examples show addresses that pass rfcCompliant() but fail rfcCompliant(true). Could you add just one example that explicitly passes or fails both, showing clearly what “less strict” does vs. “strict”? Right now, the bullet points are good, but a quick “this one fails them both” or “this one passes them both” might help clarify even further.

Extra Emphasis on validateMxRecord()

The doc says “Requires valid MX record,” but some might not realize that DNS lookups can add latency or external calls—maybe add a small note or footnote like “(this relies on DNS lookups and could fail if domain DNS is temporarily down)”. Just an idea so folks understand potential trade-offs.

withNativeValidation(true) vs. rfcCompliant(true)

You mention withNativeValidation(true) is less strict than RFC. Maybe add an explicit example showing something like "quoted [email protected]" or “[email protected]” that one method would allow or block. That’ll make it super clear to devs which to choose.

Other than that, everything looks good! Let me know what you think!

Thanks, I've been working on your feedback/suggestions, can you have a new look?

shaedrich · 2025-01-17T09:20:12Z

Hey @SanderMuller, thanks for adding more detailed docs! I have a few points of feedback after reviewing the latest updates:

Clarifying rfcCompliant(true) vs. rfcCompliant(false)

The examples show addresses that pass rfcCompliant() but fail rfcCompliant(true). Could you add just one example that explicitly passes or fails both, showing clearly what “less strict” does vs. “strict”? Right now, the bullet points are good, but a quick “this one fails them both” or “this one passes them both” might help clarify even further.

Extra Emphasis on validateMxRecord()

The doc says “Requires valid MX record,” but some might not realize that DNS lookups can add latency or external calls—maybe add a small note or footnote like “(this relies on DNS lookups and could fail if domain DNS is temporarily down)”. Just an idea so folks understand potential trade-offs.

withNativeValidation(true) vs. rfcCompliant(true)

You mention withNativeValidation(true) is less strict than RFC. Maybe add an explicit example showing something like "quoted [email protected]" or “[email protected]” that one method would allow or block. That’ll make it super clear to devs which to choose.

Other than that, everything looks good! Let me know what you think!

Thanks, I've been working on your feedback/suggestions, can you have a new look?

Wow, I have to say: Congrats! The table is massively informative 👍🏻

DanielSpravtsev · 2025-01-17T10:27:43Z

validation.md

+| `[email protected]`           | ✅                  | ✅                              | ✅                          | ✅                                            | ✅                      | ✅                     |
+| `té[email protected]`                   | ✅                  | ✅                              | ❌                          | ✅                                            | ✅                      | ✅                     |
+| `user@üñîçødé.com`                   | ✅                  | ✅                              | ❌                          | ❌                                            | ✅                      | ✅                     |
+| `admin@examрle.com` <br>(Cyrillic р) | ✅                  | ✅                              | ✅                          | ✅                                            | ✅                      | ❌                     |


I think it would be helpful to clarify why admin@examрle.com (with Cyrillic р) passes rfcCompliant(strict: true) but fails preventSpoofing(). Since it’s a potentially deceptive address

Because it's a valid email address, just deceptive so potentially unwanted. So the RFC has nothing to do with how. I am not sure how to add these kind of details without making the docs for email validation a book on itself 😄

DanielSpravtsev · 2025-01-17T10:28:32Z

validation.md

+| `test@localhost` <br>(no TLD)        | ✅                  | ❌                              | ❌                          | ❌                                            | ❌                      | ✅                     |
+| `[email protected]`           | ✅                  | ✅                              | ✅                          | ✅                                            | ✅                      | ✅                     |
+| `té[email protected]`                   | ✅                  | ✅                              | ❌                          | ✅                                            | ✅                      | ✅                     |
+| `user@üñîçødé.com`                   | ✅                  | ✅                              | ❌                          | ❌                                            | ✅                      | ✅                     |


Similarly, user@üñîçødé.com is marked as failing withNativeValidation(allowUnicode: true), which seems counterintuitive—shouldn't it pass if Unicode is explicitly allowed?

Similarly, user@üñîçødé.com is marked as failing withNativeValidation(allowUnicode: true), which seems counterintuitive—shouldn't it pass if Unicode is explicitly allowed?

I would've expected it to, but it doesn't. These docs don't determine the behavior but describe it. The table shows why IMO rfcCompliant(strict: true) is a much better choice than withNativeValidation(allowUnicode: true) and I think withNativeValidation all together shouldn't be used, but thats an opinion

I think withNativeValidation all together shouldn't be used, but thats an opinion

There's probably a reason, why this isn't the default anymore.

DanielSpravtsev · 2025-01-17T10:30:46Z

Hey @SanderMuller, thanks for adding more detailed docs! I have a few points of feedback after reviewing the latest updates:

Clarifying rfcCompliant(true) vs. rfcCompliant(false)

The examples show addresses that pass rfcCompliant() but fail rfcCompliant(true). Could you add just one example that explicitly passes or fails both, showing clearly what “less strict” does vs. “strict”? Right now, the bullet points are good, but a quick “this one fails them both” or “this one passes them both” might help clarify even further.

Extra Emphasis on validateMxRecord()

The doc says “Requires valid MX record,” but some might not realize that DNS lookups can add latency or external calls—maybe add a small note or footnote like “(this relies on DNS lookups and could fail if domain DNS is temporarily down)”. Just an idea so folks understand potential trade-offs.

withNativeValidation(true) vs. rfcCompliant(true)

You mention withNativeValidation(true) is less strict than RFC. Maybe add an explicit example showing something like "quoted [email protected]" or “[email protected]” that one method would allow or block. That’ll make it super clear to devs which to choose.

Other than that, everything looks good! Let me know what you think!

Thanks, I've been working on your feedback/suggestions, can you have a new look?

Great improvements, thanks for the updates! I’ve left a couple of comments in the review for clarification.

SanderMuller · 2025-01-17T11:10:07Z

Hi @taylorotwell,

The details for this PR have really been sweated.

Testing the differences between email validation methods and building the matrix required significant testing effort in the framework test suite. These additions have been contributed via laravel/framework#54226.

Let me know if there’s anything else you’d like adjusted or clarified!

validation.md

taylorotwell · 2025-01-17T17:09:42Z

I got this documented. Thanks.

SanderMuller added 2 commits January 14, 2025 22:03

Add Validating Emails docs

3883628

Update validation.md

e7526ed

SanderMuller mentioned this pull request Jan 14, 2025

[11.x] Add fluent Email validation rule laravel/framework#54067

Merged

shaedrich reviewed Jan 15, 2025

View reviewed changes

SanderMuller added 2 commits January 15, 2025 10:28

Apply review feedback

8cad670

Update validation.md

6f7f34e

taylorotwell marked this pull request as draft January 15, 2025 19:56

shaedrich reviewed Jan 15, 2025

View reviewed changes

Update validation.md

a1a541e

SanderMuller added 2 commits January 15, 2025 23:19

Neaten

08e567c

Update validation.md

e4bc18c

shaedrich reviewed Jan 16, 2025

View reviewed changes

DanielSpravtsev reviewed Jan 16, 2025

View reviewed changes

Update validation.md

d85df2b

shaedrich reviewed Jan 16, 2025

View reviewed changes

SanderMuller added 3 commits January 16, 2025 23:27

Update validation.md

8c7a5f6

Update validation.md

4da4cee

Update validation.md

af2f2d5

Update validation.md

10e3baf

SanderMuller mentioned this pull request Jan 17, 2025

[11.x] Solidify Rule::email() tests laravel/framework#54226

Merged

Update validation.md

42445e9

SanderMuller requested a review from DanielSpravtsev January 17, 2025 09:16

DanielSpravtsev reviewed Jan 17, 2025

View reviewed changes

SanderMuller marked this pull request as ready for review January 17, 2025 10:49

Jubeki reviewed Jan 17, 2025

View reviewed changes

validation.md Outdated Show resolved Hide resolved

Update validation.md

d18ecca

SanderMuller changed the title ~~Document the fluent email Rule validation~~ [11.x] Document the fluent email Rule validation Jan 17, 2025

taylorotwell closed this Jan 17, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[11.x] Document the fluent email Rule validation #10112

[11.x] Document the fluent email Rule validation #10112

SanderMuller commented Jan 14, 2025

DanielSpravtsev commented Jan 15, 2025

taylorotwell commented Jan 15, 2025 •

edited

Loading

shaedrich commented Jan 15, 2025 •

edited

Loading

shaedrich Jan 15, 2025

shaedrich Jan 15, 2025

shaedrich commented Jan 15, 2025 •

edited

Loading

SanderMuller commented Jan 15, 2025

shaedrich Jan 16, 2025

shaedrich Jan 16, 2025

DanielSpravtsev Jan 16, 2025

DanielSpravtsev commented Jan 16, 2025

shaedrich Jan 16, 2025

SanderMuller commented Jan 16, 2025

shaedrich commented Jan 17, 2025

DanielSpravtsev Jan 17, 2025

SanderMuller Jan 17, 2025 •

edited

Loading

DanielSpravtsev Jan 17, 2025

SanderMuller Jan 17, 2025

shaedrich Jan 17, 2025

DanielSpravtsev commented Jan 17, 2025

SanderMuller commented Jan 17, 2025

taylorotwell commented Jan 17, 2025

		@@ -1240,6 +1241,8 @@ The `filter` validator, which uses PHP's `filter_var` function, ships with Larav
		> [!WARNING]

		@@ -1240,6 +1241,8 @@ The `filter` validator, which uses PHP's `filter_var` function, ships with Larav
		> [!WARNING]
		> The `dns` and `spoof` validators require the PHP `intl` extension.

	- Addresses that pass `rfcCompliant()` but fail `rfcCompliant(true)`:
	Addresses that pass `rfcCompliant()` but fail `rfcCompliant(true)`:

		@@ -2324,99 +2323,102 @@ Email::defaults(function () {

		### Use Cases & Examples

[11.x] Document the fluent email Rule validation #10112

[11.x] Document the fluent email Rule validation #10112

Conversation

SanderMuller commented Jan 14, 2025

DanielSpravtsev commented Jan 15, 2025

taylorotwell commented Jan 15, 2025 • edited Loading

shaedrich commented Jan 15, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

shaedrich commented Jan 15, 2025 • edited Loading

SanderMuller commented Jan 15, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DanielSpravtsev commented Jan 16, 2025

Choose a reason for hiding this comment

SanderMuller commented Jan 16, 2025

shaedrich commented Jan 17, 2025

Choose a reason for hiding this comment

SanderMuller Jan 17, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

DanielSpravtsev commented Jan 17, 2025

SanderMuller commented Jan 17, 2025

taylorotwell commented Jan 17, 2025

taylorotwell commented Jan 15, 2025 •

edited

Loading

shaedrich commented Jan 15, 2025 •

edited

Loading

shaedrich commented Jan 15, 2025 •

edited

Loading

SanderMuller Jan 17, 2025 •

edited

Loading