Pairdb Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require dovstone/pairdb
   

   Verify compatibility with your Laravel version (check composer.json requirements if documented).

2. Publish Configuration (if applicable):

   php artisan vendor:publish --provider="Dovstone\PairDB\PairDBServiceProvider"
   

   (Note: Provider/class names are speculative; adjust based on actual package structure.)

3. Basic Usage:

   • Initialize a key-value store (example inferred from "MySQL NoSql" description):

     use Dovstone\PairDB\Facades\PairDB;
     
     // Set a key-value pair
     PairDB::set('user:123:preferences', ['theme' => 'dark']);
     
     // Retrieve a value
     $preferences = PairDB::get('user:123:preferences');
     
     // Delete a key
     PairDB::delete('user:123:preferences');
     

4. First Use Case:

   • Caching session-like data: Replace Redis/Memcached for non-critical, low-volume key-value storage.
   • Prototype a feature: Store temporary state (e.g., form drafts, API rate limits) without schema migrations.

Where to Look First

• Source Code: Since documentation is minimal, inspect:
  • src/ for core classes (e.g., PairDBManager, Connection).
  • config/pairdb.php (if published) for default settings.
• Tests: Check for unit tests (e.g., tests/Feature/) to infer usage patterns.
• Database: Verify if the package creates tables via migrations (e.g., pairdb_keys or similar).

Implementation Patterns

Usage Patterns

1. Key-Value Abstraction:

   • Treat as a drop-in replacement for Laravel’s cache() helper or Redis, but with MySQL persistence.
   • Example: Store user-specific metadata:

     PairDB::set("user:{$user->id}:last_active", now()->toDateTimeString());
     $lastActive = PairDB::get("user:{$user->id}:last_active");
     

2. Bulk Operations:

   • If supported, use for batch inserts/updates (e.g., syncing external data):

     PairDB::batch([
         'product:101:stock' => 50,
         'product:102:stock' => 30,
     ]);
     

3. Expiration:

   • Set TTL (Time-To-Live) for ephemeral data (if implemented):

     PairDB::set('temp:token', $token, 3600); // Expires in 1 hour
     

4. Query Patterns:

   • Prefix-based filtering: Use keys like user:{id}:* to scope data (e.g., for a user’s records).
   • Composite keys: Encode relationships (e.g., order:123:items:5 for order line items).

Workflows

1. Laravel Service Integration:

   • Bind to the container in a service provider:

     $this->app->singleton('pairdb', function ($app) {
         return new \Dovstone\PairDB\PairDBManager(config('pairdb'));
     });
     

   • Inject into controllers/services:

     public function __construct(private PairDB $pairDB) {}
     

2. Event-Driven Updates:

   • Listen for model events (e.g., saved) to sync PairDB:

     User::saved(function ($user) {
         PairDB::set("user:{$user->id}:updated_at", now());
     });
     

3. Fallback for Missing Data:

   • Use in AppServiceProvider to populate default values:

     public function boot()
     {
         $defaults = PairDB::get('app:defaults', []);
         config(['app.defaults' => $defaults]);
     }
     

Integration Tips

• Database Migrations:

  • Check if the package auto-creates tables. If not, add a migration:

    Schema::create('pairdb_entries', function (Blueprint $table) {
        $table->string('key')->primary();
        $table->json('value');
        $table->timestamp('expires_at')->nullable();
        $table->timestamps();
    });
    

• Caching Layer:

  • Combine with Laravel’s cache for performance:

    $value = cache()->remember("pairdb:{$key}", 60, function () use ($key) {
        return PairDB::get($key);
    });
    

• Testing:

  • Mock the PairDB facade in tests:

    PairDB::shouldReceive('get')->with('key')->andReturn(['data']);
    

Gotchas and Tips

Pitfalls

1. No Schema Enforcement:

   • The package may not validate key/value formats. Sanitize inputs to avoid:
     • SQL injection (if using raw queries).
     • Large values breaking MySQL limits (e.g., TEXT vs. JSON columns).

2. Concurrency Issues:

   • MySQL lacks atomicity for complex key-value operations. Use transactions for critical updates:

     DB::transaction(function () {
         PairDB::delete('cart:123:item:4');
         PairDB::set('cart:123:total', $newTotal);
     });
     

3. Key Collisions:

   • Without namespacing (e.g., app:, user: prefixes), keys may clash across features. Enforce a convention:

     $key = "feature:{$featureName}:{$id}:{$subKey}";
     

4. Performance:

   • No indexing: Scanning all keys (e.g., PairDB::all()) will be slow. Avoid full-table queries.
   • Serialization overhead: JSON encoding/decoding values may impact latency. Use raw strings for simple data.

5. Laravel Conflicts:

   • Service Provider: Ensure the package’s provider doesn’t override Laravel’s bindings (e.g., cache).
   • Facade: If PairDB conflicts with another facade, alias it:

     'aliases' => [
         'PairDB' => Dovstone\PairDB\Facades\PairDB::class,
     ],
     

Debugging

1. Query Logging:

   • Enable Laravel’s query log to inspect underlying SQL:

     DB::enableQueryLog();
     PairDB::get('key');
     dd(DB::getQueryLog());
     

2. Missing Keys:

   • Default return values to avoid null errors:

     $value = PairDB::get('key', []); // Defaults to empty array
     

3. Connection Issues:

   • Verify the package uses Laravel’s database connection:

     config(['pairdb.connection' => 'mysql']);
     

Tips

1. Extension Points:

   • Custom Storage: Implement Dovstone\PairDB\Contracts\Store to add Redis/S3 backends.
   • Encryption: Wrap values before storage:

     PairDB::set('key', encrypt($value));
     

2. Configuration:

   • Override defaults in config/pairdb.php:

     'table' => 'custom_pairdb_entries',
     'default_ttl' => 86400, // 1 day
     

3. Monitoring:

   • Track usage with Laravel’s events:

     PairDB::set('key', $value);
     event(new PairDBStored($key, $value));
     

4. Fallback Strategy:

   • Combine with Laravel’s cache for high-read scenarios:

     $value = cache()->remember("pairdb:{$key}", 300, function () use ($key) {
         return PairDB::get($key);
     });
     

5. Documentation Workarounds:

   • Generate API docs from source using phpDocumentor:

     vendor/bin/phpdoc src/