Breadcrumbs Laravel Package

Getting Started

1. Install the package with Composer and let Laravel discover the service provider:

   composer require <vendor>/<package>
   

2. Publish the package config:

   php artisan vendor:publish --tag=sb-config
   

3. Confirm the published config is named with the sb- prefix, for example:

   config/sb-package.php
   

4. Clear cached config before testing:

   php artisan config:clear
   

5. Look first at:
   • config/sb-*.php for credentials, defaults, and feature flags.
   • The package service provider for bindings and publish tags.
   • The main facade/helper or injected service class for the public API.
   • Published migrations, if the package stores data.

A good first use case is a single read/write flow through the package’s main service: configure the sb- config file with environment-backed values, resolve the service from the container, perform one operation, and assert the result in a feature test.

Implementation Patterns

• Publish once per project, configure through env vars. Commit config/sb-*.php with safe defaults and use SB_* environment variables for secrets and per-environment values.
• Resolve the package service from the container. Prefer constructor injection over facades in application services, jobs, and tests:

  public function __construct(private PackageService $service) {}
  

• Use config overrides for tests. Set the sb- config keys in setUp() or phpunit.xml rather than mocking internal classes:

  config(['sb-package.driver' => 'fake']);
  

• Treat published config as application code. Do not edit files under vendor/; publish and override.
• Keep package operations behind a thin application wrapper. If the package API changes, only the wrapper needs updating.
• Run config caching in deployment. After publishing or changing sb- config, run:

  php artisan config:cache
  

• Use publish tags deliberately. If the package offers separate tags for config, migrations, and assets, publish only what the application needs.
• Integrate through events and queues where supported. Dispatch package operations from jobs when they are slow or external, and listen for package events instead of polling state.

Gotchas and Tips

• v1.0.1 changed config file naming to use the sb- prefix. If you published config under v1.0.0, the package may no longer read that file. Re-publish the config, compare it with your old file, and remove or rename the stale config.
• Check both filename and config keys after upgrading. A config file can exist but still be ignored if its name or publish tag does not match. Verify with:

  php artisan vendor:publish --tag=sb-config --force
  php artisan config:clear
  

• Config cache can mask the fix. After upgrading, always run php artisan config:clear locally and php artisan config:cache in deployment. A stale cached config can make it appear that the new sb- file is not loaded.
• Do not assume the old file is harmless. Laravel loads all PHP files in config/, so a leftover pre-fix config can create duplicate or misleading keys. Remove it after migrating values.
• Use the package publish tag, not a hard-coded path. The v1.0.1 fix is specifically about naming; relying on published file paths can break across patch releases.
• Debug config resolution with:

  php artisan tinker
  >>> config('sb-package')
  

  Also confirm the service provider is registered with php artisan about.
• Extension points to prefer: container bindings, published config, package events, and macros. Avoid subclassing vendor internals unless the package documents it as stable API.
• Pin the version in CI. Because this release corrects config naming, ensure CI installs v1.0.1 or later and runs a fresh config publish/cache step rather than reusing a cached vendor/ or bootstrap/cache/ directory.