dogado MugShot

A small service that helps you take screenshots of web pages and generate PDFs from HTML content.

Requirements

• PHP 8.4+
• MariaDB / MySQL
• Node.js for Puppeteer

Installation

Clone the repository and install dependencies:

git clone https://github.com/dogado-group/mugshot.git mugshot
cd mugshot
composer install --no-dev -o

Set up your environment and generate an application key:

cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan storage:link

Install Puppeteer:

npm install puppeteer --global

Docker / Laravel Sail

The project ships with a docker-compose.yml for local development via Laravel Sail:

./vendor/bin/sail up -d
./vendor/bin/sail artisan migrate

Authentication

API endpoints are protected with Laravel Sanctum. Include a Bearer token in every request:

Authorization: Bearer <your-token>

Usage

Capture Screenshot

POST /api/v1/screenshot
Authorization: Bearer <token>
Content-Type: application/json

Parameter	Type	Required	Description
url	string	yes	URL of the page to capture (http / https)
width	integer	no	Viewport width in pixels
height	integer	no	Viewport height in pixels
fullPage	boolean	no	Capture the full scrollable page
deviceScale	integer	no	Device scale factor, between 1 and 3
quality	integer	no	JPEG quality, between 30 and 100 (ignored for PNG)
delay	integer	no	Seconds to wait before capturing (useful for JS-heavy pages)
fileExtension	string	no	Output format: jpeg (default) or png
response	string	no	Response mode: inline (default), download, or json

Generate PDF

POST /api/v1/pdf
Authorization: Bearer <token>
Content-Type: application/json

Parameter	Type	Required	Description
content	string	yes	Raw HTML content to render as a PDF
response	string	no	Response mode: inline (default) or download

Health Check

GET /api/v1/_healthz

Returns application health status. No authentication required.

Development

Running tests

composer test
# or directly
./vendor/bin/phpunit

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

License

The MIT License (MIT). Please see License File for more information.