Nova Honeybadger Laravel Package

Getting Started

Version 0.0.1 is an initial release — there is no changelog history, no documented API surface, and no established compatibility contract. Treat the first hour as due diligence rather than integration.

1. Read composer.json before installing. The only reliable compatibility signal at 0.0.1 is the constraint block. Check require.php, require.illuminate/* (or laravel/framework), and the extra.laravel.providers / extra.laravel.aliases keys. If the illuminate/* constraints are loose (^10.0|^11.0) assume they were guessed, not tested.
2. Pin exactly, not with a caret. composer require vendor/package:0.0.1 --prefer-dist. Note the Composer caret trap: ^0.0.1 resolves to >=0.0.1 <0.0.2, and ^0.1.0 to <0.2.0 — pre-1.0 caret constraints are far tighter than most developers expect, and 0.0.x patch bumps are where breaking changes actually land.
3. Install on a throwaway branch and run php artisan package:discover --ansi explicitly so you can see whether auto-discovery fires or silently doesn't.
4. Inventory what it ships. composer show -a vendor/package for the file list, then look for config/, database/migrations/, routes/, src/Providers/, and any README. At 0.0.1 these are the entire documentation.
5. First use case: one endpoint, one job. Pick a single low-risk call site — a console command or an isolated queued job is better than a controller — and exercise it with php artisan tinker before wiring it into a request path. You are validating that the service container bindings resolve and that nothing throws on boot.

The realistic first-run loop is: publish config, boot the app, call one method, inspect the exception trace. Budget for that rather than for a working integration.

Implementation Patterns

Adapter-wrap everything. At 0.0.x the package has made no backward-compatibility commitment. Do not reference its classes or facades directly from controllers, models, or jobs. Define your own narrow interface in app/Contracts/, implement it in a small app/Services/*Adapter that delegates to the package, and bind the implementation in a dedicated application service provider. When 0.0.2 renames a method, you change one file.

Resolve from the container, never new. If the package registers a singleton or a driver/manager, app(Contract::class) keeps you compatible with any future binding changes and makes the swap to a test double trivial. Direct instantiation couples you to a constructor signature that is very likely to change.

Publish config, then stop editing the vendor copy. Use php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" rather than guessing a --tag. Publish first, then make every tweak in config/package.php and back it with an env var. Keep a short comment in that file noting the package version it was published from — published configs are not automatically updated on upgrade, and a stale config is the most common post-upgrade failure.

Isolate behind a feature flag. A config-driven flag (config('features.package_x')) around the call sites costs nothing on day one and gives you a one-line rollback that doesn't require a deploy revert when a patch release misbehaves.

Test at the boundary. Use orchestra/testbench if you need to assert on the package's own behaviour, but in application tests prefer faking your adapter. If the package ships anything stateful (an HTTP client, a cache, a queue interaction), check for a ::fake() helper or Http::fake() coverage before writing integration tests against the real implementation.

Upgrade with evidence. Pin the version, and when 0.0.2 arrives, diff vendor/vendor/package between the two tags (composer show -a lists the version, or diff the GitHub tags directly) before bumping. With no changelog, the source diff is the changelog.

Gotchas and Tips

• 0.0.1 means no SemVer guarantee. Composer will happily resolve a patch bump that removes a method. Your composer.lock is the only thing protecting you; commit it and don't run composer update broadly while the package is pre-1.0.
• Auto-discovery may be absent. If extra.laravel.providers is missing from composer.json, you must register the provider in bootstrap/providers.php (Laravel 11+) or config/app.php (10 and below). A "class not found" at boot is usually this, not a broken package.
• Aliases moved. In Laravel 11+, facade aliases are auto-resolved and config/app.php's aliases array is gone. Docs and snippets written against L9/L10 will mention registering alias entries that no longer exist.
• Config cache bites after publishing. php artisan config:cache will freeze the package config. If a value appears ignored in production but works locally, you are looking at a stale config cache — php artisan config:clear first, before debugging the package.
• Migrations are opt-in and unordered. Published migrations carry their own timestamps; if the package adds tables other migrations of yours reference via foreign keys, ordering can break. Publish early in the project, not after your schema is set.
• Migrations don't roll back cleanly at 0.0.x. If the package's down() methods are stubs, migrate:rollback can leave orphaned tables. Snapshot the database before the first migrate on a non-local environment.
• Debugging entry points: php artisan about --only=environment for the resolved provider list, php artisan package:discover -v for discovery failures, and APP_DEBUG=true plus Log::debug() inside the adapter for binding issues. composer dump-autoload -o resolves a surprising number of "class not found" reports that are really stale autoload maps.
• Extension points to inspect while the codebase is small: whether the service provider binds an interface you can rebind, whether the main class implements Macroable, whether there's a manager/driver pattern with a public extend() method, and whether container bindings are singleton or bind. At 0.0.1 the entire source is readable in a few minutes — do that now, because it will not stay small.
• No tests, docs, or CI signals yet. Absence of a test suite and a changelog is the headline risk, not a detail. Weigh that against the alternative package, and factor the cost of the adapter wrapper into the decision.