odinns/laravel-wayback-flipbook

Build PNG timelines for one archived page through Wayback Machine history.

v1.1.0 2026-04-30 13:09 UTC

Requires

• php: 8.3.* || 8.4.*
• illuminate/console: ^12.0 || ^13.0
• illuminate/filesystem: ^12.0 || ^13.0
• illuminate/support: ^12.0 || ^13.0
• odinns/laravel-wayback-machine: ^1.0
• symfony/process: ^7.0 || ^8.0

Requires (Dev)

• larastan/larastan: ^3.0
• odinns/coding-style: ^1.0.3
• odinns/phpstan-pest-this: ^1.0
• orchestra/testbench: ^10.0 || ^11.0
• pestphp/pest: ^3.0 || ^4.0
• pestphp/pest-plugin-laravel: ^3.0 || ^4.0
• rector/rector: ^2.0

MIT

• Odinn Sorensen

• laravel
• archive
• flipbook
• internet-archive
• wayback-machine

README

Build PNG timelines for one archived page through Wayback Machine history.

This package takes one page URL, finds archived captures for that exact page, renders selected captures through raw Wayback replay, and writes PNG frames plus a JSON manifest.

It does not crawl a site. It does not follow links. It does not mirror sibling pages. If you ask for https://example.com/page, that page is the whole job.

Installation

composer require odinns/laravel-wayback-flipbook
npm install
npx playwright install chromium

Laravel discovers the service provider automatically.

The package depends on odinns/laravel-wayback-machine for CDX access and Wayback replay URL generation.

Usage

Render one frame per year, oldest to newest:

php artisan wayback:flipbook https://example.com/page

Plan the run without screenshots:

php artisan wayback:flipbook https://example.com/page --dry-run --json

Render newest to oldest:

php artisan wayback:flipbook https://example.com/page --direction=newest-first

Bound a larger run:

php artisan wayback:flipbook https://example.com/page --sample=all --from=2020 --to=2024

Write somewhere specific:

php artisan wayback:flipbook https://example.com/page --output=storage/app/page-history

Export an MP4 from an existing manifest and frames:

php artisan wayback:flipbook:export storage/app/page-history/manifest.json --fps=2

MP4 export is a post-processing step. It reads the manifest, uses the PNG frame order already written there, and does not query Wayback or render screenshots again. It requires ffmpeg on your PATH.

Default output:

storage/app/wayback-flipbook/{safe-page}/{run-timestamp}/

Artifacts:

manifest.json
frames/0001-20200101000000.png
frames/0002-20210101000000.png

Command Options

wayback:flipbook {url}
    --from=
    --to=
    --status=200
    --mime=text/html
    --sample=first-per-year
    --direction=oldest-first
    --limit=
    --delay-ms=2000
    --output=
    --viewport=1280x900
    --full-page
    --timeout=60
    --dry-run
    --json
    --force

wayback:flipbook:export {manifest}
    --output=
    --fps=2
    --force

Sampling modes:

• all
• first-per-day
• first-per-month
• first-per-year
• unique-digest
• latest-per-url

--sample=all without --limit, --from, or --to is blocked unless you pass --force.

Screenshot Defaults

Published config controls the default screenshot viewport, timeout, and Wayback delay:

return [
    'delay_ms' => 2000,
    'viewport' => '1280x900',
    'timeout' => 60,
];

Command options override config for a single run:

php artisan wayback:flipbook https://example.com/page --viewport=1920x1080 --timeout=90 --delay-ms=1000

Use --full-page when you want the whole page height. The width still comes from --viewport.

If you plan to export MP4, prefer viewport screenshots. Full-page captures can produce frames with different heights across archived captures, and ffmpeg expects one stable frame size for video. This package does not scale, crop, or pad frames yet. Use --full-page only when you are fine handling that yourself.

Laravel Surface

The package registers two commands:

wayback:flipbook
wayback:flipbook:export

It publishes one config file:

php artisan vendor:publish --tag=wayback-flipbook-config

There are no migrations, queues, views, routes, middleware, or facades.

Development

composer validate --strict
composer test:all
npm install
npx playwright install chromium
git diff --check

Versioning

Versions come from Git tags. Composer should not have a version field.

Contributing

Keep the package page-targeted. Do not add crawling, host-wide exports, or animation formats as a casual side quest. MP4 export stays explicit and manifest-driven.

Security

Report security issues through GitHub Security Advisories:

https://github.com/odinns/laravel-wayback-flipbook/security/advisories/new

Changelog

See CHANGELOG.md.

License

MIT. See LICENSE.