Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions docs/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## [Unreleased]

### Added

- DDD host (B3 of the DDD-host checklist, REQ-ARCH-001): the bundle's table can stay off a host's domain entity manager. Three opt-in options under `doctrine`, defaults unchanged (standard Symfony path):
- `register_mapping` (default `true`): `false` leaves the mapping of `HttpLogEntry` to the host; the bundle then adds a disabled `NowoHttpLogBundle` mapping so Doctrine `auto_mapping` does not map the entity on the auto-mapped manager too.
- `mapping_type` (default `attribute`): `xml` registers the shipped `src/Resources/config/doctrine/HttpLogEntry.orm.xml` (same table, columns, options, indexes and repository as the attributes).
- `entity_manager` (default `null`): maps the entity on that manager instead of the default one; the container build fails unless the manager exists and is the only one mapping the bundle entities (`HttpLogEntityManagerPass`).
- Tests: `XmlMappingParityTest` (XML vs attributes: metadata and DDL on SQLite, MySQL and PostgreSQL, with the table-naming and path-prefix listeners), `DedicatedEntityManagerKernelTest` (XML host leg: entries on a dedicated manager and connection, mapped by the bundle or by the host, with `auto_mapping` on the host manager; a pending host change is never flushed; double mapping fails the build), prepend and pass unit tests.

### Changed

- Internal: `HttpLogCommitTrackingPass` reads the managers mapping the entries through the new internal `EntityManagerMappings` helper (same result).

## [1.23.1] - 2026-11-21

