Common Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require anzusystems/common-bundle --no-scripts
   

   Ensure use_putenv is enabled in composer.json for environment variables:

   "extra": { "runtime": { "use_putenv": true } }
   

2. Kernel Configuration: Update src/Kernel.php to extend AnzuKernel with required parameters:

   public function __construct(
       private string $appSystem,
       private string $appVersion,
       private bool $appReadOnlyMode,
       string $environment,
       bool $debug,
   ) {
       parent::__construct($environment, $debug);
   }
   

   Update public/index.php and bin/console to pass these parameters.

3. Configuration: Define config/packages/anzu_common.yaml with minimal required settings:

   anzu_common:
       settings:
           app_redis: TestRedis
           user_entity_class: App\Entity\User
           app_entity_namespace: App\Entity
           app_value_object_namespace: App\Model\ValueObject
   

4. First Use Case: Enable health checks and logs:

   anzu_common:
       health_check:
           enabled: true
           modules: [AnzuSystems\CommonBundle\HealthCheck\Module\OpCacheModule]
       logs:
           enabled: true
           messenger_transport:
               name: 'core_log'
               dsn: '%env(MESSENGER_TRANSPORT_DSN)%?topic[name]=core_log'
   

Implementation Patterns

Core Workflows

1. Health Checks

• Usage: Integrate health checks for system monitoring.
• Pattern:

  anzu_common:
      health_check:
          enabled: true
          modules:
              - AnzuSystems\CommonBundle\HealthCheck\Module\MysqlModule
              - AnzuSystems\CommonBundle\HealthCheck\Module\RedisModule
  

• Access: Endpoint /health (auto-configured via AnzuKernel).

2. Logging (Journal & Audit)

• Journal Logs (MongoDB):

  anzu_common:
      logs:
          enabled: true
          journal:
              mongo:
                  uri: '%env(ANZU_MONGODB_APP_LOG_URI)%'
                  collection: appLogs
  

• Audit Logs (MongoDB):

  anzu_common:
      logs:
          audit:
              mongo:
                  uri: '%env(ANZU_MONGODB_AUDIT_LOG_URI)%'
                  collection: auditLogs
              logged_methods: ['POST', 'PUT', 'PATCH', 'DELETE']
  

• Messenger Transport: Logs are sent via Symfony Messenger (configure dsn in messenger_transport).

3. Permissions & Access Control

• Define Permissions:

  anzu_common:
      permissions:
          config:
              app_article:
                  create: { grants: [2, 0] }
                  delete: { grants: [0, 1, 2] }
          roles: [ROLE_USER, ROLE_ADMIN]
  

• Voters: Extend AbstractVoter for custom logic:

  use AnzuSystems\CommonBundle\Security\Voter\AbstractVoter;
  
  class ArticleVoter extends AbstractVoter {
      protected function supports(string $attribute, $subject): bool {
          return $attribute === 'edit' && $subject instanceof Article;
      }
  }
  

4. Value Objects

• Namespace Mapping:

  anzu_common:
      settings:
          app_value_object_namespace: App\Model\ValueObject
  

• Usage: Auto-register VO classes (e.g., Money, Email) via AnzuSystems\CommonBundle\ValueObject\ValueObjectTrait.

5. Locks & Concurrency

• Command Locking: Disable locking for specific commands:

  anzu_common:
      settings:
          unlocked_commands:
              - Symfony\Component\Messenger\Command\ConsumeMessagesCommand
  

6. Argument Resolvers

• Auto-Registration: Resolvers like CurrentUserResolver or RequestParamResolver are auto-wired.
• Custom Resolver:

  use AnzuSystems\CommonBundle\Controller\ArgumentResolver\AbstractArgumentResolver;
  
  class CustomResolver extends AbstractArgumentResolver {
      public function supports(Request $request, Controller $controller): bool {
          return $request->attributes->has('custom_param');
      }
  }
  

7. Fixtures & Testing

• Load Fixtures:

  php bin/console doctrine:fixtures:load --group=test
  

• Traits: Use AnzuSystems\CommonBundle\Test\Traits\TestCaseTrait for base test setups.

Integration Tips

1. Environment Variables:

   • Use env() in YAML or PHP for sensitive data (e.g., MongoDB URIs, Redis DSN).
   • Example:

     anzu_common:
         logs:
             journal:
                 mongo:
                     uri: '%env(ANZU_MONGODB_APP_LOG_URI)%'
     

2. Read-Only Mode:

   • Enable via appReadOnlyMode: true in Kernel constructor.
   • Throws AppReadOnlyModeException for write operations (handled by AppReadOnlyModeExceptionHandler).

3. Proxy Cache:

   • Enable headers:

     anzu_common:
         settings:
             app_cache_proxy_enabled: true
     

4. Error Handling:

   • Customize exception handlers:

     anzu_common:
         errors:
             exception_handlers:
                 - App\Exception\Handler\CustomHandler
     

5. Localization:

   • Add locale to User entity (v11.1.0+):

     // App\Entity\User
     use AnzuSystems\CommonBundle\Entity\Traits\UserTracking;
     
     class User implements UserInterface {
         use UserTracking;
         // ...
     }
     

Gotchas and Tips

Pitfalls

1. Kernel Initialization:

   • Issue: Forgetting to extend AnzuKernel or pass required parameters (appSystem, appVersion, appReadOnlyMode).
   • Fix: Verify public/index.php and bin/console pass all constructor args.

2. MongoDB Logs:

   • Issue: Logs not appearing in MongoDB due to misconfigured messenger_transport DSN.
   • Fix: Ensure MESSENGER_TRANSPORT_DSN is set and topic is correct:

     dsn: '%env(MESSENGER_TRANSPORT_DSN)%?topic[name]=core_log'
     

3. Permission BC Breaks:

   • Issue: Upgrading from v7.x to v8.x may require updating voters to use ROLE_SUPER_ADMIN instead of ROLE_ADMIN.
   • Fix: Update AbstractVoter implementations:

     protected function supports(string $attribute, $subject): bool {
         return $this->decisionManager->decide(
             $this->authenticationToken,
             $subject,
             $attribute
         ) === AccessDecisionManagerInterface::ACCESS_GRANTED;
     }
     

4. Deprecated Features:

   • Issue: param_converters are deprecated (v7.0+). Use argument_resolvers instead.
   • Fix: Replace ParamConverter logic with ArgumentResolver:

     // Old (deprecated)
     use AnzuSystems\CommonBundle\Controller\ParamConverter\AbstractParamConverter;
     
     // New
     use AnzuSystems\CommonBundle\Controller\ArgumentResolver\AbstractArgumentResolver;
     

5. Health Check Modules:

   • Issue: Health check fails silently if modules are misconfigured (e.g., missing MysqlModule for MySQL checks).
   • Fix: Explicitly list required modules:

     anzu_common:
         health_check:
             modules:
                 - AnzuSystems\CommonBundle\HealthCheck\Module\MysqlModule
                 - AnzuSystems\CommonBundle\HealthCheck\Module\RedisModule
     

6. Locale Field:

   • Issue: Missing locale field in User entity (pre-v11.1.0).
   • Fix: Add field and update migrations:

     // App\Entity\User
     use Doctrine\ORM\Mapping as ORM;
     
     #[ORM\Column(type: 'string', length: 5)]
     private ?string $locale = null;
     

Debugging Tips

1. Enable Debug Mode:

   • Set APP_DEBUG=1 in .env to log detailed errors.

2. Health Check Debugging:

   • Access /health endpoint directly to see module-specific errors.
   • Example output:

     {
         "status": "error",
         "modules": {
             "mysql