Network Primitives Laravel Package

Getting Started

Install the package via Composer to gain access to typed network primitives like IPv4Address, IPv6Address, MACAddress, and PortNumber. Start by validating and normalizing simple network inputs — for example, converting user-provided IP strings into strongly-typed objects:

composer require daverandom/network-primitives

Then in code:

use DaveRandom\NetworkPrimitives\IPv4Address;

try {
    $ip = IPv4Address::create('192.168.1.1');
    echo $ip->toString(); // Safe normalized string
} catch (\DaveRandom\NetworkPrimitives\InvalidIPv4AddressException $e) {
    // Handle invalid input
}

Check the README for minimal examples, but expect to rely on source code inspection (e.g., src/) to discover available types and methods.

Implementation Patterns

• Domain Model Enforcement: Replace loosely typed string $ip or string $port properties in DTOs or domain objects with IPv4Address/PortNumber. Prevents accidental misassignment and enforces validity.

• Middleware/Hydrator Wrapper: Create a service that wraps raw request data (e.g., $_GET['ip']) into primitives before passing to handlers — ideal for REST APIs or config forms.

• Validation with Laravel Validator: Integrate into custom validation rules:

  Rule::required()->after(function ($attribute, $value, $fail) {
      try {
          IPv4Address::create($value);
      } catch (\Exception $e) {
          $fail('Invalid IP address format.');
      }
  })
  

• Database Integration: Store primitives as strings via toString(), but hydrate using create() in repository layers — keeping validation co-located with persistence logic.

• Port Range Validation: Use PortNumber::create() for input like firewall rules or proxy configs. Note: 0 is valid (reserved), so add domain-specific checks if needed (e.g., reject 0 for listening ports).

Gotchas and Tips

• Low Maturity = High Risk: With 2 stars, 0 dependents, and no active release history, treat this as experimental. Avoid critical infrastructure paths unless you’re prepared to maintain a fork.

• No PSR, No Framework Integration: This package doesn’t support PSR-7, PSR-15, or Laravel contracts out-of-the-box. You’ll write adapters for middleware, form requests, or validation.

• Enum-Based Exceptions: Uses daverandom/enum v1 — not PHP 8 native enums — so exception types (InvalidIPv4AddressException, etc.) are custom. Avoid instanceof checks across versions.

• Silent Port Edge Cases: PortNumber accepts 0–65535, but 0 is reserved and unusable on most systems. Consider wrapping in a domain-specific validator if binding ports is involved.

• No Built-in Debug Aid: No __debugInfo() implementations — dump toString() instead for logs, or create a helper trait:

  trait LogsPrimitive {
      public function loggable(): string { return $this->toString(); }
  }
  

• No Extension Points: Can’t subclass or extend primitives. Add behavior (e.g., geoip lookup) via composition — wrap primitives in decorator classes.

• Test Smartly: Unit tests should assert behavior (e.g., “invalid IPs throw”), not internal state. Mock strings — don’t hardcode assumed formats.