### Changed
Expand Down
21 changes: 21 additions & 0 deletions docs/CONFIGURATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ All options live under the root key `nowo_http_log` (alias `nowo_http_log`).
- [redaction](#redaction)
- [retention](#retention)
- [doctrine](#doctrine)
- [Mapping and entity manager (1.24)](#mapping-and-entity-manager-124)
- [export](#export)
- [web_ui](#web_ui)
- [Form profile (FormKit)](#form-profile-formkit)
Expand Down Expand Up @@ -92,6 +93,9 @@ nowo_http_log:
doctrine:
table_name_prefix: nowo_http_log_ # Replaces the nowo_http_log_ part of the table name (REQ-ORM-002)
table_prefix: '' # Prefix for nowo_http_log_entry + index names (REQ-ORM-002)
register_mapping: true # 1.24: false = the host maps HttpLogEntry itself (DDD host)
mapping_type: attribute # 1.24: attribute | xml (shipped src/Resources/config/doctrine/HttpLogEntry.orm.xml)
entity_manager: null # 1.24: the manager holding the entries (null = whichever maps them)
export:
formats:
- csv
Expand Down Expand Up @@ -252,6 +256,23 @@ from its default) rewrites the `HttpLogEntry` mapping only. Changing either opti
table: run the rename statements from [UPGRADING](UPGRADING.md#to-1211) (or generate a migration and turn the
drop/create into a rename) instead of dropping the table.

### Mapping and entity manager (1.24)

Three options decide where `HttpLogEntry` is mapped (B3 of the DDD-host checklist). The defaults keep the 1.23 mapping:
the entity attributes, as a bundle mapping named `NowoHttpLogBundle`, on the default entity manager.

| Key | Default | Description |
| --- | --- | --- |
| `register_mapping` | `true` | `true`: the bundle registers the mapping. `false`: the host maps the entity itself (any mapping name, e.g. from the shipped XML); the bundle then adds a disabled `NowoHttpLogBundle` mapping so Doctrine `auto_mapping` does not map the entity on the auto-mapped manager too (unless the host already uses that mapping name). A literal boolean (no `%env()%`). |
| `mapping_type` | `attribute` | What the bundle registers while `register_mapping` is true: `attribute` (the entity attributes) or `xml` (`src/Resources/config/doctrine/HttpLogEntry.orm.xml`: same table, columns, options, indexes and repository; CI checks the parity and the DDL on SQLite, MySQL and PostgreSQL). Switching it changes no schema. |
| `entity_manager` | `null` | `null`: the services use whichever manager maps the entity (`ManagerRegistry::getManagerForClass()`). A name: with `register_mapping: true` the mapping goes on that manager instead of the default one, which must be declared under `doctrine.orm.entity_managers` (or be the default manager). Either way the container build fails unless that manager exists and is the **only** manager mapping `Nowo\HttpLogBundle\Entity`. A literal name (no `%env()%`). |

Every option of this section (table names, path prefix and usage columns, rollup tables, exact collations) applies on
whichever manager maps the entity, attribute or XML. The bundle never flushes a host manager: entries are written by
DBAL on the connection of the manager that maps them. Moving the table to another connection is a data move (copy
the rows, or keep both managers on one connection): the bundle does not migrate rows. See
[USAGE](USAGE.md#keeping-the-log-table-off-your-domain-manager-124) for a DDD host configuration.

**PostgreSQL with a SEQUENCE id strategy** (only when you set DoctrineBundle's `identity_generation_preferences` to
`SEQUENCE` for PostgreSQL; the ORM 3 default is IDENTITY, whose sequence PostgreSQL names after the prefixed table):
the sequence keeps its unprefixed name `nowo_http_log_entry_id_seq`. The listener does not rename it, on purpose: a
Expand Down
2 changes: 1 addition & 1 deletion docs/INSTALLATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ Copy the default YAML from the recipe or from `src/Resources/config/packages/now

## Database schema

The bundle registers a Doctrine mapping for `Nowo\HttpLogBundle\Entity\HttpLogEntry` (table `nowo_http_log_entry` by default, renamed by `doctrine.table_name_prefix`: see [CONFIGURATION](CONFIGURATION.md#doctrine)).
The bundle registers a Doctrine mapping for `Nowo\HttpLogBundle\Entity\HttpLogEntry` (table `nowo_http_log_entry` by default, renamed by `doctrine.table_name_prefix`: see [CONFIGURATION](CONFIGURATION.md#doctrine)) on the default entity manager. Since 1.24 it can map the shipped XML instead, on a manager of your own, or leave the mapping to you (`doctrine.register_mapping`, `mapping_type`, `entity_manager`: see [CONFIGURATION](CONFIGURATION.md#mapping-and-entity-manager-124)).

Generate and run a migration:

Expand Down
13 changes: 13 additions & 0 deletions docs/UPGRADING.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,19 @@ This document describes how to upgrade between versions of **Http Log Bundle**.

## Unreleased

Nothing to change: the defaults keep the 1.23 mapping (attributes, on the default entity manager).

Opt-in (DDD host): keep the log table off your domain manager with `doctrine.mapping_type: xml` and
`doctrine.entity_manager: <name>`, or map the shipped XML yourself with `doctrine.register_mapping: false`
([CONFIGURATION](CONFIGURATION.md#mapping-and-entity-manager-124)). Notes:

- If you already map `Nowo\HttpLogBundle\Entity` by hand on another manager (next to the bundle's own mapping on the
default one), set `register_mapping: false` (and `entity_manager`) so only your mapping remains; `entity_manager`
makes the build fail while a second manager still maps the entity.
- Moving the table to another connection does not move the rows: copy them first, or point the dedicated manager at
the same connection.
- `register_mapping`, `mapping_type` and `entity_manager` are read at compile time: `%env()%` is rejected.

## To 1.23.1

From **1.23.0**:
Expand Down
48 changes: 47 additions & 1 deletion docs/USAGE.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ How to capture HTTP traffic, use the admin UI, export, purge, and exclude routes
- [Backfill](#backfill)
- [Standard Symfony host](#standard-symfony-host)
- [DDD / hexagonal host](#ddd--hexagonal-host)
- [Keeping the log table off your domain manager (1.24)](#keeping-the-log-table-off-your-domain-manager-124)
- [Keeping your domain free of the bundle](#keeping-your-domain-free-of-the-bundle)
- [Entry-recorded event](#entry-recorded-event)
- [Known limitations](#known-limitations)
Expand Down Expand Up @@ -729,7 +730,7 @@ hooks are autoconfigured services: the request-context resolver
## DDD / hexagonal host

The same bundle, with the domain kept free of Symfony and Doctrine types (REQ-ARCH-001). Nothing is forced: no base
class, no trait, no `resolve_target_entities`, no XML mapping to ship (the bundle owns its table and never maps your
class, no trait, no `resolve_target_entities`, no XML mapping to write (the bundle owns its table and never maps your
entities). Every port a host implements or calls takes scalars or bundle value objects:

| Need | Port (no framework type) | Value objects |
Expand All @@ -741,6 +742,51 @@ entities). Every port a host implements or calls takes scalars or bundle value o
| Erase / export personal data | `Privacy\HttpLogPersonalDataErasureInterface`, `HttpLogPersonalDataExporterInterface` | `HttpLogPersonalDataSubject`, `HttpLogErasureResult` |
| Erase usage of a credential or tenant | `Privacy\HttpLogUsageEraserInterface` | scalars |

### Keeping the log table off your domain manager (1.24)

By default the bundle maps `HttpLogEntry` (attributes) on the default entity manager. A host whose default manager holds
only its domain moves the table to a manager of its own ([CONFIGURATION](CONFIGURATION.md#doctrine)):

```yaml
doctrine:
dbal:
connections:
default: { url: '%env(resolve:DATABASE_URL)%' }
http_log: { url: '%env(resolve:HTTP_LOG_DATABASE_URL)%' } # or the same URL: a separate manager is enough
orm:
default_entity_manager: default
entity_managers:
default: { connection: default, mappings: { App: { type: xml, dir: '%kernel.project_dir%/config/doctrine', prefix: 'App\Domain' } } }
http_log: { connection: http_log }

nowo_http_log:
doctrine:
mapping_type: xml # the shipped src/Resources/config/doctrine/HttpLogEntry.orm.xml
entity_manager: http_log # mapped there only; the build fails if another manager maps it too
```

Or map it yourself (`register_mapping: false`) from the shipped XML, under any mapping name; the bundle then keeps
Doctrine `auto_mapping` from mapping it on the auto-mapped manager:

```yaml
doctrine:
orm:
entity_managers:
http_log:
connection: http_log
mappings:
HttpLog: { type: xml, is_bundle: false, prefix: 'Nowo\HttpLogBundle\Entity', dir: '%kernel.project_dir%/vendor/nowo-tech/http-log-bundle/src/Resources/config/doctrine' }

nowo_http_log:
doctrine:
register_mapping: false
entity_manager: http_log # optional: checks that this manager, and only it, maps the entries
```

The bundle writes entries by DBAL on that manager's connection and never flushes, clears or resets a host manager (it
resets the manager only when it is closed and maps the bundle's entities alone). Give the dedicated manager the bundle's
entities only: none of your entities ever reach it.

### Keeping your domain free of the bundle

- **Feeding context in.** Implement `HttpRequestContextResolverInterface` in your infrastructure layer and return an
Expand Down
97 changes: 97 additions & 0 deletions src/DependencyInjection/Compiler/EntityManagerMappings.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
<?php

declare(strict_types=1);

namespace Nowo\HttpLogBundle\DependencyInjection\Compiler;

use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Reference;

use function array_keys;
use function is_array;
use function is_string;
use function preg_match;
use function rtrim;
use function sprintf;
use function str_starts_with;

/**
* Reads DoctrineBundle's compiled definitions: which configured entity managers map the bundle entities, and the
* connection of a manager. Shared by {@see HttpLogCommitTrackingPass} and {@see HttpLogEntityManagerPass}.
*
* @internal
*/
final class EntityManagerMappings
{
/** Namespace of the bundle's entities. */
public const ENTITY_NAMESPACE = 'Nowo\\HttpLogBundle\\Entity';

/**
* Every configured manager whose metadata driver chain has a driver for a namespace covering the bundle entities.
*
* @return list<string>
*/
public static function managersMappingTheEntities(ContainerBuilder $container): array
{
$found = [];
foreach (self::managerNames($container) as $name) {
$chainId = sprintf('doctrine.orm.%s_metadata_driver', $name);
if (!$container->hasDefinition($chainId)) {
continue;
}

foreach ($container->getDefinition($chainId)->getMethodCalls() as $call) {
if ($call[0] === 'addDriver' && self::mapsTheEntities($call[1])) {
$found[] = $name;

break;
}
}
}

return $found;
}

/**
* Names of the configured entity managers (DoctrineBundle's `doctrine.entity_managers` parameter).
*
* @return list<string>
*/
public static function managerNames(ContainerBuilder $container): array
{
$managers = $container->hasParameter('doctrine.entity_managers') ? $container->getParameter('doctrine.entity_managers') : [];
$names = [];
foreach (array_keys(is_array($managers) ? $managers : []) as $name) {
$names[] = (string) $name;
}

return $names;
}

public static function connectionOf(ContainerBuilder $container, string $manager): ?string
{
$id = sprintf('doctrine.orm.%s_entity_manager', $manager);
$argument = $container->hasDefinition($id) ? ($container->getDefinition($id)->getArguments()[0] ?? null) : null;
if ($argument instanceof Reference && preg_match('/^doctrine\.dbal\.(.+)_connection$/D', (string) $argument, $match) === 1) {
return $match[1];
}

return null;
}

/**
* @param array<mixed> $arguments the `addDriver(driver, namespace)` arguments
*/
private static function mapsTheEntities(array $arguments): bool
{
$namespace = $arguments[1] ?? null;
if (!is_string($namespace)) {
return false;
}

$mapped = rtrim($namespace, '\\') . '\\';
$bundle = self::ENTITY_NAMESPACE . '\\';

return str_starts_with($bundle, $mapped) || str_starts_with($mapped, $bundle);
}
}
66 changes: 3 additions & 63 deletions src/DependencyInjection/Compiler/HttpLogCommitTrackingPass.php
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,9 @@
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Reference;

use function array_keys;
use function array_unique;
use function array_values;
use function is_array;
use function is_string;
use function preg_match;
use function rtrim;
use function sprintf;
use function str_starts_with;

/**
* 1.22 (REQ-RUNTIME-003 rule 6): scopes the commit tracking of the conflict answer (audit UE-CF-1: never every host
Expand All @@ -46,7 +40,7 @@ final class HttpLogCommitTrackingPass implements CompilerPassInterface
public const TRANSACTION_DOCTRINE_MIDDLEWARE = 'nowo_transaction_doctrine.commit_tracking_middleware';

/** Namespace of the bundle's entities. */
public const ENTITY_NAMESPACE = 'Nowo\\HttpLogBundle\\Entity';
public const ENTITY_NAMESPACE = EntityManagerMappings::ENTITY_NAMESPACE;

public function process(ContainerBuilder $container): void
{
Expand Down Expand Up @@ -94,11 +88,11 @@ private function transactionDoctrineTracksCommits(ContainerBuilder $container):
private function bundleConnections(ContainerBuilder $container): array
{
$default = $container->hasParameter('doctrine.default_entity_manager') ? $container->getParameter('doctrine.default_entity_manager') : 'default';
$managers = [is_string($default) && $default !== '' ? $default : 'default', ...$this->managersMappingTheEntities($container)];
$managers = [is_string($default) && $default !== '' ? $default : 'default', ...EntityManagerMappings::managersMappingTheEntities($container)];

$connections = [];
foreach ($managers as $name) {
$connection = $this->connectionOf($container, $name);
$connection = EntityManagerMappings::connectionOf($container, $name);
if ($connection !== null) {
$connections[] = $connection;
}
Expand All @@ -111,58 +105,4 @@ private function bundleConnections(ContainerBuilder $container): array

return array_values(array_unique($connections));
}

/**
* Every configured manager whose metadata driver chain has a driver for a namespace covering the bundle entities.
*
* @return list<string>
*/
private function managersMappingTheEntities(ContainerBuilder $container): array
{
$managers = $container->hasParameter('doctrine.entity_managers') ? $container->getParameter('doctrine.entity_managers') : [];
$found = [];
foreach (array_keys(is_array($managers) ? $managers : []) as $name) {
$chainId = sprintf('doctrine.orm.%s_metadata_driver', $name);
if (!$container->hasDefinition($chainId)) {
continue;
}

foreach ($container->getDefinition($chainId)->getMethodCalls() as $call) {
if ($call[0] === 'addDriver' && $this->mapsTheEntities($call[1])) {
$found[] = (string) $name;

break;
}
}
}

return $found;
}

/**
* @param array<mixed> $arguments the `addDriver(driver, namespace)` arguments
*/
private function mapsTheEntities(array $arguments): bool
{
$namespace = $arguments[1] ?? null;
if (!is_string($namespace)) {
return false;
}

$mapped = rtrim($namespace, '\\') . '\\';
$bundle = self::ENTITY_NAMESPACE . '\\';

return str_starts_with($bundle, $mapped) || str_starts_with($mapped, $bundle);
}

private function connectionOf(ContainerBuilder $container, string $manager): ?string
{
$id = sprintf('doctrine.orm.%s_entity_manager', $manager);
$argument = $container->hasDefinition($id) ? ($container->getDefinition($id)->getArguments()[0] ?? null) : null;
if ($argument instanceof Reference && preg_match('/^doctrine\.dbal\.(.+)_connection$/D', (string) $argument, $match) === 1) {
return $match[1];
}

return null;
}
}
Loading
Loading