Download the PHP package padosoft/product-image-discovery without Composer

On this page you can find all versions of the php package padosoft/product-image-discovery. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Informations about the package product-image-discovery

Product Image Discovery

Latest Version on Packagist PHP Laravel

Official documentation: https://doc.product-image-discovery.padosoft.com

Table of Contents

Find the right product image, not just any image.

padosoft/product-image-discovery is a Laravel package for discovering, verifying, scoring and preparing product images from supplier data, search providers and trusted sources. It is built for catalog teams, ERPs, PIMs and marketplaces where the expensive mistake is not "we found no image"; the expensive mistake is publishing the wrong image for a product-color variant.

The package gives you a conservative pipeline, an API for ingestion and review, database-backed configuration, queue-ready jobs, audit events and an optional Playwright sidecar for pages that need browser rendering.

Responsible Use Disclaimer

Use this package only for lawful, authorized product image discovery workflows. Do not use it to abuse third-party services, bypass access controls, overload websites, violate robots.txt or source terms, or collect images from sources where you do not have explicit permission or another valid legal basis. Configure trusted sources, rate limits and manual review policies conservatively, and use it only on websites, suppliers, brand sources or search providers that you are allowed to access for this purpose.

Why This Package

Quick Start (5 minutes, junior-friendly)

Goal: from a fresh Laravel 13 app to a passing end-to-end discovery request, without paid keys, copy-pasting nine blocks in order. The pipeline runs synchronously and returns a stored candidate from a bundled fake provider, so you can see the full flow before plugging in any external API.

Prerequisites: PHP 8.3+, Composer, a clean Laravel 13 app, ~5 minutes. No queue worker, no Redis, no Node, no API keys.

1. Require the package

2. Publish config

3. Publish migrations

4. Create the SQLite database file

On Windows PowerShell:

5. Migrate

6. Seed default settings + provider templates

7. Minimal .env overrides (append four lines)

8. Activate the bundled fake provider + issue a token via tinker

Inside Tinker, paste this single block:

Copy the printed token. Exit tinker.

If App\Models\User does not use Laravel\Sanctum\HasApiTokens, add the trait first — see step 4 in Live Smoke Test From A Fresh Laravel App.

9. Hit the API (replace YOUR_TOKEN)

In another terminal:

You should receive {"ok":true, "request_id":1, "status":"queued"}.

✅ Done — you just ran the full ingest → search → extract → verify → download → quality pipeline locally with a deterministic fake provider. Next steps:

Supported Search Providers

Since v1.0.0, the search layer is consumed via the standalone composer package padosoft/laravel-ai-search-providers. This repo declares it as a hard dependency in composer.json; the package ships every driver listed below, the SearchProviderInterface contract, the SearchProviderManager orchestrator, the DTOs, the Eloquent model and the create-table migration. product-image-discovery only exposes a backwards-compatible ProductImageSearchProvider Eloquent subclass that hard-codes the legacy product_image_search_providers table, so existing host apps and the sister padosoft/product_image_discovery_admin package keep working unchanged. For full driver documentation, the Http::fake test pattern, custom-driver extension and the package Quick Start, jump to the package README at https://github.com/padosoft/laravel-ai-search-providers#readme.

The package currently bundles 9 search providers — 1 deterministic for tests + 8 live drivers covering global, EU-friendly, free-tier and scrape-friendly options. All providers are stored in the same product_image_search_providers table and resolved through a single SearchProviderManager, so swapping one for another is a row update.

Provider Driver Image search Site filter Free tier Docs
Fake (deterministic) fake ✅ ✅ — n/a — bundled for tests
Brave Search brave ✅ ✅ 2000 / month https://api-dashboard.search.brave.com/app/documentation
Tavily tavily ✅ ✅ (include_domains) 1000 credits / month https://docs.tavily.com
Exa.ai exa ✅ (extras.imageLinks) ✅ (includeDomains) Free trial credits https://docs.exa.ai
Firecrawl firecrawl ✅ (sources:["images"]) ✅ (via site: operator) 500 credits / month https://docs.firecrawl.dev/api-reference/v2-endpoint/search
WebSearchAPI.ai websearchapi ❌ (web-only) ✅ (includeDomains) Free trial credits https://websearchapi.ai/docs/search-api
DuckDuckGo (HTML lite) duckduckgo ❌ ✅ (via site: operator) No key required https://duckduckgo.com/html/
SearchAPI.io searchapi ✅ (engine=google_images) ✅ (via site: operator) Free trial credits https://www.searchapi.io/docs/google-images
You.com youcom ❌ (web-only) ✅ (include_domains) Free trial credits https://you.com/docs/api-reference/search/v1-search

