Contact Bundle Laravel Package

Getting Started

v0.1 is the first public release, so treat it as a pre-stable API: pin it exactly ("vendor/package": "0.1.*") and expect breaking changes before 1.0.

1. Install and inspect the package manifest first.

   composer require vendor/package:0.1.*
   

   Before writing any code, open the package's composer.json to confirm:

   • the service provider class under extra.laravel.providers (auto-discovered in Laravel 5.5+, so no manual registration should be needed),
   • any aliases under extra.laravel.aliases,
   • the required PHP and illuminate/* constraints — a mismatch here is the most common reason a fresh v0.1 install silently does nothing.

2. Publish and read the config, even if you think you don't need to.

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

   The published file is the best documentation a 0.1 release has. Defaults tell you which features are opt-in vs. on-by-default, and the config/ file is usually the only stable contract at this stage.

3. Check migrations and routes before your first request.

   php artisan migrate --pretend   # inspect before running
   php artisan route:list | grep -i <package-prefix>
   

   A first public release may ship migrations that run automatically or only when published — verify which, so you don't get surprised in CI.

4. First use case: the README's happy path in a scratch route or tinker session. Get one end-to-end call working in php artisan tinker (or a throwaway route) against a local database before wiring it into application code. At v0.1 the highest-value thing you can establish is a minimal reproducible "it works" baseline you can return to when the next release breaks something.

Implementation Patterns

• Wrap the package behind your own thin abstraction. Even a single interface plus one adapter class (App\Support\<Thing>\<Thing>Interface → VendorPackageAdapter) costs an hour now and saves a refactor when 0.2 renames methods. Bind it in a PackageServiceProvider of your own.
• Feature-flag it. Put the integration behind a config flag (config('features.<package>')) so you can disable it in production without a deploy if v0.1 misbehaves:

  // config/features.php
  'billing_sync' => env('FEATURE_BILLING_SYNC', false),
  

• Isolate the integration in jobs/events, not controllers. Call the package from a queued job so failures are retryable and don't block the request cycle. This also gives you a natural place to add logging and idempotency keys.
• Test against the package's own fakes where provided, and your abstraction otherwise. If the package ships a fake or an in-memory driver, bind it in tests/TestCase::setUp() and never hit the real backend in unit tests. If it doesn't ship one, mock your interface, not the package class — mocking vendor internals is brittle across patch releases.
• Snapshot the behavior you depend on. Write one or two "characterization" tests that assert the exact output/shape you rely on. When v0.2 lands, those tests failing is your early-warning system that the contract moved.
• Config-driven environment differences. Keep all package config in config/<package>.php referencing env(), and never call env() outside config files — it returns null once php artisan config:cache has run.
• Log the package version at boot in non-production (or expose it on a health endpoint) so you can confirm what's actually deployed after a rollback.

Gotchas and Tips

• API instability is the headline risk. v0.1 has no semver guarantees. Avoid extending package classes, overriding protected methods, or type-hinting concrete vendor classes in your own signatures — those are exactly the surfaces that break first.
• config:cache hides new config keys. After upgrading, always php artisan config:clear (and in deploys, config:cache as a fresh build step). A missing key usually manifests as a confusing "undefined index" or a silently disabled feature rather than a clear error.
• Auto-discovery can be cached. If the provider isn't loading, check bootstrap/cache/packages.php and run php artisan package:discover. This bites most often in Docker images built before composer install completed.
• Publish tags are easy to get wrong. vendor:publish --tag=<package>-config may not exist yet in a 0.1; fall back to --provider= and inspect what actually landed with git status.
• Migrations in 0.1 are often not reversible. Run migrate --pretend first and check the down() method exists before you run it anywhere that matters. If down() is empty, take a database snapshot before the first migrate on shared environments.
• Facade/alias collisions. Check extra.laravel.aliases for names that clash with existing facades; a duplicate alias resolves to whichever provider registers last and produces genuinely confusing bugs.
• Queue and serialization pitfalls. If the package's objects get queued, verify they serialize cleanly (SerializesModels). If not, keep them out of job payloads — pass IDs and re-resolve inside the job.
• Timeouts and retries are your responsibility. A 0.1 release rarely has sensible defaults; set explicit HTTP timeouts and $tries/$backoff on any job wrapping the package rather than trusting library defaults.
• Debugging technique: wrap the call in a try/catch, log get_class($e) plus config('app.debug') ? $e->getTraceAsString() : null, and re-throw. Vendor exceptions in early releases are frequently unhelpful (InvalidArgumentException with no context), and having the wrapper in place from day one makes triage far faster.
• Extension points to prefer: published config, published views/migrations, container bindings, and Laravel events. These are the surfaces package authors most reliably keep stable; subclassing is the least stable.
• Watch the issue tracker and CHANGELOG between 0.1 and 0.2. For a first public release, the changelog is thin by definition — the commit history and open issues are where the real "known limitations" live.