README

此软件包提供了一种简单的接口，将您的Laravel项目与MBurger CMS连接起来，帮助您轻松检索数据。

1.0 安装

此软件包可以通过Composer安装

composer require mumble/mburger

2.0 配置

您只需几个步骤就可以使用我们的PHP SDK。

2.1 发布ServiceProvider

首先，您需要发布Service Provider，包括您在config/mburger.php中找到的MBurger配置

php artisan vendor:publish --provider="Mumble\MBurger\MBurgerServiceProvider"

2.2 项目API密钥

将API密钥放在您的.env文件中，如下所示

MBURGER_API_KEY=1234567890ABCDEFGHI

或者，如果您需要SDK的多个实例，可以直接在构造函数中传递API密钥

$sdk = new MBurger('YOUR_API_KEY');

如果您还没有API密钥，请在项目设置页面生成一个。

3.0 如何使用

在当前版本的PHP SDK中，您可以在代码中实现一些方法，但它们非常强大，使您能够使用MBurger CMS做很多事情。

SDK将返回表示响应的数组。默认情况下，返回对象列表的方法限制为25个元素。下面将说明如何使用分页。

此SDK提供由以下部分组成的流畅语法

类实例
参数或修改器
所需函数

以下是所有参数/修改器和函数的列表，以及一些示例。

有关所有可用参数的完整列表，请参阅官方API文档 https://docs.mburger.cloud/api-docs-1。

3.1 实例化SDK

要实例化SDK，请使用

$sdk = new MBurger();

或使用紧凑版本（适用于链式调用）

$response = (new MBurger())->getProject();

3.2 函数

获取项目

$response = (new MBurger())->getProject();

获取区块列表

$response = (new MBurger())->getBlocks();

通过id获取特定区块

$response = (new MBurger())->getBlock($block_id);

获取部分列表

$response = (new MBurger())->getSections($block_id);

通过id或slug获取特定部分

$response = (new MBurger())->getSection($section_id_or_slug);

3.3 修改器

以下是一些有用的修改器（或中间方法），可用于自定义请求。

3.3.1 区域设置

要请求特定区域设置，请使用 locale(string $locale) 修改器。示例

$response = (new MBurger())->locale($locale)->getProject();

如果请求的区域设置不存在，将自动回退。如果您想在请求的区域设置不存在或为空时强制回退，请使用 forceLocaleFallback() 修改器

$response = (new MBurger())->forceLocaleFallback()->getBlock();

3.3.2 分页

要在返回列表项的函数中使用分页，请使用 skip(int $skip) 和 take(int $take) 修改器。示例

$response = (new MBurger())->skip(5)->take(50)->getSections(100);

默认值为0和25。响应将包含一个包含分页信息的元字段，例如总项数和实际索引。

3.3.3 包含

要在响应中包含关系，可使用一组方便的方法。例如，这可以用于在一次请求中获取所有所需的区域及其相关元素。

注意：并非所有方法都适用于所有函数。SDK将抛出 MBurgeInvalidRequestException 异常。有关更多信息，请检查我们的API参考。

注意：在一个请求中加载大量关系可能会对性能产生负面影响。

include(array $include)：通用方法，您可以通过传递所需关系的数组。
includeBlocks()：它将包含区块。仅适用于 getProject()。
includeSections()：它将包含部分。仅适用于 getBlocks() 和 getBlock()。
includeElements()：它将包含元素。仅在 getSections() 和 getSection() 上可用。
includeStructure()：它将包含块结构。仅在 getProject()、getBlocks() 和 getBlock() 上可用。
includeBeacons()：它将包含信标。仅在 getProject()、getSections() 和 getSection() 上可用。
includeContracts()：它将包含块。仅在 getProject() 上可用。

示例：获取块100的前15个部分及其相关元素

$response = (new MBurger())->take(15)->includeElements()->getSections(100);

3.3.4 排序

要应用特定顺序，可以使用此方法 sortBy(string $value, string $direction = 'asc')。第一个参数指定排序的值，第二个参数指定方向。示例

$response = (new MBurger())->sortBy('created_at', 'desc')->take(15)->getSections(100);

默认排序按 id 顺序升序。

注意：此方法仅在返回项目列表的函数上可用。

3.3.4 过滤

可用一组便利方法进行项目过滤。

注意：并非所有方法都适用于所有函数。SDK将抛出 MBurgeInvalidRequestException 异常。有关更多信息，请检查我们的API参考。

注意：这些方法仅在返回项目列表的函数上可用。

filterByIds(array $ids)：根据 id 数组进行过滤，匹配完全相同。仅在 getBlocks() 和 getSections() 上可用。
filterByRelation(int $block_id, int $section_id)：根据相关部分进行过滤。仅在 getSections() 上可用。
filterByValue(array $values, string $element_name = null)：根据值数组进行过滤。指定第二个参数 element_name，则仅在名称匹配的元素上执行过滤。仅在 getSections() 上可用。
filterByTitle(string $title)：根据标题进行过滤。仅在 getBlocks() 上可用。
filterByGeofence(float $latNE, float $latSW, float $lngNE, float $lngSW)：根据地理围栏矩形进行过滤。仅在 getSections() 上可用。

3.3.5 距离

如果您有包含地址类型元素（其中自动包含坐标）的部分，您可以通过提供坐标使用方法 istance(float $latitude, float $longitude) 来获取您的位置与 "部分"（如 POI）的距离。示例

$response = (new MBurger())->distance(22.231232, 16.325322)->getSections(100);

注意：此方法仅在 getSections() 函数上可用。

3.3.6 精简链接

通常通过 id 或 精简链接 来检索部分。MBurger 会尝试根据参数类型推断使用哪种方法：如果是数字，则使用 id；如果是字符串，则使用 精简链接。可以使用以下方法 forceSlug() 强制使用 精简链接。示例

$response = (new MBurger())->locale('en')->forceSlug()->getSection('321287');

注意：此方法仅在 getSection() 函数上可用。

3.4 错误

MBurger SDK 使用基于异常的错误系统，在发生错误时将抛出带有描述性信息的异常。

3.5 缓存

每个函数都包含一个 cache(int $cache_ttl = 0) 方法来自动缓存响应。TTL 以秒为单位。示例

$response = (new MBurger())->cache(300)->getSections(100);

3.6 转换器

有一些实用方法有助于将响应转换为更易于使用的格式。

要转换块，请使用 transformBlocks($blocks)。示例

$blocks = (new MBurger())->getBlocks();
$data = MBurger::transformBlocks($blocks);

4.0 支持 & 反馈

有关 MBurger、SDK 或任何类型反馈的支持，请随时通过 support.mburger.cloud 联系我们

5.0 许可证

MIT 许可证（MIT）。有关更多信息，请参阅许可证文件

mumble / mburger

维护者

详细信息