spinen/connectwise-php-client

SPINEN的ConnectWise PHP客户端。

维护者

详细信息

github.com/spinen/connectwise-php-client

源代码

问题

安装次数: 6,044

依赖: 0

建议: 0

安全: 0

星级: 15

关注者: 13

分支: 8

开放问题: 3

6.2.0 2024-04-08 15:52 UTC

Requires

Requires (Dev)

MIT 27853da4483eb187d89e8e63771938617e981099

  • Jimmy Puckett <jimmy.puckett.woop@spinen.com>

clientspinenconnectwise

This package is auto-updated.

Last update: 2024-09-08 16:35:55 UTC

README

Latest Stable Version Total Downloads Latest Unstable Version License

PHP客户端，用于RESTful ConnectWise API。

我们仅使用Laravel构建我们的应用程序，因此如果您在Laravel应用程序中使用此客户端，则可以使用一些特定的Laravel文件。我们已尝试确保您可以在Laravel之外使用此客户端，并在下面提供了一些相关文档。

构建状态

关于集成的说明

我们使用“成员伪装”模型，您需要设置一个集成器用户名和密码，并具有访问“成员API”的权限，这样所有对ConnectWise的调用都将以应用程序（成员ID）用户的权限执行。

我们将所有ConnectWise用户的成员ID设置为他们的电子邮件地址（例如，joe.doe@spinen.com在ConnectWise中的成员ID为joedoe）[注意：从joe.doe中删除了点，因为ConnectWise不允许在成员ID中使用点]。按照此约定，我们可以从我们的应用程序中登录用户的电子邮件地址推断成员ID。我们已包含一个可以用于User模型的特质，它将执行上述逻辑。

截至2019.3，它们在连接到API时需要clientId，因此您需要在此处注册一个...

https://developer.connectwise.com/ClientID

支持的操作

客户端支持标准的http动词以及一个额外的...

  • delete
  • get（ConnectWise默认分页为25条记录，除非您指定不同的pageSize，否则您将获得25条记录）
  • getAll（进行尽可能多的API调用以获取集合中的所有记录。在您使用此方法时请务必小心，因为您的系统可能耗尽内存。）
  • head
  • put
  • post
  • patch

模型

响应被转换为具有Swagger文档中定义的类型属性模型。您可以在src/Models文件夹中查看模型。每个模型上都有一个名为casts的属性，指示工厂如何将响应中的属性转换为类型。如果casts属性为空，则属性未在Swagger中定义，因此返回一个数组。

关系

一些响应包含到相关资源的链接。如果属性具有关系，则可以将其作为方法调用，并且将自动进行额外的调用并返回。值将存储在原始数据的位置，因此一旦加载就将其缓存。

$ psysh
Psy Shell v0.8.18 (PHP 7.2.17 — cli) by Justin Hileman

>>> // Using "$member" object for this example
>>> get_class($member) // Verify that it is a "Member"
=> "Spinen\ConnectWise\Models\v2019_3\System\Member"
>>> get_class($member->defaultLocation) // On load, the "defaultLocation" is a "SystemLocationReference" object
=> "Spinen\ConnectWise\Models\v2019_3\System\SystemLocationReference"
>>> get_class($member->defaultLocation()) // Call it as a method to load the relationship
=> "Spinen\ConnectWise\Models\v2019_3\System\Location"
>>> get_class($member->defaultLocation) // Now it is cached as a "Location" object
=> "Spinen\ConnectWise\Models\v2019_3\System\Location"

在"_info"属性中也可能有“相关”属性，您可以让系统为您加载这些属性。[注意：这将为相关属性执行getAll，因此将根据需要执行尽可能多的API调用以获取所有相关项目]

$ psysh
Psy Shell v0.8.18 (PHP 7.2.17 — cli) by Justin Hileman

