Upgrading to 7.0

Migrate from auditor-bundle 6.x to 7.0

This guide covers upgrading from auditor-bundle 6.x to 7.0.

📋 Requirements Changes

PHP

6.x	7.0
>= 8.2	>= 8.4

Symfony

6.x	7.0
>= 5.4	>= 8.0

CAUTION

Symfony 5.4, 6.x, and 7.x are no longer supported.

Doctrine

Package	6.x	7.0
DBAL	>= 3.2	>= 4.0
ORM	>= 2.13	>= 3.2
DoctrineBundle	>= 2.0	>= 3.0

auditor Library

6.x	7.0
>= 3.0	>= 4.0

TIP

See auditor upgrade guide for library-specific changes.

PHPUnit

6.x	7.0
>= 11.0	>= 12.0

🔧 Bundle Changes

AbstractBundle Migration

The bundle now extends Symfony\Component\HttpKernel\Bundle\AbstractBundle instead of Bundle.

This is an internal change and doesn't affect your configuration.

🗑️ Removed Classes

Removed Class	Reason
DH\AuditorBundle\DependencyInjection\Configuration	Merged into DHAuditorBundle::configure()
DH\AuditorBundle\DependencyInjection\DHAuditorExtension	Merged into DHAuditorBundle::loadExtension()
DH\AuditorBundle\DependencyInjection\Compiler\AddProviderCompilerPass	No longer needed with autowiring
DH\AuditorBundle\DependencyInjection\Compiler\CustomConfigurationCompilerPass	Merged into bundle
DH\AuditorBundle\DependencyInjection\Compiler\DoctrineProviderConfigurationCompilerPass	Replaced by DoctrineMiddlewareCompilerPass

🗑️ Removed Files

• src/Resources/config/services.yaml - Services defined programmatically

Composer Scripts

The following composer scripts have been removed:

• setup5 (Symfony 5.4)
• setup6 (Symfony 6.4)
• setup7 (Symfony 7.x)
• setup8 (Symfony 8.0)

Use the new unified setup script instead:

composer setup

🚀 Upgrade Steps

1️⃣ Update PHP

Ensure you have PHP 8.4+:

php -v
# PHP 8.4.x ...

2️⃣ Update Symfony

composer require symfony/framework-bundle:^8.0

3️⃣ Update Doctrine

composer require \
    doctrine/dbal:^4.0 \
    doctrine/orm:^3.2 \
    doctrine/doctrine-bundle:^3.0

4️⃣ Update auditor

composer require damienharper/auditor:^4.0

5️⃣ Update auditor-bundle

composer require damienharper/auditor-bundle:^7.0

6️⃣ Clear Cache

bin/console cache:clear

7️⃣ Check Schema

bin/console audit:schema:update --dump-sql

8️⃣ Run Tests

bin/phpunit

⚙️ Configuration

No configuration changes required. Your dh_auditor.yaml should work as-is.

⚠️ Breaking Changes

auditor Library Changes

This bundle requires damienharper/auditor >= 4.0 which introduces several breaking changes.

Namespace Rename: Annotation → Attribute

IMPORTANT

The Annotation namespace has been renamed to Attribute to align with PHP 8+ terminology.

// Before (auditor 3.x)
use DH\Auditor\Provider\Doctrine\Auditing\Annotation\Auditable;
use DH\Auditor\Provider\Doctrine\Auditing\Annotation\Ignore;

// After (auditor 4.0)
use DH\Auditor\Provider\Doctrine\Auditing\Attribute\Auditable;
use DH\Auditor\Provider\Doctrine\Auditing\Attribute\Ignore;

utf8_convert is now opt-in

IMPORTANT

The implicit mb_convert_encoding() pass that ran on every audit entry has been removed from the default path.

In auditor 3.x, UTF-8 conversion ran automatically. In auditor 4.0 it defaults to false because DBAL 4 enforces UTF-8 connections on PHP 8.4+, making the conversion a no-op for virtually all modern applications.

If your application handles data from legacy non-UTF-8 sources, re-enable it explicitly:

# config/packages/dh_auditor.yaml
dh_auditor:
    providers:
        doctrine:
            utf8_convert: true

Entry Model - Property Hooks (PHP 8.4)

The Entry model now uses PHP 8.4 property hooks. Getter methods have been replaced by direct property access:

