Nova Blockchain Exchange Rates Laravel Package

Getting Started

v1.0.0 is a greenfield release with a terse changelog, so treat the package source as the source of truth — there is no migration guide, no deprecation path, and no battle-tested body of Stack Overflow answers to lean on.

1. composer require <vendor>/<package> and then immediately read composer.json from vendor/<vendor>/<package>/. Check the require block for the PHP and illuminate/* constraints — on a v1.0.0 this is the fastest way to find out whether the package actually supports your Laravel version rather than trusting the README.
2. Find the entry point. Look for extra.laravel.providers in the package's composer.json. If it's there, the provider is auto-discovered; if not, you'll be registering it manually in bootstrap/providers.php (Laravel 11+) or config/app.php. Open the provider and read register() and boot() line by line — on a fresh package this is 90% of the documentation.
3. Publish and inspect configuration: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider". Even if you intend to keep defaults, publishing gives you a commented file that documents every option far better than the README will.
4. Look for publishable assets you must not skip — migrations (--tag=migrations), views, translations, JS/CSS. A missing migration publish is the single most common first-run failure.
5. First use case: get one visible result end-to-end before designing anything around it. Run php artisan list to see whether the package registers commands, run php artisan route:list if it ships routes, then resolve the package's main class out of the container in php artisan tinker and exercise its primary method once. If that works, you understand the wiring.

Implementation Patterns

Resolve from the container, never new. The package's service provider almost certainly binds an interface or a configured singleton. Constructor-inject that contract into your controllers, jobs, and console commands so the package's config and any decorators are honoured. If there is a facade, restrict it to Blade templates and quick tinker checks — facades in application code make it painful to swap the implementation later.

Wrap it in your own thin adapter. On a v1.0.0, the public API is not yet stable. Put a single application-level class (App\Services\Whatever) in front of the package and call that from your controllers, jobs, and listeners. When v1.1 renames a method or changes a return type, you edit one file instead of grepping forty.

Drive behaviour through config, not code. Publish the config file into config/ and commit it, then use env() only inside that file. Anything the package exposes as a config key (driver, queue name, timeout, base URL) belongs there so staging and production differ without a code deploy.

Respect the publish/migrate ordering. The correct install sequence is: composer require → publish config → publish migrations → php artisan migrate → clear caches. Do this in a fresh CI job too; locally you'll have cached config and a warm database hiding ordering bugs.

Test with the container, and use fakes where offered. In feature tests, $this->app->instance(Contract::class, $fake) or the package's Package::fake() if shipped. If the package makes outbound HTTP calls, confirm it's using Laravel's HTTP client so Http::fake() intercepts it — if it uses raw cURL or Guzzle directly, you'll need Http::preventStrayRequests() plus a real test double.

Integrate via events, not by patching the package. If you need to react to what the package does, look for dispatched events (they're usually in the provider or the main service) and write listeners. That keeps you upgrade-safe.

Background the slow path. Anything that hits a network or does per-record work should be pushed to a queued job you own, calling the package from inside the job. This also isolates you from a package that isn't queue-aware.

Gotchas and Tips

• Config caching bites first. After publishing or editing the package config, run php artisan config:clear. A stale bootstrap/cache/config.php silently ignores your changes and is the number one "the package is broken" false alarm.
• vendor:publish --force overwrites your edits. Publish once, commit the result, and re-publish only deliberately — diffing the new stub against your customised copy when you upgrade.
• Provider discovery is cached. If the package's commands or bindings don't appear, run php artisan package:discover and check bootstrap/cache/packages.php. A stale discovery cache after composer update produces confusing "class not found" errors.
• Deferred providers change timing. If the provider implements DeferrableProvider, its bindings don't exist until first resolved. Don't reference them in another provider's register() — move that to boot() or a later lifecycle point.
• Facade aliases aren't always registered. Manual (non-auto-discovered) packages often leave the alias out of config/app.php. Add it under aliases if the README references a facade that doesn't resolve.
• Pin the version. There is no v2 to learn lessons from. Use "vendor/package": "1.0.*" rather than ^1.0 semantics you haven't validated, and read the diff of every 1.0.x before bumping — patch releases with no changelog detail are where behaviour changes hide.
• Debugging order that actually works: php artisan about (env sanity) → php artisan package:discover (registration) → config:clear (config staleness) → dump the resolved instance from tinker and inspect it → Log::debug() inside the provider's boot() to confirm it ran at all. Nine times out of ten the failure is registration or config cache, not the package logic.
• Extension points to check before reaching for a fork: bind()/singleton() overrides in your own AppServiceProvider, Macroable traits on the package's classes, dispatched events, and any Resolver/Factory-style interface the package accepts in config. Overriding a binding in AppServiceProvider::register() is far cheaper than maintaining a fork — and on a v1.0.0 you may well end up forking, so confirm the license permits it before you build anything substantial on top.
• Watch the package's own migrations. They often create tables with generic names. If you already own a table by that name, publish the migration and rename it before running migrate.