Eddy Backup Cli Laravel Package

Getting Started

This is the first tagged release (1.0.0), so there is no upgrade path, no deprecation history, and no community track record to lean on. Treat the install as an evaluation, not a migration.

1. Read composer.json first. Confirm the require block's php and illuminate/* constraints actually match your app's Laravel version. A 1.0.0 package is often pinned to a narrow range, and this is the single most common reason an install fails before you write a line of code.
2. Install into a scratch branch, not main:

   composer require vendor/package:^1.0
   

3. Check whether the service provider was auto-discovered. Look in vendor/vendor/package/composer.json for an extra.laravel.providers entry. If it's absent, you must register the provider manually in bootstrap/providers.php (Laravel 11+) or config/app.php (Laravel 10 and below).
4. Publish and inspect config before touching code:

   php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
   

   Read the published config top to bottom — it usually reveals the package's mental model faster than the README does.
5. Check for migrations. php artisan vendor:publish --tag=migrations and then review them before running php artisan migrate. Never run an unfamiliar package's migrations against a database you care about without reading them.

Where to look first, in order: published config → service provider register()/boot() → src/ public classes → README examples → tests/.

First use case: pick one non-critical, easily reverted code path — a single artisan command, a queued job, or one read-only endpoint. Do not introduce a new package at the centre of your domain model until you've confirmed it behaves under your config cache and queue setup.

Implementation Patterns

Resolve through the container, never new. Even if the package exposes concrete classes, bind them (or an interface you define) in a service provider so you can swap or fake them:

$this->app->bind(MyWrapper::class, fn ($app) => new MyWrapper($app->make(PackageClient::class)));

Wrap third-party surface area behind your own boundary. For a 1.0.0 dependency, a thin adapter class (App\Support\PackageAdapter) with 3–5 methods costs an hour and caps the blast radius of a 1.1 breaking change.

Config-driven, env-backed. Put package credentials and toggles in config/package.php, read from .env, and reference them only via config('package.key'). This keeps you compatible with php artisan config:cache and lets you override per environment.

Publishing strategy as a pattern. Decide up front whether you own the published config file or track upstream. Committing published config to VCS and re-publishing with --force after each upgrade is a common workflow — just be aware --force silently discards local edits.

Queue and command integration. If the package performs I/O (HTTP, storage, mail), wrap calls in a job rather than invoking inline in a request. A 1.0.0 package's retry/timeout semantics are usually undocumented, so your job's $tries/$backoff become the safety net.

Testing. Fake at your adapter boundary, not the package's. If the package ships its own fake or test double, prefer it, but add one integration test that hits the real thing — a fake proves your code matches your assumptions, not the package's behaviour.

Gotchas and Tips

• Pin the constraint. Use ^1.0 at minimum; consider 1.0.* until you've read the 1.1 changelog. Initial releases frequently ship minor-version changes that are breaking in practice.
• Config cache is the classic silent failure. Package defaults merged in register() behave differently once config:cache is warm. Always re-test with php artisan config:cache before deploying, and php artisan optimize:clear when debugging.
• Auto-discovery can be disabled globally. If the app calls $app->withProviders() with an explicit list, or you run in a custom skeleton, discovery may not fire. Symptom: Target class [...] does not exist or "class not found" on a facade alias.
• Migrations are fire-once. Publishing won't re-publish files that already exist. After an upgrade, compare the vendor migration files against your published copies by hand — an initial release has no upgrade guide to tell you this.
• Facade aliases drift. Auto-aliased facades resolve from extra.laravel.aliases. If you've aliased the same short name for your own class, one will silently win.
• Unpublishable extension points. Before committing, check whether the provider binds concrete classes without interfaces. If so, your only override lever is container bind() in your own provider registered after theirs — order matters, and this is worth confirming early.
• Debugging toolkit: php artisan about (confirms provider load), php artisan tinker to app()->make(...) and inspect the resolved object, and composer show vendor/package to verify which version actually landed versus what you requested.
• Watch the issue tracker for the first 30 days. For a 1.0.0 package, upstream bug-fix velocity is the best predictor of whether it's safe to build on. If the repo has no CHANGELOG, no tests directory, or no CI config, treat the package as experimental regardless of the version number.