Soon Bundle Laravel Package

Getting Started

1. Install the package: composer require <vendor>/<package>.
2. Read the README first. v1.0.1 ships the first real documentation, so this is the authoritative source for install steps, config keys, and usage examples.
3. Publish the configuration template (new in this release):

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

   (Check the README for the exact --tag; some packages tag it config, others package-config.)
4. Open config/<package>.php and set the options you need (credentials, driver, table names, etc.). The template documents each key with inline comments.
5. First use case: after publishing and editing the config, resolve the package from the container (facade, injected service, or helper) and exercise one read-only path against a staging environment before wiring it into a feature.

If you're upgrading from v1.0.0, the package may now expect config keys that didn't exist before — publish the template so the config is complete, then diff it against anything you'd already configured.

Implementation Patterns

• Publish once, override via .env. Treat the published config file as structure, not secrets. Keep the config file in the repo, drive environment-specific values through env() calls inside it.
• Config-driven behavior. Prefer changing options in config/<package>.php over subclassing or monkey-patching. The config template is the intended extension point.
• Service container overrides. In a service provider's register()/boot(), merge or override config values before the package boots if you need programmatic control:

  $this->mergeConfigFrom(base_path('config/<package>.php'), '<package>');
  

• Testing. Set config in setUp() with config()->set('<package>.key', $value) rather than mutating the published file. This keeps tests isolated and fast.
• Multi-tenant / multi-connection setups. Publish the config per environment and use runtime config overrides (config()->set(...)) scoped to the request or job, then restore in a finally block.
• Local-only publishing. Commit the config template; do not re-run vendor:publish in production deploys — it can overwrite operator edits.

Gotchas and Tips

• vendor:publish is non-destructive by default. It won't overwrite an existing config file. Use --force deliberately, and diff before doing so — the v1.0.1 template may rename or remove keys.
• config:cache and env(). Once you run php artisan config:cache, env() only resolves inside config files. Keep all environment reads in config/<package>.php, never in application code that consumes the package.
• Missing config keys after upgrade. Going from v1.0.0 to v1.0.1 without republishing can leave the package reading null for new keys. Republish (or copy the new keys manually) if behavior looks off.
• Tag mismatch. vendor:publish without --tag publishes everything from every provider, which is noisy and can overwrite unrelated config. Always pin the provider or tag.
• Config caching during development. Forget to re-run php artisan config:clear after editing the file and you'll debug a stale value — check this first.
• Extension points. The config template usually exposes driver/class bindings; resolving a custom implementation through the container is cleaner than editing vendor code. Confirm the README documents a binding key before assuming one exists.
• Diagnosing the package's view of config. php artisan tinker → config('<package>') shows the live resolved array. Do this before anything else when setup appears broken.