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

🔑 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](https://github.com/Audit)\Auditable
 * [@Audit](https://github.com/Audit)\Security(view={"ROLE_ADMIN"})
 */
class User
{
    /**
     * [@Audit](https://github.com/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](https://github.com/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