Symfony2Hipaylib Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require djoo/symfony2hipaylib
   

2. Autoload Configuration Modify app/autoload.php to include the Hipay library:

   $loader->add('HIPAY', __DIR__.'/../vendor/djoo/symfony2hipaylib/lib/hipay');
   require __DIR__.'/../vendor/djoo/symfony2hipaylib/lib/hipay/mapi_package.php';
   

3. First Use Case Use the library in a Symfony2 controller to initialize a payment:

   use HIPAY;
   
   $params = new \HIPAY_MAPI_PaymentParams();
   $params->setSite('YOUR_SITE_ID');
   $params->setPassword('YOUR_PASSWORD');
   $params->setAccount('YOUR_ACCOUNT_ID');
   

Implementation Patterns

Workflows

1. Payment Initialization Use HIPAY_MAPI_PaymentParams to configure payment details:

   $params = new \HIPAY_MAPI_PaymentParams();
   $params->setAmount(1000); // Amount in cents
   $params->setCurrency('978'); // EUR
   $params->setOrderId('ORDER_123');
   $params->setReturn('https://your-site.com/return');
   

2. Sending Payment Requests Use HIPAY_MAPI_SEND_XML to send XML requests to Hipay:

   $xmlTx = $params->createXML();
   $urlHipay = 'https://secure.hipay.com/payment/v4';
   $output = \HIPAY_MAPI_SEND_XML::sendXML($xmlTx, $urlHipay);
   

3. Handling Responses Parse Hipay’s response using HIPAY_MAPI_ResponseParser:

   $responseParser = new \HIPAY_MAPI_ResponseParser();
   $responseParser->setXml($output);
   $response = $responseParser->getResponse();
   

4. Webhook Validation Validate Hipay webhook notifications:

   $notification = new \HIPAY_MAPI_Notification();
   $notification->setXml($rawPostData);
   if ($notification->isValid()) {
       $status = $notification->getStatus();
   }
   

Integration Tips

• Symfony2 Services: Register the library as a service in services.yml for dependency injection:

  services:
      hipay.payment:
          class: HIPAY_MAPI_PaymentParams
          arguments: ['%hipay.site_id%', '%hipay.password%', '%hipay.account_id%']
  

• Configuration: Store Hipay credentials in parameters.yml:

  parameters:
      hipay.site_id: YOUR_SITE_ID
      hipay.password: YOUR_PASSWORD
      hipay.account_id: YOUR_ACCOUNT_ID
  

• Error Handling: Wrap Hipay calls in try-catch blocks to handle exceptions gracefully:

  try {
      $output = \HIPAY_MAPI_SEND_XML::sendXML($xmlTx, $urlHipay);
  } catch (\Exception $e) {
      // Log error or notify admin
  }
  

Gotchas and Tips

Pitfalls

1. Namespace Conflicts The package uses the HIPAY namespace directly. Ensure no naming collisions exist in your project. Prefix classes if necessary:

   use HIPAY as HipayLib;
   

2. XML Parsing Issues Hipay’s XML responses may fail if malformed. Validate XML before parsing:

   if (!\HIPAY_MAPI_Tools::isValidXml($output)) {
       throw new \RuntimeException('Invalid XML response from Hipay');
   }
   

3. Deprecated Methods The package mirrors Hipay’s original library, which may include deprecated methods. Check Hipay’s official documentation for updates.

4. Autoloading Quirks Forgetting to add the HIPAY namespace to autoload.php will result in ClassNotFound errors. Always include:

   $loader->add('HIPAY', __DIR__.'/../vendor/djoo/symfony2hipaylib/lib/hipay');
   

Debugging

• Enable Hipay Logging Configure Hipay’s logger to debug issues:

  \HIPAY_MAPI_Tools::setLogLevel(\HIPAY_MAPI_Tools::LOG_DEBUG);
  \HIPAY_MAPI_Tools::setLogFile(__DIR__.'/hipay_debug.log');
  

• Test with Sandbox Use Hipay’s sandbox environment (https://sandbox.hipay.com) for testing:

  $urlHipay = 'https://sandbox.hipay.com/payment/v4';
  

Extension Points

1. Custom Response Handlers Extend HIPAY_MAPI_ResponseParser to add custom logic:

   class CustomResponseParser extends \HIPAY_MAPI_ResponseParser {
       public function getCustomField() {
           return $this->getField('CUSTOM_FIELD');
       }
   }
   

2. Event Dispatching Integrate with Symfony’s event system to trigger actions on Hipay events:

   $dispatcher->dispatch('hipay.notification', new HipayNotificationEvent($notification));
   

3. Middleware for Webhooks Create a Symfony firewall or middleware to validate Hipay webhooks:

   public function onKernelRequest(GetResponseEvent $event) {
       if ($event->getRequest()->getPathInfo() === '/hipay/webhook') {
           $notification = new \HIPAY_MAPI_Notification();
           $notification->setXml($event->getRequest()->getContent());
           if (!$notification->isValid()) {
               throw new \RuntimeException('Invalid Hipay webhook');
           }
       }
   }