Templates for serpapi and google_custom_search were originally seeded but Google's Custom Search JSON API was closed to new customers in 2026 and new Programmable Search Engines can no longer index the full web — see the Roadmap for the Vertex AI Search / Agent Search adapter slated as a separate sub-package.

⚠️ Provider configs are redacted in audit logs. Always store secrets in .env and let the seeders/tinker scripts populate api_key_encrypted, never expose API keys through user-facing endpoints.

Brave Search

Activate the seeded provider:

Tavily

JSON search API with first-class image support (images[]) and include_domains site filtering.

Activate:

Exa.ai

POST /search with contents.extras.imageLinks per result, flattened into one candidate per image URL. Site filter via includeDomains. Auth via x-api-key header.

Activate:

The image_links_per_result config key (default 5) caps how many imageLinks Exa returns per result and how many candidates the provider emits per Exa result.

Firecrawl

POST /v2/search with sources:[{type:"images"}] (or [{type:"web"}] for searchWeb()). Bearer auth. Site filter propagated as includeDomains array. Returns data.images[] with imageUrl, imageWidth, imageHeight, and the source page url.

Activate:

WebSearchAPI.ai

POST /ai-search with Bearer auth. Google-backed organic web results with optional AI content extraction. Site filter via includeDomains. Web-only: WebSearchAPI does not expose a dedicated image search endpoint, so supportsImageSearch() returns false and SearchProviderManager skips this driver for image queries (the extraction pipeline can still harvest images from the returned pages).

Activate:

DuckDuckGo (HTML lite)

Free, no-API-key fallback for web search. Posts to https://html.duckduckgo.com/html/ and parses the response with \DOMDocument + \DOMXPath. Result .result__a links use the //duckduckgo.com/l/?uddg=<encoded> redirect form — the provider decodes them transparently and returns the real destination URL. No image search: supportsImageSearch() returns false, so SearchProviderManager skips it for image queries automatically.

Activate:

Use it sparingly and respect DuckDuckGo's terms — it is best as a low-volume fallback, not a primary driver. DuckDuckGo applies anti-bot rate limits to shared/datacenter IPs; the live E2E test self-skips in CI and on 403/429/503 responses.

SearchAPI.io

Single GET /api/v1/search endpoint that switches between engine=google_images (image search → images[] with original.link, original.{width,height}, thumbnail, source.{link,name}) and engine=google (web search → organic_results[]). Bearer auth. Site filter appended as site:<host> operator in the query. Added by padosoft/laravel-ai-search-providers v1.2.0.

Activate:

You.com

GET /v1/search against https://ydc-index.io with X-API-Key header. Parses results.web[] (and optionally results.news[]) with title, url, description, snippets[], thumbnail_url, page_age, favicon_url. Site filter propagated as include_domains (comma-separated). Web-only as of 2026-05: You.com does not expose a dedicated image-search endpoint, so supportsImageSearch() returns false and SearchProviderManager skips this driver for image queries automatically — thumbnail_url is still surfaced per result, and the extraction pipeline can still harvest images from the returned pages. Added by padosoft/laravel-ai-search-providers v1.2.0.

Activate:

Fake provider

Deterministic, no network. Use it for local smoke tests, CI and unit tests. See the Quick Start above for an example configuration that feeds an inline base64 image directly into the download/quality steps.

What It Does

Architecture

The package is split into small layers so you can replace the parts that touch infrastructure:

Web Admin UI

Need a ready-made back office for this package? The professional Laravel admin is already available as a sister repository:

padosoft/product_image_discovery_admin

