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_GETACC_BALACCBAL_GETACCDOCACCDOC_GETADDRESS_GROUPS_GETAPI_NOTIFICATIONCMXADRADRGRPBATCH_GETBILL_OF_MATERIAL_GETCMXABOCMXADRCMXBOMCMXBTCCMXDLVCMXEPFCMXINVCMXKNDCMXMGDCMXORD-2CMXPODCMXPRDCMXPRICMXPRI_CHANGECMXSTKCMXUMSCUSTOMER_GETDELIVERY_GETINVOICE_GETINVOICE_OUTPUTINVOICE_OUTPUT_SETMEMBER_GETOPEN_ITEMOPEN_ITEMS_GETPAYMENT_CONFIRMATIONPRICE_GROUPPRICE_GROUPS_GETPRDGRPPRODUCT_GETPRODUCT_GROUPS_GETPRODUCT_PRICE_GETPRODUCTION_ORDERPRODUCTION_ORDER_GETPROJECT_STAFFPROJECT_STAFF_GETPURCHASE_ORDER_GETSALES_ORDER_GETSHIPMENT_CONFIRMSHIPMENT_NOTIFICATION_SENDSHIPMENT_ORDERS_GETSTOCK_AVAILABLESTOCK_AVAILABLE_GETSTOCK_CHANGESTOCK_CHANGE_GETSTOCK_GETTRACKING_NUMBERVOUCHERVOUCHER_GET
The Collmex PHP SDK requires PHP >= 7.3. If you're still using an ancient PHP version, you can install older versions of the Collmex PHP SDK:
- for PHP 7.2 compatibility: use the 1.x tags (
composer require mjaschen/collmex:^1.0); this version will receive security updates until version 3.0 is released. - 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.
Using Composer, just add it to your composer.json by running:
composer require mjaschen/collmexIf 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,
],
// ...
];- 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:
| Class | Old Name | New Name |
|---|---|---|
Stock |
charge_number |
batch_number |
Stock |
charge_description |
batch_description |
StockChange |
destination_charge |
destination_batch |
StockChange |
destination_charge_labeling |
destination_batch_labeling |
StockChange |
source_charge |
source_batch |
AccountDocumentGet |
only_changed |
changed_only |
CustomerGet |
only_changed |
changed_only |
MemberGet |
only_changed |
changed_only |
SalesOrderGet |
only_changed |
changed_only |
StockGet |
only_changed |
changed_only |
VoucherGet |
only_changed |
changed_only |
Customer |
forename |
firstname |
CustomerOrder |
forename |
firstname |
Invoice |
forename |
firstname |
Member |
forename |
firstname |
Customer |
firm |
company |
DifferentShippingAddress |
firm |
company |
Member |
firm |
company |
CustomerOrder |
customer_firm |
customer_company |
Invoice |
customer_firm |
customer_company |
CustomerOrder |
delivery_firm |
delivery_company |
Invoice |
delivery_firm |
delivery_company |
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());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());
}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.5,
'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,
'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());
}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.
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/phpunitPsalm:
./vendor/bin/psalmYou can use a Composer script to autoformat the code:
composer fix:php-cs