From a9544a5e7f0ee6dfd19398c3bd56caaa405c17d1 Mon Sep 17 00:00:00 2001
From: Zan Baldwin <hello@zanbaldwin.com>
Date: Wed, 16 Sep 2026 14:35:30 +0200
Subject: [PATCH 1/2] =?UTF-8?q?docs(doctrine):=20=F0=9F=93=9A=20explain=20?=
 =?UTF-8?q?how=20to=20pass=20IP=20values=20to=20QueryBuilder=20and=20DQL?=
 =?UTF-8?q?=20parameters?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An untyped parameter is bound as a string, so the object is cast to protocol notation and silently matches nothing (#87, #91).
---
 docs/08-doctrine.md | 46 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/docs/08-doctrine.md b/docs/08-doctrine.md
index 0ad99df..5e74923 100644
--- a/docs/08-doctrine.md
+++ b/docs/08-doctrine.md
@@ -45,3 +45,49 @@ class AnalyticsEntity
     public IP $ipAddress;
 }
 ```
+
+## Querying
+
+Doctrine converts a value through the `ip` type only when it knows the column
+type. Repository methods such as `findBy()`, `findOneBy()` and the magic
+`findByIpAddress()` read the type from the entity mapping, so they accept an IP
+object directly.
+
+```php
+<?php
+use Darsyn\IP\Version\Multi as IP;
+
+$ip = IP::fromProtocol('192.168.0.1');
+$entities = $repository->findBy(['ipAddress' => $ip]);
+```
+
+The QueryBuilder and DQL do not know which column a parameter is compared
+against. A parameter passed to `setParameter()` without a type is bound as a
+plain string:
+
+- An IP object is cast to its protocol notation (`"192.168.0.1"`) and compared
+  against the raw bytes stored in the column. No row matches and no error is
+  raised.
+- A raw binary string from `getBinary()` is bound as text. This matches on MySQL
+  but not on SQLite, where text and binary values never compare equal.
+
+Always pass the type name as the third argument to `setParameter()`:
+
+```php
+<?php
+use Darsyn\IP\Version\Multi as IP;
+
+$ip = IP::fromProtocol('192.168.0.1');
+$entities = $repository->createQueryBuilder('a')
+    ->andWhere('a.ipAddress = :address')
+    ->setParameter('address', $ip, 'ip')
+    ->getQuery()
+    ->getResult();
+```
+
+`'ip'` is the name the type was registered under (either `Type::addType()` or
+the Symfony configuration shown above). The type accepts an IP object or a
+protocol string, converts it to the stored binary form, and binds it as binary
+on every database platform. If you must bind raw bytes yourself, pass
+`Doctrine\DBAL\ParameterType::BINARY` (DBAL v2.8+, otherwise `\PDO::PARAM_LOB`)
+as the third argument instead.

From 9c14040ef5b25a506d2dd1c465622ec5aadb00b8 Mon Sep 17 00:00:00 2001
From: Zan Baldwin <hello@zanbaldwin.com>
Date: Wed, 16 Sep 2026 14:48:22 +0200
Subject: [PATCH 2/2] =?UTF-8?q?docs(doctrine):=20=F0=9F=93=9A=20state=20th?=
 =?UTF-8?q?e=20DBAL=20version=20per=20darsyn/ip-doctrine=20major?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/08-doctrine.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/08-doctrine.md b/docs/08-doctrine.md
index 5e74923..cdca4a9 100644
--- a/docs/08-doctrine.md
+++ b/docs/08-doctrine.md
@@ -6,7 +6,9 @@
 > functionality.
 
 This library can be used to support IP address as column types with Doctrine
-DBAL versions `^2.3 || ^3.0`.
+DBAL. Version `5.*` of `darsyn/ip-doctrine` supports DBAL `^2.3 || ^3.0` (PHP
+`5.6` and greater), and version `6.*` supports DBAL `^4` (PHP `8.1` and
+greater).
 
 Three Doctrine types are provided to match the three version classes: