Skip to content

Commit 4f9ce75

Browse files
eramitguptaeramitgupta
committed
docs: update README and refresh Laravel Boost package guidance
1 parent fa81a26 commit 4f9ce75

3 files changed

Lines changed: 154 additions & 274 deletions

File tree

‎README.md‎

Lines changed: 5 additions & 232 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,14 @@
11
# Laravel Disposable Email Detection
22

3-
4-
<center>
5-
<img width="956" alt="Screenshot 2024-10-04 at 10 34 23 PM" src="https://github.com/user-attachments/assets/6011a887-484f-48a3-8737-de6dfd64e553">
6-
</center>
73
<div align="center">
84

9-
[![Packagist License](https://img.shields.io/badge/Licence-MIT-blue)](https://github.com/eramitgupta/laravel-disposable-email/blob/main/LICENSE)
5+
[![Packagist License](https://img.shields.io/badge/License-MIT-blue)](https://github.com/eramitgupta/laravel-disposable-email/blob/main/LICENSE)
106
[![Latest Stable Version](https://img.shields.io/packagist/v/erag/laravel-disposable-email?label=Stable)](https://packagist.org/packages/erag/laravel-disposable-email)
117
[![Total Downloads](https://img.shields.io/packagist/dt/erag/laravel-disposable-email.svg?label=Downloads)](https://packagist.org/packages/erag/laravel-disposable-email)
128

139
</div>
1410

15-
16-
17-
A Laravel package to detect and block disposable (temporary) email addresses during validation or runtime logic.
11+
Laravel Disposable Email Detection is a Laravel package for detecting and blocking disposable email addresses during validation and runtime checks. It helps protect registrations, lead forms, and application workflows from temporary inbox abuse.
1812

1913
> **Already contains 110,646+ disposable email domains!** 🔥
2014
---
@@ -32,229 +26,8 @@ A Laravel package to detect and block disposable (temporary) email addresses dur
3226
* ✅ **Compatible with Laravel 10, 11, 12, and 13**
3327
---
3428

29+
## Official Documentation
3530

36-
## 🚀 Installation
37-
38-
```bash
39-
composer require erag/laravel-disposable-email
40-
```
41-
42-
## Register the Service Provider
43-
44-
### For Laravel (Optional) v11.x, v12.x, v13.x
45-
46-
Ensure the service provider is registered in your `/bootstrap/providers.php` file:
47-
48-
```php
49-
use EragLaravelDisposableEmail\LaravelDisposableEmailServiceProvider;
50-
51-
return [
52-
// ...
53-
LaravelDisposableEmailServiceProvider::class,
54-
];
55-
```
56-
57-
### For Laravelv v10.x
58-
59-
Ensure the service provider is registered in your `config/app.php` file:
60-
61-
```php
62-
'providers' => [
63-
// ...
64-
EragLaravelDisposableEmail\LaravelDisposableEmailServiceProvider::class,
65-
],
66-
```
67-
68-
---
69-
70-
## 🛠 Configuration
71-
72-
Publish the config file:
73-
74-
```bash
75-
php artisan erag:install-disposable-email
76-
```
77-
78-
This will create `config/disposable-email.php`.
79-
80-
---
81-
82-
## ⚙ Usage
83-
84-
### 1. **Form Request Validation**
85-
86-
#### ✅ String-based Rule:
87-
```php
88-
$request->validate([
89-
'email' => 'required|email|disposable_email',
90-
]);
91-
92-
```
93-
94-
```php
95-
$request->validate([
96-
'email' => ['required', 'email', 'disposable_email'],
97-
]);
98-
```
99-
100-
#### ✅ Custom Rule:
101-
```php
102-
use EragLaravelDisposableEmail\Rules\DisposableEmailRule;
103-
104-
$request->validate([
105-
'email' => ['required', 'email', new DisposableEmailRule()],
106-
]);
107-
```
108-
109-
---
110-
111-
### 2. **Direct Runtime Check**
112-
```php
113-
use EragLaravelDisposableEmail\Rules\DisposableEmailRule;
114-
115-
if (DisposableEmailRule::isDisposable('test@tempmail.com')) {
116-
// Do something if email is disposable
117-
}
118-
```
119-
120-
Or via facade:
121-
```php
122-
use DisposableEmail;
123-
124-
if (DisposableEmail::isDisposable('agedmail.com')) {
125-
// Do something
126-
}
127-
```
128-
129-
---
130-
131-
### 3. **Blade Directive**
132-
133-
```blade
134-
@disposableEmail('amit@0-mail.com')
135-
<p class="text-red-600">Disposable email detected!</p>
136-
@else
137-
<p class="text-green-600">Valid email.</p>
138-
@enddisposableEmail
139-
```
140-
141-
---
142-
143-
144-
## 🔄 Sync From Remote (Optional)
145-
146-
Update the list manually:
147-
148-
```bash
149-
php artisan erag:sync-disposable-email-list
150-
```
151-
152-
### ⏰ Keeping the Domain List Up to Date
153-
154-
This package receives a **weekly** patch release containing updates to the built-in disposable domains list. If you are not able to bump your installed version accordingly, or just want to stay ahead of things, make sure to update the domains list yourself at any interval you like by running or scheduling the `erag:sync-disposable-email-list` command:
155-
156-
```php
157-
// routes/console.php
158-
159-
use Illuminate\Support\Facades\Schedule;
160-
161-
Schedule::command('erag:sync-disposable-email-list')->daily();
162-
```
163-
164-
---
165-
166-
## 🔗 Config Options (config/disposable-email.php)
167-
168-
```php
169-
return [
170-
'blacklist_file' => storage_path('app/blacklist_file),
171-
172-
'remote_url' => [
173-
'https://raw.githubusercontent.com/eramitgupta/disposable-email/main/disposable_email.txt',
174-
],
175-
176-
'cache_enabled' => false,
177-
'cache_ttl' => 60,
178-
];
179-
```
180-
181-
> ✅ **Note:** The `.txt` files from `remote_url` must follow this format:
182-
> Each line should contain **only a domain name**, like:
183-
184-
```
185-
0-00.usa.cc
186-
0-30-24.com
187-
0-attorney.com
188-
0-mail.com
189-
00-tv.com
190-
00.msk.ru
191-
00.pe
192-
00000000000.pro
193-
000728.xyz
194-
000777.info
195-
00082cc.com
196-
00082dd.com
197-
00082ss.com
198-
```
199-
200-
If the file contains anything other than plain domains (like comments or extra data), it may cause parsing issues.
201-
202-
203-
## 🧩 Add Your Own Disposable Domains
204-
205-
> ✅ **Want to block additional disposable domains?**
206-
> You can **easily extend the list manually** — no coding, no command required!
207-
208-
209-
| Step | Action |
210-
|------|--------|
211-
| 🔹 **1** | Go to the following path: <br>**`storage/app/blacklist_file/`** |
212-
| 🔹 **2** | Create or edit this file: <br>**`disposable_domains.txt`** |
213-
| 🔹 **3** | Add your custom domains like:<br>`abakiss.com`<br>`fakemail.org`<br>`trashbox.io`<br>*(one per line)* |
214-
215-
---
216-
217-
> 📌 **Important Notes:**
218-
- Each line must contain **only the domain name** – no extra symbols, no comments.
219-
- The package will **automatically detect and use** the domains from this file.
220-
- You **do not** need to run any Artisan command. 🧙‍♂️
221-
222-
---
223-
224-
### ⚙️ Ensure File Path Matches Configuration
225-
226-
Your file path **must match** the one defined in `config/disposable-email.php`:
227-
228-
```php
229-
'blacklist_file' => storage_path('app/blacklist_file'),
230-
```
231-
232-
If the path or filename is different, the package will **not load** your custom list.
233-
234-
---
235-
236-
## 🧠 Caching Support (Optional)
237-
238-
This package supports **optional caching** to improve performance, especially when dealing with large domain lists.
239-
240-
### 🔧 How It Works
241-
242-
* If **enabled**, the package will cache the compiled list of disposable domains for faster lookup.
243-
* This is useful in high-traffic applications where the same list is accessed frequently.
244-
245-
### 🛠 Enable Caching
246-
247-
To enable caching, update the config file `config/disposable-email.php`:
248-
249-
```php
250-
'cache_enabled' => true,
251-
'cache_ttl' => 60,
252-
```
253-
254-
### 🧹 Clear Cached List
255-
256-
If you manually update the domain list and want to clear the cache, you can use:
31+
Complete documentation for installation, configuration, validation, syncing, caching, and troubleshooting is available at:
25732

258-
```bash
259-
php artisan cache:clear
260-
```
33+
https://eramitgupta.github.io/laravel-disposable-email/

‎resources/boost/skills/disposable-email-detection/SKILL.md‎

Lines changed: 20 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,43 @@
11
---
22
name: disposable-email-detection
3-
description: Build and work with laravel-disposable-email validation, runtime checks, Blade conditionals, config, sync commands, and custom blacklist workflows. Use when adding or updating disposable email validation in Laravel forms, services, middleware, controllers, Blade views, or scheduled tasks.
3+
description: Add and maintain laravel-disposable-email validation, runtime checks, sync flows, scheduling, caching, troubleshooting, and Blade conditionals in Laravel applications. Use when working on forms, Form Requests, APIs, services, middleware, jobs, or custom blacklist workflows.
44
---
55

66
# Laravel Disposable Email Detection
77

8-
Use this skill when a task involves this package's validation rule, facade, Blade directive, install command, sync command, or config.
8+
Use this skill when a task involves the package's validation rule, rule object, facade, Blade conditional, install command, sync command, scheduler setup, config, caching, or blacklist files.
99

1010
## Read First
1111

12-
Read `reference.md` in this folder before making changes. It contains the package API, conventions, and implementation examples that match the package README and source.
12+
Read `reference.md` in this folder before making changes. It mirrors the current package docs and keeps examples aligned with the package API and Laravel usage patterns.
1313

1414
## Working Rules
1515

16-
- Prefer the built-in validation rule name `disposable_email` for standard request validation.
17-
- Use `EragLaravelDisposableEmail\Rules\DisposableEmailRule` when an explicit rule object is clearer.
18-
- Use `EragLaravelDisposableEmail\Support\Email` when the task is about package internals or shared support logic.
19-
- Use `DisposableEmailRule::isDisposable($email)` or the `DisposableEmail` facade for runtime checks.
20-
- Use the `@disposableEmail(...)` Blade conditional for view-only branching.
21-
- Use `php artisan erag:install-disposable-email` to publish config before instructing users to edit `config/disposable-email.php`.
22-
- Use `php artisan erag:sync-disposable-email-list` when the task is about refreshing remote domain lists.
23-
- Put custom domains in the configured blacklist directory as plain domains, one per line.
24-
- If caching is enabled, remember cache invalidation when domain sources change.
16+
- Prefer the built-in validation rule name `disposable_email` for standard request validation in controllers, Form Requests, APIs, and manual validators.
17+
- Use `EragLaravelDisposableEmail\Rules\DisposableEmailRule` when an explicit rule object or direct runtime check is clearer.
18+
- Use the `DisposableEmail` facade when the codebase already favors facade-style package access.
19+
- Use `@disposableEmail(...)` only for Blade branching, not as a replacement for request validation.
20+
- Use `php artisan erag:install-disposable-email` before instructing users to edit `config/disposable-email.php`.
21+
- Use `php artisan erag:sync-disposable-email-list` when the task is about refreshing remote domain lists from configured sources.
22+
- Treat `config('disposable-email.remote_url')` as the source of truth for sync inputs.
23+
- Put custom domains in the configured blacklist directory as plain domains, one per line, in `.txt` files.
24+
- Mention scheduling separately when the user wants automatic syncs. Use Laravel's scheduler with `erag:sync-disposable-email-list`.
25+
- Mention caching separately when the user wants repeated lookups optimized or config changes reflected.
26+
- If caching is enabled, include cache clearing as part of troubleshooting and rollout steps.
2527

2628
## Implementation Notes
2729

2830
- The package registers the string validation rule as `disposable_email`.
2931
- The Blade conditional name is `disposableEmail`.
3032
- The config file is `config/disposable-email.php`.
3133
- The default blacklist directory is `storage/app/blacklist_file`.
32-
- The package accepts plain domains and also strips `user@domain.tld` entries down to their domain when loading local text files.
34+
- Remote sync sources are configured through `remote_url`.
35+
- The package reads every `.txt` file in the configured blacklist directory.
36+
- The package accepts plain domains and also normalizes `user@domain.tld` style entries down to their domain when loading local text files.
3337

3438
## Output Expectations
3539

36-
- Show package-native examples first.
37-
- Keep examples in Laravel style.
40+
- Start with the simplest Laravel-native example, then move to more advanced usage only if needed.
41+
- Keep examples in Laravel style and match current docs terminology: Installation, Configuration, Validation and Runtime, Sync and Blacklist, Schedule Sync, Caching, Troubleshooting.
3842
- When documenting setup, mention the exact Artisan commands exposed by the package.
43+
- If the task is about a bug or package behavior, include the fastest troubleshooting step first.

0 commit comments

Comments
 (0)