Customers Laravel Package

Getting Started

Because netflex/customers is a read-only subtree split of netflex/framework, the first thing to decide is whether you actually need it as a standalone dependency. If your app already requires netflex/framework or netflex/commerce, the Netflex\Customers\* classes are already available — requiring the split on top of it is the most common way to create duplicate-class or version-skew problems.

• Where to look first: the Netflex\Customers\Customer model and its related CustomerGroup, Contact, and Address types. These are the surface you will touch 90% of the time. Browse the source here for signatures, then go to netflex/framework for docs, changelogs, and issue tracking.
• Install (only if standalone): composer require netflex/customers and pin it to the same minor as your netflex/framework version. Treat the version constraint as coupled, not independent.
• First use case: look up a known customer by email and read their stored attributes, e.g. resolving a logged-in shopper's profile to render an account page or prefill a checkout form. That single flow exercises the model, the contact/address relations, and the attribute accessor behavior you will rely on everywhere else.

If nothing resolves, the usual culprit is that the Netflex service provider (from the framework, not this split) hasn't booted or the API credentials/config for the Netflex tenant aren't set — verify that before debugging model code.

Implementation Patterns

Treat models as remote-backed, not just Eloquent. Customer data is sourced from the Netflex API, so the everyday patterns look like Eloquent but carry network semantics:

• Lookup by identity, not primary key guesswork. Resolve customers via the documented finders (email/contact lookup) rather than assuming numeric IDs are stable across environments. Keep the ID you get back and reuse it for relation calls.
• Eager-load relations before iterating. When rendering a list (e.g., group members with their addresses), fetch addresses/contacts/groups up front. N+1 against a remote API is far more painful than N+1 against MySQL.
• Group-scoped queries. Filter by CustomerGroup when you need pricing tiers or B2B segmentation; don't pull all customers and filter in PHP.
• Relation traversal for the account page. Typical workflow: customer → contacts (email/phone) → addresses (billing/shipping) → orders (from the commerce package). Keep each hop explicit so you can cache or stub independently.
• Attribute access with a fallback layer. Customer records often have custom/structured-content fields. Wrap reads in a small presenter or accessor so a missing key returns null/default rather than throwing in templates.
• Authentication boundary. If you're implementing login, keep password verification and session handling in your app's guard, and use the package only to hydrate the customer record. Don't scatter auth logic through views; centralize it in a service or guard so you can swap to Netflex's own auth flow later.
• Caching. Wrap read-heavy customer fetches (especially on public pages) in a short-TTL cache keyed by customer ID, and invalidate on profile updates. This is the single highest-leverage integration tip.

Gotchas and Tips

• Don't open issues or PRs here. The repo is a generated split; all changes go to netflex/framework. A PR against this repo will be discarded, and a fork here will drift immediately.
• Version coupling is real. Mixing a customers split with a mismatched framework minor produces subtle breakage (method signatures, relation names). Lock them together in composer.json.
• Remote latency in loops. Any foreach that touches $customer->addresses or similar inside the body is a candidate for refactor. Profile with query/logging enabled from the framework before assuming your code is slow.
• Null versus empty. Optional contact fields and secondary addresses frequently come back empty. Normalize once in a presenter; don't if ($x->phone ?? null) in twelve Blade files.
• Don't rely on save() semantics blindly. Writes go through the API; validate and handle failures explicitly rather than assuming Eloquent's return contract. Surface API errors instead of swallowing them.
• Testing. Stub at the service/repository boundary you introduce, not at the HTTP client deep inside the package — otherwise a framework bump silently changes your fixtures. A thin CustomerRepository wrapper pays for itself here and is the natural extension point.
• Debugging tip: when a lookup returns unexpectedly empty, log the resolved tenant/config and the raw API response before suspecting the model. Most "customer not found" reports are environment or credential mismatches, not query bugs.
• Extension point: subclass or decorate Customer in your app namespace and bind it via the container if you need domain-specific accessors; avoid editing vendor code, since the next split update overwrites it.