Skip to main content
Version: 4.x

Upgrading to 3.x from 2.x

Migrate from annotations to PHP 8 attributes

This document describes the changes when upgrading from auditor 2.x to 3.x.

⚠️ Requirements Changes​

PHP Version​

IMPORTANT

Minimum PHP version is 8.2 (was 7.4 in 2.x)

Symfony Version​

Minimum Symfony version is 5.4 (was 4.4 in 2.x)

Symfony 6.x and 7.x are also supported.

Doctrine Versions​

Package2.x Version3.x Version
Doctrine DBALMixed>= 3.2
Doctrine ORMMixed>= 2.13

🔑 Key Changes​

PHP 8 Attributes​

TIP

3.x uses native PHP 8 attributes instead of Doctrine annotations.

Before (2.x with annotations):

use DH\Auditor\Provider\Doctrine\Auditing\Annotation as Audit;

/**
 * @Audit\Auditable
 * @Audit\Security(view={"ROLE_ADMIN"})
 */
class User
{
    /**
     * @Audit\Ignore
     */
    private string $password;
}

After (3.x with attributes):

use DH\Auditor\Provider\Doctrine\Auditing\Annotation\Auditable;
use DH\Auditor\Provider\Doctrine\Auditing\Annotation\Ignore;
use DH\Auditor\Provider\Doctrine\Auditing\Annotation\Security;

#[Auditable]
#[Security(view: ['ROLE_ADMIN'])]
class User
{
    #[Ignore]
    private string $password;
}

Type Declarations​

All classes now use strict type declarations:

declare(strict_types=1);

Method signatures have return types and parameter types.

Read-Only Properties​

Many classes now use PHP 8.1+ readonly properties:

final readonly class Reader implements ReaderInterface
{
    public function __construct(private DoctrineProvider $provider) {}
}

📋 Migration Steps​

1️⃣ Update PHP Version​

Ensure you're running PHP 8.2 or higher:

php -v
# PHP 8.2.x ...

2️⃣ Update Dependencies​

composer require damienharper/auditor:^3.0

3️⃣ Convert Annotations to Attributes​

Replace all Doctrine annotations with PHP 8 attributes:

# Find files with old annotations
grep -r "@Audit\\\\" src/Entity/

WARNING

Then update each entity to use the new attribute syntax.

4️⃣ Update Configuration​

If you have any configuration arrays, ensure they use the current option names.

5️⃣ Run Tests​

./vendor/bin/phpunit

❓ Need Help?​

Check the GitHub repository for:

  • Release notes
  • Open issues
  • Discussions