- What does siketyan/kagawa-bundle actually do?
- It is a narrow-domain utility that answers one question: did this request originate from Kagawa, Japan. That verdict can drive regional content gating, prefecture-targeted campaigns or pricing, local licensing and compliance checks, or delivery-area logic. It is a leaf utility rather than a platform component, so it only belongs in the dependency graph if your product has a Kagawa-specific branch.
- How do I install it in a Laravel application?
- Install with Composer using composer require siketyan/kagawa-bundle, then rely on package auto-discovery for the service provider and publish the config file if one is provided. Attach the middleware or validation rule only at the routes where the Kagawa check matters, and pin the constraint to ^1.0.1 with 1.0.0 explicitly excluded. Confirm the actual class names and config keys in the README because the release note does not spell them out.
- Which Laravel and PHP versions are supported?
- The provided release note does not publish a Laravel or PHP version matrix, so check the package's composer.json constraints before installing. It advertises PSR-4 autoloading and modern PHP features, but that is not the same as confirmed Laravel 10 or 11 support. Run composer why-not checks against your application's PHP and framework versions.
- How does the package detect Kagawa-origin requests?
- The release note does not reveal the resolution source, which is the most important integration question. It could ship a geo-IP dataset, call an external service, read a header set by an upstream edge, or expect the host application to supply a resolver. Each option carries different accuracy, latency, privacy, and maintenance implications, so verify this before rollout.
- What happens for non-Kagawa requests or unresolvable IPs?
- Version 1.0.1 fixed an error when the request is not from Kagawa, which means version 1.0.0 threw on the overwhelmingly common path. Treat 1.0.0 as non-deployable and pin ^1.0.1 as the floor. Verify that an unresolvable IP returns false or null rather than throwing, and test private-range, IPv6, and proxy-derived addresses.
- Does it respect TrustProxies and request()->ip()?
- It is not documented whether the package uses Laravel's Request::ip() or reads REMOTE_ADDR directly. Behind a load balancer, the latter is systematically wrong and will return the same verdict for all traffic. Configure TrustProxies correctly before testing, then assert that the package sees the real client IP.
- Is it safe to use with Laravel Octane, RoadRunner, or Swoole?
- Confirm that the resolver does not hold per-request origin state in a container singleton; long-lived workers can leak one request's verdict into the next. A geo-IP dataset or HTTP client can safely be a singleton, but the Kagawa decision must be computed per request. Test under Octane with alternating Kagawa and non-Kagawa requests before production.
- Should I replace existing region logic with this package?
- Do not rip out working in-house region logic, whether that is a header check, a MaxMind lookup, or a manual IP list. Run the package in shadow mode first, computing its verdict alongside your incumbent logic and logging both. The divergence rate is the number that decides whether migration is justified, and it also surfaces caching opportunities for per-request resolution cost.
- How should I test the package in my application?
- Cover the negative case first: non-Kagawa requests, private-range IPs, IPv6 addresses, proxied requests, and IPs the resolver cannot place. Assert that each returns a clean false or null rather than an exception, because that was the v1.0.0 failure class. Also test the middleware or validation rule behavior at the route level, not just the underlying helper.
- Is it maintained, and what alternatives should I consider?
- It is a v1.x package with a single-maintainer concentration risk and one known field bug fixed quickly in 1.0.1, which is reassuring on responsiveness but evidence of thin pre-release testing. Check the license, release cadence, and whether upstream pull requests are accepted. Alternatives include MaxMind GeoIP2 with a maintained database, edge geo headers from your CDN, or a small custom middleware if your only signal is an upstream header.