>>> // Using "$company" object for this example
>>> get_class($company) // Verify that it is a "Company"
=> "Spinen\ConnectWise\Models\v2018_6\Company\Company"
>>> $company->_info // Look for potential relations
=> Spinen\ConnectWise\Models\v2018_6\Company\Metadata {#5678
     +"lastUpdated": "2019-05-20T18:12:38Z",
     +"updatedBy": "someone",
     +"dateEntered": "2006-06-21T16:04:59Z",
     +"enteredBy": "someone",
     +"contacts_href": "https://some.host/v4_6_release/apis/3.0/company/contacts?conditions=company/id=250",
     +"agreements_href": "https://some.host/v4_6_release/apis/3.0/finance/agreements?conditions=company/id=250",
     +"tickets_href": "https://some.host/v4_6_release/apis/3.0/service/tickets?conditions=company/id=250",
     +"opportunities_href": "https://some.host/v4_6_release/apis/3.0/sales/opportunities?conditions=company/id=250",
     +"activities_href": "https://some.host/v4_6_release/apis/3.0/sales/activities?conditions=company/id=250",
     +"projects_href": "https://some.host/v4_6_release/apis/3.0/project/projects?conditions=company/id=250",
     +"configurations_href": "https://some.host/v4_6_release/apis/3.0/company/configurations?conditions=company/id=250",
     +"orders_href": "https://some.host/v4_6_release/apis/3.0/sales/orders?conditions=company/id=250",
     +"documents_href": "https://some.host/v4_6_release/apis/3.0/system/documents?recordType=Company&recordId=250",
     +"sites_href": "https://some.host/v4_6_release/apis/3.0/company/companies/250/sites",
     +"teams_href": "https://some.host/v4_6_release/apis/3.0/company/companies/250/teams",
     +"reports_href": "https://some.host/v4_6_release/apis/3.0/company/companies/250/managementSummaryReports",
     +"notes_href": "https://some.host/v4_6_release/apis/3.0/company/companies/250/notes",
   }
>>> isset($company->agreements) // Not loaded before the call
=> false
>>> $company->agreements // Client goes to get "agreements" from the $company->_info->agreements_fref URI
=> Spinen\ConnectWise\Support\Collection {#6123
     // Removed to make example shorter
   }
>>> isset($company->agreements) // Cached & loaded for next call
=> true

安装

安装ConnectWise PHP客户端

$ composer require spinen/connectwise-php-client

Laravel配置和使用

对于>=Laravel 5.5，安装完成

该包使用Laravel 5的自动注册功能。

对于< Laravel 5.5，您需要注册服务提供者

  1. 将提供者添加到config/app.php
    'providers' => [
        # other providers omitted
        Spinen\ConnectWise\Laravel\ServiceProvider::class,
    ],
  1. [可选] 将别名添加到config/app.php
    'aliases' => [
        # other aliases omitted
        'ConnectWise' => Spinen\ConnectWise\Laravel\Facades\ConnectWise::class,
    ],

配置

  1. 将以下内容添加到 config/services.php...
    'connectwise' =>  [
        'client_id' => env('CW_CLIENT_ID'),
        'company_id' => env('CW_COMPANY_ID'),
        // Optional member id to use if there is not a logged in user
        'default_member_id' => env('CW_DEFAULT_MEMBER_ID'),
        'integrator' => env('CW_INTEGRATOR'),
        'password' => env('CW_PASSWORD'),
        'url' => env('CW_URL'),
        // Optional version of the API models to use
        //'version' => '' // default is the latest supported
    ],
  1. 将适当的值添加到您的 .env...
CW_CLIENT_ID=<the-client-id>
CW_COMPANY_ID=<company_id>
CW_DEFAULT_MEMBER_ID=<default_member_id>
CW_INTEGRATOR=<integrator username>
CW_PASSWORD=<integrator password>
CW_URL=https://<FQDN to ConnectWise server>
  1. 在 User 模型上使用 ConnectWiseMemberIdFromEmail 特性，该特性位于 Spinen\ConnectWise\Laravel\ConnectWiseMemberIdFromEmail，如果您的 ConnectWise member_id 与上述描述的电子邮件匹配。如果您不遵循该约定，则可以在 User 模型上定义自己的 getConnectWiseMemberIdAttribute 访问器，或者只需在您的用户表中添加一个 connect_wise_member_id 列，并用适当的值填充。

用法

以下是一个获取系统信息的示例...

从版本 3.1.0 开始，响应可以是 Laravel 模型集合或单个模型。您可以在 src/Models 中查看模型。它们都扩展了 Spinen\ConnectWise\Support，因此您可以查看它们提供的方法。

$ php artisan tinker
Psy Shell v0.8.0 (PHP 7.0.14 — cli) by Justin Hileman
>>> Auth::loginUsingId(1); // If not useing the default member id
=> App\User {#983
     id: "1",
     first_name: "Joe",
     last_name: "Doe",
     email: "joe.doe@domain.tld",
     admin: "0",
     created_at: "2017-01-02 18:30:47",
     updated_at: "2017-01-12 22:22:39",
     logged_in_at: "2017-01-12 22:22:39",
     deleted_at: null,
   }
