From d6755312fa3d41f30c25c472a004c2030c03a5de Mon Sep 17 00:00:00 2001 From: Zan Baldwin Date: Wed, 16 Sep 2026 14:13:52 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20=F0=9F=93=9A=20use=20the=20strict=20nam?= =?UTF-8?q?ed=20constructors=20instead=20of=20factory()?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit factory() is deprecated in 6.1.0, examples show fromProtocol() and its siblings. --- README.md | 10 +++---- docs/03-overview.md | 26 +++++++++--------- docs/04-helpers.md | 63 ++++++++++++++++++++++--------------------- docs/05-strategies.md | 8 +++--- docs/06-formatters.md | 4 +-- docs/07-types.md | 52 +++++++++++++++++------------------ 6 files changed, 82 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index 7c6580d..e9b8358 100644 --- a/README.md +++ b/README.md @@ -33,9 +33,9 @@ using core, bleeding edge, and deprecation rules. - There are three main classes: [`IPv4`](src/Version/IPv4.php), [`IPv6`](src/Version/IPv6.php), and [`Multi`](src/Version/Multi.php) (for both version 4 and 6 addresses). -- Objects are created using a static factory method - [`IpInterface::factory()`](src/IpInterface.php) instead of the constructor to - speed up internal processes. +- Objects are created using static named constructors such as + [`FactoryInterface::fromProtocol()`](src/Contracts/FactoryInterface.php) + instead of the constructor to speed up internal processes. - When using `Multi`, the default strategy for representing version 4 addresses internally is [IPv4-mapped](docs/05-strategies.md). @@ -46,12 +46,12 @@ use Darsyn\IP\Exception; use Darsyn\IP\Version\IPv4; try { - $ip = IPv4::factory('192.168.0.1'); + $ip = IPv4::fromProtocol('192.168.0.1'); } catch (Exception\InvalidIpAddressException $e) { exit('The IP address supplied is invalid!'); } -$companyNetwork = IPv4::factory('216.58.198.174'); +$companyNetwork = IPv4::fromProtocol('216.58.198.174'); if (!$ip->inRange($companyNetwork, 25)) { throw new \Exception('Request not from a known company IP address.'); } diff --git a/docs/03-overview.md b/docs/03-overview.md index 6836996..41b9186 100644 --- a/docs/03-overview.md +++ b/docs/03-overview.md @@ -3,9 +3,9 @@ > The `::factory()` static method is now deprecated. See the strict-parsing > named constructors below. -IP addresses get automatically validated on creation through the static factory -method; if the IP address supplied is invalid an `InvalidIpAddressException` -will be thrown. +IP addresses get automatically validated on creation through the static named +constructors; if the IP address supplied is invalid an +`InvalidIpAddressException` will be thrown. ```php **Note:** `InvalidBinaryException` extends `InvalidIpAddressException`, so > existing `catch` blocks keep working unchanged. @@ -181,7 +181,7 @@ will result in a `WrongVersionException` being thrown. use Darsyn\IP\Version\Multi as IP; use Darsyn\IP\Exception; -$ip = IP::factory('127.0.0.1'); +$ip = IP::fromProtocol('127.0.0.1'); try { echo $ip->toDotAddress(); // string("127.0.0.1") @@ -201,7 +201,7 @@ address according to the embedding strategy. toCompactedAddress(); // string("::ffff:7f00:1") ``` @@ -216,7 +216,7 @@ according to the embedding strategy. toExpandedAddress(); // string("0000:0000:0000:0000:0000:ffff:7f00:0001") ``` @@ -230,7 +230,7 @@ dot notation, otherwise it returns a compacted version 6 address. toProtocolAppropriateAddress(); // string("127.0.0.1") ``` @@ -248,7 +248,7 @@ use Darsyn\IP\Version\IPv4 as IP; // binary, the same as the binary for the ASCII string "Poop". Today you learnt // something new. -$ip = IP::factory('80.111.111.112'); +$ip = IP::fromProtocol('80.111.111.112'); $ip->getBinary(); // string("Poop") ``` @@ -347,7 +347,7 @@ returned string is in protocol-appropriate notation and can be re-parsed via getNetworkIp(26); +IP::fromProtocol('127.0.0.1')->getNetworkIp(26); // IP is version 4 address but CIDR is more than 32. Uses IPv6::getNetworkIp(). -IP::factory('127.0.0.1')->getNetworkIp(107); +IP::fromProtocol('127.0.0.1')->getNetworkIp(107); // IP is version 6 address. Uses IPv6::getNetworkIp(), even though CIDR is below 32. -IP::factory('2001:db8::a60:8a2e:0:7334')->getNetworkIp(31); +IP::fromProtocol('2001:db8::a60:8a2e:0:7334')->getNetworkIp(31); ``` A `Darsyn\IP\Exception\InvalidCidrException` is thrown whenever a CIDR value @@ -75,44 +75,43 @@ instance. inRange(Multi::factory('127.0.0.1'), 23); +IPv6::fromProtocol('ffff:7f00:1')->inRange(Multi::fromProtocol('127.0.0.1'), 23); // IPv4 operation: called from Multi, both IPs are IPv4-embedded, CIDR below 32. -Multi::factory('127.0.0.1')->inRange(Multi::factory('127.0.0.1'), 23); +Multi::fromProtocol('127.0.0.1')->inRange(Multi::fromProtocol('127.0.0.1'), 23); // IPv6 operation: both IPv4-embedded, but CIDR above 32. -Multi::factory('127.0.0.1')->inRange(Multi::factory('127.0.0.1'), 35); +Multi::fromProtocol('127.0.0.1')->inRange(Multi::fromProtocol('127.0.0.1'), 35); // IPv6 operation: supplied IP is not IPv4-embedded. -Multi::factory('127.0.0.1')->inRange(Multi::factory('d6be:583:b07a::c7'), 23); +Multi::fromProtocol('127.0.0.1')->inRange(Multi::fromProtocol('d6be:583:b07a::c7'), 23); // IPv6 operation: embedding strategies do not match. -Multi::factory('127.0.0.1', new Mapped) - ->inRange(Multi::factory('127.0.0.1', new Derived), 23); +Multi::fromProtocol('127.0.0.1', new Mapped) + ->inRange(Multi::fromProtocol('127.0.0.1', new Derived), 23); // WrongVersionException: Multi and IPv4 are different byte lengths. -Multi::factory('127.0.0.1')->inRange(IPv4::factory('127.0.0.1'), 23); +Multi::fromProtocol('127.0.0.1')->inRange(IPv4::fromProtocol('127.0.0.1'), 23); // InvalidCidrException: CIDR above 128. -Multi::factory('127.0.0.1')->inRange(Multi::factory('127.0.0.1'), 129); +Multi::fromProtocol('127.0.0.1')->inRange(Multi::fromProtocol('127.0.0.1'), 129); ``` ## Method Reference ### Network IP -> ``` +> ```text > @throws \Darsyn\IP\Exception\InvalidCidrException > > getNetworkIp(int $cidr): IpInterface > ``` - ```php getNetworkIp(19); $networkIp->toProtocolAppropriateAddress(); // string("12.34.32.0") @@ -120,7 +119,7 @@ $networkIp->toProtocolAppropriateAddress(); // string("12.34.32.0") ### Broadcast IP -> ``` +> ```text > @throws \Darsyn\IP\Exception\InvalidCidrException > > getBroadcastIp(int $cidr): bool @@ -130,7 +129,7 @@ $networkIp->toProtocolAppropriateAddress(); // string("12.34.32.0") getBroadcastIp(19); $broadcastIp->toProtocolAppropriateAddress(); // string("12.34.63.255") @@ -138,7 +137,7 @@ $broadcastIp->toProtocolAppropriateAddress(); // string("12.34.63.255") ### Is IP in Range? -> ``` +> ```text > @throws \Darsyn\IP\Exception\WrongVersionException > @throws \Darsyn\IP\Exception\InvalidCidrException > @@ -149,8 +148,8 @@ $broadcastIp->toProtocolAppropriateAddress(); // string("12.34.63.255") inRange($hostIp, 11); // bool(true) $clientIp->inRange($hostIp, 24); // bool(false) @@ -158,7 +157,7 @@ $clientIp->inRange($hostIp, 24); // bool(false) ### Greatest Common CIDR -> ``` +> ```text > @throws \Darsyn\IP\Exception\WrongVersionException > > getCommonCidr(IpInterface $ip): int @@ -168,8 +167,8 @@ $clientIp->inRange($hostIp, 24); // bool(false) getCommonCidr($clientIp); // int(60) ``` @@ -210,9 +209,10 @@ strategy and always deals with CIDR values from 0 to 128. > unless you absolutely know that you need to deal with both interchangeably. > Using `Multi` can cause unexpected behaviour. > -> For example, `Multi::factory('0.0.0.1', new Strategy\Compatible)` results in -> an object which is both a loopback address `::1` if viewing as IPv6, but also -> not a loopback address `127.x.x.x` if viewing as an IPv4-embedded address. +> For example, `Multi::fromProtocol('0.0.0.1', new Strategy\Compatible)` results +> in an object which is both a loopback address `::1` if viewing as IPv6, but +> also not a loopback address `127.x.x.x` if viewing as an IPv4-embedded +> address. > > Use `Multi` with caution. @@ -229,20 +229,21 @@ an IPv6 address. ```php toCompactedAddress(); // string("::ffff:7f00:1") - try { $ip->toDotAddress(); } catch (\Error $e) { // IPv6 addresses are not considered IPv4 addresses and // therefore do not have the method toDotAddress(). } -``` -> Please note that calling `Multi::fromEmbedded()` returns an instance of -> `Multi` and effectively is the same as calling the factory method. +$ip = Multi::fromEmbedded('127.0.0.1', new Derived); +$ip->toCompactedAddress(); // string("2002:7f00:1::") +$ip->toDotAddress(); // string("127.0.0.1") +``` diff --git a/docs/05-strategies.md b/docs/05-strategies.md index b3e94ee..03a2f13 100644 --- a/docs/05-strategies.md +++ b/docs/05-strategies.md @@ -42,7 +42,7 @@ use Darsyn\IP\Version\Multi as IP; IP::setDefaultEmbeddingStrategy(new Strategy\Compatible); // But for this specific instance use the 6to4-derived embedding strategy. -$ip = IP::factory('127.0.0.1', new Strategy\Derived); +$ip = IP::fromProtocol('127.0.0.1', new Strategy\Derived); ``` ## Canonical and Non-Canonical Packing @@ -158,10 +158,10 @@ use Darsyn\IP\Version\Multi as IP; $strategy = new Composite(new Mapped, Nat64::wellKnown()); // Addresses embedded under either scheme are recognised as version 4. -IP::factory('::ffff:7f00:1', $strategy)->toDotAddress(); // string("127.0.0.1") -IP::factory('64:ff9b::7f00:1', $strategy)->toDotAddress(); // string("127.0.0.1") +IP::fromProtocol('::ffff:7f00:1', $strategy)->toDotAddress(); // string("127.0.0.1") +IP::fromProtocol('64:ff9b::7f00:1', $strategy)->toDotAddress(); // string("127.0.0.1") // But only the first strategy (here, Mapped) is ever used to pack a version 4 // address into version 6. -IP::factory('127.0.0.1', $strategy)->toCompactedAddress(); // string("::ffff:7f00:1") +IP::fromProtocol('127.0.0.1', $strategy)->toCompactedAddress(); // string("::ffff:7f00:1") ``` diff --git a/docs/06-formatters.md b/docs/06-formatters.md index 10b6cd7..bc35621 100644 --- a/docs/06-formatters.md +++ b/docs/06-formatters.md @@ -19,7 +19,7 @@ use Darsyn\IP\Formatter\NativeFormatter; use Darsyn\IP\Version\Multi as IP; IP::setProtocolFormatter(new NativeFormatter); -$ip = IP::factory('::ffff:c22:384e'); +$ip = IP::fromProtocol('::ffff:c22:384e'); $ip->toCompactedAddress(); // string("::ffff:12.34.56.78") ``` @@ -39,7 +39,7 @@ use Darsyn\IP\Formatter\NativeFormatter; use Darsyn\IP\Version\IPv6 as IP; IP::setProtocolFormatter(new ConsistentFormatter()); -$ip = IP::factory('::ffff:c22:384e'); +$ip = IP::fromProtocol('::ffff:c22:384e'); $ip->toCompactedAddress(); // string("::ffff:c22:384e") $ip->toCompactedAddress(new NativeFormatter); // string("::ffff:12.34.56.78") diff --git a/docs/07-types.md b/docs/07-types.md index cce4326..9b4695b 100644 --- a/docs/07-types.md +++ b/docs/07-types.md @@ -14,7 +14,7 @@ the embedding strategy used when creating the IP object. isEmbedded(); // bool(true) ``` @@ -28,7 +28,7 @@ statement: use Darsyn\IP\Strategy\Derived; use Darsyn\IP\Version\Multi as IP; -$ip = IP::factory('127.0.0.1', new Derived); +$ip = IP::fromProtocol('127.0.0.1', new Derived); $rfc4291 = $ip->isMapped() || $ip->isCompatible(); // bool(false) ``` @@ -43,7 +43,7 @@ this method. isMapped(); // bool(true) ``` @@ -58,7 +58,7 @@ method. isDerived(); // bool(true) ``` @@ -75,7 +75,7 @@ for this method. isCompatible(); // bool(true) ``` @@ -156,7 +156,7 @@ Link-Local Addresses") (IPv4) or [RFC 4291 section isLinkLocal(); // bool(false) ``` @@ -172,7 +172,7 @@ Architecture") (IPv6). isLoopback(); // bool(true) ``` @@ -188,7 +188,7 @@ Address Assignments") (IPv4) or [RFC 4291 section isMulticast(); // bool(false) ``` @@ -203,7 +203,7 @@ Private Internets") (IPv4) or [RFC 4193](https://tools.ietf.org/html/rfc4193 isPrivateUse(); // bool(false) ``` @@ -218,7 +218,7 @@ Version 6 Addressing Architecture") (IPv6). isUnspecified(); // bool(false) ``` @@ -236,7 +236,7 @@ Network Interconnect Devices") corrected in [errata isBenchmarking(); // bool(false) ``` @@ -251,7 +251,7 @@ Address Prefix Reserved for Documentation") (IPv6). isDocumentation(); // bool(false) ``` @@ -267,7 +267,7 @@ following: isGloballyReachable(); // bool(false) ``` @@ -285,8 +285,8 @@ Whether the IP is a broadcast address, according to isBroadcast(); // bool(false) -IPv4::factory('255.255.255.255')->isBroadcast(); // bool(true) +IPv4::fromProtocol('127.0.0.1')->isBroadcast(); // bool(false) +IPv4::fromProtocol('255.255.255.255')->isBroadcast(); // bool(true) ``` ### Reserved for Future Use @@ -298,8 +298,8 @@ Whether the IP is reserved for future use, according to [RFC isFutureReserved(); // bool(false) -IPv4::factory('255.34.85.169')->isFutureReserved(); // bool(true) +IPv4::fromProtocol('127.0.0.1')->isFutureReserved(); // bool(false) +IPv4::fromProtocol('255.34.85.169')->isFutureReserved(); // bool(true) ``` ### Shared @@ -312,8 +312,8 @@ Address Space"). isShared(); // bool(false) -IPv4::factory('100.127.43.2')->isShared(); // bool(true) +IPv4::fromProtocol('100.128.179.30')->isShared(); // bool(false) +IPv4::fromProtocol('100.127.43.2')->isShared(); // bool(true) ``` ## IPv6 Specific @@ -335,7 +335,7 @@ The following constants are available on `Darsyn\IP\Version\Version6Interface`: getMulticastScope() === IPv6::MULTICAST_ORGANIZATION_LOCAL; // bool(true) +$isOrganizationLocal = IPv6::fromProtocol('ff08:1:6e6f:cbb::980e:3816')->getMulticastScope() === IPv6::MULTICAST_ORGANIZATION_LOCAL; // bool(true) ``` ### Unique Local @@ -347,8 +347,8 @@ Whether the IP is a unique local address, according to [RFC isUniqueLocal(); // bool(false) -IPv6::factory('fdff:ffff::')->isUniqueLocal(); // bool(true) +IPv6::fromProtocol('b638:cc70:716:c4d4:f69c:4ee3:6c65:a0b2')->isUniqueLocal(); // bool(false) +IPv6::fromProtocol('fdff:ffff::')->isUniqueLocal(); // bool(true) ``` ### Unicast @@ -362,8 +362,8 @@ vice-versa). isUnicast(); // bool(false) -IPv6::factory('::ffff:1:0')->isUnicast(); // bool(true) +IPv6::fromProtocol('ff08::')->isUnicast(); // bool(false) +IPv6::fromProtocol('::ffff:1:0')->isUnicast(); // bool(true) ``` ### Unicast Global @@ -376,6 +376,6 @@ Architecture"). isUnicastGlobal(); // bool(false) -IPv6::factory('140c:12f1:6e6f:c0bb:980e:3816:3e52:1193')->isUnicastGlobal(); // bool(true) +IPv6::fromProtocol('2001:db8:85a3::8a2e:370:7334')->isUnicastGlobal(); // bool(false) +IPv6::fromProtocol('140c:12f1:6e6f:c0bb:980e:3816:3e52:1193')->isUnicastGlobal(); // bool(true) ```