// Before (auditor 3.x)
$entry->getId();
$entry->getType();
$entry->getObjectId();
$entry->getUserId();
$entry->getUsername();
$entry->getCreatedAt();

// After (auditor 4.0)
$entry->id;
$entry->type;
$entry->objectId;
$entry->userId;
$entry->username;
$entry->createdAt;

TIP

See auditor UPGRADE-4.0.md for the complete list of changes.

Route Names

The viewer route names have been updated for consistency:

Before (6.x)	After (7.0)
dh_auditor_show_entity_history	dh_auditor_show_entity_stream
dh_auditor_show_transaction	dh_auditor_show_transaction_stream

Update any route references in your code:

// Before
$url = $urlGenerator->generate('dh_auditor_show_entity_history', [...]);

// After
$url = $urlGenerator->generate('dh_auditor_show_entity_stream', [...]);

ConsoleUserProvider

CLI commands now use the command name as the user identifier instead of a generic "command" string:

Before (6.x)	After (7.0)
id: "command"	id: "app:import-users"
username: "app:import-users"	username: "app:import-users"

This allows filtering audit entries by specific CLI command in the viewer.

NOTE

Existing audit entries with blame_id = "command" will not be automatically migrated.

Template Blocks

The following Twig blocks have been removed from the base layout:

Removed Block	Reason
navbar	Replaced by built-in header
breadcrumbs	No longer used

Available blocks in 7.0:

Block	Description	Available in
title	Page title	All pages
stylesheets	CSS includes	All pages
dh_auditor_content	Main content area	All pages
dh_auditor_header	Sub-header with back link & filters	Entity stream, Transaction view
dh_auditor_pager	Pagination	Entity stream
javascripts	JavaScript includes	All pages

If you override layout.html.twig and use any of the removed blocks, update your template accordingly.

UserProvider

The AnonymousToken handling was removed (deprecated in Symfony 6.0).

Before (6.x):

if ($token instanceof AnonymousToken) {
    return null;
}

After (7.0): Anonymous tokens no longer exist in Symfony 8.0.

Custom Providers

If you have custom providers extending bundle classes, verify they still work.

The provider interfaces from the auditor library haven't changed:

• UserProviderInterface
• SecurityProviderInterface
• RoleCheckerInterface

PHP Attributes Migration

The bundle now uses modern PHP 8.4+ and Symfony 8+ attributes for service auto-configuration:

Class	Change
ConsoleEventSubscriber	Uses #[AsEventListener] instead of EventSubscriberInterface
ViewerEventSubscriber	Uses #[AsEventListener] instead of EventSubscriberInterface
ViewerController	Uses #[AsController] attribute
TimeAgoExtension	Uses #[AsTwigFilter] instead of extending AbstractExtension
RoutingLoader	Uses #[AutoconfigureTag('routing.loader')] attribute

🔒 Final Classes

CAUTION

The following classes are now final and cannot be extended:

// These classes can no longer be extended
DH\AuditorBundle\Event\ConsoleEventSubscriber
DH\AuditorBundle\Event\ViewerEventSubscriber
DH\AuditorBundle\Twig\TimeAgoExtension
DH\AuditorBundle\Routing\RoutingLoader
DH\AuditorBundle\User\UserProvider
DH\AuditorBundle\User\ConsoleUserProvider
DH\AuditorBundle\Security\SecurityProvider
DH\AuditorBundle\Security\RoleChecker
DH\AuditorBundle\Viewer\ActivityGraphProvider

If you were extending any of these classes, you'll need to use composition instead of inheritance.

ActivityGraphProvider API Changes

ActivityGraphProvider now uses PHP 8.4 property hooks with asymmetric visibility:

// Before (6.x)
$days = $provider->getDays();
$layout = $provider->getLayout();

// After (7.0)
$days = $provider->days;
$layout = $provider->layout;

SecurityProvider

SecurityProvider now uses #[Autowire] attribute for dependency injection. This is an internal change but may affect you if you were manually constructing this service.

🔧 Troubleshooting

Class Not Found

If you get class not found errors for removed classes, you may have code referencing internal bundle classes. Update to use public APIs only.

Configuration Errors

Clear cache and warmup:

bin/console cache:clear
bin/console cache:warmup

Schema Issues

Check and update audit tables:

bin/console audit:schema:update --dump-sql
bin/console audit:schema:update --force

❓ Need Help?

• Check GitHub Issues
• Open a new issue with details about your error