People Php Laravel Package

Getting Started

• Install with composer require oki-technologies/people-php:^1.0. Confirm the package supports your Laravel/PHP versions before merging.
• Laravel should auto-discover the service provider. If not, register the package provider manually and publish its config with php artisan vendor:publish --provider="OkiTechnologies\\People\\PeopleServiceProvider" after verifying the exact provider namespace from composer.json.
• Start by reading: the package README, config/people.php, src/*ServiceProvider.php, the main client class, facade classes, DTO/collection classes, and tests/.
• Add credentials to .env only, for example PEOPLE_BASE_URL, PEOPLE_API_KEY/PEOPLE_TOKEN, and PEOPLE_TIMEOUT. Mirror them in config/people.php rather than calling env() directly in application code.
• First smoke test: resolve the client from the container in php artisan tinker and perform the safest read operation available, such as fetching one page of people/employees or calling a health/whoami endpoint. Then move to a single-record read before attempting writes.
• First real use case: an authenticated read path that lists or finds a person, maps the response into your domain model, and stores the external ID for later updates.

Implementation Patterns

• Inject the package client through Laravel’s container rather than using the facade throughout the codebase. Bind the package client or a small adapter interface in a service provider so tests and future SDK changes stay isolated.
• Keep SDK usage behind an application service/action layer. Controllers and jobs should call your service, not the vendor client directly, so you can enforce validation, authorization, logging, and retry policy in one place.
• Persist remote identifiers locally, e.g. people_id or external_id, with a unique index. Use updateOrCreate-style logic for sync flows and avoid creating duplicates when jobs retry.
• For writes, prefer queued jobs with explicit idempotency controls where the API supports them. If the API does not support idempotency keys, guard with local state and unique constraints before dispatching.
• Handle pagination deliberately. Use the package’s cursor/page helpers if available; for large datasets, process page-by-page in jobs instead of loading all records into memory.
• Cache read-heavy lookups with a short TTL and clear/invalidate on successful writes. Do not cache sensitive PII longer than necessary.
• Validate inbound app data with Form Requests before calling the client. Translate package/API exceptions into domain exceptions in one place, and let Laravel’s exception handler render consistent API responses.
• In tests, bind a fake client or mock the underlying HTTP transport. Keep a small contract test against a sandbox if credentials are available, but do not let the default test suite call the live API.
• If webhooks are supported, verify signatures before trusting payloads, enqueue processing, and store event IDs to prevent replay.

Gotchas and Tips

• The v1.0.0.0 release notes only link to the changelog. Before adopting, inspect the tag diff and README for actual auth, endpoint, and configuration details; do not assume features from the version number alone.
• The four-part version 1.0.0.0 may not behave like strict SemVer in Composer constraints. Pin a tested range and commit composer.lock for applications.
• Run php artisan config:clear after changing package env values. Cached config is a common cause of “credentials changed but the app still uses old values.”
• Verify base URL, auth header format, sandbox vs production host, timeout, and retry settings against the README. Default timeouts are often too short or too long for bulk sync jobs.
• Catch package-specific exceptions rather than only Throwable. Distinguish validation/permission errors from transient network errors so queued jobs retry only when appropriate.
• Queue retries can duplicate creates. Combine unique local constraints, idempotency keys where available, and careful job middleware.
• Watch for pagination quirks: total counts may be approximate, page sizes may be capped, and cursors may expire. Design sync jobs to resume safely.
• Treat dates, timezones, currency, and nullable fields carefully when mapping responses. Normalize at the boundary and keep vendor DTOs out of your domain models.
• Redact tokens and PII from logs. Use Laravel’s HTTP client events, Telescope, or the package’s debug option if present, but never log full request/response bodies containing personal data in production.
• Prefer extension points such as publishing config, binding a custom client/adapter, or decorating the package client. Avoid editing files under vendor/.
• If the package is not deeply Laravel-native, keep a thin adapter layer so you can replace it without rewriting controllers, jobs, and tests.