Riak Odm Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require cosmow/riak-odm-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Cosmow\DoctrineRiakBundle\CosmowDoctrineRiakBundle::class => ['all' => true],
   ];
   

2. Configuration Define Riak connection in config/packages/cosmow_doctrine_riak.yaml:

   cosmow_doctrine_riak:
       connections:
           default:
               host: '127.0.0.1'
               port: 8087
               bucket_type: 'default'
               timeout: 30
   

3. First Use Case Create a Riak entity (e.g., src/Entity/User.php):

   namespace App\Entity;
   
   use Cosmow\DoctrineRiakBundle\Mapping\Annotation as Riak;
   use Doctrine\ORM\Mapping as ORM;
   
   /** @ORM\Entity */
   /** @Riak\Document */
   class User
   {
       /** @Riak\Id */
       private $id;
   
       /** @Riak\Field */
       private $name;
   
       // Getters/setters...
   }
   

   Use the entity in a service or controller:

   use App\Entity\User;
   use Doctrine\ORM\EntityManagerInterface;
   
   public function __construct(EntityManagerInterface $em) {}
   
   public function createUser()
   {
       $user = new User();
       $user->setName('John Doe');
       $this->em->persist($user);
       $this->em->flush();
   }
   

Implementation Patterns

Workflow Integration

1. Repository Pattern Extend Cosmow\DoctrineRiakBundle\Repository\DocumentRepository for custom queries:

   namespace App\Repository;
   
   use Cosmow\DoctrineRiakBundle\Repository\DocumentRepository;
   use App\Entity\User;
   
   class UserRepository extends DocumentRepository
   {
       public function findByName($name)
       {
           return $this->createQueryBuilder('u')
               ->where('u.name = :name')
               ->setParameter('name', $name)
               ->getQuery()
               ->getResult();
       }
   }
   

2. Event Listeners Use Doctrine lifecycle events for pre/post operations:

   namespace App\EventListener;
   
   use Cosmow\DoctrineRiakBundle\Event\LifecycleEventArgs;
   use App\Entity\User;
   
   class UserListener
   {
       public function prePersist(LifecycleEventArgs $args)
       {
           $entity = $args->getEntity();
           if ($entity instanceof User && empty($entity->getId())) {
               $entity->setId(uniqid());
           }
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\UserListener:
           tags:
               - { name: 'doctrine.event_listener', event: 'prePersist' }
   

3. Batch Operations Leverage Riak’s batch API for bulk inserts/updates:

   use Cosmow\DoctrineRiakBundle\Manager\RiakManager;
   
   public function batchCreateUsers(RiakManager $riakManager, array $users)
   {
       $batch = $riakManager->createBatch();
       foreach ($users as $user) {
           $batch->insert($user);
       }
       $batch->execute();
   }
   

Common Patterns

• Secondary Indexes: Use @Riak\Index for querying:

  /** @Riak\Index(name="name_idx", type="binary") */
  private $name;
  

• Links: Model relationships with @Riak\Link:

  /** @Riak\Link(target="App\Entity\Post") */
  private $posts;
  

• Conflict Resolution: Implement Cosmow\DoctrineRiakBundle\Conflict\ConflictResolverInterface for custom merge logic.

Gotchas and Tips

Pitfalls

1. Connection Issues

   • Riak’s default port is 8087 (not 8080). Verify host/port in config.
   • Firewall/network rules may block connections. Test with telnet or curl.

2. Bucket Types

   • Buckets must exist in Riak before use. Create them via riak-admin or the Riak Control Panel.
   • Bucket properties (e.g., allow_mult) are not configurable via the bundle; use Riak CLI or HTTP API.

3. Id Generation

   • Riak requires unique IDs. Avoid auto-increment (use uniqid(), UUID, or custom logic).
   • If using @ORM\GeneratedValue, override with @Riak\Id to prevent conflicts.

4. Query Limitations

   • Riak lacks SQL-like joins. Use @Riak\Link or denormalize data.
   • Secondary indexes are not full-text search. For advanced search, use Riak Search or Solr.

5. Transactions

   • Riak is eventually consistent. Avoid expecting ACID behavior; use flush() strategically.

Debugging

• Enable Logging Add to config/packages/monolog.yaml:

  handlers:
      riak:
          type: stream
          path: "%kernel.logs_dir%/riak.log"
          level: debug
          channels: ["riak"]
  

  Then configure the bundle to use the riak channel.

• Check Riak Logs Inspect /var/log/riak/ (Linux) or Riak’s admin console for errors.

Tips

1. Use Riak’s HTTP API For low-level operations, bypass Doctrine:

   $client = new \Riak\Client($host, $port);
   $bucket = $client->useBucket('default');
   $bucket->store('key', ['data' => 'value']);
   

2. Leverage Riak TS For time-series data, enable Riak TS and configure the bundle’s bucket_type to use riak_ts.

3. Caching Cache frequent queries with @Riak\Cache:

   /** @Riak\Cache(ttl=3600) */
   private $cachedData;
   

4. Testing Use riak-test Docker image for CI:

   # docker-compose.yml
   services:
       riak:
           image: basho/riak-test:2.2
           ports:
               - "8087:8087"
   

5. Backup Strategy Riak’s data is distributed. Use riak-admin bucket-props to set last-write-wins: false for critical data and implement application-level backups.

6. Performance

   • Batch writes to reduce network overhead.
   • Use preload: true in @Riak\Document for frequently accessed fields:

     /** @Riak\Document(preload=true) */
     class User { ... }