Laravel Abuse Ip Laravel Package

Getting Started

This release is primarily a hardening/cleanup pass with one genuinely new capability: a configurable switch for ip2long() conversion. Start there.

1. Upgrade and verify autoloading first. The "restructured the code" bullet is the riskiest item in 1.4. Run composer update <vendor>/<package> -W, then composer dump-autoload -o and boot the app. If you were importing concrete classes directly (rather than resolving through the container or a facade), grep your codebase for the old namespace before deploying.
2. Publish/republish the config. The new toggle ships with a default; if you already have a published config file, it will not receive the new key. Re-publish to a temp path and diff, or add the key manually. Expect something along the lines of 'use_ip2long' => env('IP_USE_IP2LONG', true).
3. Read the updated README before the source. The 1.4 docs refresh is the fastest way to confirm the config key name and any renamed public API after the restructure.
4. First use case: take an inbound request, resolve the client IP, convert it to an integer for storage in an indexed column, and convert back on read. Flip the toggle off in one environment (e.g. a staging box with an IPv6-only load balancer) to confirm the package degrades to string storage instead of throwing.

If you are evaluating rather than upgrading: the package is only worth adopting if you actually need integer IP columns for range queries or indexing. If you store IPs as VARCHAR(45) and never range-scan, the toggle is the only feature here you'd use.

Implementation Patterns

Keep the toggle in config, not in code. The whole point of the 1.4 feature is environment-driven behavior. Set it in config/*.php via env(), and let per-environment .env files differ. Avoid if (config(...)) branches scattered through your domain code — wrap the conversion behind a single service or cast so the rest of the app never knows which mode is active.

Isolate conversion behind one boundary. The cleanest integration is a custom Eloquent cast or a small IpValue value object:

• Write path: ip2long() when enabled, raw string when disabled.
• Read path: long2ip() when enabled and the stored value is an int, raw string otherwise.
• Keep both branches in one class. When the package restructures again (and it just did once), you patch one file.

Match the column type to the mode. ip2long() on 64-bit PHP returns an int that can exceed PHP_INT_MAX only in the negative-wrap sense — the canonical fix is sprintf('%u', ip2long($ip)). That value does not fit a signed INT. Use unsignedBigInteger (or unsignedInteger if you accept IPv4-only) so both modes coexist; a VARCHAR column holding "2130706433" is a bug waiting to happen.

Plan for mixed-mode data. During a rollout you will have string rows and integer rows in the same table. Either:

• backfill in a single maintenance window with a chunked job, or
• version the data (a format column) and branch the cast on it.

Do not let the toggle flip silently against a populated table.

Use it in middleware for coarse analytics. Resolving and converting the IP once in middleware, then attaching it to the request or a DTO, avoids repeated conversion in logs, rate limiters, and audit trails.

Test both modes explicitly. In Pest/PHPUnit, override the config in setUp and assert round-trip equality (long2ip(ip2long($ip)) === $ip) for IPv4, plus the no-conversion path. Add one IPv6 fixture to prove the toggle-off path works and the toggle-on path is a documented gap rather than a crash.

Dependency-inject, don't static-call. Post-restructure, the package's internals are more likely to change than its container bindings. Type-hint the interface the service provider registers; that is the extension point that survived the refactor.

Gotchas and Tips

• ip2long() returns false, not 0, on malformed input. false casts to 0, which is a valid-looking integer. Check with === false before persisting, or you will silently write 0.0.0.0.
• Negative integers. On some platforms ip2long('255.255.255.255') yields -1. Always pass through sprintf('%u', ...) before storage, and be aware existing rows written without that guard are now corrupt under long2ip().
• IPv6 is not supported by ip2long(). The toggle does not fix this — it only lets you avoid the failure. If your traffic is IPv6-capable, either keep the toggle off or pair the package with inet_pton()-based handling.
• env() inside a published config is resolved at config-cache time. After changing the toggle in .env, run php artisan config:clear (and re-cache in deploy). A stale bootstrap/cache/config.php is the single most likely cause of "the feature doesn't work."
• Upgrade breakage from the restructure. Class renames, moved namespaces, and changed constructor signatures are the usual fallout from a cleanup release. Symptoms: Class not found at boot, or container resolution errors only on code paths your tests don't hit. Pin the exact version, deploy to staging, and check composer why-not before rolling forward.
• Serialized payloads. If the package's objects are queued or cached (e.g. in a job payload or a cached DTO), a class rename in 1.4 will break unserialization of in-flight jobs. Drain queues before deploying.
• Don't flip the toggle on a live table without a backfill. Reading integer rows as strings yields "2130706433" in your UI; reading string rows as integers yields 0.
• Debugging tip: in tinker, config('...'), ip2long('203.0.113.7'), and sprintf('%u', ip2long('203.0.113.7')) side by side will immediately tell you which mode the app is in and whether your column type is adequate.
• Extension points that are worth relying on: the published config file, the container binding for the resolver/converter, and (if present) any macroable facade. Everything under src/ moved in 1.4 — treat it as private API.