README

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

使用Composer安装

composer require coolrunner/business-central-sdk

入门指南

• 注册 Business Central凭据集
  • SDK使用基本身份验证
• 将库安装到您的应用程序中
• 加载SDK

构建模型

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

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

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

连接到Business Central

Business Central for PHP使用单例模式来处理SDK实例。

一旦初始化了一个实例，它将从您的Business Central中获取架构。（包括标准实体）。

$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'
]);

手动获取实体

Business Central for 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();

类参考

实体

用于从Business Central获取的实体的类

实体属性/关系

由于Business Central的动态性，来自Business Central的实体不一定在所有实现中具有标准化的属性。请参考您的特定实现。

或者查看构建模型时生成的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

  • 将实体保存到Business Central

• validate() : bool

  • 验证实体是否与Business Central设置的规则相符（此方法也称为save()时调用

• getEntityType: 实体类型

  • 获取实体的实体类型

• query() : 构建器

  • 获取指向实体的查询

• toArray() : array

  • 获取实体作为关联数组

实体集合

用于存储从Business Central获取的实体的容器类

实体集合属性

无

实体集合方法

• 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

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

• getEntitySet: 实体集

  • 获取集合的实体集

• query() : 构建器

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

• toArray() : array

  • 以数组的形式获取集合（也转换了其中的所有实体）

构建器

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

注意：所有EntityCollection方法调用都可以在Builder实例本身上执行，
因为在方法调用之前有一个对$collection->fetch()的内部调用。

构建器属性

无

构建器方法

构建器导航

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

  • 将Builder指向一个组件

• fetch() : 实体集合

  • 获取指针处的所有实体

构建器元数据

• count() : int

  • 获取与Builder匹配的总数

• exists() : bool

  • 检查是否有任何内容与Builder匹配

构建器分页

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

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

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

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

• nextPage() : self

  • 翻到下一页

• prevPage() : self

  • 翻到前一页

构建器排序

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

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

• orderByAsc(string $property) : self

  • 按指定的属性升序排序Builder

• orderByDesc(string $property) : self

  • 按指定的属性降序排序Builder

构建器扩展

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参考： 参考

过滤器使我们能够更仔细地选择从商业中心获取的实体。
这使我们能够提高性能，并从一开始就排除不相关的模型。

存在多种不同的过滤方法。
对于每种过滤方法，都存在一个“或”版本（例如：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属性是datetime（格式：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

  • 克隆当前构建器实例并扩展（过滤器、扩展、排序等）

• cloneWithoutExtensions() : self

  • 克隆当前构建器实例而不扩展（过滤器、扩展、排序等）

扩展实体模型

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

示例

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

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

调试

SDK记录了所有来自和发往商业中心的应用程序请求，用于调试和监控目的。

您可以从 $sdk->request_log 获取SDK的所有日志条目，它返回一个RequestLog对象的数组。

RequestLog属性

贡献

此SDK不是最终产品。
鼓励输入、添加和更改 - 分支到仓库，进行更改/添加/修复，并创建pull请求。

需要什么？

模式覆盖

商业中心中的许多实体都具有只读字段，这些字段被伪装成实际属性，但实际上是虚拟的（例如，客户上的currencyCode是客户的货币代码属性的值，不能在客户本身上更改）。

需要找到并标记这些属性。
请查看schema_overrides.json文件，并按照语法规则标记属性为只读。