README

Trucker 是一个 PHP 包，用于将远程 API 资源（通常是 RESTful）映射为 ActiveResource 风格的模型。其优势在于在快速且干净的编程接口中更易于使用远程 API。

<?php

class Product extends Trucker\Resource\Model {} //create a class to use

$p = new Product(['name' => 'My Test Product']);
$success = $p->save(); //create a new entity

$found = Product::find(1); //find an existing entity

$found->name = 'New Product Name';
$success = $found->save(); //update an entity

$success = $found->destroy(); //destroy an entity

$results = Product::all(); //find a collection

README 内容

• 安装
  • 要求
  • 使用 Composer 安装
    • 在 Laravel 中配置
    • 在 Laravel 外部配置
• 配置选项
  • 身份验证
  • 错误处理器
  • 查询条件
  • 请求
  • 资源
  • 响应
  • 结果排序
  • 传输
• 创建实体
• 与实体一起工作
  • 获取记录
    • 获取实例
    • 获取集合
      • 使用查询条件和结果排序获取集合
  • 创建、更新 & 删除操作
    • 创建
    • 更新
    • 删除
• 定制实体
  • 设置具体类属性
  • 设置运行时属性
  • 在运行时设置配置值

• 任何 PHP 7.0+ 版本都适用

您可以通过 Composer 安装库

composer require alexmanno/trucker

有关 Laravel 5 支持的信息，请参阅 laravel-5 分支

现在您需要发布配置文件。

Trucker 的配置文件是您定义与您交互的 API 的常量事项的地方，例如端点、您想要使用的驱动程序等。

Trucker 与 Laravel 框架配合良好。如果您在 Laravel 中使用 Trucker，只需运行以下命令将 Trucker 配置文件发布到 app/config/packages/alexmanno/trucker 文件夹。

php artisan config:publish alexmanno/trucker

最后一步是添加服务提供者。打开 app/config/app.php，并在提供者数组中添加一个新条目。

'Trucker\TruckerServiceProvider'

现在您应该可以开始了。

如果您在 Laravel 外部使用 Trucker，只需在项目根目录中创建 .trucker 文件夹，并将包的配置文件复制到那里。以下是 *nix 命令。

