Skip to content

INSTALLATION.md

Latest commit

 

History

History
231 lines (163 loc) · 7 KB

INSTALLATION.md

File metadata and controls

231 lines (163 loc) · 7 KB
Raw

Installation Guide

Table of contents

Prerequisites

  • PHP >= 8.2, < 8.6
  • Symfony >= 6.1 || >= 7.0 || >= 8.0
  • Doctrine ORM >= 2.13 || >= 3.0
  • Doctrine Bundle >= 2.8 || >= 3.0 (3.0 required for Symfony 8)

Note: Symfony 6.1+ is required because the bundle uses #[Autowire] attribute for dependency injection, which is only available from Symfony 6.1 onwards.

Step 1: Install the Bundle

⚠️ Important: This bundle is development-only. Always install it as a dev dependency.

Install the bundle using Composer with the --dev flag:

composer require nowo-tech/anonymize-bundle --dev

Step 2: Register the Bundle

⚠️ Security: Register the bundle only for dev and test environments. Never enable it in production.

If you're using Symfony Flex, the bundle is automatically registered for dev/test environments. Otherwise, manually register it in config/bundles.php:

<?php

return [
    // ...
    Nowo\AnonymizeBundle\AnonymizeBundle::class => ['dev' => true, 'test' => true],
];

⚠️ Security Note: The bundle includes built-in protection that prevents execution in production environments. The command will automatically fail if run outside of dev or test environments, even if the bundle is registered.

Step 3: Configure the Bundle (Optional)

⚠️ Important: The configuration file is only automatically created when:

  • The bundle is installed from Packagist
  • Symfony Flex is enabled and can access the official Symfony recipes repository
  • The recipe is published in the Symfony recipes-contrib repository (https://github.com/symfony/recipes-contrib)

Current Status: The recipe is not yet published in the official repository, so the configuration file will not be created automatically. You need to manually create it (see below).

If you're installing the bundle from a local path, Git repository, or private repository, you also need to manually create the configuration file.

Automatic Configuration (Symfony Flex from Packagist)

If you installed the bundle from Packagist using Symfony Flex, the configuration file should be automatically created at config/packages/dev/nowo_anonymize.yaml.

If the file was not created automatically, you can manually create it (see below).

Manual Configuration

Manually create the configuration file config/packages/dev/nowo_anonymize.yaml:

nowo_anonymize:
    locale: 'en_US'
    connections: []
    dry_run: false
    batch_size: 100

See CONFIGURATION.md for detailed configuration options.

Step 4: Mark Your Entities

Add the #[Anonymize] attribute to entities you want to anonymize:

<?php

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use Nowo\AnonymizeBundle\Attribute\Anonymize;
use Nowo\AnonymizeBundle\Attribute\AnonymizeProperty;
use Nowo\AnonymizeBundle\Trait\AnonymizableTrait;

#[ORM\Entity]
#[Anonymize]
class User
{
    use AnonymizableTrait; // Optional: Track anonymization status
    
    #[ORM\Id]
    #[ORM\GeneratedValue]
    #[ORM\Column]
    private ?int $id = null;

    #[ORM\Column(length: 255)]
    #[AnonymizeProperty(type: 'email', weight: 1)]
    private ?string $email = null;

    #[ORM\Column(length: 255)]
    #[AnonymizeProperty(type: 'name', weight: 2)]
    private ?string $firstName = null;
}

Note: The AnonymizableTrait is optional but recommended if you want to track which records have been anonymized. See Anonymization Tracking below.

Step 5: Generate Migration for Anonymized Column (Optional)

If you're using AnonymizableTrait, generate a migration to add the anonymized column:

php bin/console nowo:anonymize:generate-column-migration

This will generate SQL statements to add the anonymized boolean column to your tables. Review and apply the generated SQL to your database(s).

Step 6: Run the Command

Test the installation with a dry-run:

php bin/console nowo:anonymize:run --dry-run

If everything looks good, run the actual anonymization:

php bin/console nowo:anonymize:run

Verification

To verify the installation:

  1. Check that the command is available:

    php bin/console list nowo:anonymize

  2. Run a dry-run to see what would be anonymized:

    php bin/console nowo:anonymize:run --dry-run

  3. Check your entities have the correct attributes:

    php bin/console debug:container --parameter=nowo_anonymize.locale

Troubleshooting

Command Not Found

If the command is not found, clear the cache:

php bin/console cache:clear

No Entities Found

Make sure your entities have the #[Anonymize] attribute and at least one property has the #[AnonymizeProperty] attribute.

Connection Errors

Verify your Doctrine connections are properly configured in config/packages/doctrine.yaml.

Anonymization Tracking

The bundle provides an optional AnonymizableTrait that adds an anonymized boolean field to track which records have been anonymized.

Using AnonymizableTrait

  1. Add the trait to your entity:

    use Nowo\AnonymizeBundle\Trait\AnonymizableTrait;

#[ORM\Entity]
#[Anonymize]
class User
{
    use AnonymizableTrait;
    // ... your properties
}

  2. Generate the migration:

    php bin/console nowo:anonymize:generate-column-migration

  3. Apply the generated SQL to your database(s)

  4. Run anonymization - records will be automatically marked:

    php bin/console nowo:anonymize:run

Benefits

  • Query anonymized records: SELECT * FROM users WHERE anonymized = true;
  • Check programmatically: if ($user->isAnonymized()) { ... }
  • Audit trail: Know exactly which records have been anonymized
  • Validation: Easy to verify anonymization status

Next Steps

  • Read the README.md for usage examples
  • Check CONFIGURATION.md for configuration options
  • Review the demo project in the demo/ directory