Products Sign Laravel Package

Getting Started

Minimal Steps

1. Install Dependencies:

   composer require baks-dev/barcode baks-dev/products-sign
   

2. Set Up Storage:

   mkdir -p public/upload/product_sign_code
   chown -R www-data:www-data public/upload/product_sign_code
   

3. Configure System Tools:
   • Install pdftk and texlive-extra-utils (Linux).
   • Update ImageMagick policy (/etc/ImageMagick-6/policy.xml) to allow PDF processing.
   • Grant sudo permissions for pdfcrop (if needed):

     sudo visudo
     

     Add:

     unit ALL=(ALL) NOPASSWD: /usr/bin/pdfcrop
     

4. Run Initial Setup:

   php bin/console baks:assets:install
   php bin/console doctrine:migrations:diff
   php bin/console doctrine:migrations:migrate
   

First Use Case

Generate a product signature for a new product:

use BaksDev\ProductsSign\Services\SignatureCreator;

$creator = new SignatureCreator();
$signature = $creator
    ->setProduct($product) // Assuming Product model with required fields
    ->setExpiryDate(now()->addYear())
    ->generate();

return $signature->getPath(); // Returns path to generated PDF/QR

Implementation Patterns

Core Workflows

1. Product Signature Generation

• Synchronous Generation:

  $signature = app(SignatureCreator::class)
      ->setProduct($product)
      ->setCustomFields(['manufacturer_id' => 123])
      ->generate();
  

• Asynchronous Generation (Recommended for bulk operations):

  dispatch(new GenerateProductSignature($product, $expiryDate));
  

  Use Laravel Queues with a worker:

  php artisan queue:work
  

2. Validation Workflows

• Single Product Validation:

  $validator = app(SignatureValidator::class);
  $result = $validator->validate($signature);
  

• Batch Validation (For marketplaces):

  $results = $validator->validateBatch($productSignatures);
  // Returns array of ValidationResult objects
  

3. Storage Integration

• Local Storage (Default):

  PRODUCT_SIGN_DISK=local
  PRODUCT_SIGN_PATH=public/upload/product_sign_code
  

• S3 Storage:

  PRODUCT_SIGN_DISK=s3
  AWS_BUCKET=my-compliance-signs
  AWS_REGION=eu-central-1
  

4. API Integration

• Expose Validation Endpoint (Example in routes/api.php):

  Route::post('/api/signatures/validate', [SignatureController::class, 'validate']);
  

• Controller Example:

  public function validate(Request $request, SignatureValidator $validator)
  {
      $results = $validator->validateBatch($request->products);
      return response()->json($results);
  }
  

Integration Tips

1. Laravel Nova Integration: Create a custom Nova resource for managing product signatures:

   public static $title = 'signature';
   public static $search = ['product_id', 'qr_code'];
   
   public function fields(Request $request)
   {
       return [
           ID::make(),
           Text::make('Product ID')->onlyOnDetail(),
           Text::make('QR Code')->onlyOnDetail(),
           Text::make('Expiry Date'),
           Boolean::make('Is Valid'),
           Actions::make('Validate', ValidateSignature::class),
       ];
   }
   

2. Event-Based Workflows: Listen for product creation to auto-generate signatures:

   ProductCreated::dispatch($product)
       ->then(function ($product) {
           app(SignatureCreator::class)->setProduct($product)->generate();
       });
   

3. Testing: Use the provided test group:

   php bin/phpunit --group=products-sign
   

   Mock external tools (pdftk, ImageMagick) in tests:

   $this->mockPdfTools()->shouldReceive('crop')->andReturn(true);
   

4. Custom Templates: Extend the default PDF template by publishing and overriding:

   php artisan vendor:publish --tag=products-sign-views
   

   Modify resources/views/vendor/products-sign/signature.blade.php.

Gotchas and Tips

Pitfalls

1. System Tooling Dependencies:

   • Issue: pdftk or ImageMagick may fail silently if not properly configured.
   • Fix: Use Docker to containerize dependencies or implement a fallback to a serverless PDF service (e.g., AWS Textract).

2. Permission Errors:

   • Issue: Web server user (e.g., www-data) may lack write permissions to public/upload/product_sign_code.
   • Fix: Ensure correct ownership:

     chown -R www-data:www-data public/upload/product_sign_code
     chmod -R 755 public/upload/product_sign_code
     

3. PDF Processing Timeouts:

   • Issue: Large PDFs may cause HTTP timeouts during generation.
   • Fix: Offload to queues and use async processing:

     dispatchSync(new GenerateProductSignature($product));
     

4. Validation API Changes:

   • Issue: New versions may introduce breaking changes in validation logic.
   • Fix: Test with the --group=products-sign test suite before upgrading:

     php bin/phpunit --group=products-sign
     

5. QR Code Standards:

   • Issue: Russian regulations may require specific QR formats (e.g., GS1 DataMatrix).
   • Fix: Verify compliance with GS1 Russia standards and extend the SignatureCreator class.

Debugging Tips

1. Enable Debug Logging: Add to config/logging.php:

   'channels' => [
       'products_sign' => [
           'driver' => 'single',
           'path' => storage_path('logs/products_sign.log'),
           'level' => env('APP_DEBUG') ? 'debug' : 'info',
       ],
   ],
   

   Then log in your service classes:

   \Log::channel('products_sign')->debug('Generating signature for product ID: ' . $product->id);
   

2. Validate PDF Output: Use pdftk to inspect generated PDFs:

   pdftk public/upload/product_sign_code/signature_123.pdf dump_data
   

3. Check ImageMagick Policies: If PDF processing fails, verify policies:

   grep -A5 -B5 "PDF" /etc/ImageMagick-6/policy.xml
   

   Ensure it allows read/write:

   <policy domain="coder" rights="read|write" pattern="PDF" />
   

Extension Points

1. Custom Signature Fields: Extend the SignatureCreator to include additional fields:

   class CustomSignatureCreator extends SignatureCreator
   {
       public function setCustomField(string $key, $value): self
       {
           $this->customFields[$key] = $value;
           return $this;
       }
   }
   

2. Validation Rules: Add custom validation logic by extending SignatureValidator:

   class CustomValidator extends SignatureValidator
   {
       protected function validateCustomRules(Signature $signature): void
       {
           if (!$signature->isExpiryValid()) {
               $this->errors[] = 'Signature expired';
           }
       }
   }
   

3. Storage Adapters: Implement a custom storage adapter for cloud providers:

   class GoogleCloudStorageAdapter implements StorageAdapterInterface
   {
       public function store(string $path, string $content): string
       {
           // Upload to Google Cloud Storage
       }
   
       public function retrieve(string $path): string
       {
           // Retrieve from Google Cloud Storage
       }
   }
   

4. Webhook Notifications: Dispatch events for signature generation/validation:

   event(new SignatureGenerated($signature));
   

   Listen for events in another service:

   SignatureGenerated::listen(function ($event) {
       // Send notification to sellers
   });
   

Configuration Quirks

1. Environment Variables: Ensure these are set in .env:

   PRODUCT_SIGN_ENABLED=true
   PRODUCT_SIGN_DISK=local
   PRODUCT_SIGN_PATH=public/upload/product_sign_code
   PRODUCT_SIGN_PDFTK_PATH=/usr/bin/pdftk
   PRODUCT_SIGN_IMAGEMAGICK_POLICY=/etc/ImageMagick-6/policy.xml
   

2. Queue Configuration: For async processing, configure queues in .env:

   QUEUE_CONNECTION=database
   PRODUCT_SIGN_QUEUE_CONNECTION=redis
   

3. **Barcode