It provides an operational dashboard, request review queues, candidate comparison, protected image previews, approve/reject/retry actions, provider and trusted-source configuration, debug-flow execution, health checks, report inspection, API workbench tooling, CSV export, saved demo filters and a GitHub Actions release gate.

Request Flow

Installation

Requirements:

1. Require the package

If you are testing directly from GitHub before Packagist is updated, add the repository first:

2. Review the env examples

The repository ships two examples:

For a local smoke test, the important host-app values are:

3. Publish the config

This creates:

4. Publish the migrations

5. Run migrations

6. Seed default settings and provider templates

The seeder creates default matching thresholds, quality settings and disabled provider templates such as Brave, SerpAPI and Google Custom Search.

7. Configure Sanctum abilities

The API middleware expects token abilities like:

For a back-office integration, give operators read and review; give system ingestion tokens write; reserve settings and admin for trusted maintainers.

8. Configure queues

By default, jobs use dedicated queue names:

Run your Laravel queue workers as usual:

If you use Horizon, map these queues in config/horizon.php.

Live Smoke Test From A Fresh Laravel App

This path is intentionally explicit so a junior developer can prove the package works in a real Laravel application without setting up Redis, MySQL or a paid search API.

1. Create a clean Laravel app

2. Install the package from GitHub tag v0.1.0

3. Configure .env

Create the SQLite database file:

On Windows PowerShell:

Set these values in the Laravel app .env:

Then generate the app key:

4. Install Sanctum tables and enable API tokens

In app/Models/User.php, make sure the model uses Sanctum tokens:

Keep any existing traits such as HasFactory and Notifiable; just add HasApiTokens.

5. Publish package files and migrate

6. Create a test API token

Inside Tinker:

Copy the printed token for the Authorization: Bearer ... header.

7. Add a deterministic fake provider

This provider lets you test the whole API and queue path without a paid search API:

Inside Tinker:

8. Start the app

9. Send a real API request

Replace YOUR_TOKEN with the Sanctum token from step 6:

The same payload is available as a ready-to-edit JSON file:

You should receive a JSON response with ok: true and a request_id. Because QUEUE_CONNECTION=sync, the pipeline runs during the request cycle.

Check the stored request:

10. Optional: activate Brave for a real external search

Add your key to .env:

Then activate the seeded Brave provider:

Inside Tinker:

Disable the fake provider when you want only live search results:

Debug Flow Command

The package includes a console command for full live debugging from a request JSON file. It runs the same pipeline jobs as the queue flow and streams a step-by-step console trace: ingest, generated queries, sites/images found, candidate verification order, every candidate examined, score components, deterministic evidence, optional AI output, download path, hash, quality analysis, errors and final decision.

Before verification, the command ranks candidates with deterministic scoring, so constrained runs start from the strongest product identity match and avoid spending live AI calls on obvious wrong-color or wrong-model candidates first. Use --report=... to keep the complete JSON report on disk; use --json when you need machine-readable output instead of the live console trace.

Where to run it:

What you see on screen:

That php artisan form only works from a Laravel app root. If you run it from the package root and see Could not open input file: artisan, use the Testbench commands in the Herno example below.

Useful options:

Early stop is controlled by:

With early stop enabled, the command stops candidate verification when a verified candidate is good enough because it comes from an auto-publish/trusted source, the source domain contains the brand, or its final score reaches the configured threshold. Use --exhaustive when you intentionally want to inspect all candidates up to --max-candidates.

--fresh also cleans the storage directory for the matching old request ids and the new debug request id. This matters especially when running from the package with Testbench: the database is often SQLite in-memory, so request ids can restart from 1 while physical files under vendor/orchestra/testbench-core/laravel/storage/... remain from older debug or live test runs.

To inspect and download every verified candidate in a broad run, combine:

Herno Live Debug Example

The repository includes a real fashion request example without any source page or image URL:

It describes:

Run it in a host Laravel app:

Run it from this package with Testbench on Windows PowerShell:

Run it from this package with Testbench on macOS/Linux shell:

