PHPackages                             ngfw/dnsdumpster - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. ngfw/dnsdumpster

ActiveLibrary[Utility & Helpers](/categories/utility)

ngfw/dnsdumpster
================

A Laravel package to fetch DNS reconnaissance data from the DNSDumpster API, easily installable via Composer and configurable as a service provider.

1.0.1(1y ago)03MITPHPPHP ^7.4|^8.0CI failing

Since Jan 8Pushed 5mo ago1 watchersCompare

[ Source](https://github.com/ngfw/dnsdumpster)[ Packagist](https://packagist.org/packages/ngfw/dnsdumpster)[ Docs](https://github.com/ngfw/dnsdumpster)[ RSS](/packages/ngfw-dnsdumpster/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (2)Versions (5)Used By (0)

DNSDumpster - Laravel Service Provider
======================================

[](#dnsdumpster---laravel-service-provider)

A Laravel package for fetching and managing DNS reconnaissance data using the DNSDumpster API. This package simplifies integration with the API, enabling you to query domain-related data directly within your Laravel application.

[![Latest Version on Packagist](https://camo.githubusercontent.com/354af8b6c831ffc2df91b75760ef60d5c1a0aff6449610cf2d57c696f0f9bb80/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6e6766772f444e5344756d70737465722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ngfw/DNSDumpster)[![Total Downloads](https://camo.githubusercontent.com/c60b025e5f065f274826bfca958d00bab41dd67c16a1962d3e27363ed1c22a30/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6e6766772f444e5344756d70737465722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ngfw/DNSDumpster)[![StyleCI](https://camo.githubusercontent.com/1ff2f0fafdc9efe93a586ece9823520c3a1397f033dd4beca6e691231df199e9/68747470733a2f2f7374796c6563692e696f2f7265706f732f3931333633313734302f736869656c643f6272616e63683d6d61696e)](https://styleci.io/repos/913631740)

Features
--------

[](#features)

- **Rate Limiting**: Built-in rate limiting (1 request per 2 seconds) to comply with API restrictions
- **Caching**: Optional caching support to reduce API calls and improve performance
- **Retry Logic**: Automatic retry mechanism for failed requests
- **Bulk Lookups**: Support for querying multiple domains at once
- **Custom Exceptions**: Specific exception types for better error handling
- **Logging**: Optional logging support for debugging and monitoring
- **CLI Command**: Artisan command for testing and manual lookups
- **Full Test Coverage**: Comprehensive test suite with PHPUnit
- **Static Analysis**: PHPStan integration for code quality
- **CI/CD**: GitHub Actions workflow for automated testing

Installation
------------

[](#installation)

Install the package using Composer:

```
composer require ngfw/dnsdumpster
```

The package will automatically register the service provider.

Configuration
-------------

[](#configuration)

Publish the configuration file:

```
php artisan vendor:publish --tag=dnsdumpster-config
```

Add the required environment variables to your `.env` file:

```
DNSDumpster_API_KEY=your_api_key
DNSDumpster_API_URL=https://api.dnsdumpster.com
DNSDumpster_ENABLE_LOGGING=false
DNSDumpster_CACHE_ENABLED=true
DNSDumpster_CACHE_TTL=3600
```

You can obtain your key here: [dnsdumpster api](https://dnsdumpster.com/developer/)

**Configuration Options:**

- `DNSDumpster_API_KEY`: Your API key (required)
- `DNSDumpster_API_URL`: The API endpoint URL (required)
- `DNSDumpster_ENABLE_LOGGING`: Enable logging for debugging (optional, default: false)
- `DNSDumpster_CACHE_ENABLED`: Enable caching of API responses (optional, default: true)
- `DNSDumpster_CACHE_TTL`: Cache time-to-live in seconds (optional, default: 3600)

Usage
-----

[](#usage)

### Basic Usage

[](#basic-usage)

Here's how you can fetch domain data using this package:

#### 1. Using Dependency Injection

[](#1-using-dependency-injection)

```
namespace App\Http\Controllers;

use Ngfw\DNSDumpster\DNSDumpster;
use Illuminate\Http\JsonResponse;

class DomainController extends Controller
{
    private DNSDumpster $dnsDumpster;

    public function __construct(DNSDumpster $dnsDumpster)
    {
        $this->dnsDumpster = $dnsDumpster;
    }

    public function lookup(string $domain): JsonResponse
    {
        try {
            $data = $this->dnsDumpster->fetchData($domain);
            return response()->json($data);
        } catch (\Ngfw\DNSDumpster\Exceptions\InvalidDomainException $e) {
            return response()->json(['error' => 'Invalid domain'], 400);
        } catch (\Ngfw\DNSDumpster\Exceptions\RateLimitException $e) {
            return response()->json(['error' => 'Rate limit exceeded'], 429);
        } catch (\Ngfw\DNSDumpster\Exceptions\ApiException $e) {
            return response()->json(['error' => $e->getMessage()], 500);
        }
    }
}
```

#### 2. Using the Facade-like Access

[](#2-using-the-facade-like-access)

```
use Illuminate\Support\Facades\App;

$dnsDumpster = App::make('DNSDumpster');
// or
$dnsDumpster = resolve('DNSDumpster');

// Use the service
$data = $dnsDumpster->fetchData('example.com');
```

#### 3. Using the `app()` Helper

[](#3-using-the-app-helper)

```
$dnsDumpster = app('DNSDumpster');
$data = $dnsDumpster->fetchData('example.com');
```

### Advanced Features

[](#advanced-features)

#### Pagination

[](#pagination)

For domains with more than 200 host records, use pagination to retrieve additional results:

```
$domainInfoPage2 = $dnsDumpster->fetchData('example.com', 2);
```

#### Cache Management

[](#cache-management)

Force refresh data from the API, bypassing cache:

```
$freshData = $dnsDumpster->fetchData('example.com', 1, true);
```

Clear cache for a specific domain:

```
// Clear cache for page 1
$dnsDumpster->clearCache('example.com', 1);

// Clear cache for all pages
$dnsDumpster->clearCache('example.com');
```

#### Bulk Domain Lookups

[](#bulk-domain-lookups)

Query multiple domains at once:

```
$domains = ['example.com', 'google.com', 'github.com'];
$result = $dnsDumpster->fetchBulkData($domains);

// Access successful results
foreach ($result['results'] as $domain => $data) {
    echo "Domain: {$domain}\n";
    print_r($data);
}

// Access errors
foreach ($result['errors'] as $domain => $error) {
    echo "Domain: {$domain} - Error: {$error['error']}\n";
}
```

### CLI Command

[](#cli-command)

Use the Artisan command for quick lookups:

```
# Single domain lookup
php artisan dnsdumpster:lookup example.com

# With pagination
php artisan dnsdumpster:lookup example.com --page=2

# Force refresh (bypass cache)
php artisan dnsdumpster:lookup example.com --force

# Bulk lookup
php artisan dnsdumpster:lookup "example.com,google.com,github.com" --bulk
```

### Exception Handling

[](#exception-handling)

The package provides custom exceptions for better error handling:

- `ConfigurationException`: Thrown when API configuration is missing or invalid
- `InvalidDomainException`: Thrown when an invalid domain is provided
- `RateLimitException`: Thrown when API rate limit is exceeded
- `ApiException`: Thrown when an API request fails

```
use Ngfw\DNSDumpster\Exceptions\ConfigurationException;
use Ngfw\DNSDumpster\Exceptions\InvalidDomainException;
use Ngfw\DNSDumpster\Exceptions\RateLimitException;
use Ngfw\DNSDumpster\Exceptions\ApiException;

try {
    $data = $dnsDumpster->fetchData('example.com');
} catch (InvalidDomainException $e) {
    // Handle invalid domain
} catch (RateLimitException $e) {
    // Handle rate limit
    $statusCode = $e->getCode(); // HTTP 429
} catch (ApiException $e) {
    // Handle API errors
    $statusCode = $e->getStatusCode();
} catch (ConfigurationException $e) {
    // Handle configuration errors
}
```

### Rate Limiting

[](#rate-limiting)

The package includes built-in rate-limiting logic to prevent exceeding the API's limit of 1 request per 2 seconds. This is handled automatically and transparently.

Development
-----------

[](#development)

### Running Tests

[](#running-tests)

```
composer test
```

### Running PHPStan

[](#running-phpstan)

```
composer phpstan
```

### Generating Code Coverage

[](#generating-code-coverage)

```
composer test-coverage
```

API Response Format
-------------------

[](#api-response-format)

The API returns data in the following format:

```
{
  "domain": "example.com",
  "dns_records": {
    "A": ["192.168.1.1"],
    "MX": ["mail.example.com"]
  },
  "host_records": ["www.example.com", "api.example.com"]
}
```

Troubleshooting
---------------

[](#troubleshooting)

### Common Issues

[](#common-issues)

**Rate Limit Exceeded**

- The API enforces a rate limit of 1 request per 2 seconds
- The package automatically handles this with built-in rate limiting
- If you still encounter issues, enable caching to reduce API calls

**Invalid API Key**

- Ensure your API key is set correctly in the `.env` file
- Verify the key is valid at [dnsdumpster.com/developer/](https://dnsdumpster.com/developer/)

**Configuration Not Found**

- Run `php artisan vendor:publish --tag=dnsdumpster-config` to publish the config file
- Ensure environment variables are set correctly

### Debugging

[](#debugging)

Enable logging in your `.env` file:

```
DNSDumpster_ENABLE_LOGGING=true
```

Then check your Laravel logs for detailed information:

```
tail -f storage/logs/laravel.log
```

Changelog
---------

[](#changelog)

Refer to the [CHANGELOG](CHANGELOG.md) for details on recent changes.

Contributing
------------

[](#contributing)

Contributions are welcome! Please see [CONTRIBUTING](CONTRIBUTING.md) for guidelines.

Credits
-------

[](#credits)

- [Nick Gejadze](https://github.com/ngfw)
- [All Contributors](../../contributors)

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT License](LICENSE.md).

###  Health Score

30

—

LowBetter than 64% of packages

Maintenance57

Moderate activity, may be stable

Popularity3

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 72.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

495d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/fd40929eda2ffab2359616a80e7d05b6bacc32dc68203f5938a9da8badde8d37?d=identicon)[gejadze](/maintainers/gejadze)

---

Top Contributors

[![ngfw](https://avatars.githubusercontent.com/u/203863?v=4)](https://github.com/ngfw "ngfw (8 commits)")[![claude](https://avatars.githubusercontent.com/u/81847?v=4)](https://github.com/claude "claude (2 commits)")[![StyleCIBot](https://avatars.githubusercontent.com/u/11048387?v=4)](https://github.com/StyleCIBot "StyleCIBot (1 commits)")

---

Tags

ngfwDNSDumpster

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/ngfw-dnsdumpster/health.svg)

```
[![Health](https://phpackages.com/badges/ngfw-dnsdumpster/health.svg)](https://phpackages.com/packages/ngfw-dnsdumpster)
```

###  Alternatives

[nystudio107/eagerbeaver

Allows you to eager load elements from auto-injected Entry elements on demand from your templates.

251.5k](/packages/nystudio107-eagerbeaver)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)