Oneall Bundle Laravel Package

Getting Started

The 1.0.0 release is the first stable tag, so treat it as the baseline contract: the public API, config keys, and published assets are now covered by semver. There is no prior assessment to diff against, so verify the surface yourself rather than assuming stability from a pre-1.0 branch.

First moves, in order:

1. Read the service provider. Open src/*ServiceProvider.php (or Providers/) before anything else. It tells you what is bound into the container, which singletons are registered, what is publishable, and whether anything is deferred. Ninety percent of "how do I use this" questions are answered there.
2. Check what is publishable. Look for publishes() calls — config, migrations, views, translations, assets. Run php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" --tag=config (adjust tag) and read the generated config file end to end. The config file is the package's de facto documentation.
3. Read composer.json. Confirm the illuminate/* constraints against your Laravel version, and check extra.laravel.providers / aliases for package auto-discovery. If discovery is declared, you do not register the provider manually.
4. Skim the contracts, not the implementation. src/Contracts/ (or interfaces) shows what is swappable and what is safe to depend on. Anything you can type-hint against an interface is a stable seam; anything you resolve as a concrete class is an implementation detail.
5. Run the test suite once locally (composer test or vendor/bin/phpunit) if the package ships tests — it confirms the package works against your PHP/Laravel combo before you build on it.

First use case: get the happy path working end to end in a throwaway route or an artisan tinker session before wiring it into application code. Resolve the package's main entry point from the container (app(MainClass::class)), run one operation, and inspect the result. This surfaces missing migrations, missing config keys, and required env vars in about two minutes.

Implementation Patterns

Resolve from the container, never new. The package almost certainly registers bindings so that config, HTTP clients, and loggers are injected. Constructing the class yourself bypasses that and usually produces "config is null" errors in tests.

public function __construct(private PackageClient $client) {}

Prefer the facade for terse call sites, the interface for testability. Facades are convenient in controllers and Blade; injecting the underlying contract is better in services and jobs because it keeps the dependency explicit and lets you swap in a fake without Facade::shouldReceive.

Wrap third-party calls in your own thin adapter. Even at 1.0.0, the package's method signatures may shift in a 2.x. A single App\Support\PackageAdapter class that delegates means a future upgrade touches one file instead of forty.

Configure per-environment, not per-call. Publish the config, commit it, and drive environment differences through .env values referenced in the config file. Resist the urge to mutate config at runtime (config(['package.key' => ...])) inside request handling — it is invisible to anyone reading the config and it does not survive Octane workers cleanly.

Use the package's queue integration rather than rolling your own. If it ships jobs or a queue config block, prefer those — they typically handle retries, backoff, and serialization correctly. If you need to call it from a job, keep the job payload small (IDs, scalars) and re-resolve the client inside handle().

Testing pattern: bind a fake in setUp() via the container rather than hitting the network.

protected function setUp(): void
{
    parent::setUp();
    $this->app->instance(PackageClientContract::class, new FakePackageClient());
}

If the package ships its own fakes or Http::fake()-compatible clients, use them — they track the package's own request shapes and will not drift.

Integration tip: if the package exposes events, listen to them rather than polling or subclassing. Event listeners are the lowest-coupling integration point and survive internal refactors.

Gotchas and Tips

• Config caching bites after upgrade. php artisan config:cache will freeze any config keys added in 1.0.0. After upgrading, always run php artisan config:clear (and optimize:clear in production) before debugging a "config value is missing" error.
• Publish-then-merge. vendor:publish --force will happily overwrite your edited config and migrations with the package defaults. Publish once, record the published file paths in your README or onboarding doc, and diff against the package's stubs when upgrading instead of re-publishing.
• Auto-discovery vs. manual registration. If you registered the provider by hand and the package declares extra.laravel.providers, you will get double registration — often visible as duplicated event listeners or a "class already bound" style error. Pick one.
• Migrations. Check whether the package loads migrations from its own directory (loadMigrationsFrom) or expects you to publish them. If it publishes, they become your migrations — you own naming collisions and rollback order. Timestamp collisions with app migrations are common; rename if artisan complains.
• Deferred providers and Octane. If the provider is deferred, container bindings resolve lazily and may behave differently under long-running workers. If you run Octane, clear any per-request state in a listener on RequestReceived / RequestTerminated as the package docs suggest.
• Version pinning. At 1.0.0 you are now on semver. Pin with a caret (^1.0) and read the CHANGELOG before every minor — "minor" here means features only, but Laravel packages frequently ship behavior changes in config defaults.
• Debugging tip: when behavior seems wrong, dump the resolved config and the bound instance early. dd(config('package'), get_class(app(PackageContract::class))) distinguishes "misconfigured" from "wrong implementation bound" instantly, and those two failure modes account for most package issues.
• Extension points to note before you customize: published config, bound contracts (swap via $this->app->bind() in your own provider), and events. If you find yourself extending a concrete class or reaching into protected properties, you are outside the supported surface and will feel it at the next minor release.
• Logging. Most packages log under their own channel. If you cannot find output, check config/logging.php for a package channel and confirm its level — silent failures are usually a channel swallowing debug-level messages.