README

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

使用 Composer 安装

composer require hirokx/business-central-sdk

入门

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

构建模型

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

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

可以使用一个使用您的凭据获取通过您的 Web 服务公开的实体的 post-autoload-dump composer 脚本来生成此内容。

连接到 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: EntityType

  • 获取实体的 EntityType

• query() : Builder

  • 获取指向实体的查询

• toArray() : array

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

EntityCollection

从 Business Central 获取的实体的容器类

EntityCollection 属性

无

EntityCollection 方法

• 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() : Builder

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

• toArray() : array

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

构建器

查询构建器用于在Business Central上检索和更新实体

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

构建器属性

无

构建器方法

构建器导航

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

  • 将构建器指向一个组件

• fetch() : EntityCollection

  • 获取指针上的所有实体

构建器元数据

• count() : int

  • 获取与Builder匹配的总数

• 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

  • 按指定的属性和$direction对构建器进行排序
  • $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 获取哪些实体。
这允许我们提高性能并从一开始就排除不相关的模型。

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

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

• cloneWithoutExtentions() : self

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

扩展实体模型

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

示例

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

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

调试

SDK 记录了从您的应用程序到 Business Central 的所有请求，以进行调试和监控。

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

RequestLog 属性

贡献

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

需要什么？

模式覆盖

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

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