Enhance documentation for MysqlAes encryptor

- Updated CONFIGURATION.md to clarify the use of the `<ENC>` marker in MySQL and its implications for data insertion and retrieval.
- Expanded MYSQL_AES.md with detailed examples for inserting encrypted data using both Doctrine and native SQL, emphasizing the importance of column types and formats to avoid confusion.

Author: HecFranco

docs/CONFIGURATION.md

@@ -69,7 +69,7 @@ Each config has its own key file: `.{encryptor_class}.{alias}.key` (e.g. `.Halit
   ```
 
 - **MysqlAes**  
-  Compatible with MySQL [`AES_ENCRYPT()`](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html) / [`AES_DECRYPT()`](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html) (AES-128-ECB, default `block_encryption_mode`). The passphrase is a plain string (file or env). Use a **BLOB** column when encrypting in SQL. See [MYSQL_AES.md](MYSQL_AES.md) and the symfony8 demo (`/mysql-aes-note`). **Performance:** PHP OpenSSL on every ORM read/write; SQL `AES_ENCRYPT` only avoids PHP on insert/update for columns you manage in raw SQL. Searching secrets via `LIKE` on decrypted values in SQL is among the most expensive patterns — see [PERFORMANCE.md](PERFORMANCE.md).
+  Compatible with MySQL [`AES_ENCRYPT()`](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html) / [`AES_DECRYPT()`](https://dev.mysql.com/doc/refman/8.0/en/encryption-functions.html) (AES-128-ECB, default `block_encryption_mode`). The passphrase is a plain string (file or env). Use a **BLOB** column when encrypting in SQL. See [MYSQL_AES.md](MYSQL_AES.md) (INSERT examples, repository pattern, demo `/mysql-aes-note`) and the symfony8 demo routes under `/mysql-aes-note`. **Performance:** PHP OpenSSL on every ORM read/write; SQL `AES_ENCRYPT` only avoids PHP on insert/update for columns you manage in raw SQL. Searching secrets via `LIKE` on decrypted values in SQL is among the most expensive patterns — see [PERFORMANCE.md](PERFORMANCE.md).
 
 ### Encryptor and query performance (overview)
 

docs/MYSQL_AES.md

@@ -30,7 +30,236 @@ private ?string $secret = null;
 
 Doctrine will encrypt/decrypt in PHP (same algorithm as MySQL). The subscriber still appends the `<ENC>` marker for ORM-managed fields.
 
-## Native SQL (repository / DQL)
+## The `<ENC>` marker — when you need it (and when you must not add it)
+
+This is the most common source of confusion with **MysqlAes**.
+
+| How you insert | Column (demo) | `<ENC>` in DB? | How to read |
+|----------------|---------------|----------------|-------------|
+| **`$em->persist()`** + `#[Encrypted('mysql_aes')]` | `secret_orm` | **Yes** (added by subscriber) | Doctrine load, `\|decrypt('mysql_aes')`, `EncryptUtil` |
+| **`EncryptUtil::encrypt($plain, 'mysql_aes')`** then save | `secret_orm` | **Yes** (util adds it) | Same as above |
+| **`INSERT … AES_ENCRYPT(…)`** in SQL | `secret_native` (BLOB) | **No** | `AES_DECRYPT` in SQL, or `MysqlAesEncryptor::decrypt($blob)` in PHP |
+| **`INSERT … CONCAT(AES_ENCRYPT(…), '<ENC>')`** (advanced) | `secret_orm` | **Yes** (you append in SQL) | Doctrine / `\|decrypt('mysql_aes')` — see below |
+
+**Do not** append `<ENC>` to `secret_native` rows that you only read with `AES_DECRYPT`.  
+**Do not** expect `AES_DECRYPT(secret_orm, …)` to work on Doctrine-managed columns (ciphertext differs and includes `<ENC>`).
+
+### “I used `AES_ENCRYPT` and Doctrine / Twig does not decrypt”
+
+That is **expected** if:
+
+- You wrote to **`secret_orm`** without `<ENC>`, or
+- You wrote to **`secret_native`** but load the entity with Doctrine (subscriber looks for `<ENC>` on `secret_orm` only), or
+- You use `{{ value|decrypt }}` on a blob/hex string **without** the `<ENC>` suffix.
+
+**Fix:** pick one read path per column (see table above). In the demo, use **`/mysql-aes-note/db-values`** to compare raw vs decrypted.
+
+### Insert encrypted data **for Doctrine** (you do not build `<ENC>` yourself)
+
+Let the bundle add the marker:
+
+```php
+// Option A — entity (recommended)
+$note = new MysqlAesNote();
+$note->setTitle('Invoice');
+$note->setSecretOrm('my-secret'); // plaintext in PHP
+$em->persist($note);
+$em->flush(); // stored as: MysqlAes ciphertext + "<ENC>"
+
+// Option B — EncryptUtil (e.g. before raw UPDATE)
+use Nowo\DoctrineEncryptBundle\Util\EncryptUtil;
+
+$stored = $encryptUtil->encrypt('my-secret', 'mysql_aes');
+// $stored ends with "<ENC>" — safe to persist on an Encrypted property
+```
+
+Twig (value must be the **raw DB string** including `<ENC>`, e.g. from SQL export):
+
+```twig
+{{ row.secret_orm_raw|decrypt('mysql_aes') }}
+```
+
+### Insert with **`AES_ENCRYPT` in SQL** (no `<ENC>`)
+
+Use a **separate BLOB column** (demo: `secret_native`):
+
+```sql
+INSERT INTO mysql_aes_note (title, secret_native)
+VALUES ('SQL row', AES_ENCRYPT('my-secret', 'your_mysql_aes_passphrase'));
+```
+
+Read in SQL:
+
+```sql
+SELECT CAST(AES_DECRYPT(secret_native, 'your_mysql_aes_passphrase') AS CHAR) AS plain
+FROM mysql_aes_note WHERE id = 1;
+```
+
+Read in PHP (no `<ENC>`, no Twig `|decrypt`):
+
+```php
+$plain = $encryptorRegistry->get('mysql_aes')->decrypt($binaryBlobFromDb);
+```
+
+### Advanced: SQL `INSERT` into an ORM column **with** `<ENC>` (MySQL only)
+
+Only if you **must** insert in SQL but read via Doctrine/`#[Encrypted('mysql_aes')]` on the **same** column. The ciphertext bytes from MySQL must match PHP `MysqlAes` (same passphrase, default `block_encryption_mode`).
+
+```sql
+INSERT INTO mysql_aes_note (title, secret_orm)
+VALUES (
+    'From SQL for ORM',
+    CONCAT(AES_ENCRYPT('my-secret', :passphrase), '<ENC>')
+);
+```
+
+Prefer **VARBINARY/BLOB** for binary-safe storage; the demo uses `TEXT` for `secret_orm` (works for typical UTF-8 secrets but binary in `TEXT` can be charset-sensitive).
+
+After insert, `$em->find(MysqlAesNote::class, $id)` should decrypt on load.  
+**Do not** use this on `secret_native` if you also use `AES_DECRYPT` there — choose one format per column.
+
+## Inserting encrypted data in MySQL (native SQL)
+
+Use this when the **ciphertext must be produced by MySQL** (`AES_ENCRYPT`), e.g. legacy data, ETL, or another service writing directly to the DB. The plaintext is **not** stored; only the binary result of `AES_ENCRYPT` goes into the column.
+
+### 1. Table and column type
+
+Store ciphertext in **BLOB** or **VARBINARY** (not plain `TEXT`/`VARCHAR`):
+
+```sql
+CREATE TABLE my_secrets (
+    id INT AUTO_INCREMENT PRIMARY KEY,
+    title VARCHAR(255) NOT NULL,
+    secret_native BLOB NULL
+);
+```
+
+The **passphrase** is the same string you configure for `MysqlAes` (`MYSQL_AES_KEY` or key file content). MySQL pads it to 16 bytes internally (AES-128-ECB, default `block_encryption_mode`).
+
+### 2. INSERT in SQL (mysql client)
+
+Replace the passphrase with your env value (never commit real keys):
+
+```sql
+INSERT INTO my_secrets (title, secret_native)
+VALUES (
+    'Invoice ACME',
+    AES_ENCRYPT('password-doctrine-acme', 'change_me_mysql_aes_passphrase')
+);
+```
+
+Verify (decrypt in the same session):
+
+```sql
+SELECT id, title,
+       CAST(AES_DECRYPT(secret_native, 'change_me_mysql_aes_passphrase') AS CHAR) AS secret_plain
+FROM my_secrets;
+```
+
+Optional: inspect raw bytes as hex:
+
+```sql
+SELECT id, title, HEX(secret_native) AS secret_hex FROM my_secrets;
+```
+
+### 3. INSERT with bound parameters (Doctrine DBAL)
+
+Recommended in PHP: bind **plaintext** and **passphrase**; MySQL performs encryption server-side.
+
+```php
+use Doctrine\DBAL\Connection;
+
+final class MySecretRepository
+{
+    public function __construct(
+        private readonly Connection $connection,
+        private readonly string $mysqlAesKey, // inject %env(MYSQL_AES_KEY)%
+    ) {
+    }
+
+    public function insertEncrypted(string $title, string $plaintext): int
+    {
+        $this->connection->executeStatement(
+            'INSERT INTO my_secrets (title, secret_native)
+             VALUES (:title, AES_ENCRYPT(:plain, :key))',
+            [
+                'title' => $title,
+                'plain' => $plaintext,
+                'key'   => $this->mysqlAesKey,
+            ],
+        );
+
+        return (int) $this->connection->lastInsertId();
+    }
+}
+```
+
+Symfony `services.yaml`:
+
+```yaml
+services:
+    App\Repository\MySecretRepository:
+        arguments:
+            $mysqlAesKey: '%env(MYSQL_AES_KEY)%'
+```
+
+The demo implements the same pattern in `MysqlAesNoteRepository::insertWithAesEncrypt()` (symfony7/symfony8, route `/mysql-aes-note/sql/new`).
+
+### 4. UPDATE an existing row
+
+```sql
+UPDATE my_secrets
+SET secret_native = AES_ENCRYPT('new-secret-value', :passphrase)
+WHERE id = :id;
+```
+
+```php
+$this->connection->executeStatement(
+    'UPDATE my_secrets SET secret_native = AES_ENCRYPT(:plain, :key) WHERE id = :id',
+    ['plain' => $newSecret, 'key' => $this->mysqlAesKey, 'id' => $id],
+);
+```
+
+### 5. INSERT with multiple columns (plain + encrypted)
+
+Keep searchable metadata in **plain** columns; encrypt only sensitive fields:
+
+```sql
+INSERT INTO my_secrets (title, secret_native)
+VALUES (
+    :title,
+    AES_ENCRYPT(:secret, :key)
+);
+-- title = plain (LIKE / INDEX possible)
+-- secret_native = binary ciphertext
+```
+
+### 6. Two paths — do not mix formats on the same column
+
+| Path | How to insert | Column example | Stored format |
+|------|----------------|----------------|---------------|
+| **Doctrine + `#[Encrypted('mysql_aes')]`** | `$em->persist($entity); $em->flush();` | `secret_orm` TEXT | MysqlAes ciphertext + `<ENC>` marker |
+| **Native MySQL** | `INSERT … AES_ENCRYPT(:plain, :key)` | `secret_native` BLOB | Raw MySQL AES blob, **no** `<ENC>` |
+| **SQL for ORM (advanced)** | `INSERT … CONCAT(AES_ENCRYPT(…), '<ENC>')` | `secret_orm` | MySQL AES blob + `<ENC>` (see section above) |
+
+`AES_DECRYPT` on a Doctrine `secret_orm` value will **not** return the original text.  
+`{{ x|decrypt('mysql_aes') }}` does **nothing** unless `x` ends with `<ENC>`.
+
+### 7. Same key as the bundle `MysqlAes` encryptor
+
+The passphrase in SQL must match the config used by PHP:
+
+```yaml
+nowo_doctrine_encrypt:
+    configs:
+        mysql_aes:
+            encryptor_class: MysqlAes
+            secret_key_env_var: '%env(MYSQL_AES_KEY)%'
+```
+
+Then rows inserted with `AES_ENCRYPT(..., :key)` and rows encrypted via `#[Encrypted('mysql_aes')]` use the **same algorithm**, but **different storage formats** unless you only use the native BLOB column for SQL inserts.
+
+## Native SQL (repository / read)
 
 For **pure** `AES_ENCRYPT` / `AES_DECRYPT` in SQL (no `<ENC>` marker), use a **BLOB** (or VARBINARY) column and bind the **passphrase** (not the derived key bytes):