Wallabag Webarchive Bundle Laravel Package

Getting Started

This assessment is written against a package at 1.0.0-alpha.1 whose release notes read only "Fixed bugs." There is no prior assessment and no package metadata in the source data, so the guidance below is deliberately procedural rather than feature-specific. Treat it as the checklist to run the moment you have the package name and repo in hand — do not skip straight to integration.

Orientation, in order:

1. composer.json — read require before you install anything. Check the illuminate/* constraint (tells you the supported Laravel range) and the php constraint. A package pinned to illuminate/support: ^10.0 will not run on Laravel 11/12 without --with-all-dependencies gymnastics.
2. extra.laravel.providers / extra.laravel.aliases — if present, service provider is auto-discovered and there is nothing to register. If absent, you must add it to config/app.php (Laravel ≤10) or bootstrap/providers.php (Laravel 11+).
3. config/ and src/ — look for a published config file and for the public surface (interfaces, facades, DTOs). Anything not in those is internal and will move.
4. CHANGELOG.md / UPGRADING.md — "Fixed bugs" is not a changelog. If these files don't exist, git diff between the previous tag and this one before upgrading.

First install, given the pre-release:

composer require vendor/package:"1.0.0-alpha.1" --with-all-dependencies
php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"  # only if you need to override
php artisan optimize:clear

First use case: wire the package into one feature test in isolation — resolve it from the container, assert the happy path — before it touches application code. At alpha, you want a failing test to tell you what broke, not a white screen in staging.

Implementation Patterns

Pin and lock. An alpha has no semver contract; a patch-level bump (alpha.1 → alpha.2) can rename methods. Use an exact constraint or ^1.0@alpha, commit composer.lock, and upgrade on a branch with CI green before merging. Never let this float on dev-main.

Bind behind your own interface. This is the single highest-value pattern for a pre-1.0 dependency:

// app/Contracts/Thing.php — yours
// app/Services/PackageThing.php — adapts the package
$this->app->bind(Thing::class, PackageThing::class);

Resolve from the container, never new the package class. When alpha.2 changes a signature, you edit one adapter instead of grepping the codebase.

Write contract tests against the public API. You cannot trust the changelog, so encode expected behavior yourself. A small suite that exercises each package call you depend on turns an opaque upgrade into a precise diff of what changed.

Gate the rollout. Config-flag the integration and ship it dark. For an alpha this costs an hour and buys you a rollback that isn't a git revert.

Prefer the facade-or-injection boundary consistently. Do not mix Package::method() and app(Package::class)->method() across the codebase — it makes it harder to trace which entry points you actually depend on when auditing an upgrade.

Gotchas and Tips

Composer will refuse to install it. The default "minimum-stability": "stable" does not resolve pre-release tags. Either use a per-package constraint ("vendor/package": "1.0.0-alpha.1", which implies the stability flag) or add "prefer-stable": true globally. Do not flip minimum-stability to dev project-wide — it silently destabilizes every other dependency.

"Fixed bugs" is an anti-signal. It tells you a fix landed but not what broke, and at alpha a bug fix is frequently a behavior change. If the repo has no CHANGELOG/UPGRADING, clone it and git diff v1.0.0-alpha.0..v1.0.0-alpha.1 -- src/ before you upgrade, then file an issue asking for structured release notes. Watch specifically for anything under src/Contracts, src/Exceptions, or a UPGRADING file appearing for the first time — those are the breaking-change tells.

Published config goes stale silently. Once you vendor:publish, your copy stops tracking upstream defaults; new keys added in a release simply won't exist for you, and you get nulls rather than errors. Before upgrading, re-publish to a temp path and diff:

php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --force --tag=config
git diff config/package.php

Caches outlive upgrades. After any install or version bump: php artisan optimize:clear (or config:clear && cache:clear && package:discover). Cached config and the package manifest are the usual cause of "I upgraded and nothing changed."

Auto-discovery needs a manifest rebuild. If the service provider is registered in bootstrap/cache/packages.php and you're running a cached build, a new provider in composer.json won't appear until php artisan package:discover runs. This is invisible in local dev (it regenerates automatically) and consistent in deploy pipelines.

Debugging resolution. php artisan about gives you environment and cache state at a glance; app()->make(Vendor\Package\Thing::class) inside php artisan tinker confirms the container binding is live and surfaces constructor dependency errors immediately. When a package throws an opaque exception, check whether it's wrapping a Laravel exception — ->getPrevious() usually reveals the real cause.

Extension points to prefer over forking. Service-provider bindings you can override after the package registers, published config, events, and macros are all upgrade-safe. Forking is not — if you find yourself editing vendor/, open an upstream issue first; at alpha the maintainer is likely to accept the patch, and you avoid carrying a permanent merge burden.

Track the stability trajectory. 1.0.0-alpha.1 signals active churn. Re-read the release notes at every alpha/beta/rc — each one is a candidate upgrade you should take deliberately on a branch, not a routine composer update. Expect the API to firm up between beta and rc; that's the moment to remove your compatibility shims, not before.