updated SepaUtilities to at least 1.0.2 to fix a n issue with the att…

…ributes purpose and category purpose

updated readme
updated example

CHANGE_LOG.md

@@ -1,6 +1,10 @@
 Sephpa - Change Log
 ===============
 
+##1.2.1 - Oct 18, '14##
+- updated SepaUtilities: Sephpa 1.2.0 throws an exception if you entering a purpose (`purp`) 
+or a category purpose (`ctgypurp`) while `checkAndSanitize` is set to true.
+
 ##1.2.0 - Oct 18, '14##
 - Sephpa is now available via composer
 - Sephpa is now splitted up into `SephpaCreditTransfer` and `SephpaDirectDebit`

README.md

@@ -18,70 +18,96 @@ the specifications of Electronic Banking Internet Communication Standard (EBICS)
     - pain.008.003.02
 
 ##Requirements##
-Sephpa was tested on PHP version 5.3 and requires SepaUtilities 1.0.1+ and [SimpleXML](http://php.net/manual/en/book.simplexml.php).
+Sephpa was tested on PHP version 5.3 and requires [SepaUtilities 1.0.2+](https://github.com/AbcAeffchen/SepaUtilities) and [SimpleXML](http://php.net/manual/en/book.simplexml.php).
 
-###Get it###
-You can download it here (make sure you also download [SepaUtilities](https://github.com/AbcAeffchen/SepaUtilities) and make it available) or
-you can use composer. Just add
+##Installation##
+
+###Composer###
+Just add
 
     {
         "require": {
-            "abcaeffchen/sephpa": "~1.2"
+            "abcaeffchen/sephpa": "~1.2.1"
         }
     }
 
-to your `composer.json`.
-
-###Creating a new SEPA file###
+to your `composer.json` and include the Composer autoloader to your script.
+
+###Direct download###
+You can download it here. Make sure you also download [SepaUtilities](https://github.com/AbcAeffchen/SepaUtilities) 
+and make it available. If you put src directory to your project root, you can use the following
+snippet to make Sephpa and SepaUtilities available to your project.
+
+    function sephpaAutoloader($class) {
+        switch($class)
+        {
+            case 'Sephpa':
+            case 'SephpaCreditTransfer':
+            case 'SephpaDirectDebit':
+            case 'SepaUtilities':
+                require __DIR__ . '/src/' . $class . '.php';
+            default:
+                require __DIR__ . '/src/payment-collections/' . $class . '.php';
+        }
+    }
+
+    spl_autoload_register('sephpaAutoloader');
 
-Note: This is not meant to teach you SEPA. If you want to learn more about SEPA or SEPA files,
-you should ask your bank for help. Everyone uses this class at his/her own risk and I assume no liability
-if anything goes wrong. You are supposed to check the files after handing them to your bank.
+Feel free to improve or adapt this to your requirement.
+You also have to remove the composer autoloader from `Sephpa.php`.
 
+##Creating a new SEPA file##
+**Note:** This is not meant to teach you SEPA. If you want to learn more about SEPA or SEPA files,
+you should ask your bank for help. You use this library at your own risk and I assume no liability
+if anything goes wrong. You are supposed to check the files **before** handing them to your bank.
 
+###Credit Transfer###
 Just include the file `Sephpa.php`. All other files will be included automatically. After that
 you can create a new Sephpa object.
 
-    $creditTransferFile = new Sephpa('Initiator Name', 'MessageID-1234', SEPA_PAIN_001_002_03);
+    $creditTransferFile = new SephpaCreditTransfer('Initiator Name',
+                                                   'MessageID-1234', 
+                                                   SephpaCreditTransfer::SEPA_PAIN_001_002_03);
 
-You have to input the initiator name, the unique message id and the type of the file. The message
-id have to be unique for all sepa files you hand over to your bank. As type you can choose one of
-the following:
+You have to input the initiator name, the unique message id and the version of the file. The message
+id have to be unique for all sepa files you hand over to your bank. This is one of the things Sephpa
+will not check for you. Currently supported credit transfer versions are:
 
 - `SEPA_PAIN_001_002_03`: Credit transfer version pain.001.002.03
 - `SEPA_PAIN_001_003_03`: Credit transfer version pain.001.003.03
-- `SEPA_PAIN_008_002_02`: Direct debit version pain.008.002.02
-- `SEPA_PAIN_008_003_02`: Direct debit version pain.008.003.02
 
-If you don't know which version to choose ask your bank which version they do accept. Normally
+If you don't know which version to choose, ask your bank which versions they do accept. Normally
 banks are not the fastest and so they will most likely accept the older one.
 
-Once you created the Sephpa object you can add a payment collection. You can add as many payment
-collections as you like, but they have to be all of the same type.
+By default `checkAndSanitize` is set to true, which means that Sephpa will check and sanitize every
+input it self and throw exceptions if something can not be sanitized. This sounds nagging but if
+you turn off this checks and just ignore the exceptions your bank will not accept the files.
+But it is **recommended** to check all inputs at input time (using [SepaUtilities](https://github.com/AbcAeffchen/SepaUtilities))
+and then only add valid data. Then you can turn off `checkAndSanitize` to prevent double checking everything.
 
-    $creditTransferCollection = $creditTransferFile->addCreditTransferCollection(array(
-    // required information about the payer
+Once you created the SephpaCreditTransfer object, you can add a payment collection. You can add 
+as many payment collections as you like.
+
+    $creditTransferCollection = $creditTransferFile->addCollection(array(
+    // required information about the debtor
         'pmtInfId'      => 'PaymentID-1234',        // ID of the payment collection
-        'dbtr'          => 'Name of Debtor2',       // (max 70 characters)
+        'dbtr'          => 'Name of Debtor',        // (max 70 characters)
         'iban'          => 'DE21500500001234567897',// IBAN of the Debtor
         'bic'           => 'SPUEDE2UXXX',           // BIC of the Debtor
     // optional
         'ccy'           => 'EUR',                   // Currency. Default is 'EUR'
         'btchBookg'     => 'true',                  // BatchBooking, only 'true' or 'false'
-        //'ctgyPurp'      => ,                      // Do not use this if you do not know how. For further information read the SEPA documentation
+        //'ctgyPurp'      => ,                      // Category Purpose. Do not use this if you do not know how. For further information read the SEPA documentation
         'reqdExctnDt'   => '2013-11-25',            // Date: YYYY-MM-DD
         'ultmtDebtr'    => 'Ultimate Debtor Name'   // just an information, this do not affect the payment (max 70 characters)
     ));
 
-You can use methods from [SepaUtilities](https://github.com/AbcAeffchen/SepaUtilities) to 
-validate and sanitize the inputs.
-
-To each collection you can add as many payments as you want
+You can add as many payments as you want to each collection.
 
     $creditTransferCollection->addPayment(array(
-    // needed information about the one who gets payed
+    // needed information about the creditor
         'pmtId'     => 'TransferID-1234-1',     // ID of the payment (EndToEndId)
-        'instdAmt'  => 1.14,                    // amount,
+        'instdAmt'  => 0.42,                    // amount,
         'iban'      => 'DE21500500009876543210',// IBAN of the Creditor
         'bic'       => 'SPUEDE2UXXX',           // BIC of the Creditor (only required for pain.001.002.03)
         'cdtr'      => 'Name of Creditor',      // (max 70 characters)
@@ -91,22 +117,64 @@ To each collection you can add as many payments as you want
         'rmtInf'    => 'Remittance Information' // unstructured information about the remittance (max 140 characters)
     ));
 
+###Direct Debits###
+Direct debits work the same way as credit transfers, but they have little different inputs.
+
+    $directDebitFile = new SephpaDirectDebit('Initiator Name', 
+                                             'MessageID-1235', 
+                                             SephpaDirectDebit::SEPA_PAIN_008_002_02);
+
+    $directDebitCollection = $directDebitFile->addCollection(array(
+    // needed information about the payer
+        'pmtInfId'      => 'PaymentID-1235',        // ID of the payment collection
+        'lclInstrm'     => SepaUtilities::LOCAL_INSTRUMENT_CORE_DIRECT_DEBIT,
+        'seqTp'         => SepaUtilities::SEQUENCE_TYPE_RECURRING,
+        'cdtr'          => 'Name of Creditor',      // (max 70 characters)
+        'iban'          => 'DE87200500001234567890',// IBAN of the Creditor
+        'bic'           => 'BELADEBEXXX',           // BIC of the Creditor
+        'ci'            => 'DE98ZZZ09999999999',    // Creditor-Identifier
+    // optional
+        'ccy'           => 'EUR',                   // Currency. Default is 'EUR'
+        'btchBookg'     => 'true',                  // BatchBooking, only 'true' or 'false'
+        //'ctgyPurp'      => ,                      // Do not use this if you not know how. For further information read the SEPA documentation
+        'ultmtCdtr'     => 'Ultimate Creditor Name',// just an information, this do not affect the payment (max 70 characters)
+        'reqdColltnDt'  => '2013-11-25'             // Date: YYYY-MM-DD
+    ));
+                        
+    $directDebitCollection->addPayment(array(
+    // needed information about the 
+        'pmtId'         => 'TransferID-1235-1',     // ID of the payment (EndToEndId)
+        'instdAmt'      => 2.34,                    // amount
+        'mndtId'        => 'Mandate-Id',            // Mandate ID
+        'dtOfSgntr'     => '2010-04-12',            // Date of signature
+        'bic'           => 'BELADEBEXXX',           // BIC of the Debtor
+        'dbtr'          => 'Name of Debtor',        // (max 70 characters)
+        'iban'          => 'DE87200500001234567890',// IBAN of the Debtor
+    // optional
+        'amdmntInd'     => 'false',                 // Did the mandate change
+        'elctrncSgntr'  => 'test',                  // do not use this if there is a paper-based mandate
+        'ultmtDbtr'     => 'Ultimate Debtor Name',  // just an information, this do not affect the payment (max 70 characters)
+        //'purp'        => ,                        // Do not use this if you not know how. For further information read the SEPA documentation
+        'rmtInf'        => 'Remittance Information',// unstructured information about the remittance (max 140 characters)
+        // only use this if 'amdmntInd' is 'true'. at least one must be used
+        'orgnlMndtId'           => 'Original-Mandat-ID',
+        'orgnlCdtrSchmeId_nm'   => 'Creditor-Identifier Name',
+        'orgnlCdtrSchmeId_id'   => 'DE98AAA09999999999',
+        'orgnlDbtrAcct_iban'    => 'DE87200500001234567890',// Original Debtor Account
+        'orgnlDbtrAgt'          => 'SMNDA'          // only 'SMNDA' allowed if used
+    ));
+
+###Get the Sepa file###
 After you have added some payments to your payment collection you can save the finished file by
 
-    $ct = fopen('credit_transfer.xml', 'w');
-    fwrite($ct, $creditTransferFile->generateXml());
-    fclose($ct);
+    $creditTransferCollection->storeSepaFile();
 
 or get it directly without saving it on the server by
 
-    header('Content-Disposition: attachment; filename="credit_transfer.xml"');
-    print $creditTransferFile->generateXml();
-
-Notice that you can change the `.xml` file to a `.xsd` file by changing the name.
+    $creditTransferCollection->downloadSepaFile();
 
-This works for direct debits the same way. Please have a look at the example.
+Notice that you can hand over a filename you like, but you should only use the file extension  
+`.xsd` or `.xml`.
 
 ###Licence###
 Licensed under the MIT Licence.
-
-###

composer.json

@@ -18,7 +18,7 @@
     "require": {
         "php": ">=5.3.0",
         "ext-simplexml": "*",
-        "abcaeffchen/sepa-utilities": "~1.0.1"
+        "abcaeffchen/sepa-utilities": "~1.0.2"
     },
     "autoload": {
         "psr-4": {

example/example.php

@@ -5,6 +5,7 @@
  */
 
 use AbcAeffchen\Sephpa\SephpaCreditTransfer;
+use AbcAeffchen\SepaUtilities\SepaUtilities;
 use AbcAeffchen\Sephpa\SephpaDirectDebit;
 
 require_once '../src/Sephpa.php';
@@ -50,9 +51,9 @@
 // at least one in every SEPA file. No limit.
 $directDebitCollection = $directDebitFile->addCollection(array(
                     // needed information about the payer
-                        'pmtInfId'      => 'PaymentID-1235',        // ID of the paymentcollection
-                        'lclInstrm'     => 'CORE',                  // only 'CORE' or 'B2B'
-                        'seqTp'         => 'RCUR',                  // only 'FRST', 'RCUR', 'OOFF' or 'FNAL'
+                        'pmtInfId'      => 'PaymentID-1235',        // ID of the payment collection
+                        'lclInstrm'     => SepaUtilities::LOCAL_INSTRUMENT_CORE_DIRECT_DEBIT,
+                        'seqTp'         => SepaUtilities::SEQUENCE_TYPE_RECURRING,
                         'cdtr'          => 'Name of Creditor',      // (max 70 characters)
                         'iban'          => 'DE87200500001234567890',// IBAN of the Creditor
                         'bic'           => 'BELADEBEXXX',           // BIC of the Creditor
@@ -77,7 +78,7 @@
                         'iban'          => 'DE87200500001234567890',// IBAN of the Debtor
                     // optional
                         'amdmntInd'     => 'false',                 // Did the mandate change
-                        'elctrncSgntr'  => 'test',                  // do not use this if there is a paper-based mandate
+                        //'elctrncSgntr'  => 'test',                  // do not use this if there is a paper-based mandate
                         'ultmtDbtr'     => 'Ultimate Debtor Name',  // just an information, this do not affect the payment (max 70 characters)
                         //'purp'        => ,                        // Do not use this if you not know how. For further information read the SEPA documentation
                         'rmtInf'        => 'Remittance Information',// unstructured information about the remittance (max 140 characters)

src/Sephpa.php

@@ -178,7 +178,7 @@ public function downloadSepaFile($filename = 'payments.xsd')
      * @param string $filename The path and filename
      * @throws SephpaInputException
      */
-    public function storeSepaFile($filename = 'patments.xsd')
+    public function storeSepaFile($filename = 'payments.xsd')
     {
         $file = fopen($filename, 'w');
         fwrite($file, $this->generateXml());