README

此库为Collmex API提供了一个包装器。它尚未完成，一些记录类型（可能还有一些功能）缺失。

如果您实现了新的类型/功能，请创建一个pull request；如果您发现bug或提出功能请求，请创建问题。

对于每个Collmex记录类型（“Satzart”）都有一个类型类。目前，只实现了基本类型（MESSAGE、LOGIN、NEW_OBJECT_ID）和一些常规记录类型。

ABO_GET
ACC_BAL
ACCBAL_GET
ACCDOC
ACCDOC_GET
... 完整列表 »

兼容性

Collmex PHP SDK需要PHP >= 8.1。如果您仍在使用不再受支持的PHP版本，则可以安装Collmex PHP SDK的旧版本。

对于PHP 7.3、7.4和8.0的兼容性：使用2.x标签（composer require mjaschen/collmex:^2.0）；此版本将在版本4.0发布之前接收安全更新。
对于PHP 7.2的兼容性：使用1.x标签（composer require mjaschen/collmex:^1.0）；此版本不会接收任何更新。
对于PHP 7.0的兼容性：使用0.12.x标签（composer require mjaschen/collmex:^0.12）；此版本不会接收任何更新。
对于PHP 5.6的兼容性：使用0.11.x标签（composer require mjaschen/collmex:^0.11）；此版本不会接收任何更新。

新功能只会进入主分支，而不会回滚。

安装

使用Composer，只需运行以下命令将其添加到您的composer.json文件中：

composer require mjaschen/collmex

如果您想使用包含的Laravel服务提供程序CollmexServiceProvider，请将其添加到config/app.php提供程序数组中。

return [

    // ...

    'providers' => [
        // ...
        \MarcusJaschen\Collmex\CollmexServiceProvider::class,
    ],

    // ...
];

升级

2.x版本到3.x版本

阅读变更日志。您将看到版本2和3之间所有更改的列表。
确保您的代码库与composer.json中的所有要求兼容。
更新您的composer.json以要求Collmex PHP SDK的3.x版本。

{
  "require": {
    "mjaschen/collmex": "^3.0"
  }
}

1.x版本到2.x版本

阅读变更日志。您将看到版本1和2之间所有更改的列表。
确保您的代码库与composer.json中的所有要求兼容。
在您的代码库中重命名属性。类型类中的一些属性已被重命名。如果您使用这些属性，您必须相应地调整您的代码。简单的搜索和替换就足够了。下面是重命名属性的完整列表

用法/示例

从Collmex API获取数据

加载Collmex Customer记录

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());

向Collmex发送数据

创建新的Collmex Customer记录并从响应数据中获取Collmex客户ID

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());
  }

一次性发送多个记录

Collmex API接受包含多个记录的请求。

例如，一个有三个行项的客户订单作为单个请求中的三个CSV记录/行发送。

MultiRequest类提供了一种简单的方法，可以在一次操作中将多个记录发送到Collmex。任何有效的Type（或有效的Type实例的数组）都可以添加到队列中，并最终发送到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());
}

注释

Collmex期望所有字符串使用代码页1252（Windows）进行编码，而Collmex PHP SDK期望所有输入为UTF-8，并将所有输出都转换为UTF-8。字符串编码的转换是通过使用Symfony String Component和PHP的mb_convert_encoding()函数在发送请求到Collmex API之前以及从API接收响应之后透明完成的。

数字/货币值

此SDK默认不将数字值转换为Collmex API所需的字符串格式。

有关格式要求的更多信息，请参阅官方API文档。

该库提供了一些辅助函数，用于将几种类型转换为Collmex货币格式

辅助类的完全限定名称：\MarcusJaschen\Collmex\CollmexField\Money。

有关更多示例，请参阅单元测试。

日期值

Collmex理解两种不同的日期格式

ISO样式：YYYYMMDD
德国样式：DD.MM.YYYY

该库提供了一个辅助函数，用于将DateTime（包括Carbon实例）从Collmex日期格式转换过来和转换过去

use MarcusJaschen\Collmex\CollmexField\Date;

echo Date::toDateTime('20220921')->format('Y-m-d')
echo Date::toDateTime('12.08.2022')->format('Y-m-d')

这将输出

2022-09-21
2022-08-12

要将DateTime实例转换为Collmex格式（ISO样式）

use MarcusJaschen\Collmex\CollmexField\Date;

echo Date::fromDateTime(new \DateTime('2022-09-21T00:00:00', new \DateTimeZone('Europe/Berlin')))

这将输出

20220921

支持类型列表

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

开发

运行代码检查

要运行检查和测试，最简单的方法是使用提供的Composer脚本

使用composer ci:lint检查PHP文件的语法错误
使用Psalm进行静态分析并报告错误：composer ci:psalm
使用PHPUnit运行单元测试：composer ci:tests
使用PHP_CodeSniffer检查代码风格：composer ci:sniff

要一次性运行所有检查和测试，只需使用composer ci。

当然，可以直接使用测试运行器，例如对于PHPUnit

./vendor/bin/phpunit

Psalm

./vendor/bin/psalm

自动格式化代码

您可以使用Composer脚本来自动格式化代码

composer fix:php-cs

Collmex API文档

https://www.collmex.de/cgi-bin/cgi.exe?1005,1,help,api

mjaschen / collmex

维护者

详细信息