Select Laravel Package

Getting Started

v1.0.1 is a patch release, so there is no migration work — but it does rename the published config file to use the sb- prefix, which is the first thing to verify on an existing install.

1. composer require <vendor>/<package> (or composer update <vendor>/<package> if already installed).
2. Run php artisan vendor:publish without flags first and read the interactive list — confirm the tag and the exact destination filename (config/sb-*.php). Publish with the explicit tag so you don't accidentally publish every package's assets.
3. Open the freshly published config/sb-*.php and scan the top of the file. Most packages of this shape document their env keys as comments; mirror those into .env with the matching SB_ prefix rather than editing the config file directly.
4. php artisan config:clear (or config:cache in a deployed environment) before testing. Config changes are invisible until the cached config is rebuilt.

First useful use case: publish the config, set the two or three env values the file actually requires (usually an enable flag, a driver/endpoint, and a credential), then exercise the package's simplest entry point — a facade call, an injected service, or an artisan command — from php artisan tinker. That confirms wiring end-to-end before you touch application code.

Where to look first, in order: the package's README install section → the published config/sb-*.php (it is the most accurate documentation of available options) → the service provider's register()/boot() to see what is bound into the container and under what keys.

Implementation Patterns

Publish once, configure via env. Treat config/sb-*.php as read-only scaffolding. Commit it to the repo so the option set is visible in code review, but drive every environment-specific value from .env. This keeps staging/production differences out of git and makes rollbacks a matter of reverting env, not code.

Wrap the package behind a thin application-level abstraction. Even for a small package, add a single App\Services\* class or a bound interface that your controllers and jobs depend on, and let that class call the package. When the config key names change (as they did with the sb- prefix in this release), you edit one file instead of grepping the codebase.

Multi-environment config. If the package reads credentials or endpoints, define the keys in config/sb-*.php with env('SB_...') fallbacks, then override per environment. For tests, set the values in phpunit.xml or a TestCase::setUp() config override rather than publishing a separate test config file.

Feature-flag the integration. Most config-driven packages expose an enabled-style key. Gate calls behind it so local and CI runs don't attempt outbound connections, and so you can disable the integration in an incident without a deploy.

Queue and event integration. If the package emits events or dispatches jobs, register listeners in EventServiceProvider rather than inside the package's config callbacks. This keeps behaviour discoverable via php artisan event:list and testable with Event::fake().

Deployment sequence. In your deploy script, order matters: composer install → config:cache → any package-specific warm-up command. Never cache config before the new env values are in place; a cached config built against stale env is the single most common "the fix didn't work" report.

Gotchas and Tips

The v1.0.1 rename is a silent-failure risk. If you installed v1.0.0 and published the old, unprefixed config file, the package now looks for config/sb-*.php. Depending on how the package resolves defaults, the old file will either be ignored entirely (you silently get package defaults — often the dangerous outcome, since defaults may be permissive or point at a sandbox endpoint) or trigger a "config not found" exception. After upgrading:

• ls config/ | grep sb- — the file must carry the prefix.
• Re-publish to get the new filename, then diff it against your old file and port your customisations across. php artisan vendor:publish --force will overwrite local edits without warning; copy the file aside first.
• Look for a leftover config/ file matching the old name and delete it, so nobody edits the wrong file six months later.

Config caching masks the fix. php artisan config:cache snapshots the entire config tree. Deleting the old file or changing env without re-caching leaves the old values live. Always php artisan config:clear locally and re-run config:cache on deploy.

Publish tags vs. provider. vendor:publish without a tag publishes every registered package's assets — a common way to accidentally dump an unrelated package's migrations into your app. Use --tag= and confirm the tag name interactively the first time.

Env parsing traps. Unquoted values containing #, spaces, or = get truncated by phpdotenv. Quote anything non-trivial, and remember env() returns null — not false — for a missing key in some contexts; use explicit env('SB_FLAG', false) defaults.

Don't call env() outside config files. Once config is cached, env() returns null everywhere except config/*.php. If the package docs show an env() call in a service provider or command, route it through config.

Debugging order. (1) php artisan config:show on the specific key to confirm the resolved value, not what you think is in .env. (2) php artisan about to confirm the package is discovered and the version is actually the one you expect — a stale composer.lock on a shared branch is a frequent culprit. (3) Check whether the config file is being merged by the package provider or read directly; merged config means your app-level file wins, direct reads mean the package's own defaults do.

Extension points. Before subclassing or decorating package internals, check whether the config file exposes a driver/class key — most packages of this shape let you swap the implementation via config, which survives upgrades far better than extending an internal class. Similarly, prefer the package's published interface/contract for type-hints so a container binding swap works.