{"id":51549391,"url":"https://github.com/eyupfidan/whois-scope","last_synced_at":"2026-07-09T22:30:27.282Z","repository":{"id":364158577,"uuid":"1263369325","full_name":"eyupfidan/whois-scope","owner":"eyupfidan","description":"Open-source WHOIS lookup platform with REST API and Vue.js UI. Single \u0026 bulk domain queries, caching, rate limiting, registration status, CSV export. Built with Laravel 13. MIT licensed.","archived":false,"fork":false,"pushed_at":"2026-06-11T22:14:06.000Z","size":458,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T23:10:15.758Z","etag":null,"topics":["bulk-lookup","caching","ddd","ddd-architecture","domain-lookup","domain-registration","laravel","open-source","openapi","php","rate-limiting","rest-api","self-hosted","tailwindcss","vite","vuejs","whois","whois-api"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eyupfidan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-08T22:22:48.000Z","updated_at":"2026-06-11T22:14:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/eyupfidan/whois-scope","commit_stats":null,"previous_names":["eyupfidan/whois-scope"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/eyupfidan/whois-scope","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eyupfidan%2Fwhois-scope","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eyupfidan%2Fwhois-scope/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eyupfidan%2Fwhois-scope/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eyupfidan%2Fwhois-scope/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eyupfidan","download_url":"https://codeload.github.com/eyupfidan/whois-scope/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eyupfidan%2Fwhois-scope/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35314872,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-09T02:00:07.329Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bulk-lookup","caching","ddd","ddd-architecture","domain-lookup","domain-registration","laravel","open-source","openapi","php","rate-limiting","rest-api","self-hosted","tailwindcss","vite","vuejs","whois","whois-api"],"created_at":"2026-07-09T22:30:24.762Z","updated_at":"2026-07-09T22:30:27.273Z","avatar_url":"https://github.com/eyupfidan.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/readme-banner.png\" alt=\"WhoisScope — Fast WHOIS lookup API and web app\" width=\"900\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"MIT License\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/PHP-8.3%2B-777BB4?logo=php\u0026logoColor=white\" alt=\"PHP 8.3+\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Laravel-13-FF2D20?logo=laravel\u0026logoColor=white\" alt=\"Laravel 13\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Vue.js-3-4FC08D?logo=vuedotjs\u0026logoColor=white\" alt=\"Vue 3\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Tailwind-4-06B6D4?logo=tailwindcss\u0026logoColor=white\" alt=\"Tailwind CSS 4\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Architecture-DDD-4338ca\" alt=\"Domain-Driven Design\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eWhoisScope\u003c/strong\u003e is an open-source WHOIS lookup platform built with Laravel and Vue.js.\u003cbr\u003e\n  Use it as a \u003cstrong\u003eREST API\u003c/strong\u003e, a \u003cstrong\u003efull-stack web app\u003c/strong\u003e, or both — with caching, rate limiting, bulk queries, and a multilingual UI.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-quick-start\"\u003eQuick Start\u003c/a\u003e ·\n  \u003ca href=\"#-features\"\u003eFeatures\u003c/a\u003e ·\n  \u003ca href=\"#-api-reference\"\u003eAPI\u003c/a\u003e ·\n  \u003ca href=\"#-configuration\"\u003eConfiguration\u003c/a\u003e ·\n  \u003ca href=\"#-architecture\"\u003eArchitecture\u003c/a\u003e ·\n  \u003ca href=\"LICENSE\"\u003eLicense\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Overview\n\nWhoisScope lets you look up domain registration data through a clean web interface or a versioned JSON API. It parses raw WHOIS responses, detects whether a domain is **registered**, **available**, or **unknown**, and returns structured fields such as registrar, creation date, expiry date, and status codes.\n\nThe project follows **Domain-Driven Design (DDD)** so business rules stay independent from Laravel, the WHOIS library, and the Vue frontend.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/icon.png\" alt=\"WhoisScope icon\" width=\"96\" height=\"96\"\u003e\n\u003c/p\u003e\n\n| Mode | Best for |\n|------|----------|\n| **Web UI** | Manual lookups, bulk CSV export, exploring results |\n| **REST API** | Integrations, scripts, backend services |\n| **API + UI** | Self-hosted product with built-in documentation at `/docs` |\n\n---\n\n## ✨ Features\n\n| Feature | Description |\n|---------|-------------|\n| 🔍 **Single lookup** | Query one domain with `summary` or `full` response format |\n| 📦 **Bulk lookup** | Up to 50 domains per request, parallel processing, per-domain status |\n| ⚡ **Smart cache** | Results cached by default (1 hour); repeat queries are near-instant |\n| 🛡️ **Rate limiting** | Per-IP limits on single and bulk endpoints |\n| 🌍 **Multilingual UI** | 7 languages in the web interface |\n| 📄 **CSV export** | Download bulk results from the web UI |\n| 🎯 **Registration status** | `registered`, `available`, `unknown`, or `error` per domain |\n| 📚 **Built-in API docs** | Interactive reference at `/docs` |\n| 🔓 **MIT licensed** | Free for personal and commercial use |\n\n---\n\n## 🚀 Quick Start\n\n### Requirements\n\n| Tool | Version |\n|------|---------|\n| PHP | 8.3 or higher |\n| Composer | 2.x |\n| Node.js | 20+ (for frontend build) |\n| SQLite | Included (default) or MySQL/PostgreSQL |\n\n### Installation\n\n```bash\ngit clone https://github.com/your-org/whois-api.git\ncd whois-api\n\ncomposer install\ncp .env.example .env\nphp artisan key:generate\nphp artisan migrate\n\nnpm install\nnpm run build\n```\n\n### Run locally\n\n**Option A — Full stack (recommended for first run)**\n\n```bash\n# Terminal 1\nphp artisan serve\n\n# Terminal 2\nnpm run dev\n```\n\nOpen **[http://localhost:8000](http://localhost:8000)**\n\n| Page | URL |\n|------|-----|\n| Home (lookup UI) | `/` |\n| API documentation | `/docs` |\n\n**Option B — API only**\n\n```bash\nphp artisan serve\n```\n\nThe API works without building the frontend. Endpoints are available under `/api/v1/whois/*`.\n\n**Option C — One command (dev)**\n\n```bash\ncomposer dev\n```\n\nRuns the PHP server, queue worker, logs, and Vite dev server together.\n\n---\n\n## 🖥️ Web Interface\n\nThe UI includes two tabs:\n\n1. **Domain Whois** — single domain lookup with summary/full format\n2. **Bulk Whois** — paste up to 50 domains (one per line or comma-separated), view accordion results, export CSV\n\nSupported interface languages:\n\n| Code | Language |\n|------|----------|\n| `en` | English *(default)* |\n| `tr` | Türkçe |\n| `es` | Español |\n| `fr` | Français |\n| `pt` | Português |\n| `zh` | 中文 |\n| `ar` | العربية |\n\n---\n\n## 📡 API Reference\n\nBase URL: `http://localhost:8000/api/v1/whois`\n\n### Endpoints\n\n| Method | Endpoint | Rate limit | Description |\n|--------|----------|------------|-------------|\n| `GET` | `/whois/{domain}` | 60/min per IP | Single domain lookup |\n| `POST` | `/whois/bulk` | 10/min per IP | Bulk domain lookup |\n\n### Query / body parameters\n\n| Parameter | Location | Values | Default |\n|-----------|----------|--------|---------|\n| `format` | query or JSON body | `summary`, `full` | `summary` |\n| `domains` | JSON body (bulk only) | array of strings, max 50 | — |\n\n### Response formats\n\n**`summary`** — essential fields:\n\n`domain`, `registration_status`, `registrar`, `created_at`, `expires_at`, `states`\n\n**`full`** — all parsed fields plus raw WHOIS text:\n\n`whois_server`, `owner`, `updated_at`, `name_servers`, `dnssec`, `raw`, …\n\n### Single lookup example\n\n```bash\ncurl -s \"http://localhost:8000/api/v1/whois/google.com?format=summary\" | jq\n```\n\n```json\n{\n  \"data\": {\n    \"domain\": \"google.com\",\n    \"registration_status\": \"registered\",\n    \"registrar\": \"MarkMonitor Inc.\",\n    \"created_at\": \"1997-09-15T04:00:00+00:00\",\n    \"expires_at\": \"2028-09-14T04:00:00+00:00\",\n    \"states\": [\"client delete prohibited\", \"client transfer prohibited\"]\n  }\n}\n```\n\n### Bulk lookup example\n\n```bash\ncurl -s -X POST \"http://localhost:8000/api/v1/whois/bulk\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"domains\": [\"google.com\", \"this-domain-is-free-xyz123.com\"],\n    \"format\": \"summary\"\n  }' | jq\n```\n\n```json\n{\n  \"format\": \"summary\",\n  \"results\": [\n    {\n      \"domain\": \"google.com\",\n      \"status\": \"registered\",\n      \"data\": { \"domain\": \"google.com\", \"registration_status\": \"registered\", \"...\": \"...\" }\n    },\n    {\n      \"domain\": \"this-domain-is-free-xyz123.com\",\n      \"status\": \"available\",\n      \"data\": { \"domain\": \"this-domain-is-free-xyz123.com\", \"registration_status\": \"available\", \"...\": \"...\" }\n    }\n  ]\n}\n```\n\n### Bulk result statuses\n\n| Status | Meaning |\n|--------|---------|\n| `registered` | Domain has active WHOIS registration data |\n| `available` | Domain appears unregistered / available |\n| `unknown` | WHOIS response could not be classified confidently |\n| `error` | Lookup failed (invalid domain, timeout, server error) |\n\n### Error responses\n\nErrors return JSON with `message` and `code`:\n\n| HTTP | Code | Typical cause |\n|------|------|----------------|\n| `422` | `invalid_domain` | Malformed domain name |\n| `429` | `too_many_requests` | Rate limit exceeded |\n| `502` | `lookup_failed` | WHOIS server unreachable or TLD unsupported |\n| `500` | `server_error` | Unexpected server error |\n\n---\n\n## ⚙️ Configuration\n\nAll WHOIS-related settings live in `.env` and `config/whois.php`.\n\n```env\n# Timeouts (seconds)\nWHOIS_TIMEOUT=8\nWHOIS_CONNECT_TIMEOUT=3\n\n# Bulk\nWHOIS_BULK_LIMIT=50\nWHOIS_BULK_CONCURRENCY=5\nWHOIS_BULK_MAX_EXECUTION=300\n\n# Cache\nWHOIS_CACHE_ENABLED=true\nWHOIS_CACHE_TTL=3600\n\n# Rate limits (requests per minute, per IP)\nWHOIS_RATE_LIMIT=60\nWHOIS_BULK_RATE_LIMIT=10\n\n# Laravel cache driver — use redis in production for best performance\nCACHE_STORE=database\n```\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `WHOIS_TIMEOUT` | `8` | Max seconds to read WHOIS server response |\n| `WHOIS_CONNECT_TIMEOUT` | `3` | Max seconds to open TCP connection (port 43) |\n| `WHOIS_BULK_CONCURRENCY` | `5` | Parallel lookups during bulk requests |\n| `WHOIS_BULK_LIMIT` | `50` | Max domains per bulk request |\n| `WHOIS_CACHE_TTL` | `3600` | Cache lifetime in seconds (1 hour) |\n| `WHOIS_RATE_LIMIT` | `60` | Single lookup requests per minute per IP |\n| `WHOIS_BULK_RATE_LIMIT` | `10` | Bulk requests per minute per IP |\n\n\u003e **Tip:** For production, set `CACHE_STORE=redis` and keep `WHOIS_CACHE_ENABLED=true`. Cached lookups typically respond in ~1 ms.\n\nCustom WHOIS servers for specific TLDs can be added in `config/whois.php` under `custom_servers`.\n\n---\n\n## 🏗️ Architecture\n\nWhoisScope uses a layered DDD structure:\n\n```mermaid\nflowchart TB\n    subgraph Presentation\n        UI[Vue 3 Web UI]\n        API[Laravel API Controllers]\n    end\n\n    subgraph Application\n        UC1[LookupWhoisUseCase]\n        UC2[BulkLookupWhoisUseCase]\n    end\n\n    subgraph Domain\n        ENT[WhoisRecord]\n        VO[Value Objects]\n        REPO_IF[WhoisRepositoryInterface]\n    end\n\n    subgraph Infrastructure\n        CACHE[CachedWhoisRepository]\n        PHP[PhpWhoisRepository]\n        LIB[io-developer/php-whois]\n    end\n\n    UI --\u003e API\n    API --\u003e UC1 \u0026 UC2\n    UC1 \u0026 UC2 --\u003e REPO_IF\n    REPO_IF --\u003e CACHE\n    CACHE --\u003e PHP\n    PHP --\u003e LIB\n    PHP --\u003e ENT\n```\n\n### Directory layout\n\n```\napp/\n├── Domain/Whois/              # Entities, value objects, domain services, exceptions\n├── Application/Whois/         # Use cases, DTOs, application services\n├── Infrastructure/Whois/      # php-whois adapter, cache decorator, socket loader\n├── Http/                      # Controllers, form requests, API resources\n└── Providers/                 # DI bindings, rate limiters\n\nresources/js/                  # Vue 3 SPA (router, i18n, components)\nroutes/\n├── api.php                    # /api/v1/whois/*\n└── web.php                    # SPA catch-all\n```\n\n### Request flow (single lookup)\n\n```mermaid\nsequenceDiagram\n    participant Client\n    participant API as WhoisController\n    participant UC as LookupWhoisUseCase\n    participant Cache as CachedWhoisRepository\n    participant WHOIS as PhpWhoisRepository\n    participant Server as WHOIS Server :43\n\n    Client-\u003e\u003eAPI: GET /api/v1/whois/example.com\n    API-\u003e\u003eUC: execute(domain)\n    UC-\u003e\u003eCache: lookup(domain)\n    alt cache hit\n        Cache--\u003e\u003eUC: WhoisRecord\n    else cache miss\n        Cache-\u003e\u003eWHOIS: lookup(domain)\n        WHOIS-\u003e\u003eServer: TCP WHOIS query\n        Server--\u003e\u003eWHOIS: raw text\n        WHOIS--\u003e\u003eCache: WhoisRecord\n        Cache--\u003e\u003eUC: WhoisRecord\n    end\n    UC--\u003e\u003eAPI: WhoisRecord\n    API--\u003e\u003eClient: JSON response\n```\n\n---\n\n## 🧪 Tests\n\n```bash\nphp artisan test\n```\n\nThe test suite covers API responses, caching, rate limiting, and registration status detection.\n\n---\n\n## 📦 Tech Stack\n\n\u003cp\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Laravel-13-FF2D20?logo=laravel\u0026logoColor=white\" alt=\"Laravel\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Vue-3-4FC08D?logo=vuedotjs\u0026logoColor=white\" alt=\"Vue\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Vite-8-646CFF?logo=vite\u0026logoColor=white\" alt=\"Vite\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Tailwind-4-06B6D4?logo=tailwindcss\u0026logoColor=white\" alt=\"Tailwind\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/php--whois-4.1-777BB4?logo=php\u0026logoColor=white\" alt=\"php-whois\"\u003e\n\u003c/p\u003e\n\n| Layer | Technology |\n|-------|------------|\n| Backend | Laravel 13, PHP 8.3+ |\n| WHOIS library | [io-developer/php-whois](https://github.com/io-developer/php-whois) |\n| Frontend | Vue 3, Vue Router, Tailwind CSS 4, Vite 8 |\n| Cache | Laravel Cache (database, file, or Redis) |\n| Database | SQLite by default |\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome. Please open an issue or pull request. By contributing, you agree that your code will be released under the [MIT License](LICENSE).\n\n---\n\n## 📄 License\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"MIT License\"\u003e\n\u003c/p\u003e\n\nWhoisScope is open source software licensed under the **[MIT License](LICENSE)**.\n\nYou may use, copy, modify, merge, publish, distribute, sublicense, and sell copies of the software — for personal or commercial projects — as long as the license notice is included.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/icon.png\" alt=\"\" width=\"32\" height=\"32\"\u003e\n  \u003cbr\u003e\n  \u003csub\u003eBuilt with Laravel \u0026 Vue · MIT Licensed\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feyupfidan%2Fwhois-scope","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feyupfidan%2Fwhois-scope","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feyupfidan%2Fwhois-scope/lists"}