mkdir .trucker && cp vendor/alexmanno/trucker/src/config/* .trucker/

Trucker自带配置文件，您可以在其中指定对您配置恒定的选项。

支持选项详细信息

支持选项详细信息

在请求集合时，您可以指定类似于SQL WHERE子句的条件。这些条件将以数组参数的形式随请求发送，其中包含定义条件集合的键/值组合。

支持选项详细信息

生成的GET参数可能看起来像这样

search[0][property]=someProperty
search[0][operator]=<
search[0][value]=1234
search[1][property]=anotherProperty
search[1][operator]=LIKE
search[1][value]=someString
logical_operator=AND

支持选项详细信息

可以使用通配符来匹配一个http代码的起始部分（例如 - 20*）。

支持选项详细信息

支持选项详细信息

现在您可以为API中的名词创建一个实体对象（这是您开始所需的最低代码）

<?php
class Product extends Trucker\Resource\Model
{

}

Trucker采用约定优于配置，因此它将根据您的类名推断URI。在“产品”的示例中，URI将被假定是/products。

现在您有了Trucker对象，您可以像使用ORM一样使用CRUD操作。

Trucker将API中的记录检索分为两类。获取实例和获取集合。

如果您有一个实体，并且知道它的identity_property的值，您可以使用find()方法检索它。

$p = Product::find(1);

可选第二个参数： find() 还可以接受第二个参数，允许您传递一个任意关联数组，该数组将被转换为查询字符串参数并发送与请求一起。

可选第三个参数： find() 还可以接受第三个参数，允许您传递一个对象，该对象是您正在查找的类，其中包含在运行时设置的属性。如果提供了该对象，则 find() 函数将使用该对象来解释 URL，否则它将在 find() 被调用的类上调用 new static;。

当您想获取记录的集合时，可以使用 all() 函数。

$results = Product::all();

all() 函数接受参数，允许您指定返回结果的条件。对 API 的请求方式取决于您使用的 collection_query_condition_driver 和 collection_result_order_driver。

$conditions = ConditionFactory::build();
$conditions->addCondition('name', '=', 'Roomba 650');
$conditions->addCondition('vendor', '=', 'Irobot');
$conditions->addCondition('price', '>=', 10000);
$conditions->setLogicalOperator($conditions->getLogicalOperatorAnd());

$order = ResultOrderFactory::build();
$order->setOrderByField('name');
$order->setOrderDirection($order->getOrderDirectionDescending());

$results = Product::all($conditions, $order);

注意： 您还可以向 all() 函数提供一个包含要作为查询字符串参数包含的值的关联数组的第三个数组参数。

$attributes = ['name' => 'XYZ Headphones', 'vendor' => 'Acme', 'price' => '10000'];

//pass attributes to the constructor
$p = new Product($attributes);

//or use the fill() method
$p = new Product;
$p->fill($attributes);

//get the attributes back if you want to see them
print_r($p->attributes());
// => ['name' => 'XYZ Headphones', 'vendor' => 'Acme', 'price' => '10000']

//maybe you want to see a particular property
echo $p->name; // => XYZ Headphones

//or modify a property
$p->name = "ABC Headphones";

//save the object over the API.  The save() method will create or update 
//the object as necessary.  It returns true or false based on success.
$success = $p->save(); 

if ($success) {

  //the identity property is set back on the object after it is created
  echo "Saved product '{$p->name}' with ID: ". $p->getId();

} else {

  //maybe you want to print out the errors if there were some
  echo "Errors: ". implode(", ", $p->errors());
  // => ['Category is required', 'Cost must be greater than 0']
}

更新功能与创建功能非常相似，从代码角度来看，它们几乎相同。

$p = Product::find(1);
$p->name = "My Product";

if ($p->save()) {
   echo "Updated!";
} else {
   echo "Error: ". implode(", ", $p->errors());
}

销毁函数需要一个现有实例，并基于请求的成功与否返回一个布尔值。

$p = Product::find(1);

if ($p->destroy()){
  echo "Deleted product: {$p->name}";
} else {
  echo "Error deleting product: {$p->name}";
  echo "Errors: ". implode(", ", $p->errors());
}

Trucker 为其默认配置使用合理的默认值，但允许您通过配置设置进行自定义。此外，您可以通过覆盖具体实现上的属性来覆盖单个类的配置设置；通过在类或配置中设置运行时值。

以下字段可以在类实现上设置，以覆盖解释值、默认值或仅定义类功能。

示例

<?php
class Product extends Trucker\Resource\Model
{
  protected $uri = "/small_electronic_products";
  protected $guarded = "price,sale_price";
  protected $fileFields = "picture";
}

可能存在这样的情况，即由于属性值在运行时是可变的，您无法在具体类实现中设置该属性。对于这种情况，您可以在使用请求中使用该属性之前设置该属性。

示例

<?php
$vendor_id = 9876;
$p = new Product;
$p->nestedUnder = "Vendor:{$vendor_id}";
$found = Product::find(1, [], $p);
//will hit /vendors/9876/products/1

在发出使用这些值的请求之前，您可能需要在运行时更改在Trucker配置文件中设置的值。您可以使用Trucker的配置管理器来完成此操作。

注意：如果您在使用Laravel的Trucker，您可能希望将Trucker配置管理器Config别名改为TruckerConfig，以避免与Laravel自己的Config类冲突。

示例

<?php
use Trucker\Facades\Config as TruckerConfig;

TruckerConfig::set('auth.basic.username', $someUsername);
TruckerConfig::set('auth.basic.password', $somePassword);
$found = Product::find(1);