- How do I install zhuzhichao/ip-location-zh in a Laravel app?
- Install it with Composer by running composer require zhuzhichao/ip-location-zh. Laravel's package auto-discovery registers the bundled service provider, so no manual entry in config/app.php is normally required. If the package ships publishable assets, run php artisan vendor:publish to expose them, then import the Ip class and start querying addresses.
- How do I get the country, province, city and ISP for an IP address?
- Use the static Ip::find() method from Zhuzhichao\IpLocationZh\Ip and pass it a single IP string. It returns an array containing the country, province, city and ISP details resolved from the offline QQWry database. No dependency injection, facade or bootstrapping step is needed, which makes it easy to call from controllers, jobs or console commands.
- Does this package call an external geolocation API?
- No. All lookups are performed locally against the QQWry data file that ships with the package, so no HTTP requests, API keys, rate limits or third-party uptime dependencies are involved. That makes it suitable for high-volume lookups and for servers without outbound internet access. The trade-off is that the data is only as fresh as the bundled or manually replaced .dat file.
- Does it support IPv6 addresses?
- The QQWry database is an IPv4 data set, so IPv6 lookups are not meaningfully supported by this package. If your application accepts IPv6 traffic, resolve or skip those addresses before calling the lookup, or fall back to a separate IPv6-capable provider. Test with representative addresses from both stacks before relying on the output in production.
- How accurate is it for IPs outside mainland China?
- QQWry is optimised for Chinese IP ranges, which is where it returns province, city and ISP detail. For many non-Chinese addresses you should expect only a country-level result, and some reserved or private ranges return placeholder values. If global city-level accuracy is a hard requirement, pair it with a MaxMind GeoLite2 database instead of relying on this package alone.
- Which Laravel and PHP versions does it support?
- The package is fundamentally plain PHP with a thin, optional Laravel service provider, so it generally installs across recent Laravel releases. Before upgrading, check the require constraints in the package's composer.json against your pinned PHP and Laravel versions, and run it in CI on your actual matrix. If you are on an older Laravel version with manual provider registration, confirm auto-discovery is not assumed.
- Is it fast enough for production, and should I cache results?
- Lookups read from a local binary file with an indexed search, so they are fast and add no network latency per request. Nevertheless, geolocation for a given IP does not change often, so caching results per IP in Redis or the Laravel cache is a cheap win on high-traffic endpoints. Remember to invalidate or version that cache when you swap the underlying data file.
- How do I update the IP database without updating the package?
- You can replace the bundled QQWry .dat file with a newer build and point the package at it through its published configuration, avoiding a Composer release cycle. Keep the replacement in a known path and treat it as versioned reference data so you can roll back. After updating, clear any IP-keyed caches, since previously cached results will reflect the old data set.
- How do I test IP lookups in a Laravel test suite?
- Because lookups are entirely offline, you do not need Http::fake or any network stubbing; you can assert directly against known IPs and expected regions. Keep a small fixture list of representative addresses, including private and reserved ranges, and assert your own formatting or fallback logic rather than the raw database output. Avoid asserting exact city strings for addresses whose data may change between .dat file versions.
- What are the alternatives, and is this package still maintained?
- Common alternatives are MaxMind's geoip2 with GeoLite2 for worldwide accuracy, ip2location, and Searcher-style integrations of the same QQWry data. This package remains the simplest option when you specifically need Chinese province, city and ISP data with zero external calls. Check the GitHub repository for recent commits and release cadence before adopting it, and pin a version so an infrequent data refresh cannot surprise you.