>>> $cw = app('Spinen\ConnectWise\Api\Client');
=> Spinen\ConnectWise\Api\Client {#934}
>>> $info = $cw->get('system/info');
=> Spinen\ConnectWise\Models\v2019_3\System\Info {#1008}
>>> $info->toArray();
=> [
     "version" => "v2016.6.43325",
     "isCloud" => false,
     "serverTimeZone" => "Eastern Standard Time",
   ]
>>> $info->toJson()
=> "{"version":"v2016.6.43325","isCloud":false,"serverTimeZone":"Eastern Standard Time"}"
>>> $info->isCloud
=> false
>>> $info['isCloud'];
=> false

使用外观进行相同的调用...

$ php artisan tinker
Psy Shell v0.8.0 (PHP 7.0.14 — cli) by Justin Hileman
>>> Auth::loginUsingId(1);  // If not useing the default member id
=> App\User {#983
     id: "1",
     first_name: "Joe",
     last_name: "Doe",
     email: "joe.doe@domain.tld",
     admin: "0",
     created_at: "2017-01-02 18:30:47",
     updated_at: "2017-01-12 22:22:39",
     logged_in_at: "2017-01-12 22:22:39",
     deleted_at: null,
   }
>>> ConnectWise::get('system/info');
=> Spinen\ConnectWise\Models\v2019_3\System\Info {#1005}
>>> ConnectWise::get('system/info')->toArray();
=> [
        "version" => "v2018.6.59996",
        "isCloud" => false,
        "serverTimeZone" => "Eastern Standard Time",
        "licenseBits" => [
          // ... All of the properties
        ],
        "cloudRegion" => "NA",
      ]
>>> ConnectWise::get('system/info')->toJson();
=> "{"version":"v2018.6.59996",...}"
>>> ConnectWise::get('system/info')->isCloud;
=> false
>>> ConnectWise::get('system/info')['isCloud'];
=> false
>>>

非 Laravel 用法

要在 Laravel 之外使用客户端，只需创建对象...

$ psysh
Psy Shell v0.8.18 (PHP 7.2.17 — cli) by Justin Hileman

>>> // New-up objects
>>> $token = (new Spinen\ConnectWise\Api\Token())->setCompanyId('<company_id>')->setMemberId('<member_id>');
=> Spinen\ConnectWise\Api\Token {#208}
>>> $guzzle = new GuzzleHttp\Client();
=> GuzzleHttp\Client {#196}
>>> $resolver = new Spinen\ConnectWise\Support\ModelResolver();
=> Spinen\ConnectWise\Support\ModelResolver {#201}
>>> $client = (new Spinen\ConnectWise\Api\Client($token, $guzzle, $resolver))->setClientId('<the-client-id>')->setIntegrator('<integrator>')->setPassword('<password>')->setUrl('https://<domain.tld>');
=> Spinen\ConnectWise\Api\Client {#231}
>>> $info = $client->get('system/info');                                                                                                                     => Spinen\ConnectWise\Models\v2019_3\System\Info {#237}
>>> $info->toArray();
=> [
     "version" => "v2018.6.59996",
     "isCloud" => false,
     "serverTimeZone" => "Eastern Standard Time",
     "licenseBits" => [
       // ... All of the properties
     ],
     "cloudRegion" => "NA",
   ]
>>> // Set client to use different version
>>> $client->setVersion('2019.1')
=> Spinen\ConnectWise\Api\Client {#231}
>>> $info = $client->get('system/info');
>>> /// NOTE: the version in the namespace
=> Spinen\ConnectWise\Models\v2019_1\System\Info {#235}

支持的 API 模型版本

您可以通过以下 3 种方式之一指定所需模型的版本...

  1. Client 构造函数中的第 4 个参数
  2. 在 client 对象上调用 setVersion 方法
  3. [仅 Laravel] 在配置中设置 version 属性

支持的版本有

  • 2018.4
  • 2018.5
  • 2018.6
  • 2019.1
  • 2019.2
  • 2019.3
  • 2019.4
  • 2019.5 (默认)

您可以通过查看 src/Models/<version> 目录中各个 models 的 casts 属性来查看模型之间的差异。