feat: Add region-aware endpoint resolution via getContentstackEndpoint()

[sunil-lakshman]

Summary

This PR introduces a centralized endpoint resolution mechanism for Contentstack services across all supported regions and cloud providers.

Key Changes

• Added Endpoint::getContentstackEndpoint() as the single source of truth for resolving Contentstack service URLs.
• Added Utils::getContentstackEndpoint() as a backward-compatible proxy to avoid breaking existing implementations.
• Introduced automatic download of regions.json during composer install and composer update.
• Added runtime fallback to automatically fetch regions.json if it is missing.
• Added composer refresh-regions command to manually update region metadata.
• Eliminated hardcoded Contentstack host strings across the SDK.

---

Files Changed

File | Description -- | -- src/Endpoint.php | New endpoint resolution implementation with cache → file → live-download fallback strategy src/Utils.php | Added backward-compatible getContentstackEndpoint() proxy scripts/download-regions.php | New script for downloading region metadata with cURL and file_get_contents fallback composer.json | Added install/update hooks and refresh-regions script .gitignore | Ignored generated src/assets/regions.json tests/EndpointTest.php | Added comprehensive endpoint resolution test coverage README.md | Added endpoint resolution documentation and usage examples CHANGELOG.md | Added v1.3.0 release notes

---

Supported Regions

Supports 7 Contentstack regions across 3 cloud providers:

• AWS: NA, EU, AU
• Azure: NA, EU
• GCP: NA, EU

---

Supported Services

Endpoint resolution supports all available Contentstack services, including:

• Content Delivery
• Content Management
• GraphQL Delivery
• GraphQL Preview
• Preview
• Auth
• Application
• Images
• Assets
• Automate
• Launch
• Developer Hub
• Brand Kit
• GenAI
• Personalize Management
• Personalize Edge
• Composable Studio
• Asset Management

---

Example Usage

use Contentstack\Utils\Endpoint;

// Get a service endpoint
Endpoint::getContentstackEndpoint('eu', 'contentDelivery');

// Remove protocol for Stack::setHost()
Endpoint::getContentstackEndpoint('eu', 'contentDelivery', true);

// Get all endpoints for a region
Endpoint::getContentstackEndpoint('azure-na');

// Delivery SDK integration
$host = Endpoint::getContentstackEndpoint($region, 'contentDelivery', true);

$stack = Contentstack::Stack(
    $API_KEY,
    $DELIVERY_TOKEN,
    $ENVIRONMENT
);

$stack->setHost($host);

---

Testing

• ./vendor/bin/phpunit tests/EndpointTest.php
  • 39 tests
  • 99 assertions
  • All passing
• Verified composer install downloads regions.json
• Verified composer refresh-regions updates region metadata from the live registry
• Verified runtime fallback automatically downloads regions.json when missing
• Verified endpoint resolution against a live stack and successfully fetched content
• Existing test suite executed successfully
  • 213 tests passed
  • 2 pre-existing failures in UtilsJsonToHtmlTest (unrelated to this change)

---

Backward Compatibility

✅ Fully backward compatible.

Existing implementations using Utils::getContentstackEndpoint() continue to work without modification.