README

许可证：MIT
此软件按原样提供，不提供任何类型的保证。
如果您发现错误或有功能请求，请创建一个问题

使用Composer进行安装

composer require coolrunner/business-central-sdk

入门指南

• 注册一套商务中心凭证
  • SDK使用基本身份验证
• 将库安装到您的应用程序中
• 加载SDK

构建模型

由于商务中心的Web服务是动态创建的，因此所有实体都可以预先生成。

BusinessCentral\Constructor::buildModels(
    'my-tenant-id.onmicrosoft.com',
    'Application (client) ID',
    'CLIENT_SECRET'
);

可以使用带有您的凭据的post-autoload-dump composer脚本来生成实体，以通过您的Web服务公开实体。

连接到商务中心

商务中心PHP使用单例模式进行SDK实例。

一旦初始化了一个实例，它将从一个商务中心获取模式。（包括标准实体）。

$sdk = \BusinessCentral\SDK::instance('my-tenant-id.onmicrosoft.com', [
	// OAuth2 [Required]
    'client_id' => 'Application (client) ID',
    
    // Basic auth token [Required]
    'client_secret'    => '***',
    
    // Default collection size [Optional]
    // Amount of entities to load initially and per page per collection
    // Can be changed on the fly on any collection instance
    'default_collection_size' => 20,
    
    // Default environment [Optional - 'production' by default]
    'environment' => 'dev'
]);

手动获取实体

商务中心PHP使用内部查询构建器来导航和获取实体。

访问查询

$query = $sdk->query();

使用查询进行导航

$query = $sdk->query();

// Navigate using ->navigateTo(...) (or shorthand ->to(...))
$query->to('Company','CompanyName')->to('invoicingCustomers'); // Equivalent of fetching from 'Company(CompanyName)/invoicingCustomers'

获取结果

$collection = $query->fetch(); // Fetches the results of the query as a collection

// Fetches the first result of the query 
$entity = $query->first(); // equivalent of $query->fetch()->first()

// Fetches all the results of the query 
$entity = $query->all(); // Fetches all matching entities

获取实体

// Fetch a single company
$company = $sdk->company('CompanyName');
// Fetch all companies available to the authorized user
$companies = $sdk->companies();

类参考

实体

从商务中心获取的实体的类

实体属性/关系

由于商务中心是动态的，商务中心的实体在所有实现中不一定具有标准化的属性。请参考您的具体实现。

或者查看构建模型时生成的entities.md文件。

获取关系

您可以通过调用关系的名称作为属性或方法来从给定的实体中获取关系。

// Returns a collection of entities if the relation is a collection,
// else returns the single instance of the related entity or if none is found
$customers = $entity->relation;
// Returns a query builder pointing at the relation - Use this if you have further filters (See [Builer/Filters](#builderfilters))
$customers = $entity->relation();

如果关系不指向集合，则仅返回单个相关实体。

请检查实体概述以查看关系是否为集合类型。

实体方法

• fill(array $attributes) : 实体

  • 一次性更新/设置多个属性 - 仅设置可填充属性
  • 请参考实体概述上的单个实体类型

• save() : bool

  • 将实体保存到商务中心

• validate() : bool

  • 将实体与商务中心设置的规则进行验证（该方法在save()期间也会调用）

• getEntityType: 实体类型

  • 获取实体的实体类型

• query() : 构建器

  • 获取指向实体的查询

• toArray() : array

  • 将实体作为关联数组获取

实体集合

从商务中心获取的实体的容器类

实体集合属性

无

实体集合方法

• find(string|array $id, $default = null) : 实体 | null

  • 根据给定的id或失败时的$default查找并返回集合中的实体

• create(array $attributes) : 实体

  • 创建并返回具有给定属性的新的实体

• update(string|array $id, array $attributes) : 实体

  • 更新并返回具有给定属性的现有实体

• delete(string|array $id) : bool

  • 根据给定的id从集合中删除实体 - 成功/失败时返回true/false

• first($default = null) : 实体 | null | mixed

  • 返回集合的第一个索引或当$default为空时

• count() : int

  • 返回集合中实体的数量

• all() : array

  • 以数组形式获取集合中的所有实体
  • 这是一个在大型集合上执行的重方法调用 - 请谨慎使用！
  • 注意：如果实体集合未完全加载，则将获取剩余的实体！

• getEntitySet: 实体集

  • 获取集合的实体集

• query() : 构建器

  • 获取指向集合的查询（包括扩展）

• toArray() : array

  • 以数组形式获取集合（也将转换所有实体）

构建器

查询构建器用于在业务中心获取和更新实体

注意：可以在构建器实例上执行所有实体集合方法调用，
因为在方法调用之前，内部会调用$collection->fetch()。

构建器属性

无

构建器方法

构建器导航

• navigateTo(string $component, string $id = null) | to(string $component, string $id = null) : self

  • 将构建器指向一个组件

