Codecs Base64Vlq Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation:

   composer require axy/codecs-base64vlq
   

   Ensure your composer.json has "php": "^8.1" or higher.

2. First Use Case: Encode/decode a simple array of integers:

   use axy\codecs\base64vlq\Encoder;
   
   $encoder = Encoder::getStandardInstance();
   $encoded = $encoder->encode([12345, -12345, 0]); // Output: "yjYzjYA"
   $decoded = $encoder->decode($encoded); // Output: [12345, -12345, 0]
   

3. Where to Look First:

   • README.md: For algorithm explanation and basic usage.
   • Encoder class: Core functionality (methods: encode(), decode()).
   • Exceptions: axy\codecs\base64vlq\Encoder\Errors for error handling.

Implementation Patterns

Core Workflows

1. Standard Encoding/Decoding: Use the singleton Encoder::getStandardInstance() for default Base64VLQ (6-bit, signed, standard alphabet).

   $encoder = Encoder::getStandardInstance();
   $data = [1, -2, 3];
   $encoded = $encoder->encode($data);
   $decoded = $encoder->decode($encoded);
   

2. Custom Alphabets/Bit Lengths: Override defaults for niche use cases (e.g., compact storage, non-standard alphabets):

   $customEncoder = new Encoder('ABCDEFGHIJKLMNOPQRSTUVWXYZabcdef', 4, false);
   $encoded = $customEncoder->encode([1, 2, 3]); // Uses custom 4-bit VLQ
   

3. Batch Processing: Loop through arrays of data (e.g., database records) and encode/decode in bulk:

   $records = [[1, -2], [3, -4]];
   $encodedRecords = array_map([$encoder, 'encode'], $records);
   

4. Integration with JSON/XML: Useful for storing compact integer sequences in text formats:

   $jsonData = json_encode(['coordinates' => $encoder->encode([10, -20, 30])]);
   

Integration Tips

• Laravel Cache: Store encoded VLQ strings in cache/Redis for space efficiency:

  Cache::put('vlq_data', $encoder->encode($data), $ttl);
  

• Database: Store VLQ-encoded arrays in TEXT columns (e.g., for serialized data).
• API Responses: Return encoded data to reduce payload size:

  return response()->json(['data' => $encoder->encode($array)]);
  

Gotchas and Tips

Pitfalls

1. Bit Length Mismatch:

   • Custom encoders with $bits too large for the alphabet will throw InvalidBase64Input.
   • Example: A 10-bit encoder with a 3-character alphabet fails.
   • Fix: Ensure $bits <= log2(count($alphabet)).

2. Sign Handling:

   • Disabling $signed (3rd constructor arg) drops negative number support.
   • Tip: Use signed encoding for mixed-sign data (e.g., coordinates).

3. Continuation Bit Errors:

   • Invalid VLQ sequences (e.g., trailing 1 in continuation bit) throw InvalidVLQSequence.
   • Debugging: Validate encoded strings with a regex or manual bit checks.

4. Alphabet Case Sensitivity:

   • The standard alphabet is case-sensitive (A-Z, a-z).
   • Tip: Normalize custom alphabets (e.g., strtolower()) for consistency.

Debugging

• Log Encoded Output:

  \Log::debug('Encoded:', ['data' => $encodedString]);
  

• Validate Decoding: Compare decoded output to original input to catch corruption:

  assert($decoded === $originalData, 'Decoding failed!');
  

Extension Points

1. Custom Alphabets:
   • Extend functionality by adding dynamic alphabets (e.g., URL-safe Base64):

     $urlSafeEncoder = new Encoder('ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_', 6);
     

2. Error Handling:
   • Catch exceptions and retry/fallback:

     try {
         $decoded = $encoder->decode($input);
     } catch (\axy\codecs\base64vlq\Encoder\Errors\InvalidVLQSequence $e) {
         \Log::error('VLQ error:', ['input' => $input]);
         return null;
     }
     

3. Performance:
   • For large datasets, pre-initialize the encoder (singleton pattern) to avoid re-parsing alphabets.

Laravel-Specific Tips

• Service Provider: Bind the encoder to the container for dependency injection:

  $this->app->singleton(Encoder::class, function () {
      return Encoder::getStandardInstance();
  });
  

• Artisan Commands: Use VLQ for compact CLI output (e.g., logs, debug data):

  $this->info('Encoded data: ' . $encoder->encode($data));