Agendize Client Bundle Laravel Package

Getting Started

As of v0.1.6, the package expects two credentials for the Agendize API: an apiKey and a token. Start by installing the package, publishing its config, and setting both values in .env:

composer require <vendor>/<package>
php artisan vendor:publish --tag=agendize-config

AGENDIZE_API_KEY=your-api-key
AGENDIZE_TOKEN=your-api-token

Look first at the package config file and service provider to confirm the exact config keys and binding names. Then make a single authenticated read call against a low-risk endpoint — for example, listing a resource or fetching the current account — before wiring anything into application flows. The first practical use case is usually a scheduled job or admin action that reads Agendize data (appointments, queues, or account resources) using the configured apiKey and token.

Implementation Patterns

• Inject the client, not the facade. Resolve the package client through the container in services, jobs, and actions. Keep facades at the edges (controllers, commands) so domain code remains testable.
• Wrap Agendize calls in a small service layer. Create an AgendizeService or per-domain client (Appointments, Queues) that accepts the package client and returns DTOs or arrays. This isolates endpoint paths, query parameters, and response shape changes.
• Treat apiKey as application identity and token as the account/session credential. Keep the API key in config, and source the token from your own auth flow or Agendize dashboard depending on your integration. For multi-tenant apps, resolve both at runtime per tenant rather than relying only on global env values.
• Use Laravel’s HTTP client features around the package. Configure timeouts, retries with backoff, and request logging in a wrapper or via the package’s client if it exposes the underlying PendingRequest. Log request IDs and endpoint names, never full tokens.
• Handle authentication failures centrally. Catch 401/403 responses in one place and convert them into domain exceptions. If your token is refreshable, trigger refresh there; otherwise surface a clear “reconnect Agendize” error.
• Test with Http::fake() and config overrides. Set config(['agendize.apiKey' => 'test', 'agendize.token' => 'test']) in tests and fake the Agendize endpoints. Assert that your service sends the expected auth headers and maps responses correctly.
• Use queued jobs for writes and bulk reads. Agendize operations that create or update records should be queued with retries, especially when called from web requests.

Gotchas and Tips

• apiKey and token are not interchangeable. The v0.1.6 release specifically adds support for both. Mixing them up typically produces authentication errors that look like invalid credentials rather than missing config.
• Token expiry is the most likely runtime failure. Agendize tokens may expire or be revoked. Build a 401 path early and decide whether you refresh, re-authenticate, or prompt an admin. Do not assume the package refreshes tokens automatically unless the source confirms it.
• Clear config cache after credential changes. php artisan config:clear is required in local and deployed environments when changing AGENDIZE_API_KEY or AGENDIZE_TOKEN, otherwise Laravel may serve stale values.
• Check the actual config keys. The release notes use apiKey and token; confirm whether the config file uses camelCase, snake_case, or nested keys, and whether env names differ.
• Redact credentials in logs and exception handlers. Laravel’s HTTP client can log headers; ensure Authorization and token query parameters are masked. Avoid dumping the resolved config.
• Agendize error payloads may not match Laravel’s default exception shape. Normalize API errors in your wrapper so callers get consistent exceptions with status code, message, and Agendize error code.
• Watch rate limits and pagination. List endpoints often paginate; centralize pagination handling in your service rather than repeating it in controllers.
• Extension point: bind your own client wrapper or decorate the package client in a service provider. This lets you add retries, logging, tenant credential resolution, and token refresh without forking the package.
• Debugging tip: start with a single GET request and log the status, response body, and request ID. If auth fails, verify both credentials independently against the Agendize authentication documentation before changing application code.