v2.1.0

Release Highlights

• Added PHP 8.3 to 8.5 support (>=8.3 <8.6)
• Modernized package architecture:
  • Ipstack::factory()
  • IpstackClient
  • TransportInterface + Psr18Transport
  • IpstackResultMapper
• Introduced/standardized typed models:
  • IpstackResult, Country, Region, Location, Connection, Security, Routing, IpstackCollection
• Added robust API error mapping:
  • RateLimitException (104)
  • InvalidFieldsException (301)
  • TooManyIpsException (302)
  • BatchNotSupportedException (303)
  • plus transport/invalid-response exceptions
• Improved bulk lookup behavior:
  • supports up to 50 IPs
  • clear failure behavior for invalid/bulk edge cases
• Expanded automated test coverage:
  • client edge cases
  • factory behavior
  • PSR-18 transport behavior
• Upgraded CI and quality workflow:
  • PHP 8.3 / 8.4 / 8.5 matrix
  • stable quality gates
• Fully rewritten README:
  • quick start
  • advanced examples
  • migration guide
  • troubleshooting

---

Upgrade Guide (from legacy usage)

1. Replace old constructor-style usage

Old:

new Sujip\Ipstack\Ipstack($ip, $apiKey);

New:

$client = Ipstack\Ipstack::factory()
    ->withAccessKey($apiKey)
    ->withPsr18($httpClient, $requestFactory)
    ->build();

2. Replace legacy convenience calls with lookup methods

Old patterns like:

• country()
• region()
• city()
• formatted() on root object

New:

• lookup($ip)
• lookupRequester()
• lookupBulk([...])

Then read typed fields:

$result = $client->lookup('8.8.8.8');
$result->country->name;
$result->region->name;
$result->city;
$result->formatted();

3. Update bulk usage

Use:

$collection = $client->lookupBulk(['8.8.8.8', '1.1.1.1']);

Notes:

• empty array returns empty collection
• more than 50 IPs throws exception

4. Update error handling to typed exceptions

Recommended:

try {
    $result = $client->lookup($ip);
} catch (Ipstack\Exception\RateLimitException $e) {
} catch (Ipstack\Exception\TransportException|Ipstack\Exception\InvalidResponseException $e) {
} catch (Ipstack\Exception\IpstackException $e) {
}

5. If using custom HTTP stack, use transport abstraction

• Prefer withPsr18(...) for PSR-18/PSR-17 clients
• Or inject custom transport via withTransport(...)

6. Validate after upgrade

Run:

composer test
composer stan

---

If you want, I can also format this into a GitHub Release markdown block with “Breaking Changes”, “Migration”, and “Verification Checklist” sections exactly ready to paste.