With BRAVE_SEARCH_API_KEY configured, the command auto-creates a brave-live-debug provider and shows the live Brave image results. Search queries prefer product-code + color combinations before bare product-code searches, so fashion variants such as PI002223D CAMMELLO are tried before broader PI002223D searches. With AI enabled and PRODUCT_IMAGE_DISCOVERY_AI_ATTACH_REMOTE_IMAGE=true, it also sends each verified candidate image URL to the configured vision model and prints the full AI verification result.

The AI verifier is instructed to inspect the actual attached image first. Numeric vendor color ids in URLs or DOM metadata are not treated as color names: if the image visibly looks camel/tan/beige/cammello, the model can mark the requested color as equivalent; if the image visibly shows a different product or color, for example white shoes, it should mark match=false, variant_safe=false, color_match=false and product_type_match=false.

In the local Herno run, the trace found the official us.herno.com image, downloaded it under product-image-discovery/{request_id}/{candidate_id}.jpg, quality-checked it, printed the SHA-256 hash, and kept the request in manual_review because the source was not configured as auto-publishable. External results and AI wording can change, so treat the report as the source of truth for each run.

Downloaded image paths:

Console screenshots:

Quickstart

Send a product-color payload:

Example response:

Search requests:

List the candidates of a request. Every search (first run, /retry, or a re-POST of the same erp_model_color_id) is a new run, stored in raw_payload.context.search.run and on each candidate as search_run; the list shows the latest run only, add all_runs=1 for the full history. An image that an earlier run already found keeps its candidate, which moves to the new run and is verified, downloaded and quality-checked again:

The search keeps the results of the first query that returns any. Image providers such as Brave rarely return nothing: a quoted code they have not indexed brings back unrelated items of the brand. So when every candidate of the run is rejected by the scorer, the run escalates: the request goes back to searching and the next step skips the queries already executed and the families whose results were all rejected (ean, supplier_sku, model_code, description), until a candidate is promoted, no query is left or the step budget is spent. Images already seen in the run are not verified again; every step adds its candidates to the same run, recorded in raw_payload.context.search (step, families_tried, and step on each entry of executions), with a pipeline.search.escalated audit event per step.

When the run ends with every candidate rejected the request goes to manual_review, with the candidates of all its steps: candidates were found, and a reviewer can still approve one the scorer got wrong. no_candidates_found only means that the first search returned nothing.

Each step costs one provider call per query it executes and one verification (AI included, when enabled) per new image. The debug flow command runs a single step.

Approve a candidate:

Reject a candidate:

EAN / Barcode Matching

ean is optional, but when your ERP/PIM/supplier has the real product barcode it is one of the strongest identity signals in the package.

Accepted payload aliases:

The API normalizes these aliases into the stored ean field. When ean is present:

Do not invent barcodes for smoke tests. Leave ean/barcode empty unless the value comes from the real catalog, supplier or product feed.

Real Product Payload Examples

These examples are realistic ERP/PIM payloads for products that also exist on public fashion sites. The request intentionally does not include an image URL or product page URL: discovering that page/image is the job of the package. Ecommerce pages can change, go out of stock or block automated access, so treat these as smoke-test payloads rather than permanent fixtures. Do not invent EANs: leave ean empty unless your ERP/PIM has the real barcode.

Ready-to-edit request files are available in:

Nike Air Force 1 07, White/White

Source page: Nike Air Force 1 07 men's shoes

Nike Air Force 1 07, White/White, LuisaViaRoma item

Source page: LuisaViaRoma Nike Air Force 1 07 sneakers

adidas Originals Samba OG, White/Black, LuisaViaRoma item

Source page: LuisaViaRoma adidas Originals Samba OG sneakers

New Balance 550, White/Grey, LuisaViaRoma item

Source page: LuisaViaRoma New Balance 550 sneakers

Amazon is not used as a default example because product pages are highly personalized, protected and terms-sensitive. Use official brand pages or trusted fashion retailers first.

Configuration

The main config file is config/product-image-discovery.php.

Important options:

Scoring settings

The scorer reads its knobs from the product_image_discovery_settings table (global rows, or per client_id), which the admin edits on its Settings page. Two rules are off unless a setting turns them on (true, 1 or "true"):

Always on:

Trusted Sources

