Laravel Neto Laravel Package

Getting Started

1. Install the package:

   composer require venturedrake/laravel-neto
   

2. Publish the config (typical Laravel service provider convention):

   php artisan vendor:publish --tag=neto-config
   

3. Set credentials in .env — at minimum the Neto API key and the store/API endpoint URL:

   NETO_API_KEY=your-api-key
   NETO_API_URL=https://your-store.neto.com.au
   NETO_TIMEOUT=30
   

4. Resolve the client through the container (or the provided facade) and make a first call. Fetch a single order:

   use Venturedrake\LaravelNeto\Neto;
   
   $order = app(Neto::class)->orders()->find($orderId);
   

Where to look first: the config file (timeouts, retries, logging, base URL), then the Orders resource — it is the broadest surface (get, find, create, update, cancel, status, tracking) and the best place to confirm the request/response shape your app will deal with.

First real use case: pull recent orders with orders()->get([...]) and map the payload into your domain models. Since Neto's response envelope is not normalised to Eloquent, treat the returned arrays/DTOs as transport objects and map immediately — this keeps the rest of your app insulated when the client's shape changes across releases.

Implementation Patterns

• Dependency injection over facades. Type-hint Neto in controllers/jobs. This makes faking in tests and swapping a bound subclass trivial, and keeps API calls out of global helper land.
• Wrap resources, don't scatter calls. Because the client exposes orders(), items(), customers(), and a generic request()/get(), put your application-specific Neto operations behind a small service (e.g. NetoSyncService) so retry/timeout and mapping logic live in one place.
• Orders lifecycle workflows. A common pattern is a status-sync job that pages through orders()->get() and reconciles using status/tracking for fulfilment apps, and calls cancel() from a refund/admin action. Keep create/update behind validation because Neto rejects malformed order payloads with a ResponseException, not a validation error.
• Customers and items lookups. Use customers()->findByEmail() for idempotent "find or create" flows during checkout or import jobs. items()->find() for SKU lookups, falling back to get() with a filter when you only have a partial identifier.
• Escape hatch = request() / get(). Anything beyond the typed resources (reports, shipping quotes, custom endpoints) goes through these. Prefer them over adding raw Guzzle calls so you inherit auth, retries, timeout, and masked logging for free.
• Error handling by exception type. Catch each typed exception deliberately rather than \Exception:

  try {
      $order = $neto->orders()->find($id);
  } catch (NotFoundException $e) {
      // 404-style: order not in Neto, handle gracefully
  } catch (ResponseException $e) {
      // Neto returned an error payload — log & surface
  } catch (RequestException $e) {
      // transport failure after retries
  }
  

  ConfigurationException should be a startup/health-check concern, not something you catch inline — it means the package can't authenticate.
• Queue long-running syncs. Even with retries and a timeout, do bulk operations in jobs so a slow Neto response doesn't hold a web request. Combine with Laravel's own retry/backoff for jobs that hit rate limits.
• Logging integration. Enable request logging in config during staging; the API key is masked, so logs are safe to ship to your logging stack. Turn it down/off in production or point it at a dedicated channel to avoid noise.

Gotchas and Tips

• This is v0.1.0 pre-release. Pin the version ("venturedrake/laravel-neto": "0.1.*") and read the changelog before bumping. Method signatures and response shapes are not yet covered by a stability promise.
• Config cache traps. If you deploy with php artisan config:cache, remember that .env changes require a re-cache. A stale API key surfaces as ConfigurationException at runtime, not boot.
• Retries are for transient failures only. Don't wrap create/update in your own additional retry loop — a network blip on a retried create can duplicate an order. Let the package's transient retry policy handle transport errors, and make your own operations idempotent (e.g. check findByEmail before create).
• get vs find semantics. find() expects a specific identifier and maps to NotFoundException; get() is a filtered listing. Using get() with a filter that matches nothing gives you an empty result, not a NotFoundException — don't rely on exceptions for "does this exist" checks against listings.
• Masked logging only masks the API key. Other payload data (customer PII, addresses) is still logged. Point the package log channel at a restricted sink or disable it where PII compliance matters.
• Timeout vs retry interaction. Total worst-case latency is roughly timeout × (retries + 1). For web requests, keep these small and push heavy calls to queues; for queue workers, raise the job's $timeout above that worst case or you'll kill workers mid-retry.
• Response envelope differences. Since the client returns Neto's raw envelope (HTTP status vs Neto's own success/error flag), check both the exception type and the payload body — a ResponseException can represent a valid HTTP 200 with an error inside.
• Extension points. Bind your own implementation against the client contract (or subclass) in a service provider if you need custom auth headers, middleware, or a mocked transport in tests. Pair with Laravel's Http::fake() if the package uses the HTTP client under the hood to avoid live calls in CI.
• Version support window. PHP 8.3–8.5 / Laravel 12–13 means it won't slot into an older app — confirm your app's PHP constraint before adding it, since a composer require will otherwise fail or silently upgrade unrelated packages.