Namayaan Laravel Package

Getting Started

• Install with composer require vendor/package:^0.1.0. On a 0.x release, pin the constraint explicitly and commit composer.lock — minor bumps can still break BC at this stage.
• Check for a service provider in composer.json under extra.laravel.providers (auto-discovery). If it's not auto-discovered, register it manually in bootstrap/providers.php (Laravel 11+) or config/app.php.
• Publish any assets and confirm the config surface before writing code:

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

• Where to look first: the README "Quick start", then config/<package>.php for the knobs you'll actually touch, then src/ for the public entry points (facade, contract/interface, or manager class). Skip internal classes — they're not your integration surface.
• First use case: get the simplest end-to-end path working — resolve the package's main class from the container and exercise one method. If it resolves cleanly via the container, the provider wiring is correct.

Implementation Patterns

• Resolve through the container, not new. Prefer dependency injection or the facade/contract so the package can be swapped in tests and its config/services are honoured. Type-hint the package's contract (if one exists) rather than the concrete class.
• Config over code. Drive behaviour through the published config file and .env where supported. Keep overrides in config and let the package read them — don't reach in and mutate internal state.
• Feature-test at the boundary. Treat the package as an external dependency: fake or stub it behind your own abstraction, and write one or two integration tests that hit the real code path to catch wiring regressions when you bump versions.
• Wrap it in your own thin service. For anything beyond a one-liner, create an app-level service/action that wraps the package. That isolates the 0.x churn to a single class and keeps the rest of your codebase stable across upgrades.
• Watch for side channels. If the package dispatches events, registers jobs, or hooks into the scheduler, subscribe to those explicitly in your own listeners rather than relying on package defaults. This makes cross-cutting behaviour (logging, retries, alerting) yours to control.
• Queue/async awareness. If it does I/O (HTTP, mail, storage), check whether it ships queueable actions and whether retry/backoff is configurable. Wire those into your queue config early rather than retrofitting after production.
• Testing integration. If the package offers fakes or a testing helper, register them in your TestCase/Pest.php so the fakes are available app-wide.

Gotchas and Tips

• 0.1.0 means unstable API. Read the upgrade notes on every minor bump, pin versions, and don't build deep coupling to internal classes — only to documented public API.
• Config caching surprises. After changing package config, run php artisan config:clear / config:cache in your deploy pipeline. Config read at boot in the provider is a common source of "it works locally but not in production" bugs.
• Auto-discovery can be silently off. If the facade errors with "class not found" or services don't resolve, first confirm the provider is registered and composer dump-autoload has been run.
• Publishing vs. referencing. Publish config only when you need to change values; otherwise let package defaults ship and upgrade cleanly. Published config files don't auto-update with new releases.
• Facade vs. injection in tests. Facade calls without the provider booted will fail in unit tests — boot the package in your test case or use createApplication/RefreshDatabase appropriately.
• Debugging. Start with php artisan about and the package's log channel/driver config. If a call fails opaquely, drop to the container: app()->make(YourContract::class) to confirm resolution, then trace the config values it reads.
• Extension points. Look for bound contracts or a manager class registered in the container — overriding the binding in a service provider is the sanctioned way to swap behaviour without forking. If there's no contract yet (common at 0.1.0), wrapping it yourself is the pragmatic extension point until a stable extension API lands.
• Report, don't patch. On a fresh major (0.x), file issues upstream rather than patching vendor/. Keep a note of the API surface you actually rely on so you can track it against changelogs.