Credit Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require cometcult/credit-bundle:dev-master
   

   Add to AppKernel.php:

   new CometCult\CreditsBundle\CometCultCreditsBundle(),
   

2. First Use Case: Inject the CreditsManager service and perform basic operations:

   $creditsManager = $this->get('comet_cult_credits.manager');
   $creditsManager->addCredit(100, 'user123'); // Add 100 credits to user 'user123'
   $balance = $creditsManager->getCredit('user123'); // Fetch balance
   

3. Where to Look First:

   • src/CometCult/CreditsBundle/Manager/CreditsManager.php for core logic.
   • Resources/config/services.yml for service configuration.
   • Doctrine MongoDB schema (if extending).

Implementation Patterns

Core Workflows

1. Credit Management:

   • Use addCredit($amount, $ownerId) and subtractCredit($amount, $ownerId) for atomic operations.
   • For custom credit instances (e.g., with metadata), use:

     $credit = $creditsManager->createCredit(200, 'abc123', ['type' => 'premium']);
     $creditsManager->updateCredit($credit);
     

2. Event-Driven Extensions:

   • Override CreditsManager to hook into credit operations (e.g., logging, notifications):

     # config.yml
     services:
         app.credits_manager:
             class: AppBundle\Service\CustomCreditsManager
             parent: comet_cult_credits.manager
     

3. Batch Operations:

   • Loop through users and update credits in bulk (ensure transaction handling):

     foreach ($users as $user) {
         $creditsManager->addCredit(50, $user->getId());
     }
     

4. Validation:

   • Extend Credit entity to add validation (e.g., max/min limits):

     $credit = $creditsManager->createCredit(-10, 'user123'); // May fail if negative credits are disallowed.
     

Integration Tips

• Symfony Forms: Bind credit operations to form submissions (e.g., "Redeem Points").
• APIs: Expose CreditsManager methods via API Platform or custom controllers.
• Doctrine Events: Listen for prePersist/preUpdate on Credit to enforce business rules.

Gotchas and Tips

Pitfalls

1. MongoDB Dependency:

   • The bundle only supports Doctrine MongoDB. For relational databases, create a custom adapter or use a fork like spatie/laravel-activity-log (alternative).

2. Idempotency:

   • addCredit()/subtractCredit() are not idempotent by default. Handle duplicate operations in your application logic.

3. Concurrency:

   • MongoDB lacks row-level locking. Use optimistic locking (e.g., Credit entity versioning) or external locks (e.g., Redis) for high-traffic systems.

4. Error Handling:

   • Negative credit operations may fail silently. Validate inputs:

     if ($amount <= 0) {
         throw new \InvalidArgumentException("Amount must be positive.");
     }
     

Debugging

• Check MongoDB Collections:

  use your_database;
  db.credits.find(); // Verify records exist.
  

• Service Wiring: Ensure comet_cult_credits.manager is properly autowired in Symfony’s container.

Extension Points

1. Custom Credit Types: Extend the Credit entity to add fields (e.g., expiresAt, description):

   // src/AppBundle/Entity/CustomCredit.php
   class CustomCredit extends \CometCult\CreditsBundle\Entity\Credit
   {
       private $metadata;
   }
   

2. Override Manager: Subclass CreditsManager to add features (e.g., credit expiration):

   // src/AppBundle/Service/CustomCreditsManager.php
   class CustomCreditsManager extends \CometCult\CreditsBundle\Manager\CreditsManager
   {
       public function addCredit($amount, $ownerId, $metadata = [])
       {
           if ($this->isExpired($metadata)) {
               throw new \RuntimeException("Credit expired.");
           }
           parent::addCredit($amount, $ownerId, $metadata);
       }
   }
   

3. Event Listeners: Dispatch events (e.g., credit.added) using Symfony’s event dispatcher:

   $dispatcher->dispatch(new CreditEvent($credit, 'added'));
   

Configuration Quirks

• No Default Config: The bundle has minimal configuration. Override services in config.yml if needed.
• Doctrine Mappings: Ensure MongoDB mappings are registered in config.yml:

  doctrine_mongodb:
      model_managers:
          default:
              mappings:
                  CometCultCreditsBundle: ~