Sped Gtin Laravel Package

Technical Evaluation

Architecture Fit

• Microservice/Validation Layer Fit: Ideal for pre-processing GTINs in Laravel services (e.g., ProductService, OrderService) or as a standalone validator in API request pipelines. The package’s stateless, rule-based design aligns with Laravel’s dependency injection and service container patterns.
• Compliance-Centric: Directly addresses NT 2021.003 requirements for NFe/NFCe, making it a non-negotiable component for Brazilian tax-invoice systems. Can be embedded in:
  • Laravel Middleware: Validate GTINs in incoming API requests (e.g., product uploads).
  • Model Observers: Auto-validate GTINs on Product model saves/updates.
  • Form Requests: Validate GTINs in StoreProductRequest or UpdateOrderRequest.
• Extensibility: The Gtin class exposes properties (region, prefix, type) and exceptions, enabling custom logic (e.g., logging invalid GTINs to a compliance audit table).

Integration Feasibility

• Laravel Ecosystem Compatibility:
  • PSR-4 Autoloading: Works seamlessly with Laravel’s autoloader (no manual namespace mapping needed).
  • Exception Handling: Exceptions align with Laravel’s error-handling patterns (e.g., App\Exceptions\Handler).
  • Testing: PHPUnit-compatible; can integrate with Laravel’s testing tools (e.g., phpunit.xml).
• Database Agnostic: No ORM or DB dependencies; validates GTINs purely in-memory.
• API/Service Layer: Can be wrapped in a Laravel Service Provider to centralize GTIN validation logic (e.g., GtinValidatorService).

Technical Risk

Key Questions

1. Compliance Scope:
   • Does our product handle NFe/NFCe for Brazilian customers? (If yes, this is mandatory.)
   • Are we responsible for validating GTINs at the manufacturer level, or just the retailer level? (Note: SEFAZ rejects affect manufacturers/importers, not just resellers.)
2. Data Flow:
   • Where are GTINs entered in our system? (e.g., supplier portals, product uploads, ERP integrations).
   • Should validation happen at ingest (prevent bad data) or egress (before NFe generation)?
3. Error Handling:
   • How should invalid GTINs be handled? (e.g., reject API request, log warning, notify admin).
   • Should we integrate with a CNP API later? (Track GS1 Brazil’s API roadmap.)
4. Testing:
   • Do we have a suite of valid/invalid GTINs for regression testing?
   • Should we mock SEFAZ rejections in our test suite?
5. Maintenance:
   • Who will update the prefix CSV table when GS1 Brazil releases new rules?
   • Should we fork the repo to add CNP API integration?

Integration Approach

Stack Fit

• Laravel-Specific Integrations:
  • Service Container: Bind the Gtin class to a custom validator interface:

    // app/Providers/AppServiceProvider.php
    public function register()
    {
        $this->app->bind(GtinValidatorInterface::class, function ($app) {
            return new \NFePHP\Gtin\Gtin();
        });
    }
    

  • Form Requests: Validate GTINs in Laravel’s FormRequest classes:

    // app/Http/Requests/StoreProductRequest.php
    public function rules()
    {
        return [
            'gtin' => ['required', 'string', new GtinValidationRule],
        ];
    }
    

  • Model Observers: Auto-validate GTINs on Product model events:

    // app/Observers/ProductObserver.php
    public function saving(Product $product)
    {
        if ($product->gtin && !$product->gtin->isValid()) {
            throw new \InvalidArgumentException("Invalid GTIN: {$product->gtin}");
        }
    }
    

  • API Middleware: Validate GTINs in incoming requests:

    // app/Http/Middleware/ValidateGtin.php
    public function handle($request, Closure $next)
    {
        if ($request->has('gtin') && !$request->gtin->isValid()) {
            return response()->json(['error' => 'Invalid GTIN'], 422);
        }
        return $next($request);
    }
    

• Non-Laravel PHP:
  • Use as a Composer dependency in any PHP app (e.g., CLI scripts, microservices):

    $validator = new \NFePHP\Gtin\Gtin($gtin);
    if (!$validator->isValid()) {
        // Handle error
    }
    

Migration Path

1. Phase 1: Core Validation (1 Sprint)
   • Add nfephp-org/sped-gtin to composer.json.
   • Implement validation in high-risk areas (e.g., product creation, NFe generation).
   • Log invalid GTINs to a compliance_issues table for manual review.
2. Phase 2: Integration (1 Sprint)
   • Wrap in a Laravel service layer (e.g., GtinValidatorService) for reusability.
   • Add unit/integration tests (focus on edge cases like "SEM GTIN", malformed inputs).
   • Integrate with existing workflows (e.g., supplier portals, ERP connectors).
3. Phase 3: Compliance Enhancements (Future)
   • Monitor GS1 Brazil’s CNP API roadmap; plan integration when available.
   • Add GTIN metadata (e.g., region, type) to product models for reporting.

Compatibility

• Laravel Versions: Compatible with Laravel 7+ (PHP 7.2+). Test on your target Laravel version.
• PHP Extensions: No dependencies beyond PHP core.
• Database: No schema changes required (pure validation logic).
• Third-Party Services: None (avoids API rate limits or downtime risks).

Sequencing

Operational Impact

Maintenance

• Prefix Table Updates:
  • Frequency: Quarterly (GS1 Brazil updates rules).
  • Process: Download CSV from NFe site, update local copy, restart PHP workers (if using OPcache).
  • Automation: Script to parse CSV and update a config file (e.g., config/gtin_prefixes.php).
• Dependency Management:
  • Pin to ^1.0 in composer.json to avoid breaking changes.
  • Monitor GitHub Issues for updates.
• Logging:
  • Log invalid GTINs with metadata (e.g., `user_id