Pagamento Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require brazilianfriendsofsymfony/pagamento-bundle
   

   Add the bundle to config/bundles.php:

   return [
       // ...
       BFOS\PagamentoBundle\BFOSPagamentoBundle::class => ['all' => true],
   ];
   

2. Configure Encryption Service (in .env or config/packages/bfos_pagamento.yaml):

   bfos_pagamento:
       servico_de_criptografia:
           secret: 'your-secret-key-here'
   

3. First Use Case:

   • Use the ParcelamentoUtils to generate payment options for a checkout flow:

     use BFOS\PagamentoBundle\Utils\ParcelamentoConfiguracao;
     use BFOS\PagamentoBundle\Utils\ParcelamentoUtils;
     
     $config = new ParcelamentoConfiguracao();
     $config->setParcelamentoHabilitado(true)
            ->setJurosParcelamento(1.99)
            ->setQuantidadeMaximaParcelas(12);
     
     $options = ParcelamentoUtils::obterOpcoesDeParcelamento($config, 500);
     

4. Frontend Dependencies: Ensure jquery and requirejs are included in your project (e.g., via Webpack Encore or standalone).

Implementation Patterns

Core Workflow: Checkout Integration

1. Form Setup: Create a custom form type extending AbstractType to integrate payment options:

   use BFOS\PagamentoBundle\Parcelamento\Form\Type\ParcelamentoType;
   
   class CheckoutFormType extends AbstractType {
       public function buildForm(FormBuilderInterface $builder, array $options) {
           $builder->add('payment_method', 'bfos_pagamento_forma_pagamento_checkout_choice', [
               'configuracoes' => [
                   'pagseguro' => [
                       'configuracao_checkout_form' => new ParcelamentoType($config, $orderTotal)
                   ]
               ]
           ]);
       }
   }
   

2. Twig Integration: Render parcel options dynamically in templates:

   {{ bfos_pagamento_opcoes_parcelamento(config, 500, {
       'colunas': 3,
       'mostrarParcelas': [1, 2, 3, 6, 12],
       'mostrarLinkVerTudo': true
   }) }}
   

3. JavaScript Handling: Leverage Resources/assets/ for dynamic form switching (e.g., pagseguro.js for gateway-specific logic).

Payment Gateway Patterns

1. Gateway-Specific Config: Extend the bundle for new gateways (e.g., MercadoPago, PicPay) by:

   • Creating a custom FormType for each gateway.
   • Overriding bfos_pagamento_forma_pagamento_checkout_choice in your theme.

2. Encryption/Decryption: Use the bundle’s ServicoDeCriptografia for sensitive data (e.g., tokens):

   $service = $this->container->get('bfos_pagamento.servico_de_criptografia');
   $encrypted = $service->encrypt('token123');
   

3. Webhook Handling: Implement a controller to process gateway callbacks (e.g., PagSeguroWebhookController).

Common Use Cases

Gotchas and Tips

Pitfalls

1. JavaScript Dependencies:

   • Issue: Missing jquery/requirejs breaks frontend rendering.
   • Fix: Verify assets are loaded in base.html.twig:

     {{ encore_entry_link_tags('app') }}  {# If using Webpack #}
     <script src="{{ asset('js/jquery.js') }}"></script>
     

2. Encryption Key:

   • Issue: Hardcoded secrets in config (security risk).
   • Fix: Use .env and validate in config/packages/bfos_pagamento.yaml:

     secret: '%env(PAYMENT_SECRET)%'
     

3. Parcelamento Logic:

   • Issue: Incorrect ParcelamentoConfiguracao values (e.g., jurosParcelamento as decimal vs. percentage).
   • Fix: Test with ParcelamentoUtils::obterOpcoesDeParcelamento() in a console command.

4. Gateway-Specific Quirks:

   • Issue: bfos_pagamento_forma_pagamento_checkout_choice expects exact gateway names (e.g., 'pagseguro').
   • Fix: Check Resources/config/gateways.yml for supported names.

Debugging Tips

1. Form Rendering:

   • Dump the form config:

     $form->getConfig()->getOption('configuracoes');
     

   • Check browser console for JS errors (e.g., requirejs not loading).

2. Parcelamento Calculation:

   • Log the config object:

     \Symfony\Component\VarDumper\VarDumper::dump($config);
     

   • Validate valorMinimoParcela vs. total amount.

3. Encryption:

   • Test decryption:

     $service->decrypt($encryptedToken);  // Should return original value
     

Extension Points

1. Custom Gateways:

   • Override BFOS\PagamentoBundle\Resources/config/gateways.yml to add new gateways.
   • Example:

     mercado_pago:
         label: 'Mercado Pago'
         form_type: 'app.form.type.MercadoPagoType'
     

2. Twig Extensions:

   • Extend bfos_pagamento_opcoes_parcelamento() by creating a custom Twig filter:

     // src/Twig/AppExtension.php
     public function getFilters() {
         return [
             new \Twig\TwigFilter('custom_parcel_options', [$this, 'customParcelOptions']),
         ];
     }
     

3. Validation:

   • Extend PaymentValidator trait to add custom rules:

     use BFOS\PagamentoBundle\Validator\Constraints\PaymentValidator;
     
     class CustomPaymentValidator extends PaymentValidator {
         public function validateCustomRule($value, Constraint $constraint) {
             // ...
         }
     }
     

Performance Notes

• Caching: Cache ParcelamentoUtils results if used frequently (e.g., in a checkout session).
• Lazy Loading: Load JS/CSS for payment gateways only when needed (e.g., via data-attribute triggers).