Trusted source records let you prefer domains that are known to publish correct product images for a client or brand. A trusted source should improve confidence, but it should not bypass hard checks such as wrong color, wrong model, placeholder image or low-quality asset.

Optional Playwright Sidecar

Some ecommerce pages render images only after JavaScript runs. The package keeps browser rendering out of PHP and delegates it to an optional Node sidecar.

Start the sidecar:

Sidecar endpoints:

Environment variables:

The sidecar uses Playwright when available and falls back to static HTTP+HTML extraction when browser rendering is unavailable.

AI And Vision

The package includes an optional Laravel AI SDK integration for AI-assisted candidate verification. The core pipeline does not require an LLM: deterministic source/text/quality checks still run first, and AI output is stored as supporting evidence in ai_analysis.

This keeps local development, CI and production ingestion stable even when a model provider is unavailable.

The config defaults to Regolo through padosoft/laravel-ai-regolo, while still supporting OpenAI, Anthropic and OpenRouter as alternate Laravel AI providers. AI verification is disabled by default, so the core pipeline remains deterministic and offline-friendly until you opt in with credentials.

To enable AI verification:

For Anthropic:

For OpenRouter:

By default, remote image attachments are disabled and the verifier sends product/candidate metadata only. Set PRODUCT_IMAGE_DISCOVERY_AI_ATTACH_REMOTE_IMAGE=true when you want the selected provider/model to inspect the candidate image URL directly. Keep this opt-in because not every provider/model supports remote image attachments.

Regolo is the package default because it gives Laravel applications an Italian/EU sovereign AI path through the same laravel/ai API. If you switch to Anthropic, OpenAI or OpenRouter, set model names supported by that provider.

Testing

Install PHP dependencies:

Run all PHP suites:

Run sidecar tests:

The current local verification used Herd PHP 8.4:

In a fresh offline environment, live sidecar/search/AI checks are skipped cleanly unless their credentials or URLs are provided. The current local verification with real BRAVE_SEARCH_API_KEY, real ANTHROPIC_API_KEY and remote AI image attachments enabled is:

The skipped test is the live sidecar contract. Set SIDECAR_E2E_URL to test against a real running sidecar. Live search and AI checks require their provider credentials.

Run the live AI verifier explicitly when you have a real Regolo, Anthropic, OpenRouter or OpenAI key in .env:

With PRODUCT_IMAGE_DISCOVERY_AI_ATTACH_REMOTE_IMAGE=true, this live test sends a real product image URL to the provider and should pass with 1 test, 9 assertions.

Database Tables

Safety Notes

Admin UI Guidance

This package stays headless. If you want to integrate a review/configuration experience inside an existing ecommerce admin, use docs/ADMIN_UI_UX_GUIDELINES.md. It describes the recommended vanilla JavaScript screens, components, filters, debug report viewer, guided debug-flow runner, provider credential status and API calls.

Roadmap

Recent additions (since v0.1.0):

Planned:

Contributing

Pull requests are welcome. Before opening one:

  1. Keep changes focused.
  2. Add or update tests for behavior changes.
  3. Run the PHP suite.
  4. Run the sidecar suite if you touched sidecar/.
  5. Update docs when behavior, configuration or architecture changes.

License & credits

Apache-2.0. See LICENSE.

Sister packages in the Padosoft AI stack:

Each is independently usable. None requires the others. Pick what you need.


All versions of product-image-discovery with dependencies

PHP Build Version
Package Version
Requires php Version ^8.3
illuminate/bus Version ^13.0
illuminate/cache Version ^13.0
illuminate/console Version ^13.0
illuminate/contracts Version ^13.0
illuminate/database Version ^13.0
illuminate/filesystem Version ^13.0
illuminate/http Version ^13.0
illuminate/log Version ^13.0
illuminate/queue Version ^13.0
illuminate/routing Version ^13.0
illuminate/support Version ^13.0
illuminate/validation Version ^13.0
laravel/ai Version ^0.6.5
laravel/sanctum Version ^4.2
padosoft/laravel-ai-regolo Version ^0.2.3
padosoft/laravel-ai-search-providers Version ^1.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package padosoft/product-image-discovery contains the following files

Loading the files please wait ...