• fetch() : 实体集合

  • 获取指针处的所有实体

构建器元数据

• count() : int

  • 获取与构建器匹配的总数

• exists() : bool

  • 检查是否有任何内容与构建器匹配

构建器分页

• limit(int $limit = null) : self|int

  • 如果设置了$limit，则设置限制，否则返回当前限制

• page(int $page = null) : self|int

  • 如果设置了$page，则设置页面，否则返回当前页面

• nextPage() : self

  • 转到下一页

• prevPage() : self

  • 转到上一页

构建器排序

• orderBy($property, string $direction = 'asc') : self

  • 按指定的属性和方向对构建器进行排序
  • $field属性可以是一个包含多个条件（['property' => 'direction']）的数组

• orderByAsc(string $property) : self

  • 按指定的属性升序排序构建器

• orderByDesc(string $property) : self

  • 按指定的属性降序排序构建器

构建器扩展

OData参考： 参考

• expand(array $relations) : self
  • 扩展选择扩展允许我们在单个请求中获取多个级别的实体。
    这允许我们最小化获取所需实体所需请求的数量。

基本用法

示例

$company->customers()->expand([
    'paymentMethod',
    'picture',
])->fetch();

以上代码将使用一个请求获取包含公司所有客户及其paymentMethod关系的集合。

多级展开/过滤展开

利用闭包，可以在任何级别嵌套展开并应用过滤。

$company->customers()->expand([
    'paymentMethod' => function(Builder $query) {
    	$query->where('code', '=', 'CR3D17C4RD')
	      ->expand(['nested_relation']);
    },
    'picture',
]);

// Query: companies(...)/customers?$expand=picture,paymentMethod($filter=code eq 'CR3D17C4RD';$expand=nested_relation;$count=true)&$top=40&$count=true

见过滤

注意：嵌套可以无限进行，也可以非常复杂，但请注意URL仍然有字符限制。

构建器过滤

OData参考：参考

过滤使我们能够更仔细地选择从Business Central获取哪些实体。
这允许我们提高性能，并从一开始就排除无关模型。

存在多种不同的过滤方法。
对于每种过滤方法，都存在一个"OR"版本（例如：whereDate(...) -> orWhereDate(...)）
$before参数是在每个子句之前添加到查询前的布尔运算符。

• where(string $property, $operator = null, $value = null, string $before = 'and') : self

  • 基本where子句
  • 简写：where('displayName', 'John Doe');等同于where('displayName', '=', 'John Doe')

• whereIn(string $property, array $values, string $before = 'and') : self

  • 在值组中的where属性

• whereDateTime(string $property, $operator, DateTime $value = null, string $before = 'and') : self

  • where属性是日期时间（格式：Y-m-d\TH:i:s.v\Z）

• whereContains(string $property, $value, string $before = 'and') : self

  • where属性包含值 - 与SQL中的column like '%value%'相同

• whereStartsWith(string $property, $value, string $before = 'and') : self

  • where属性以值开头 - 与SQL中的column like 'value%'相同

• whereEndsWith(string $property, $value, string $before = 'and') : self

  • where属性以值结尾 - 与SQL中的column like '%value'相同

• whereGroup(Closure $callback, string $before = 'and') : self

  • 分组where子句 - 示例
    whereGroup(function(Builder $query) { $query->where('property', 'Foo')->orWhere('property', 'Bar'))
  • 此功能可以简写为where(function(Builder $query) { ... })

运算符

基本用法

构建器高级

• clone() : self

  • 克隆当前的Builder实例，包括扩展（过滤器、展开、排序等）

• cloneWithoutExtensions() : self

  • 克隆当前的Builder实例，不包括扩展（过滤器、展开、排序等）

扩展实体模型

SDK有一系列预先生成的模型，用于在用户使用SDK时包含并协助用户。
如果您想替换用作容器的类，可以做到这一点 - 唯一的要求是模型必须扩展\BusinessCentral\Entity。

示例

\BusinessCentral\ClassMap::extend('nativeInvoicingSalesCustomers', MyTotallyNewAwesomeCustomerModelReplacementOfAbsoluteDoom::class);

这覆盖了整个应用程序中所有类型为customer的实体的模型类。

调试

SDK记录所有对Business Central的请求，以进行调试和监控。

您可以从$sdk->request_log在任何时候获取SDK的所有日志条目，它返回一个请求日志对象的数组。

请求日志属性

贡献

此SDK不是一个成品。
输入、增加和更改非常受欢迎 - 分叉存储库，进行更改/添加/修复，并创建拉取请求。

需要什么？

模式覆盖

Business Central 上有很多实体具有只读字段，这些字段伪装成实际属性但实际上是虚拟的（例如，客户的 currencyCode 属性表示客户货币代码的值，无法在客户本身中更改）。

需要找到并标记这些属性。
查看 schema_overrides.json 并遵循标记属性为只读的语法。