'application/json'], json_encode([ 'success' => true, 'data' => $data, 'additional_data' => ['next_cursor' => $cursor], ], JSON_THROW_ON_ERROR)); } /** In-memory teaching example, not a durable/concurrent production repository. */ function ensurePerson(PersonsApi $api, array &$mapping, string $account, string $externalId): int { $key = $account . ':person:' . $externalId; if (isset($mapping[$key])) { if ($mapping[$key]['state'] !== 'confirmed') { throw new LogicException('Outcome unknown: reconcile before another creation.'); } return $mapping[$key]['id']; } // A timeout can occur after a remote write. Keep the pending decision. $mapping[$key] = ['state' => 'pending']; $response = $api->addPerson(new PostPersonRequestBody([ 'name' => 'Alex Martin — fictitious', 'emails' => [['value' => 'alex@example.com', 'primary' => true]], 'custom_fields' => [str_repeat('a', 40) => $externalId], ])); $id = $response->getData()?->getId(); if (!$response->getSuccess() || !is_int($id) || $id < 1) { throw new RuntimeException('No confirmed numeric Pipedrive ID.'); } $mapping[$key] = ['state' => 'confirmed', 'id' => $id]; return $id; } $mock = new MockHandler([ fixture([['id' => 1, 'name' => 'Contact A']], cursor: 'page-two'), fixture([['id' => 2, 'name' => 'Contact B']]), fixture(['id' => 42, 'name' => 'Alex Martin — fictitious'], 201), fixture(['id' => 42, 'name' => 'Alex Martin — updated']), fixture(['id' => 5071, 'title' => 'Renewal — fictitious'], 201), new ConnectException('Simulated timeout', new Request('POST', 'https://api.pipedrive.com/api/v2/persons')), new Response(429, ['Content-Type' => 'application/json', 'Retry-After' => '60'], '{"success":false,"error":"Simulated burst limit"}'), ]); $history = []; $stack = HandlerStack::create($mock); $stack->push(Middleware::history($history)); $http = new Client(['handler' => $stack, 'timeout' => 10, 'connect_timeout' => 3]); $config = (new Configuration())->setApiKey('x-api-token', 'LOCAL_FIXTURE_NOT_A_SECRET'); $persons = new PersonsApi($http, $config); $deals = new DealsApi($http, $config); $ids = []; $cursor = null; do { $page = $persons->getPersons(limit: 1, cursor: $cursor); foreach ($page->getData() as $person) { $ids[] = $person->getId(); } $cursor = $page->getAdditionalData()?->getNextCursor(); } while ($cursor !== null && $cursor !== ''); verify($ids === [1, 2], 'Read both fixture pages.'); parse_str($history[1]['request']->getUri()->getQuery(), $query); verify(($query['cursor'] ?? null) === 'page-two', 'Forward opaque cursor.'); $mapping = []; $id = ensurePerson($persons, $mapping, 'sandbox-A', 'EXT-2048'); verify($id === 42, 'Persist remote numeric ID.'); $count = count($history); verify(ensurePerson($persons, $mapping, 'sandbox-A', 'EXT-2048') === 42, 'Reuse mapping.'); verify(count($history) === $count, 'Repeated source record sends no second POST.'); $persons->updatePerson($id, new UpdatePersonRequestBody(['name' => 'Alex Martin — updated'])); $deal = $deals->addDeal(new DealPostRequestBody([ 'title' => 'Renewal — fictitious', 'person_id' => $id, 'value' => 12500, 'currency' => 'EUR', ])); verify($deal->getData()->getId() === 5071, 'Deserialize created deal.'); verify($history[2]['request']->getMethod() === 'POST', 'Create with POST.'); verify($history[2]['request']->getUri()->getPath() === '/api/v2/persons', 'Versioned creation path.'); verify($history[3]['request']->getMethod() === 'PATCH', 'Update with PATCH.'); verify($history[3]['request']->getUri()->getPath() === '/api/v2/persons/42', 'Update numeric remote ID.'); $body = json_decode((string) $history[2]['request']->getBody(), true, 512, JSON_THROW_ON_ERROR); verify($body['custom_fields'][str_repeat('a', 40)] === 'EXT-2048', 'External key inside custom_fields.'); verify(!array_key_exists('external_id', $body), 'No invented native external_id.'); verify($history[2]['request']->getHeaderLine('x-api-token') === 'LOCAL_FIXTURE_NOT_A_SECRET', 'API token header.'); $body = json_decode((string) $history[4]['request']->getBody(), true, 512, JSON_THROW_ON_ERROR); verify($body['person_id'] === 42, 'Link deal with numeric person ID.'); $timeout = false; try { ensurePerson($persons, $mapping, 'sandbox-A', 'EXT-TIMEOUT'); } catch (ApiException $error) { $timeout = $error->getCode() === 0 && str_contains($error->getMessage(), 'Simulated timeout'); } verify($timeout, 'Simulated creation timeout raised.'); verify($mapping['sandbox-A:person:EXT-TIMEOUT']['state'] === 'pending', 'Unknown outcome remains pending.'); $count = count($history); $blocked = false; try { ensurePerson($persons, $mapping, 'sandbox-A', 'EXT-TIMEOUT'); } catch (LogicException) { $blocked = true; } verify($blocked && count($history) === $count, 'Unknown write cannot trigger blind second POST.'); $limited = false; try { $persons->getPersons(limit: 1); } catch (ApiException $error) { $limited = $error->getCode() === 429; } verify($limited, 'Expose 429 to the application.'); verify(count($history) === 7, 'No automatic retry in this laboratory.'); verify($mock->count() === 0, 'All seven fabricated responses consumed.'); echo json_encode([ 'sdk' => 'pipedrive/pipedrive:19.2.1', 'checks' => $checks, 'simulated_requests' => count($history), 'external_http_calls' => 0, 'person_id' => $id, 'deal_id' => $deal->getData()->getId(), 'unconfirmed_creation' => 'blocked_pending_reconciliation', ], JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR), PHP_EOL;