Download the PHP package mnb/scraperkit without Composer
On this page you can find all versions of the php package mnb/scraperkit. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download mnb/scraperkit
More information about mnb/scraperkit
Files in mnb/scraperkit
Package scraperkit
Short Description MNB ScraperKit V1.0.3 - enterprise-ready PHP crawling and data extraction framework with AI crawl intelligence, search discovery, authorized mail/webmail extraction connectors, publisher metadata workflows, extraction recipes, provenance, quality reports, datasets, queues, dashboards, and compliance tooling.
License MIT
Informations about the package scraperkit
MNB ScraperKit v1.0.5
MNB ScraperKit is a PHP-first professional crawling and data extraction framework for safe, resumable, pipeline-based web scraping.
v1.0.5 improves common-data extraction validation. It keeps the public v1.0.x feature set stable while reducing false positives in human-name, address/location, and application/registration-number extraction on catalog/listing pages such as publisher journal indexes.
ScraperKit is designed for developers, SEO analysts, research teams, academic metadata collectors, ecommerce monitors, tender/job/government data teams, and server automation users who need safe CLI crawling, bulk jobs, resumable checkpoints, normalized records, validation, transformations, exports, and reports.
Installation
MNB ScraperKit is available on Packagist as the Composer package mnb/scraperkit.
Requirements: PHP >=8.2, Composer, and the PHP extensions listed in composer.json.
Install with:
This is the recommended install method for normal users.
Simple install
Windows CMD
Windows PowerShell
Linux/macOS/Git Bash
Verify installation
Show available commands:
On Windows CMD:
On PowerShell:
Run a basic crawl test:
On Windows CMD:
Use in a PHP file
After installing with Composer, create an index.php file in your project root.
Run it from the command line:
Or place it in your local web root and open it through your browser, for example with XAMPP:
PHP extraction rules example
You can pass extraction rules as the third argument to crawl():
A copy-ready example is available at:
Install a specific version
Install the latest stable 1.x release:
Install an exact release:
Development install from source
Use this when you want to work on MNB ScraperKit itself:
Run readiness checks:
Advanced fallback: install directly from GitHub
Most users should use:
Use the GitHub VCS method only if you need the latest main branch before a tagged release is available on Packagist, or if you are testing unreleased changes.
Windows CMD
Windows PowerShell
Linux/macOS/Git Bash
Source ZIP quick check without Composer dependencies
Source zip users can run basic diagnostics before Composer dependencies are installed. The public binary falls back to the native CLI when Symfony Console is not available:
This fallback is intended for onboarding, source-archive smoke tests, and offline QA examples. Install Composer dependencies for the full Symfony Console experience and third-party integration paths.
Troubleshooting Composer install
Error: Could not find a matching version of package mnb/scraperkit
Try clearing Composer cache and installing again:
Also check that the package is visible to Composer:
If Packagist has not updated yet, open the package page on Packagist and trigger an update, then retry the install.
Error: File "./composer.json" cannot be found
This only applies to the advanced GitHub VCS install method. Create a project first:
Then add the VCS repository and require the development branch.
Error: You have to run this command in interactive mode, or specify at least some data
Use this instead of plain composer init --no-interaction:
Error: Could not open input file: vendor/bin/mnb-scraper
The package was not installed, so the vendor binary was not created. Fix the Composer install first. On Windows after a successful install, prefer:
Quick start
Crawl one page:
Run a small safe crawl:
Run crawl plus professional pipeline:
Run the professional pipeline on an existing crawl JSON file:
What makes it different
Most PHP scraping tools focus on fetching HTML and extracting selectors. MNB ScraperKit is designed around a complete professional crawl flow:
The strongest part of the library is the professional crawl pipeline. It turns crawled pages into structured records with metadata, validation status, quality scoring, deduplication keys, failed URL handling, and export-ready output.
v1.0.5 validation hotfix focus
v1.0.5 improves the generic common-data extractor so broad catalog/index pages do not pollute structured fields. Journal and publication titles remain available as generic names, while person_names is now reserved for likely human names. Address/location extraction now avoids UI/legal text such as privacy statements and requires stronger address/location signals. Application and registration number extraction now requires real identifier structure and no longer treats word fragments such as Applicandae or Applied as numbers.
v1.0.3 patch release focus
v1.0.3 adds practical ML crawl techniques while keeping the package dependency-light and safe by default. The ML layer is deterministic and local: it learns from positive/negative URL examples and human feedback, scores candidate URLs, and creates budgeted adaptive crawl plans with exploration and diversity controls.
- Added
ml:strategiesfor safe ML crawl strategy discovery. - Added
ml:trainfor lightweight URL relevance model training from positive/negative examples or feedback. - Added
ml:scorefor scoring candidate URLs before crawling. - Added
ml:adaptive-planfor budgeted crawl plans using priority score, ML relevance, diversity, and exploration. - Added
ml:feedbackfor manual relevance feedback loops. - Added
ml:export-trainingfor JSON/JSONL ML-ready URL feature datasets. - Added ML examples and Windows CMD/PowerShell helper scripts.
- Kept existing safety posture: ML prioritizes crawl order only; it does not bypass robots, paywalls, CAPTCHAs, authentication, or access controls.
Highlights
- Hardening and production readiness with CI workflow, release hygiene checks, public command compatibility validation, local benchmarks, improved error guidance, and duplicate command dispatch checks.
- Enterprise project workspaces and access control metadata for local/team project organization, user roles, workspace membership, audit events, and dashboard/API summaries without storing passwords.
- Professional PHP CLI framework built as a Composer package with Symfony Console commands.
- Security audit and compliance toolkit for release hygiene, secret scanning, responsible crawling policy checks, browser-session safety review, plugin/config checks, and JSON/HTML compliance reports.
- Project templates and preset packs for ready-to-run SEO, ecommerce, academic, tender, and research workflows with generated command files and job manifests.
- Advanced export connectors for local artifact delivery, webhook payload automation, checksum manifests, connector validation, and downstream workflow handoff.
- Distributed workers and optional Redis queue with adapter auto-selection, file fallback, job leases, heartbeats, distributed worker loops, and multi-worker deployment support.
- Advanced browser sessions for authorized workflows with allowed-domain session profiles, manual login assist, cookie/session artifacts, session tests, and
--sessioncrawl support. - Rule builder and auto-profile assistant for analyzing HTML, suggesting profile types, generating starter schemas, testing rules, scaffolding profiles, and finding rule gaps.
- Evaluation, benchmarking, and training data quality layer for field completeness, validation health, duplicate analysis, profile benchmarking, selector performance, annotation coverage, and training-ready exports.
- Dataset versioning and annotation layer for dataset snapshots, quality summaries, JSON/CSV/JSONL exports, dataset diffs, and review labels.
- ML-ready intelligence layer for feature extraction, page classification, quality prediction, URL priority scoring, selector suggestions, relevance learning, feedback loops, and adaptive crawl planning.
- Local dashboard and admin UI for queue jobs, schedules, workers, profiles, plugins, API routes, and system health.
- Plugin system for config-only add-ons with reusable profile schemas, extractor rule files, source templates, export templates, command aliases, validation, install, enable/disable, and doctor checks.
- Advanced retry, scheduling, and monitoring with safe retry plans, local schedules, due-job enqueueing, health summaries, and stale lock diagnostics.
- Optional database storage layer using PDO with SQLite and MySQL/MariaDB support for jobs, pages, records, failures, validation issues, and export metadata.
- Optional browser-assisted crawling for JavaScript-heavy pages using
--browser=autoor--browser=always, with optional rendered HTML and screenshot artifacts. - Queue and worker commands for local file-based job automation, worker loops, job pause/resume/cancel, safe failed queue retry, and worker locks.
- Safe crawling controls including URL safety checks, redirect safety, scope rules, robots-aware behavior, userinfo blocking, URL length limits, and private/reserved IP protection.
- Bulk crawling support for processing many URLs with pacing, random jitter, cooldowns, checkpointing, failed queues, skipped queues, and resume support.
- Manifest-driven jobs for reproducible crawl configuration, including input URLs, scope, pacing, extraction profile, output settings, and resume state.
- Professional crawl pipeline that converts raw page results into normalized records with metadata, validation, deduplication, transformation, quality scoring, and exports.
- Profile schemas and extractor rules for reusable field definitions, validators, transformations, dedupe keys, export columns, CSS/XPath/meta/JSON-LD/Open Graph extraction, and fallback selectors.
- Common data profiles for academic, journal, conference, ecommerce, government, tender, jobs, SEO, contact, and document-focused extraction workflows.
- Professional exports and reports including JSON, CSV, XML, HTML summaries, failed URL reports, validation issue reports, and ZIP project bundles.
- Automation friendly for PHP CLI, CMD, PowerShell, cron, Windows Task Scheduler, and server-side workflows.
- Source connector system for collecting crawl targets from sitemaps, RSS/Atom feeds, CSV files, JSON files, generic JSON APIs, PLOS, and Elsevier/ScienceDirect.
- Future-ready architecture designed for later expansion into richer dashboards, advanced browser-worker orchestration, role-based access, and trainable ML models.
Complete feature list
This section lists the main functionality available in the current V1.0.3 CLI/library release.
Package and CLI
- Composer-installable PHP package with PSR-4 autoloading.
- Symfony Console based command-line application.
- Reusable framework-independent PHP core classes.
- Global binary support through
vendor/bin/mnb-scraper. - Built-in command list and per-command help screens.
- CMD, PowerShell, cron, Windows Task Scheduler, and server automation friendly scripts/workflows.
Production readiness and hardening
hardening:doctorruns production-readiness diagnostics for CI, release hygiene, command contracts, duplicate dispatch cases, optional runtimes, storage cleanliness, and backward compatibility posture.ci:checkruns strict repo/CI checks without failing just because Composer installedvendor/locally.release:check [archive-dir]runs final package checks and fails if the archive includesvendor/,.git/,composer.lock, or generatedstorage/outputs.benchmark:runruns deterministic local micro-benchmarks without network calls.compat:commandsprints or validates the public command and option compatibility contract..github/workflows/ci.ymlvalidates Composer metadata, installs dependencies, lints PHP files, runs tests, runsci:check, builds agit archive, runsrelease:checkon that archive, and performs a benchmark smoke test on PHP 8.2, 8.3, and 8.4.- CLI errors now include command context, help guidance, and diagnostics hints. Unknown commands include best-effort suggestions.
- V1.0.3 keeps the hardening trait boundary and fixes native CLI option parsing; future maintenance releases can continue splitting command groups.
Examples:
Backward compatibility policy
- Patch releases such as V1.0.3 should not remove public commands, rename public options, or change default output behavior without a compatibility alias.
- Minor releases may add new commands, options, profiles, connectors, and optional integrations while keeping older workflows usable.
- Major releases may remove deprecated functionality only after migration guidance is added to README examples and command compatibility notes.
Academic publisher metadata crawling
V1.0.3 adds safe publisher metadata workflows for academic journal/article discovery. The default model is metadata only: prefer official APIs, public sitemaps, RSS/Atom feeds, DOI/Crossref-style metadata, and public article landing pages. Do not bypass paywalls, CAPTCHAs, authentication, or access controls.
Commands:
Included catalog:
The normalized article metadata schema covers title, subtitle, authors, DOI, normalized DOI, ISSN/eISSN, journal, publisher, volume, issue, page range, publication date, article type, abstract, URL, HTML/PDF URL, license, open-access marker, source, and quality score.
Enterprise project workspaces and access control
enterprise:doctorshows workspace, user, role, and audit readiness.enterprise:rolesprints the built-in role capability map.workspace:create <name>creates a local project workspace manifest.workspace:listlists project workspaces.workspace:show <workspace>shows one workspace manifest.workspace:assign-user <workspace> <user> --role=operatorassigns a user to a workspace.user:create <user>creates a local user metadata record without storing passwords.user:listlists user metadata records.user:disable <user>disables a user metadata record.audit:eventslists recent enterprise audit events.- Workspace files live under
storage/enterprise/workspaces/. - User metadata lives in
storage/enterprise/users.json. - Audit events live in append-only JSONL form under
storage/enterprise/audit-events.jsonl. - Read-only API routes expose enterprise summary, workspaces, users, and audit events for dashboard/internal automation.
Example:
Security audit and compliance toolkit
security:auditruns a package/project audit for release hygiene, secrets, config validity, browser sessions, plugins, generated storage files, and public API/dashboard surfaces.security:doctorprints a concise security score and recommended actions.security:secrets-scanscans local files for common committed secret patterns.security:policyprints or writes a responsible crawling policy template.compliance:reportgenerates JSON or HTML compliance output for maintainers, internal teams, and release reviews.config/compliance-policy.example.jsondocuments safe defaults for responsible crawling, release hygiene, and secret handling.- API routes expose read-only security/compliance summaries for local admin/dashboard integrations.
Example:
Project templates and preset packs
template:listlists bundled project templates.template:show <template>displays one template manifest and generated file plan.template:validate <template>validates template JSON and generated file paths.template:create <template> --output-dir=projects/name --name=namecreates a ready-to-run project workspace.preset:listlists bundled preset packs.preset:show <pack>displays grouped profiles, templates, and workflow files.preset:validate <pack>checks referenced profiles and templates.preset:install <pack> --output-dir=presets/nameinstalls a preset pack into a local project folder.- Bundled project templates include
seo-audit,ecommerce-monitor,academic-metadata, andtender-monitor. - Bundled preset packs include
seo-research-packandcommerce-gov-pack.
Distributed workers and Redis queue
distributed:doctorchecks selected adapter, Redis availability, queue namespace, worker group, and file fallback status.distributed:statusshows pending, leased, completed, and failed distributed queue counts.distributed:enqueue --command=crawl --arg=https://example.comadds one command payload to the distributed queue.distributed:reservereserves one job for debugging worker leases.distributed:ack <job-id>marks a leased job as completed.distributed:fail <job-id>marks a leased job as failed with a message.distributed:heartbeat <job-id>refreshes a job lease heartbeat.distributed:purge --forceclears distributed queue state for local/dev cleanup.worker:distributedruns distributed jobs using Redis when configured, or the file adapter fallback otherwise.- Distributed jobs use worker IDs, lease IDs, visibility timeouts, and heartbeats so crashed workers can be recovered.
- Redis is optional. Use
--distributed-adapter=filefor local fallback or--distributed-adapter=redis --redis-url=redis://127.0.0.1:6379/0for Redis.
Example:
Redis example:
Advanced export connectors
export:connector-listlists configured export delivery connectors.export:connector-show <connector-id>shows one connector definition.export:connector-validatechecks connector IDs, types, local target paths, and webhook endpoints.export:connector-test <connector-id>creates a sample artifact and dry-runs the connector.export:manifest <file|dir>builds a checksum manifest with size, extension, SHA-256, and modified time.export:deliver <connector-id> --file=records.json --file=report.htmldelivers selected artifacts.- Local connectors copy artifacts into a delivery folder with
delivery-manifest.json. - Webhook connectors create a JSON payload and only send when
--sendis explicitly used. - Connector configuration is stored in
config/export-connectors.json; a safe example is provided inconfig/export-connectors.example.json.
Example:
Advanced browser sessions and authorized login workflows
browser:session-create <name> --domain=example.com --login-url=https://example.com/logincreates a domain-guarded browser session profile.browser:session-listlists stored session profiles and cookie/session files.browser:session-show <name>shows one session profile and its safety metadata.browser:session-clear <name>removes session cookies and artifacts; add--remove-profileto remove the profile too.browser:login <name> --url=https://example.com/loginwrites manual login instructions and prepares the session for an authorized login flow.browser:session-test <name> <url> --rendertests a session against an allowed URL using the optional browser adapter.crawl <url> --browser=auto --session=<name>uses the session profile during browser fallback or browser rendering.- Session profiles require allowed domains and block URLs outside that allowlist.
- Passwords are not stored by default. Session files are intended for authorized, user-controlled workflows only.
- Cookie import/export is best-effort and depends on the optional browser adapter/driver support. Normal HTTP crawling still works without browser dependencies.
Example:
Rule builder and auto-profile assistant
rule:analyze <html-file|url>inspects saved HTML or one URL and reports title, metadata, headings, JSON-LD types, keyword signals, candidate selectors, and suggested profile type.rule:generate <html-file|url> --profile=auto --name=my-profile --output=config/profiles/my-profile.jsoncreates a starter profile schema.rule:test <html-file|url> --profile=my-profiletests existing/generated extraction rules locally before running a crawl.rule:doctor <profile|profile.json> --input=sample.htmlchecks profile schema validity, missing required-field rules, undeclared rule fields, and sample extraction gaps.profile:scaffold <name> --profile=seo|ecommerce|jobs|tender|academiccreates a new profile schema template.- Auto-profile suggestions currently target SEO/page, ecommerce/product, jobs, tender/government notice, and academic/article workflows.
- Generated schemas include required fields, optional fields, validators, transformations, dedupe keys, export columns, and extraction rules.
- Rule builder works with saved HTML files first, so users can develop selectors safely without repeatedly hitting websites.
Example:
Evaluation, benchmarking, and training data quality
eval:dataset <dataset-id|manifest.json>evaluates dataset completeness, duplicates, validation health, annotation coverage, and training readiness.eval:pipeline <pipeline.json>evaluates pipeline output directly without first creating a dataset snapshot.eval:profile <profile> --dataset=DATASET_IDevaluates a profile schema against dataset records.eval:selectors --profile=PROFILE --dataset=DATASET_IDreports selector/field success, empty fields, and example failed records.benchmark:profile <profile> --dataset=DATASET_IDmeasures profile field success and profile grade.benchmark:compare <old> <new>compares quality, record count, duplicate rate, and training-readiness changes between two datasets.annotation:stats <dataset>shows label counts, field counts, annotated record totals, and coverage percentage.annotation:coverage <dataset>gives quick annotation coverage for review and training readiness.annotation:export <dataset> --format=jsonl|json|csvexports annotation rows with labels, notes, source URL, text, fields, and quality score.dataset:export <dataset> --training-ready --format=jsonlcreates ML-friendly rows withtext,label,fields,quality_score, and metadata.
Dataset versioning and annotations
dataset:create <input.json|urls.txt>creates versioned dataset snapshots from crawl, pipeline, source, intelligence, or URL-list data.dataset:listlists local dataset snapshots.dataset:show <dataset-id|manifest.json>shows one dataset manifest and quality summary.dataset:diff <old> <new>compares two dataset snapshots.dataset:export <dataset-id|manifest.json>exports normalized records as JSON, CSV, or JSONL. Add--training-readyfor ML-friendly JSONL/CSV/JSON exports.annotation:init <dataset-dir>creates an annotation file for review labels.annotation:add <annotations.json>adds labels, notes, field comments, and reviewer metadata.- Dataset folders include
dataset-manifest.json,records.json,records.jsonl,quality-summary.json, andannotations.json.
ML-ready intelligence and adaptive crawl techniques
intelligence:doctorshows available intelligence tools and optional PHP-ML availability.intelligence:analyze <input.json>extracts ML-ready page, record, and URL features.intelligence:classify <input.json>classifies crawled pages into useful workflow groups.intelligence:quality <input.json>predicts page and record quality labels with explainable reasons.intelligence:priority <urls.txt|source.json>ranks URLs so high-value crawl targets can run first.intelligence:selectors <html-file>suggests profile-aware selectors from saved HTML.ml:strategieslists built-in ML crawl strategies such as metadata-first academic crawling, component discovery, and quality-focused recrawling.ml:train --positive=positive.txt --negative=negative.txttrains a deterministic URL relevance model without external ML dependencies.ml:score <urls.txt> --model=model.jsonscores candidate URLs before crawling.ml:adaptive-plan <urls.txt> --model=model.jsoncreates a crawl-budget-aware plan using URL priority, model relevance, diversity, and exploration ratio.ml:feedback <url> --label=relevant|irrelevant|reviewstores manual review feedback for retraining.ml:export-trainingexports JSON/JSONL feature rows that can later feed PHP-ML, Python, or external ML systems.- Works without external ML dependencies. Optional PHP-ML or other model integration can be added later using the exported feature JSON/JSONL.
Dashboard and local admin UI
- Optional dependency-free HTML dashboard under
public/dashboard.php. dashboard:servecommand for running the local admin dashboard with PHP built-in server.dashboard:buildcommand for writing static HTML dashboard snapshots.dashboard:statuscommand for checking dashboard health and available data./dashboard.jsonoutput for machine-readable dashboard snapshots.- Consolidated dashboard view for queue counts, recent jobs, schedules, stale locks, profiles, plugins, command count, and API route count.
- Optional token protection through
MNB_SCRAPERKIT_DASHBOARD_TOKEN. - CMD and PowerShell dashboard server helper scripts.
Crawling and HTTP
- Single URL/site crawl command.
- Multi-page crawl with configurable maximum pages and depth.
- HTTP request engine with headers, timeout, redirects, response metadata, and challenge/protection detection.
- HTTP diagnostic command for checking status, headers, redirect behavior, and response handling.
- Configurable user agent, request timeout, redirects, delay, jitter, pause, and cooldown options.
- URL processing flow for sequential URL lists with retry/backoff/checkpoint behavior.
Safety and responsible crawling
- Central URL safety guard for outgoing requests and redirects.
- HTTP/HTTPS-only scheme enforcement.
- Localhost, private IP, reserved IP, link-local, and metadata address blocking.
- Numeric and hex IPv4 host detection.
- URL userinfo credential blocking.
- URL length safety checks.
- Final-domain and scope guard support.
- Robots.txt decision inspection.
- Auth/login/cart-style URL skipping.
- Challenge/protection page detection and reporting.
- Failure-aware pacing with cooldown after repeated errors.
URL filtering and scope control
- Allowed domain and denied path logic.
- Max depth and max page limit controls.
- Final URL tracking after redirects.
- Duplicate URL and final URL handling.
- Skipped URL classification for unsafe, blocked, out-of-scope, or challenge URLs.
Encoding and text normalization
- Charset detection from headers and HTML.
- UTF-8 conversion support.
- Mojibake cleanup helpers.
- Text normalization helpers for cleaner extraction output.
- Encoding diagnostic command.
Parsing and extraction
- HTML parsing helpers.
- Preset extraction support.
- Custom rule extraction support.
- V1.3 profile-driven rule extraction support.
- CSS-style selector extraction.
- XPath extraction.
- Attribute extraction such as
href,src, andcontent. - Meta tag extraction such as
meta:description. - Open Graph extraction such as
og:titleandog:image. - JSON-LD dot-path extraction such as
jsonld:nameorjsonld:offers.price. - Regex cleanup/extraction from selected text.
- Fallback selectors for fields that vary across websites.
- Multi-value fields using
many: trueor[]rule suffix. - Common data extraction for emails, phones, metadata, links, documents, and profile-oriented data.
- Common data type/profile listing command.
Plugin system
- Config-only plugins using
mnb-plugin.json. - Bundled plugins in
plugins/and installed plugins instorage/plugins/. - Plugin validation that checks required metadata and referenced profile/rule files.
- Plugin install command that copies a plugin into
storage/plugins/. - Plugin enable/disable controls by editing the manifest
enabledflag. - Plugin doctor command for validating all discovered plugins.
- Plugin-contributed profiles available to
profile:list,profile:show,extract:rules, and pipeline/profile workflows. - Safe-by-default design: V1.0.3 does not automatically execute arbitrary plugin PHP code.
Lightweight API and webhooks
- Optional no-framework JSON API router in
public/api-router.php. - API server command using PHP built-in server:
api:serve. - API route discovery command:
api:routes. - API token generation command:
api:token. - Bearer-token authentication using
MNB_SCRAPERKIT_API_TOKEN. - Health/version endpoints for local monitors.
- Queue status endpoint for pending/running/completed/failed job counts.
- Job list, job show, and job create API endpoints.
- Monitoring summary endpoint for queue, schedules, and locks.
- Plugin and profile listing endpoints for lightweight dashboards.
- Webhook endpoint listing from
config/webhooks.json. - Webhook test command that can write a local event file without network calls.
- Webhook send command for posting JSON payloads to authorized HTTP/HTTPS endpoints.
- Webhook endpoint safety uses URL safety checks and blocks unsupported/private targets by default.
Advanced retry, scheduling, and monitoring
- Safe retry policy for temporary failures such as timeout, DNS/SSL errors, 429 rate limits, 5xx errors, no response, and temporary network issues.
- Conservative non-retry defaults for robots blocks, private IP blocks, unsupported schemes, auth/cookie redirects, final-domain guard failures, validation failures, redirect loops, and most 4xx responses.
retry:plancommand for generating retry decisions from crawl JSON, failed URL reports, or failed queue jobs.- Retry plan fields: failure type, status code, attempts, eligibility, retry delay, next attempt time, reason, and recommended action.
queue:retry-safecommand to retry only eligible failed jobs instead of blindly retrying everything.- Local file-based schedules stored under
storage/schedules/. schedule:createfor cron-like scheduled crawl/source jobs without requiring a daemon.schedule:run-duefor cron, Task Scheduler, Supervisor, systemd timers, or worker loop handoff.schedule:list,schedule:show,schedule:enable, andschedule:disablecommands.- Schedule options for one-time runs, interval runs, delay, explicit run time, and max run count.
monitor:summaryfor queue counts, schedule counts, worker locks, stale locks, and health status.monitor:stale-locksfor diagnosing stuck workers or interrupted jobs.
Database storage layer
- Optional PDO-based storage layer.
- SQLite support for local development, CLI automation, and single-machine jobs.
- MySQL/MariaDB support for server and team workflows.
- Database migration command using built-in schema definitions.
- Database connection test command.
- Database status command with table counts.
- Save crawl JSON pages into database tables.
- Save pipeline records and validation issues into database tables.
- Export supported database tables to JSON or CSV.
- Storage tables for jobs, pages, normalized records, failed URLs, validation issues, and export metadata.
- File-based JSON/CSV output remains default; database storage is optional.
Browser-assisted crawling
- Normal PHP HTTP crawler remains the default.
- Optional browser fallback mode with
--browser=auto. - Forced browser rendering mode with
--browser=alwaysor--force-browser. browser:test <url>command for fallback diagnostics.- Auto fallback detection for low-text pages, JavaScript app markers, required JavaScript messages, challenge/browser-required pages, and missing required fields.
- Optional Panther/Chrome adapter through
symfony/panther; not required for normal users. - Browser options for wait selector, wait time, timeout, viewport width/height, headless mode, asset blocking, rendered HTML, and screenshots.
- Same URL safety guard, robots policy, scope rules, final-domain checks, and rate limits stay active in browser mode.
- Browser options can be stored in queued jobs and forwarded from
worker:run. - Browser output can save
rendered.html,browser-result.json, andscreenshot.pngwhen configured.
Common data profiles
- Academic and journal extraction profile direction.
- Conference extraction profile direction.
- Government and tender extraction profile direction.
- Ecommerce extraction profile direction.
- Jobs extraction profile direction.
- SEO extraction profile direction.
- Contact and document extraction profile direction.
Profile schemas and extractor rules
- Built-in profile schema directory:
config/profiles/. - Example schemas for ecommerce, SEO, academic/article metadata, jobs, and tender/government data.
- Schema fields for
profile,record_type,required_fields,optional_fields,dedupe_keys,validators,transformations,field_map,export_columns, andextraction_rules. profile:listcommand to discover available schemas.profile:show <profile>command to inspect one schema.profile:validate <profile.json>command to validate custom schemas.extract:rules <url> --profile=<name>command to test profile extraction rules before running a full crawl.- Pipeline integration that uses schema defaults for validation, transformations, dedupe keys, record type, and export metadata.
- Custom project profiles can be added without editing PHP core classes.
Bulk jobs and resume
- Bulk URL crawl from text file.
- Checkpoint files for long-running jobs.
- Resume support from saved checkpoint state.
- Pending, completed, failed, skipped, challenge, and retry queue tracking.
- Pause after N URLs.
- Rest gaps and jitter for less aggressive crawling.
- Job summary command for inspecting job output and manifest state.
Queue and worker commands
- Local file-based queue stored under
storage/queue/. - Queue states:
pending,running,completed,failed,paused,cancelled, andretry. job:createto create crawl, bulk crawl, URL process, sitemap, RSS, CSV, JSON, or API source jobs.job:listandjob:showfor queue inspection.job:pause,job:resume, andjob:cancelfor lifecycle control.job:run <job-id>to run one queued job manually.worker:onceto run exactly one pending job and exit.worker:runfor long-running CLI workers with--sleep,--max-jobs,--max-runtime,--memory-limit, and--stop-when-empty.worker:statusfor queue counts and active lock visibility.- Failed queue helpers:
queue:failed,queue:retry,queue:retry-all, andqueue:clear-failed. - Lock file support under
storage/queue/locks/to avoid duplicate execution by parallel workers. - Works without Redis, database, or external queue services.
Job manifest
- Job manifest JSON output when
--job-diris used. - Manifest sections for input, scope, request profile, pacing, extraction, output, resume state, and summary.
- Last processed URL and checkpoint metadata.
- Counts for pending, completed, failed, skipped, challenge, and retry groups.
- Job-run command for crawl/bulk jobs from JSON configuration.
Professional crawl pipeline
- Crawl JSON reader for pipeline processing.
- Normalized record builder.
- Record IDs and record types.
- Source URL and final URL traceability.
- Field metadata and profile metadata.
- Validation pipeline.
- Deduplication pipeline.
- Transformation pipeline.
- Quality scoring.
- Dropped, duplicate, invalid, and warning record tracking.
- Pipeline summary output.
Validation
- Required field validation.
- URL validation.
- Email validation.
- Phone validation.
- DOI validation.
- ISSN validation.
- ISBN validation.
- Date validation.
- Price validation.
- Validation issue export and record status reporting.
Transformations
- Whitespace cleanup.
- HTML tag stripping.
- URL cleanup.
- Date normalization.
- Price number extraction.
- Lowercase/uppercase transformations.
- Identifier casing support.
- Field-name mapping for stable exports.
Deduplication
- Dedupe key generation.
- URL/final URL/content-oriented dedupe support.
- Configurable record-level dedupe keys.
- Duplicate record reporting.
Failure handling and retry
- Standard failure classification for timeout, DNS, SSL, redirect loop, private IP block, unsupported scheme, body-too-large, HTTP 4xx, HTTP 5xx, robots block, final-domain guard, and validation failure.
- Failed URL report generation.
- Skipped URL report generation.
- Retry list generation from failed crawl output.
- Backoff/cooldown options for safer repeated runs.
Export, reports, and bundles
- Advanced export connector layer for local delivery folders and webhook automation payloads.
- Export checksum manifests with SHA-256, file sizes, extensions, and modified timestamps.
- Export connector validation, dry-run testing, and delivery result manifests.
- Crawl result JSON export.
- Pipeline record JSON export.
- Pipeline record CSV export.
- Pipeline record XML export.
- Pipeline record HTML table export.
- Failed URL reports in JSON, CSV, XML, or HTML.
- Skipped URL reports when enabled with
--include-skipped. - Validation issue reports in JSON, CSV, XML, or HTML.
- Professional crawl summary report with job metadata, page counts, record counts, failure counts, validation status counts, quality summary, resume state, and export file list.
- HTML summary reports suitable for quick review or sharing with a team/client.
- JSON/CSV/XML summary reports for downstream systems.
- ZIP project bundle creation for records, failed URLs, skipped URLs, validation reports, manifest, checkpoint, logs, and summary report files.
- Lightweight built-in ZIP writer that does not require PHP
ext-zip. - Job manifest summary and export discovery.
- Basic CSV storage/export helpers.
Source connectors
- Sitemap.xml reader support.
- Sitemap index support with nested sitemap discovery.
- Sitemap metadata extraction:
lastmod,changefreq, andpriority. - RSS/Atom feed reader support.
- CSV URL source reader with configurable
--url-column. - JSON URL source reader with dot-path support, for example
items.*.url. - Generic JSON API URL extraction with
--pathand custom--headervalues. - URL-list export from connector results using
source:urls. - Connector outputs in JSON, CSV, or TXT URL-list formats.
- Optional
--crawlhandoff from source connectors intobulk:crawl. - PLOS API/feed command support.
- Elsevier/ScienceDirect API command support.
- Fallback discovery for sitemap, feeds, robots, and well-known source candidates.
Optional/future-ready modules
- Optional browser-assisted crawling layer for JavaScript-rendered pages.
- Network profile and exit-point manager classes for future network policy expansion.
- Modular architecture ready for richer admin dashboards, advanced browser-worker orchestration, role-based access, distributed deployments, and ML-assisted intelligence.
Package direction
- First public version: 1.0.3
- Current version: 1.0.5 — Common data validation hotfix for human names, addresses/locations, and labeled identifiers
- Professional PHP CLI framework
- Composer package with PSR-4 autoloading
- Symfony Console command layer for public usage
- Reusable PHP core classes for crawler, HTTP, parser, profile schemas, extractor rules, pipeline, manifest, checkpoint, exporter, reports, bundles, source connectors, queue workers, scheduling, monitoring, database storage, browser fallback, plugins, API router, and webhooks
- CMD, PowerShell, cron, Windows Task Scheduler, and server worker friendly
- Clean release package without
vendor/or generated crawl outputs - Single documentation file: this
README.md
Requirements
- PHP 8.2+
- Composer
ext-jsonext-domext-mbstringsymfony/consoleext-curlrecommended for the cURL HTTP engineext-pdooptional, only for database storage featuressymfony/pantheroptional, only for browser-assisted crawling- Chrome/Chromium optional, only for browser-assisted crawling
API and webhook examples
List available API routes:
Generate a Bearer token for the optional API server:
Start the optional lightweight API server on localhost:
Check the health endpoint:
Create a queued job through the API:
Create a local webhook test event without making a network request:
Send a webhook payload to an authorized HTTP/HTTPS endpoint:
Example config/webhooks.json:
Plugin system examples
List discovered plugins:
Show the bundled example plugin:
Validate a plugin before installing or publishing it:
Install a local plugin into storage/plugins/:
Minimal plugin manifest shape:
After a plugin contributes a profile, the profile is available through normal profile commands:
Profile schema and extractor rule examples
List built-in schemas:
Show the ecommerce schema:
Validate a custom schema file:
Test extraction rules against one URL:
Use a profile schema during crawl and pipeline processing:
Simple custom profile schema shape:
Export and report examples
Export pipeline records:
Export failed URLs:
Export validation issues:
Generate a professional crawl summary:
Create a portable project bundle:
Windows CMD and PowerShell crawling helpers
MNB ScraperKit includes Windows-friendly scripts for users who prefer not to type long CLI commands. They are designed for safe, low-rate crawling and local testing.
PowerShell single crawl with dry run:
PowerShell single crawl with pipeline output:
PowerShell bulk crawl from a URL list:
PowerShell URL processing with retry/backoff and Windows method ladder:
PowerShell source discovery before crawling:
CMD single crawl:
CMD bulk crawl:
CMD environment overrides:
See also:
CLI commands
Useful help commands:
Advanced retry, scheduling, and monitoring examples
Create a retry plan from a crawl output or failed URL report:
Retry only failed queue jobs that are safe to retry:
Create a local schedule that enqueues a crawl job every hour:
Use cron or Windows Task Scheduler to run due schedules periodically:
Check queue/schedule/worker health:
Database storage examples
Initialize a default local SQLite database:
Use an explicit SQLite file:
Save crawl output and pipeline records:
Export stored records:
Use MySQL/MariaDB with a PDO DSN:
Database storage is optional. Normal JSON/CSV exports continue to work without SQLite, MySQL, or any database setup.
Source connector examples
Read URLs from a sitemap and save JSON:
Export sitemap URLs as a plain TXT list for bulk crawling:
Read RSS/Atom records:
Read URLs from CSV:
Read URLs from JSON with a dot path:
Read URLs from a generic JSON API:
Export URLs from any connector JSON output:
Use --crawl on connector commands to hand the discovered URLs directly to bulk:crawl:
Professional pipeline
The pipeline converts crawled pages into normalized records that are easier to validate, deduplicate, export, and review.
Record shape:
Supported validation signals include:
- required fields
- URLs
- emails
- phones
- DOI
- ISSN
- ISBN
- dates
- prices
Supported transformations include:
- whitespace normalization
- URL cleanup
- ISO-style dates
- price-number extraction
- identifier casing
- field-name mapping
Example:
Common data profiles
ScraperKit is built for reusable extraction profiles instead of one-off scraping scripts.
| Profile | Typical use |
|---|---|
academic / journal |
Authors, editors, affiliations, DOI, ISSN, ISBN, ORCID, publisher, article metadata, journal data, PDF links, submission links, and deadlines |
conference |
Event names, speakers, organizers, venues, dates, registration links, CFP deadlines, and submission details |
government / tender |
Tender numbers, notification numbers, application numbers, deadlines, document links, contacts, addresses, fees, and eligibility |
ecommerce |
Product title, price, currency, SKU, brand, availability, images, ratings, reviews, variants, and structured data |
jobs |
Job title, company, location, salary, experience, skills, apply link, deadline, and recruiter contact |
seo |
Meta title, meta description, canonical URL, robots, schema, Open Graph, Twitter cards, headings, links, and sitemap hints |
contact / document |
Emails, phones, addresses, document URLs, file metadata, and page-level contact information |
Browser-assisted crawling examples
Diagnose whether a page likely needs browser fallback:
Use auto fallback during a crawl:
Force browser rendering for one crawl:
Create a queued browser fallback job:
php bin/mnb-scraper job:create --type=crawl https://example.com --profile=ecommerce --browser=auto
php bin/mnb-scraper worker:run --stop-when-empty
Browser mode is optional. Normal crawling works without Panther or Chrome. To enable the Panther adapter locally, install the optional dependency and browser driver support:
composer require symfony/panther
Queue and worker examples
Create a queued sitemap source job:
php bin/mnb-scraper job:create --source=sitemap https://example.com/sitemap.xml --profile=seo
Create a queued CSV source job:
php bin/mnb-scraper job:create --source=csv urls.csv --url-column=url --profile=ecommerce
List queued jobs:
php bin/mnb-scraper job:list
Show one queued job:
php bin/mnb-scraper job:show JOB_ID
Run one queued job manually:
php bin/mnb-scraper job:run JOB_ID
Run one worker pass and exit:
php bin/mnb-scraper worker:once
Run a worker loop for server automation:
php bin/mnb-scraper worker:run --sleep=5 --max-jobs=10 --max-runtime=3600 --memory-limit=256M
Pause, resume, cancel, and retry:
php bin/mnb-scraper job:pause JOB_ID
php bin/mnb-scraper job:resume JOB_ID
php bin/mnb-scraper job:cancel JOB_ID
php bin/mnb-scraper queue:failed
php bin/mnb-scraper queue:retry JOB_ID
php bin/mnb-scraper queue:retry-all
The queue foundation remains local and dependency-free. It is suitable for CMD, PowerShell, cron, Windows Task Scheduler, systemd, and Supervisor. Future versions can add database/Redis queue drivers without changing the crawl/pipeline core.
Job manifest and checkpoint
When --job-dir is used, ScraperKit writes a job-manifest.json file containing:
- input
- scope
- request profile
- pacing
- extraction profile
- output settings
- resume/checkpoint metadata
- summary
Bulk and URL-processing checkpoints include these queue groups:
- pending
- completed
- failed
- skipped/challenge
This makes long jobs easier to resume, audit, and troubleshoot.
Useful pacing and safety-related options:
php bin/mnb-scraper crawl "https://example.com" \
--max-pages=20 \
--depth=1 \
--delay-ms=1000 \
--delay-jitter-ms=300 \
--pause-after-urls=10 \
--pause-seconds=30 \
--cooldown-after-failures=3 \
--cooldown-seconds=60
Safety defaults
ScraperKit is safe by default:
- only HTTP/HTTPS URLs are allowed
- localhost targets are blocked
- URL userinfo credentials are blocked
- private, reserved, link-local, and metadata IP targets are blocked
- numeric IPv4 host forms are normalized and checked
- redirects are checked by the HTTP layer
- robots policy is respected unless explicitly disabled
- auth/login/cart style URLs are skipped by default
- challenge/protection pages are detected and reported
- gaps, pauses, and retry backoff are supported for responsible crawling
Use this library for public or authorized crawling, SEO audits, website diagnostics, permitted monitoring, and your own sites. Do not use it for access-control bypass, CAPTCHA bypass, paywall bypass, credential abuse, or aggressive traffic.
Export outputs
ScraperKit focuses on practical export-ready outputs:
- crawl result JSON
- record JSON
- record CSV
- failed URL reports
- skipped URL reports
- validation issue summaries
- pipeline summaries
- job manifest summaries
PDF reports and richer role-based enterprise orchestration remain future upgrade areas. The current V1.0.3 release already includes CLI workflows, source connectors, exports/reports/bundles, export delivery connectors, local and distributed queue/worker commands, optional Redis queue support, optional browser-assisted crawling, API/webhooks, dashboard UI, ML-ready intelligence, dataset versioning, and annotation tools.
Windows CMD
scripts\run-crawl.cmd https://example.com 10 1
scripts\run-pipeline.cmd storage\jobs\example\crawl.json
PowerShell
.\scripts\run-crawl.ps1 -Url "https://example.com" -MaxPages 10 -Depth 1
.\scripts\run-pipeline.ps1 -Input "storage\jobs\example\crawl.json"
Source connectors
ScraperKit includes source connector commands for API/feed-first workflows:
- PLOS journal catalog, search, feeds, and URL exports
- Elsevier/ScienceDirect search, metadata, DOI, serial, and URL exports
- RSS/Atom feed reader support
- fallback source discovery for sitemap, feeds, robots, and well-known endpoints
Release package rules
This V1.0.3 package intentionally keeps documentation simple: README.md is the only project documentation file.
The release package should not include generated runtime files:
vendor/- crawl outputs
- pipeline outputs
- checkpoint files
- cookie/session files
The storage/ folder is kept with .gitkeep; generated files are ignored.
Testing
Run:
php tests/run-tests.php
Optional Composer script:
composer test
Evaluation and training data quality examples
Evaluate one dataset:
php bin/mnb-scraper eval:dataset dataset_products --profile=ecommerce --format=html --output=storage/reports/products-evaluation.html
Evaluate pipeline output directly:
php bin/mnb-scraper eval:pipeline storage/jobs/job-001/pipeline/records.json --profile=ecommerce --json
Benchmark a profile against a dataset:
php bin/mnb-scraper benchmark:profile ecommerce --dataset=dataset_products --json
Measure selector/field success for a profile:
php bin/mnb-scraper eval:selectors --profile=ecommerce --dataset=dataset_products --output=storage/reports/selector-report.json
Check annotation coverage and export labels:
php bin/mnb-scraper annotation:stats dataset_products --json
php bin/mnb-scraper annotation:export dataset_products --format=jsonl --output=storage/datasets/products/annotations.jsonl
Export training-ready data:
php bin/mnb-scraper dataset:export dataset_products --format=jsonl --training-ready --training-type=classification
Dataset versioning examples
Create a dataset snapshot from pipeline records:
php bin/mnb-scraper dataset:create storage/jobs/example/pipeline/records.json --id=example_dataset
List and inspect datasets:
php bin/mnb-scraper dataset:list
php bin/mnb-scraper dataset:show example_dataset
Export normalized dataset records:
php bin/mnb-scraper dataset:export example_dataset --format=csv --output=storage/datasets/example_dataset/export.csv
Compare two dataset snapshots:
php bin/mnb-scraper dataset:diff old_dataset new_dataset --json
Initialize annotations and add review labels:
php bin/mnb-scraper annotation:init storage/datasets/example_dataset
php bin/mnb-scraper annotation:add storage/datasets/example_dataset/annotations.json --record-id=dsrec_123 --label=good --note="Ready for training"
ML-ready intelligence and adaptive crawl examples
Analyze crawl or pipeline output and export features:
php bin/mnb-scraper intelligence:analyze storage/jobs/example/crawl.json --output=storage/intelligence/features.json
Classify pages and recommend profiles:
php bin/mnb-scraper intelligence:classify storage/jobs/example/crawl.json --output=storage/intelligence/classes.json
Predict quality for pages and records:
php bin/mnb-scraper intelligence:quality storage/jobs/example/pipeline.json --output=storage/intelligence/quality.json
Prioritize URLs before crawling:
php bin/mnb-scraper intelligence:priority urls.txt --format=txt --output=priority-urls.txt
Suggest selectors from saved HTML:
php bin/mnb-scraper intelligence:selectors page.html --profile=ecommerce --output=selectors.json
List safe ML crawl strategies:
php bin/mnb-scraper ml:strategies --json
Train a lightweight crawl relevance model from reviewed examples:
php bin/mnb-scraper ml:train --positive=examples/ml/positive-urls.txt --negative=examples/ml/negative-urls.txt --output=storage/ml/crawl-model.json
Score candidate URLs before crawling:
php bin/mnb-scraper ml:score examples/ml/candidate-urls.txt --model=storage/ml/crawl-model.json --output=storage/ml/scores.json
Create an adaptive crawl plan with crawl budget and exploration control:
php bin/mnb-scraper ml:adaptive-plan examples/ml/candidate-urls.txt --model=storage/ml/crawl-model.json --crawl-budget=4 --explore-ratio=0.15 --profile=academic --output=storage/ml/adaptive-plan.json
Store feedback after reviewing crawl results:
php bin/mnb-scraper ml:feedback https://link.springer.com/article/10.1007/s007770050003 --label=relevant --reason="article metadata page"
Export ML-ready URL features as JSONL:
php bin/mnb-scraper ml:export-training --positive=examples/ml/positive-urls.txt --negative=examples/ml/negative-urls.txt --format=jsonl --output=storage/ml/training-data.jsonl
Run the Windows helper:
powershell -ExecutionPolicy Bypass -File scripts/run-ml-adaptive-plan.ps1 -CrawlBudget 10
Project template examples
List available templates:
php bin/mnb-scraper template:list
Create an SEO audit project workspace:
php bin/mnb-scraper template:create seo-audit --output-dir=projects/seo-audit --name=seo-audit
Create an ecommerce monitoring workspace:
php bin/mnb-scraper template:create ecommerce-monitor --output-dir=projects/products --name=products
Install a preset pack with grouped profiles and workflow examples:
php bin/mnb-scraper preset:install commerce-gov-pack --output-dir=presets/commerce-gov
Validate a template before sharing it with a team:
php bin/mnb-scraper template:validate seo-audit
AI crawl intelligence and search discovery
The AI/search layer helps decide what can be crawled safely before launching a crawl. It is designed as a planning and discovery layer, not as a bypass system.
Core principles:
- External AI is not called unless a provider is configured.
- The default analyzer is deterministic/rule-based.
- Search discovery uses provider connectors or offline examples, not direct scraping of search-result pages.
- Outputs should be reviewed before running high-volume crawls.
List AI providers:
php bin/mnb-scraper ai:providers --json
Analyze a site or saved target for crawl flexibility:
php bin/mnb-scraper ai:analyze-site https://link.springer.com/journal/777/volumes-and-issues --goal=article_metadata --provider=rule_based --output=storage/ai/springer-analysis.json
Explain the generated crawl plan:
php bin/mnb-scraper ai:explain-plan storage/ai/springer-analysis.json
List search providers:
php bin/mnb-scraper search:providers --json
Run offline/provider-backed discovery and convert results to seed URLs:
php bin/mnb-scraper search:web "Springer journal 777 article DOI" --provider=offline --output=storage/search/results.json
php bin/mnb-scraper search:discover "Springer journal 777 article DOI" --input=examples/search/springer-search-results.json --filter-domain=link.springer.com --output=storage/search/discovered.json
php bin/mnb-scraper search:to-seeds storage/search/discovered.json --filter-domain=link.springer.com --output=storage/search/seeds.txt
Recommended production flow:
search/web discovery -> search result classification -> domain filtering -> AI crawl analysis -> seed review -> low-rate crawl -> extraction recipe -> quality report
Authorized mail and webmail extraction
The mail layer is authorization-first. It is intended for user-approved exports, Gmail API/OAuth connectors, IMAP connectors, or webmail exports. It does not automate hidden login, scrape webmail UIs, store mailbox passwords, or bypass account protections.
Supported provider slots:
local_json
eml_file
gmail_api
imap
webmail_export
List mail providers and safety policy:
php bin/mnb-scraper mail:providers --json
Search an approved local mail export:
php bin/mnb-scraper mail:search "Springer" --provider=local_json --input=examples/mail/sample-authorized-mails.json --json
Extract links, PDF URLs, text, HTML, and attachment metadata:
php bin/mnb-scraper mail:extract examples/mail/sample-authorized-mails.json --extract=links,pdfs,text,attachments --query=Springer --output=storage/mail/extracted.json
Build an attachment manifest or save approved base64 attachment content from a user export:
php bin/mnb-scraper mail:attachments examples/mail/sample-authorized-mails.json --output-dir=storage/mail/attachments --json
Convert extracted mail links into crawl seeds:
php bin/mnb-scraper mail:to-seeds storage/mail/extracted.json --filter-domain=link.springer.com --output=storage/mail/seeds.txt
Recommended production flow:
authorized mailbox/export -> mail extraction -> domain filtering -> seed review -> AI crawl analysis -> extraction recipe -> dataset/export
QA smoke examples
The package includes offline-safe examples so users can verify major workflows without live credentials or crawling external websites.
Useful files:
examples/qa/command-smoke-plan.json
examples/qa/qa-workflow-notes.txt
examples/search/multi-provider-offline-results.json
examples/ai/site-analysis-targets.json
examples/mail/sample-authorized-mails.json
examples/mail/sample-authorized-message.eml
examples/mail/sample-webmail-export.json
examples/extraction/qa-components.html
Run the QA smoke helper:
scripts/run-qa-smoke.cmd
PowerShell:
./scripts/run-qa-smoke.ps1
Run the native source-zip smoke helper when you want to verify the public archive before installing Composer dependencies:
./scripts/run-native-smoke.sh
Windows CMD:
scripts\run-native-smoke.cmd
PowerShell:
./scripts/run-native-smoke.ps1
The smoke plan covers search discovery, AI analysis, mail extraction, extraction options, recipes, quality reports, and seed generation using local example data only.
License
MIT License. See LICENSE.
Dashboard usage
Start the local dashboard server:
php bin/mnb-scraper dashboard:serve
Open:
http://127.0.0.1:8788/dashboard
Build a static dashboard snapshot:
php bin/mnb-scraper dashboard:build --output=storage/dashboard/index.html
Check dashboard status from CLI:
php bin/mnb-scraper dashboard:status --json
Protect the dashboard when exposing it outside localhost:
set MNB_SCRAPERKIT_DASHBOARD_TOKEN=your-token-here
php bin/mnb-scraper dashboard:serve
Then send Authorization: Bearer your-token-here or use ?token=your-token-here for local testing.
Enterprise publisher graph crawling
MNB ScraperKit now models real academic publisher crawling as a metadata-first navigation graph:
publisher/about page -> journal/book indexes -> journal landing pages -> volumes/issues or book chapters -> article/chapter metadata pages -> normalized article records
New commands:
php bin/mnb-scraper publisher:graph springer --json
php bin/mnb-scraper publisher:enterprise-plan springer --max-journals=10 --max-books=10 --max-issues=10 --max-articles=25 --output=storage/springer-enterprise-plan.json
php bin/mnb-scraper publisher:extract-article saved-springer-article.html --publisher=springer --url=https://link.springer.com/article/10.1007/s007770050003 --output=storage/article.json
The publisher graph supports journal/book listing pages, book landing URLs, journal volume/issue tables of contents, article/chapter URLs, and detailed metadata fields such as title, article type, published date, authors, affiliation/contact metadata when public, abstract, DOI, keywords, and references. It remains metadata-only by default and does not include paywall, CAPTCHA, or access-control bypass.
Extraction options and component intelligence
v1.0.3 adds reusable extraction controls for enterprise page data extraction:
- Word dictionary learning:
extract:dictionarycan add newly discovered words to a reusable JSON dictionary. - Data mappings:
extract:mappingsmaps source fields to normalized target fields. - Registered patterns:
extract:patternsruns configurable regex patterns for emails, phones, DOI, ISSN, ISBN, dates, prices, registration numbers, PDF URLs, and image URLs. - Common components:
extract:componentsextracts tables, lists, headings, navigation links, pagination controls, breadcrumbs, social links, download links, bio blocks, cards, and repeated component groups. - Pagination detection:
extract:paginationfinds numbered pagination, ellipsis/sliding windows, previous/next, first/last, A-Z indexes, dropdown page selectors, go-to-page inputs, infinite scroll signals, load-more buttons, cursor/offset/keyset/token API-style pagination, page-size controls, mobile compact controls, step/wizard flows, tabs, date-based controls, and timeline controls. - Extraction modes: links, plain text, inner HTML, outer HTML, whole HTML, only images, only PDFs, download files, no-image filtering, selectors, and repeated class/id/tag statistics.
Examples:
php bin/mnb-scraper extract:types
php bin/mnb-scraper extract:components examples/extraction/sample-components.html --json
php bin/mnb-scraper extract:pagination https://link.springer.com/journals/a/1 --json
php bin/mnb-scraper extract:pagination examples/extraction/sample-pagination.html --base-url=https://example.com/search --json
php bin/mnb-scraper extract:options examples/extraction/sample-components.html --type=links,text,pagination,components,patterns,dictionary --dictionary=storage/extraction/words.json --output=storage/extraction/result.json
php bin/mnb-scraper extract:patterns examples/extraction/sample-components.html --json
php bin/mnb-scraper extract:mappings records.json --mapping=article --output=storage/mapped-records.json
Pagination extraction output
Use extract:pagination when you want only page navigation controls from one URL or saved HTML file:
php bin/mnb-scraper extract:pagination https://link.springer.com/journals/a/1 --json
php bin/mnb-scraper extract:pagination examples/extraction/sample-pagination.html --base-url=https://example.com/search --json
Typical output includes:
{
"pagination": {
"has_pagination": true,
"primary_pattern": "alphabetical",
"detected_types": ["alphabetical", "previous_next", "numbered"],
"summary": {
"next_url": "https://link.springer.com/journals/a/2",
"page_numbers": [1, 2],
"pagination_links_total": 30
},
"patterns": [],
"links": []
}
}
For Springer A-Z pages, the detector separates alphabet navigation such as A B C ... Z, page links such as 1 2 Next, and API-style URL parameters if present. Infinite scroll and JavaScript-only pagination are reported as static signals; the detector does not execute hidden JavaScript or bypass access controls.
Extraction explainability, recipes, and quality reports
The extraction layer is designed to make output reusable and explainable:
- Reusable extraction recipes in
config/extraction/recipes/*.json. - Field provenance for recipe and component outputs, including selector/method/status/confidence metadata.
- Extraction quality reports with required-field completeness, missing fields, component counts, provenance coverage, and recommendations.
- Mapping transforms such as
trim,lowercase,normalize_space,strip_html,clean_url,normalize_doi,parse_date, anddedupe_array. - Dictionary entries now keep frequency metadata, first/last seen timestamps, source URL samples, category, and approval state.
- Repeated component groups now include a component type guess and confidence score.
Examples:
php bin/mnb-scraper extract:recipes --json
php bin/mnb-scraper extract:recipe article.html --recipe=config/extraction/recipes/springer-article.json --output=storage/extraction/article-recipe.json
php bin/mnb-scraper extract:quality storage/extraction/article-recipe.json --required-field=title --required-field=doi --output=storage/extraction/article-quality.jsonAll versions of scraperkit with dependencies
ext-dom Version *
ext-json Version *
ext-mbstring Version *
symfony/console Version ^6.4 || ^7.0