mjaschen / collmex
Collmex PHP SDK
Fund package maintenance!
mjaschen
www.paypal.com/paypalme/mjaschen
Installs: 47 274
Dependents: 0
Suggesters: 0
Security: 0
Stars: 18
Watchers: 9
Forks: 23
Open Issues: 7
Requires
- php: ^8.1
- ext-curl: *
- ext-fileinfo: *
- ext-json: *
- ext-zip: *
- symfony/finder: ^5.4 || ^6.4 || ^7.0
- symfony/http-foundation: ^5.4 || ^6.4 || ^7.0
- symfony/mime: ^5.4 || ^6.4 || ^7.0
- symfony/string: ^5.4 || ^6.4 || ^7.0
Requires (Dev)
- dereuromark/composer-prefer-lowest: ^0.1.10
- ergebnis/composer-normalize: ^2.0
- friendsofphp/php-cs-fixer: ^3.0
- laravel/framework: >=7.2
- mockery/mockery: ^1.6
- moneyphp/money: ^4.0
- phpunit/phpunit: ^10.0
- rector/rector: ^1.0.3
- squizlabs/php_codesniffer: ^3.7
- vimeo/psalm: ^5.0
- dev-main
- 3.2.0
- 3.1.0
- 3.0.0
- 2.12.0
- 2.11.0
- 2.10.0
- 2.9.0
- 2.8.2
- 2.8.1
- 2.8.0
- 2.7.3
- 2.7.2
- 2.7.1
- 2.7.0
- 2.6.1
- 2.6.0
- 2.5.3
- 2.5.2
- 2.5.1
- 2.5.0
- 2.4.1
- 2.4.0
- 2.3.1
- 2.3.0
- 2.2.0
- 2.1.1
- 2.1.0
- 2.0.0
- 1.6.3
- 1.6.2
- 1.6.1
- 1.6.0
- 1.5.1
- 1.5.0
- 1.4.1
- 1.4.0
- 1.3.3
- 1.3.2
- 1.3.1
- 1.3.0
- 1.2.1
- 1.2.0
- 1.1.3
- 1.1.2
- 1.1.1
- 1.1.0
- 1.0.0
- 0.12.0
- 0.11.1
- 0.11.0
- 0.10.1
- 0.10.0
- 0.9.2
- 0.9.1
- 0.9.0
- 0.8.12
- 0.8.11
- 0.8.10
- 0.8.9
- 0.8.8
- 0.8.7
- 0.8.6
- 0.8.5
- 0.8.4
- 0.8.3
- 0.8.2
- 0.8.1
- 0.8.0
- 0.7.7
- 0.7.6
- 0.7.5
- 0.7.4
- 0.7.3
- 0.7.2
- 0.7.1
- 0.7.0
- 0.6.21
- 0.6.20
- 0.6.19
- 0.6.18
- 0.6.16
- 0.6.15
- 0.6.14
- 0.6.13
- 0.6.12
- 0.6.11
- 0.6.10
- 0.6.9
- 0.6.8
- 0.6.7
- 0.6.6
- 0.6.5
- 0.6.4
- 0.6.3
- 0.6.2
- 0.6.1
- 0.6.0
- 0.5.3
- 0.5.2
- 0.5.1
- 0.5.0
- 0.4.1
- 0.4.0
- 0.3.5
- 0.3.4
- 0.3.3
- 0.3.2
- 0.3.1
- 0.3.0
- 0.2.2
- 0.2.1
- 0.2.0
- 0.1.4
- 0.1.3
- 0.1.2
- dev-dependabot/composer/main/phpunit/phpunit-tw-11.2
- dev-feature/rector
- dev-release/2.x
- dev-release/1.x
This package is auto-updated.
Last update: 2024-10-10 07:29:57 UTC
README
This library provides a wrapper for the Collmex API. It's not complete yet, some record types (and maybe some features) are missing.
Please create a pull request if you have implemented a new type/feature or create issues for bugs/feature requests.
There is (or least should be…) a Type class for every Collmex record type
("Satzart"). Currently, only the base types (MESSAGE
, LOGIN
,
NEW_OBJECT_ID
) and a few normal record types are implemented:
ABO_GET
ACC_BAL
ACCBAL_GET
ACCDOC
ACCDOC_GET
- ... full list »
Compatibility
The Collmex PHP SDK requires PHP >= 8.1. It's possible to install an older version of the Collmex PHP SDK, if you're still using a no longer supported PHP version:
- for PHP 7.3, 7.4 and 8.0 compatibility: use the 2.x tags (
composer require mjaschen/collmex:^2.0
); this version will receive security updates until version 4.0 is released. - for PHP 7.2 compatibility: use the 1.x tags (
composer require mjaschen/collmex:^1.0
); this version won't receive any updates. - for PHP 7.0 compatibility: use the 0.12.x tags (
composer require mjaschen/collmex:^0.12
); this version won't receive any updates. - for PHP 5.6 compatibility: use the 0.11.x tags (
composer require mjaschen/collmex:^0.11
); this version won't receive any updates.
New features will only go into the main branch and won't be backported.
Installation
Using Composer, just add it to your composer.json
by running:
composer require mjaschen/collmex
If you want to use the included Laravel service provider
CollmexServiceProvider
, add it to the config/app.php
providers array:
return [ // ... 'providers' => [ // ... \MarcusJaschen\Collmex\CollmexServiceProvider::class, ], // ... ];
Upgrading
Version 2.x to 3.x
- Read the change log. You will see the list of everything changed between versions 2 and 3.
- Ensure your codebase is compatible with all requirements in
composer.json
. - Update your
composer.json
to require version 3.x of the Collmex PHP SDK:
{ "require": { "mjaschen/collmex": "^3.0" } }
Version 1.x to 2.x
- Read the change log. You will see the list of everything changed between versions 1 and 2.
- Ensure your codebase is compatible with all requirements in
composer.json
. - Rename attributes which are used in your codebase. Some attributes in the type classes have been renamed. If you use these attributes, you have to adjust your code as well. A simple search-and-replace is sufficient for this. Below you will find the complete list of renamed attributes:
Usage/Examples
Fetch from Collmex API
Load a Collmex Customer record:
use MarcusJaschen\Collmex\Client\Curl as CurlClient; use MarcusJaschen\Collmex\Request; use MarcusJaschen\Collmex\Type\CustomerGet; // initialize HTTP client $collmexClient = new CurlClient('USER', 'PASSWORD', 'CUSTOMER_ID'); // create request object $collmexRequest = new Request($collmexClient); // create a record type; we're querying the API for customer with ID=12345 $getCustomerType = new CustomerGet(array('customer_id' => '12345')); // send HTTP request and get response object $collmexResponse = $collmexRequest->send($getCustomerType->getCsv()); if ($collmexResponse->isError()) { echo 'Collmex error: ' . $collmexResponse->getErrorMessage() . '; Code=' . $collmexResponse->getErrorCode() . PHP_EOL; return; } $records = $collmexResponse->getRecords(); foreach ($records as $record) { // contains one Customer object and the Message object(s) var_dump($record->getData()); } // show unparsed response contents: var_dump($collmexResponse->getResponseRaw());
Send Data to Collmex
Create a new Collmex Customer record and get the Collmex customer ID from the response data:
use MarcusJaschen\Collmex\Client\Curl as CurlClient; use MarcusJaschen\Collmex\Request; use MarcusJaschen\Collmex\Type\Customer; // initialize HTTP client $collmexClient = new CurlClient('USER', 'PASSWORD', 'CUSTOMER_ID'); // create request object $collmexRequest = new Request($collmexClient); // create a record type; we create a customer with some basic fields $customer = new Customer( [ 'client_id' => '1', 'salutation' => 'Herr', 'firstname' => 'Charly', 'lastname' => 'Cash', 'street' => 'Hauptstraße 12', 'zipcode' => '12222', 'city' => 'Berlin', 'inactive' => Customer::STATUS_ACTIVE, 'country' => 'DE', 'phone' => '+49300000000', 'email' => 'cash@example.org', 'output_medium' => Customer::OUTPUT_MEDIUM_EMAIL, ] ); // send HTTP request and get response object $collmexResponse = $collmexRequest->send($customer->getCsv()); if ($collmexResponse->isError()) { echo 'Collmex error: ' . $collmexResponse->getErrorMessage() . '; Code=' . $collmexResponse->getErrorCode() . PHP_EOL; return; } $newObject = $collmexResponse->getFirstRecord(); echo 'New Collmex customer ID=' . $newObject->new_id . PHP_EOL; $records = $collmexResponse->getRecords(); foreach ($records as $record) { // contains one NewObject object and the Message object(s) var_dump($record->getData()); }
Send Multiple Records at Once
The Collmex API accepts requests containing multiple records.
For example, a customer order with three line-items is sent as three CSV records/lines within a single request.
The MultiRequest
class provides a simple way to send multiple records to Collmex at once. Any valid Type
(or an
array of valid Type
instances) can be added to a queue and eventually sent to the Collmex API.
use MarcusJaschen\Collmex\Client\Curl as CurlClient; use MarcusJaschen\Collmex\MultiRequest; use MarcusJaschen\Collmex\Type\CustomerOrder; // initialize HTTP client $collmexClient = new CurlClient('USER', 'PASSWORD', 'CUSTOMER_ID'); // create request object $collmexMultiRequest = new MultiRequest($collmexClient); // create a record type; we create a CustomerOrder with some basic fields $customerOrderData = [ 'client_id' => '1', 'customer_salutation' => 'Herr', 'customer_firstname' => 'Charly', 'customer_lastname' => 'Cash', 'customer_street' => 'Hauptstraße 12', 'customer_zipcode' => '12222', 'customer_city' => 'Berlin', 'customer_country' => 'DE', 'customer_phone' => '+49300000000', 'customer_email' => 'cash@example.org', 'order_date' => '01.01.1970', 'status' => CustomerOrder::STATUS_CONFIRMED, ]; // set several item positions $customerOrderItem = new CustomerOrder( array_merge( $customerOrderData, [ 'product_description' => 'erster Artikel', 'quantity' => '1', 'price' => '10,50', 'tax_rate' => CustomerOrder::TAX_RATE_FULL, ] ) ); $collmexMultiRequest->add($customerOrderItem); $customerOrderItem = new CustomerOrder( array_merge( $customerOrderData, [ 'product_description' => 'zweiter Artikel', 'quantity' => '10', 'price' => '37,99', 'tax_rate' => CustomerOrder::TAX_RATE_REDUCED, ] ) ); $collmexMultiRequest->add($customerOrderItem); $customerOrderItem = new CustomerOrder( array_merge( $customerOrderData, [ 'product_description' => 'Artikel Nummer drei', 'quantity' => '3', 'price' => '1250,00', 'tax_rate' => CustomerOrder::TAX_RATE_FULL, ] ) ); $collmexMultiRequest->add($customerOrderItem); // send HTTP request and get response object $collmexResponse = $collmexMultiRequest->send(); if ($collmexResponse->isError()) { echo 'Collmex error: ' . $collmexResponse->getErrorMessage() . '; Code=' . $collmexResponse->getErrorCode() . PHP_EOL; return; } $newObject = $collmexResponse->getFirstRecord(); echo 'New Collmex order ID=' . $newObject->new_id . PHP_EOL; $records = $collmexResponse->getRecords(); foreach ($records as $record) { // contains one NewObject object and the Message object(s) var_dump($record->getData()); }
Notes
Collmex expects all strings encoded in code page 1252 (Windows) while the
Collmex PHP SDK expects all inputs as UTF-8 and outputs everything as UTF-8.
The conversion of string encodings is done transparently by using the
Symfony String Component and PHP's mb_convert_encoding()
function before
sending a request to the Collmex API and after receiving the response from
the API.
Numeric / money values
This SDK does not convert numeric values to the string format required by the Collmex API by default.
For more information on format requirements, see the offical API documentation.
The library provides helpers for simple conversion from several types to the Collmex money format:
Fully qualified class name for the helper: \MarcusJaschen\Collmex\CollmexField\Money
.
See the unit tests for more examples.
Date Values
Collmex unterstands two different formats for dates:
- ISO style:
YYYYMMDD
- German style:
DD.MM.YYYY
The library provides a helper to convert DateTime
(which covers Carbon instances as well) from and to the Collmex date format:
use MarcusJaschen\Collmex\CollmexField\Date; echo Date::toDateTime('20220921')->format('Y-m-d') echo Date::toDateTime('12.08.2022')->format('Y-m-d')
This will output
2022-09-21
2022-08-12
To convert a DateTime
instance to Collmex format (ISO style):
use MarcusJaschen\Collmex\CollmexField\Date; echo Date::fromDateTime(new \DateTime('2022-09-21T00:00:00', new \DateTimeZone('Europe/Berlin')))
This will output
20220921
List of Supported Types
ABO_GET
ACC_BAL
ACCBAL_GET
ACCDOC
ACCDOC_GET
ADDRESS_GROUPS_GET
API_NOTIFICATION
CMXADR
ADRGRP
BANK_STATEMENT_GET_FROM_BANK
BATCH_GET
BILL_OF_MATERIAL_GET
CMXABO
CMXADR
CMXBOM
CMXBTC
CMXDLV
CMXEPF
CMXINV
CMXKND
CMXLIF
CMXLRN
CMXMGD
CMXORD-2
CMXPOD
CMXPRD
CMXPRI
CMXPRI_CHANGE
CMXQTN
CMXSBI
CMXSTK
CMXUMS
CMXVAG
CUSTOMER_GET
DELIVERY_GET
EMPLOYEE
EMPLOYEE_GET
INVOICE_GET
INVOICE_PAYMENT
INVOICE_PAYMENT_GET
INVOICE_OUTPUT
INVOICE_OUTPUT_SET
MEMBER_GET
OPEN_ITEM
OPEN_ITEMS_GET
PAYMENT_CONFIRMATION
PRICE_GROUP
PRICE_GROUPS_GET
PRDGRP
PRODUCT_GET
PRODUCT_GROUPS_GET
PRODUCT_PRICE_GET
PRODUCTION_ORDER
PRODUCTION_ORDER_GET
PROJECT_STAFF
PROJECT_STAFF_GET
PURCHASE_ORDER_GET
SALES_ORDER_GET
SHIPMENT_CONFIRM
SHIPMENT_NOTIFICATION_SEND
SHIPMENT_ORDERS_GET
STOCK_AVAILABLE
STOCK_AVAILABLE_GET
STOCK_CHANGE
STOCK_CHANGE_GET
STOCK_GET
TRACKING_NUMBER
VENDOR_GET
VOUCHER
VOUCHER_GET
Development
Run code checks
To run checks and tests, it's the easiest to use the provided Composer scripts:
- lint PHP files for syntax errors:
composer ci:lint
- run static analysis with Psalm and report errors:
composer ci:psalm
- run unit tests with PHPUnit:
composer ci:tests
- check the code style with
PHP_CodeSniffer:
composer ci:sniff
To run all checks and tests at once, just use composer ci
.
Of course, it's possible to use the test runners directly, e.g. for PHPUnit:
./vendor/bin/phpunit
Psalm:
./vendor/bin/psalm
Autoformat the code
You can use a Composer script to autoformat the code:
composer fix:php-cs