Cleeng Php Sdk Laravel Package

Getting Started

Install the package with Composer and publish its configuration:

composer require vendor/package
php artisan vendor:publish --tag="package-config"

Add the required credentials to .env (for example PACKAGE_API_KEY and PACKAGE_API_URL), then clear cached config with php artisan config:clear if you are working locally. The first places to look are config/package.php, the package service provider, and the main client class (usually under src/Client.php or src/Actions/). That is where the 3.7.0 registerCustomer method will be exposed.

The most immediate use case is customer onboarding: after a user registers, create the corresponding customer in the external system and persist the returned identifier.

use Vendor\Package\Facades\Package;

$customer = Package::registerCustomer([
    'name'  => $user->name,
    'email' => $user->email,
]);

$user->update(['package_customer_id' => $customer->id]);

Check the exact method signature in the source before relying on it. Some releases accept a model or a DTO directly:

Package::registerCustomer($user);

Because 3.7.0 is an additive minor release, existing integrations should continue to work; the new method is the main reason to upgrade.

Implementation Patterns

Onboarding listener or job. Trigger customer registration from a Registered event listener, but dispatch a queued job rather than calling the API inside the request. This keeps registration fast and gives you retries.

class RegisterExternalCustomer implements ShouldQueue
{
    public function handle(): void
    {
        $customer = Package::registerCustomer([
            'name'  => $this->user->name,
            'email' => $this->user->email,
        ]);

        $this->user->update(['package_customer_id' => $customer->id]);
    }
}

Persist the external ID. Store the returned customer ID on your users table (or a dedicated customers table). You will need it for later calls such as subscriptions, invoices, or updates. Add a nullable package_customer_id column and an index.

Use idempotency where possible. If the external API supports idempotency keys, pass one derived from your user ID or email. If not, guard the job with ShouldBeUnique and check for an existing package_customer_id before calling registerCustomer.

Map data explicitly. Avoid passing the entire Eloquent model unless the package documents that behaviour. Build a small array or DTO with only the fields the API expects. This makes tests clearer and prevents accidental PII leakage.

Test with HTTP fakes. The package usually sits on top of Laravel’s HTTP client. Use Http::fake() and assert the outgoing payload:

Http::fake([
    'api.example.com/customers' => Http::response(['id' => 'cus_123'], 201),
]);

Package::registerCustomer(['name' => 'Ada', 'email' => '[email protected]']);

Http::assertSent(fn ($request) => $request['email'] === '[email protected]');

Reconcile with webhooks. If the external service emits customer-created webhooks, use them to backfill or verify the local package_customer_id. This is especially useful for bulk imports or retries.

Bulk operations. For imports, chunk users and dispatch jobs. Respect the API’s rate limits and avoid calling registerCustomer in a tight loop from a single process.

Gotchas and Tips

• Read the source for 3.7.0. The release note only says “Add registerCustomer API method.” Confirm the exact signature, return type, and exception behaviour in the client class before using it in production. The method may return a response object, an array, or a DTO.
• Watch for naming collisions. registerCustomer is a generic name. If your application already has a method with that name on a model or service, alias the facade or inject the client explicitly.
• Sandbox versus production credentials. Double-check PACKAGE_API_URL and key values per environment. A common failure is registering test customers in production because .env was copied without changes.
• Config caching. After changing API credentials, run php artisan config:clear locally and redeploy with php artisan config:cache in production.
• Handle API failures explicitly. Catch package-specific exceptions and avoid logging full request payloads, which may contain email addresses or other PII. Return a clear failure state so onboarding can retry.
• Respect rate limits. Queue jobs with backoff. If the API returns 429, use exponential backoff rather than immediate retries.
• Check idempotency support. If the API does not support idempotency keys, deduplicate on your side by checking for an existing external customer ID before calling registerCustomer.
• Extension points. Most packages allow you to bind a custom HTTP client or extend the main client class. If you need custom headers, logging, or retry logic, look for a container binding or a macroable client before forking the package.
• Debugging. Enable the package’s debug logging if available, or inspect Http::recorded() in tests. For production issues, log the request ID returned by the API rather than the full response body.
• Upgrade safely. Since 3.7.0 is additive, the main risk is adopting the new method without tests. Add a feature test that asserts the outgoing payload and the stored package_customer_id before rolling it out to all onboarding flows.