README

Field Nation PHP SDK

• 构建状态
• 安装
  • PHP支持
  • PHP要求
  • 使用Composer安装
• 使用方法
  • 身份验证
  • 环境
  • 创建工作订单
  • 工作订单操作和元数据
    • 发布
    • 路由到供应商
    • 路由到组
    • 批准
    • 取消
    • 附加文档
    • 分离文档
    • 添加消息
    • 添加自定义字段
    • 添加标签
    • 删除标签
    • 解决结算要求
    • 添加运输
    • 删除运输
    • 更新时间表
    • 获取整个工作订单
    • 获取状态
    • 获取分配的供应商
    • 获取进度
    • 获取付款
    • 获取消息
    • 获取附加文档
    • 获取运输
  • 获取您的工作订单
  • 获取您的项目
  • 获取您的文档
  • 将跟踪号转换为运输ID
  • 使用您的类
• 贡献
  • 测试
  • 编码标准
• 变更日志
• 许可

构建状态

安装

PHP支持

• PHP 5.6+
• PHP 7+
• HHVM

PHP要求

您的php运行时需要启用 Soap。请遵循 安装说明 启用Soap模块。

使用Composer安装

在您的项目中需要 fieldnation/fieldnation-sdk 包。

$ composer require fieldnation/fieldnation-sdk

使用方法

成功集成Field Nation的关键概念是描述您的业务对象如何成为Field Nation对象。我们提供了接口来描述您的数据如何在Field Nation上创建。

身份验证

要使用SDK，您需要为您公司生成一个API密钥。您可以在 https://app.fieldnation.com/api 创建API密钥。一旦您有了密钥，就可以创建连接。

<?php
$fnCompanyId = $_ENV['FIELD_NATION_COMPANY_ID'];
$fnApiKey = $_ENV['FIELD_NATION_API_KEY'];
$fnEffectiveUser = $_ENV['FIELD_NATION_EFFECTIVE_USER']; // optional - First admin user will be used if not provided.
$credentials = new \FieldNation\LoginCredentials($fnCompanyId, $fnApiKey, $fnEffectiveUser);
$fn = new \FieldNation\SDK($credentials);

环境

SDK的默认环境设置为生产环境。如果您想使用其他环境进行测试，您可以在凭证对象上设置值来实现。

<?php
$fnCompanyId = $_ENV['FIELD_NATION_COMPANY_ID'];
$fnApiKey = $_ENV['FIELD_NATION_API_KEY'];
$credentials = new \FieldNation\LoginCredentials($fnCompanyId, $fnApiKey, $fnEffectiveUser);
$credentials->setEnvironment("https://stable.fieldnation.com");
$fn = new \FieldNation\SDK($credentials);

创建工作订单

首先，让我们创建一个简单的例子，看看 您的 数据模型 可能 看起来像什么。

<?php

class MyBusinessTicket
{
    private $id;
    private $title;
    private $description;
    private $startDateTime;
    
    // ... setters and getters for the properties
}

现在我们已经在我们的 MyBusinessTicket 中实现了业务逻辑，我们如何开始在Field Nation上创建工作订单呢？很简单——我们将 MyBusinessTicket 更新为实现 FieldNation\WorkOrderSerializerInterface（或者更好，创建一个新类 MyFieldNationBusinessTicket，它扩展 MyBusinessTicket 并实现 FieldNation\WorkOrderSerializerInterface）。

<?php

use FieldNation\WorkOrderSerializerInterface;

class MyBusinessTicket implements WorkOrderSerializerInterface
{
    private $id;
    private $title;
    private $description;
    private $startDateTime;
    private $fieldNationId;
    
    // ... setters and getters for the properties
    
    // WorkOrderSerializerInterface methods
    
    /**
     * Get the name of the project the work order should be a member of.
     *
     * If not present, the work order will not belong to a project (default behavior).
     * If the project does not already exist, it will be created automatically and your effectiveUser
     * (See Login structure) will be the default manager for all newly-created projects.
     *
     * @return string
     */
    public function getGroup()
    {
        return NULL;
    }
    
    /**
     * Get the general descriptive information relevant to the job.
     *
     * @return FieldNation\ServiceDescriptionInterface
     */
    public function getDescription()
    {
        $description = new \FieldNation\ServiceDescription();
        $description->setCategoryId(1); // See docs for category IDs
        $description->setTitle($this->title);
        $description->setDescription($this->description);
        return $description;
    }
    
    /**
     * Get where the job site is located.
     *
     * @return FieldNation\ServiceLocationInterface
     */
    public function getLocation()
    {
        // My business only has one service location
        $locationType = \FieldNation\LocationTypes::COMMERCIAL;
        $location = new \FieldNation\ServiceLocation();
        $location->setType($locationType);
        $location->setName('Foo Co');
        $location->setAddress1('123 Main Street');
        $location->setCity('Minneapolis');
        $location->setState('MN');
        $location->setPostalCode('55402');
        $location->setCountry('US');
        $location->setContactName('Bob');
        $location->setContactEmail('bob@mybusiness.com');
        $location->setContactPhone('612-555-3485');
        return $location;
    }
    
    /**
     * Get scheduling information for the Work Order, including any applicable end time.
     *
     * @return FieldNation\TimeRangeInterface
     */
    public function getStartTime()
    {
        $time = new \FieldNation\TimeRange();
        $time->setTimeBegin($this->startDateTime);
        return $time;
    }
    
    /**
     * Get payment details to be advertised on the Work Order.
     * @return FieldNation\PayInfoInterface
     */
    public function getPayInfo()
    {
        // All of our tickets are a flat $20 rate with a 5 hour max
        $info = new \FieldNation\PayInfo();
        $rate = new \FieldNation\RatePay();
        $rate->setRate(20.0);
        $rate->setMaxUnits(5.0);
        $info->setPerHour($rate);
        return $info;
    }
    
    /**
     * Get whether to allow the technician to upload files to the Work Order.
     * If enabled, this Work Order will inherit required items from the project
     * it belongs to or settings your company has configured for all Work Orders.
     *
     * @return boolean
     */
    public function getAllowTechUploads()
    {
        // We always allow
        return true;
    }
    
    /**
     * Get whether to email any providers about the Work Order.
     * Typical usage is true and should only be disabled in certain circumstances.
     *
     * @return boolean
     */
    public function getWillAlertWhenPublished()
    {
        // Always alert providers
        return true;
    }

    /**
     * Get whether to grant technician access to a print-friendly version of work order details.
     * It is strongly recommended this is set to true. This should only be set false
     * if you will be attaching a printable version as a document.
     *
     * @return boolean
     */
    public function getIsPrintable()
    {
        // Always allow to print
        return true;
    }
    
    /**
     * Get additional fields (custom fields) and values provided by your company for the Work Order.
     *
     * @return FieldNation\AdditionalFieldInterface[]
     */
    public function getAdditionalFields()
    {
        // Add my 'TicketId' custom field to all work orders
        $ticketId = new \FieldNation\AdditionalField();
        $ticketId->setName('Ticket ID');
        $ticketId->setValue($this->id);
        
        return array($ticketId);
    }
    
    /**
     * Get labels that are set on the work order.
     *
     * @return string[]
     */
    public function getLabels()
    {
        return array();
    }
    
    /**
     * Get a list of requirements to be met before the Work Order is able to be marked Work Done.
     * Currently only configured and satisfied via the API. Should be NULL if not configured.
     *
     * @return array|NULL
     */
    public function getCloseoutRequirements()
    {
        return NULL;
    }
}

让我们花点时间来分析我们添加了什么。

这些方法是 WorkOrderSerializerInterface 的要求。该接口描述了您的数据如何转换为Field Nation数据，并且是SDK创建工作订单的要求。每个方法都有文档说明它做什么，以及返回类型应该是什么。有关类型的更多信息，请参阅接口部分。

有多种方法需要您将数据映射到SDK提供的类型。以getPayInfo为例。Field Nation要求使用特定模式描述工作订单的支付信息。因为我们不知道您如何支付技术人员，所以我们提供了一个接口PayInfoInterface，用于将您的支付结构转换为我们可以理解的支付结构。PayInfoInterface充当潜在支付类型（FixedPayInterface、RatePayInterface和BlendedPayInterface）的容器。这些支付接口中的每一个也都有SDK提供的具体类（FixedPay、RatePay、BlendedPay）。您可以使用我们已实现的类将您的支付结构转换为Field Nation支付结构，或者您可以创建自己的具体类，这些类实现了提供的接口。

现在我们了解了我们的业务对象如何转换为Field Nation业务对象，我们可以创建一个工作订单。

<?php
$fnCompanyId = $_ENV['FIELD_NATION_COMPANY_ID'];
$fnApiKey = $_ENV['FIELD_NATION_API_KEY'];
$fnEffectiveUser = $_ENV['FIELD_NATION_EFFECTIVE_USER'];
$credentials = new \FieldNation\LoginCredentials($fnCompanyId, $fnApiKey, $fnEffectiveUser);
$fn = new \FieldNation\SDK($credentials);

$myTicket = new MyBusinessTicket();
$myTicket->setId(uniqid());
$myTicket->setTitle('Fix something at this place');
$myTicket->setDescription('Something went wrong. Fix it.');
$myTicket->setStartDateTime(new \DateTime());

// Returns a \FieldNation\WorkOrderInterface object
$fnWorkOrder = $fn->createWorkOrder($myTicket);
$myTicket->setFieldNationId($fnWorkOrder->getId());

工作订单操作和元数据

更新工作订单与创建工作订单类似，但您可以在工作订单实例上执行更精细的操作。

获取Field Nation工作订单对象有2种方式。

1. 如果您通过SDK的createWorkOrder方法刚刚创建了一个
2. 如果您调用了SDK的getExistingWorkOrder方法。

<?php

// Just created a work order
$fnCompanyId = $_ENV['FIELD_NATION_COMPANY_ID'];
$fnApiKey = $_ENV['FIELD_NATION_API_KEY'];
$fnEffectiveUser = $_ENV['FIELD_NATION_EFFECTIVE_USER'];
$credentials = new \FieldNation\LoginCredentials($fnCompanyId, $fnApiKey, $fnEffectiveUser);
$fn = new \FieldNation\SDK($credentials);

$myTicket = new MyBusinessTicket();
$myTicket->setId(uniqid());
$myTicket->setTitle('Fix something at this place');
$myTicket->setDescription('Something went wrong. Fix it.');
$myTicket->setStartDateTime(new \DateTime());

// Returns a \FieldNation\WorkOrderInterface object
$fnWorkOrder = $fn->createWorkOrder($myTicket);
$myTicket->setFieldNationId($fnWorkOrder->getId());

// Fetching a work order after it was created
$ticket = $db->getTicket(1234); // pseudo code for fetching your ticket
$fnWorkOrder = $fn->getExistingWorkOrder($ticket->fnId);

现在您有了Field Nation工作订单实例，您可以执行操作或获取其元数据。

发布

在Field Nation上发布您的工单

/**
 * @returns ResultInterface
 */
$result = $fnWorkOrder->publish();

路由到供应商

将您的工单路由到提供商。在创建提供商对象时，您需要设置提供商ID，以便正确路由。

/**
 * Create a provider object to route to
 */
$provider = new \FieldNation\Technician();
$provider->setId('1');

/**
 * @returns ResultInterface
 */
$result = $fnWorkOrder->routeTo($provider);

路由到组

将您的工单路由到组。在创建组对象时，您需要设置组ID，以便正确路由。

/**
 * Create a group to route to
 */
$group = new \FieldNation\Group();
$group->setId('100');

/**
 * @returns ResultInterface
 */
$result = $fnWorkOrder->routeTo($group);

批准

批准您的工单。

/**
 * @returns ResultInterface
 */
$result = $fnWorkOrder->approve();

取消

有时您需要取消工单并重新开始。

/**
 * @returns ResultInterface
 */
$result = $fnWorkOrder->cancel();

附加文档

将文档附加到您的工单上。

/**
 * Create your document.
 */
 $document = new \FieldNation\Document();
 $document->setTitle('Instructions');
 $document->setType('application/pdf');
 $document->setUpdateTime(new \DateTime('now', new \DateTimeZone('UTC')));

/**
 * @returns ResultInterface
 */
$result = $fnWorkOrder->attach($document);

分离文档

从您的工单中删除文档。

/**
 * Create the document object
 */
$document = new \FieldNation\Document();
$document->setTitle('Instructions');

/**
 * @returns ResultInterface
 */
$result = $fnWorkOrder->detach($document);

添加自定义字段

您的工单属于您。通过添加自定义字段使其成为您的。

/**
 * One of your custom fields
 */
$field = new \FieldNation\CustomField();
$field->setName('My Business Ticket ID');

/**
 * @returns ResultInterface
 */
$result = $fnWorkOrder->addAdditionalField($field);

添加标签

给您的工单添加标签。

/**
 * Create a label
 */
$label = new \FieldNation\Label();
$label->setName('New Work');
$label->setHideFromTech(true);

/**
 * @returns ResultInterface
 */
$result = $fnWorkOrder->addLabel($label);

删除标签

从您的工单中删除标签。

/**
 * Create a label
 */
$label = new \FieldNation\Label();
$label->setName('New Work');

/**
 * @returns ResultInterface
 */
$result = $fnWorkOrder->removeLabel($label);

解决结算要求

将结算要求标记为已解决。

/**
 * Closeout Requirement
 */
$requirement = new \FieldNation\CloseoutRequirement();
$requirement->setName('Provider upload picture');

/**
 * @returns ResultInterface
 */
$result = $fnWorkOrder->resolveCloseoutRequirement($requirement);

添加运输

为Field Nation跟踪添加一个运输单。

/**
 * Shipment
 */
$shipment = new \FieldNation\Shipment();
$shipment->setVendor('USPS');
$shipment->setTrackingId('my-tracking-number');

/**
 * @returns ResultInterface
 */
$result = $fnWorkOrder->addShipment($shipment);

删除运输

如果不再需要跟踪运输单，请从您的工单中删除它。

// If you don't have the Field Nation shipment id, you can get it with your tracking number
$result = $fn->getShippingIdFrom('my-tracking-number');
$shipment = new \FieldNation\Shipment();
$shipment->setId($result->getShipmentId());

/**
 * @returns ResultInterface
 */
$result = $fnWorkOrder->deleteShipment($shipment);

更新时间表

事情会变化——更新您工作订单的日程安排。

/**
 * Create a TimRange object
 */
$schedule = new TimeRange();
$schedule->setTimeBegin(new \DateTime('now'));
$schedule->setTimeEnd(new \DateTime('now'));

/**
 * @returns ResultInterface
 */
$result = $fnWorkOrder->updateSchedule($schedule);

获取整个工作订单

偶尔需要获取整个工作订单。以下是方法！

如果您需要特定内容，应直接调用该getter。这个操作代价高昂，因此只有在真正需要时才使用它。

/**
 * @returns WorkOrderInterface
 */
$fnWorkOrder = $fnWorkOrder->get(); // get all metadata and reassign the existing variable

获取状态

获取您工作订单的状态

/**
 * @returns string from \FieldNation\WorkOrderStatuses
 */
$status = $fnWorkOrder->getStatus();

获取分配的供应商

获取分配给您的工单的提供商信息。

/**
 * @returns \FieldNation\TechnicianInterface
 */
$provider = $fnWorkOrder->getAssignedProvider();

获取进度

获取您工作订单的进度。

/**
 * @returns \FieldNation\ProgressInterface
 */
$progress = $fnWorkOrder->getProgress();

获取付款

获取您工作订单的支付信息。

/**
 * @returns \FieldNation\PaymentInterface
 */
$payment = $fnWorkOrder->getPayment();

获取消息

获取您工作订单上的消息。

/**
 * @returns \FieldNation\MessageInterface[]
 */
$messages = $fnWorkOrder->getMessages();

获取附加文档

获取您工作订单上附加的文档。

/**
 * @returns from \FieldNation\Document[]
 */
$documents = $fnWorkOrder->getAttachedDocuments();

获取运输

获取您工作订单的跟踪运输单。

/**
 * @returns \FieldNation\Shipment[]
 */
$shipments = $fnWorkOrder->getShipments();

获取您的工作订单

有时您需要获取所有的工作订单。以下是方法！

/**
 * Optionally you can filter your query by the status of the work order.
 * If the status is NULL we'll return all work orders.
 * You can get statuses from the \FieldNation\WorkOrderStatuses class
 */
$status = \FieldNation\WorkOrderStatuses::PUBLISHED

/**
 * @returns \FieldNation\WorkOrderInterface[]
 */
$workOrders = $fn->getWorkOrders($status);

获取您的项目

使用它来获取您公司所有的项目。

/**
 * @returns \FieldNation\ProjectInterface[]
 */
$projects = $fn->getProjects();

获取您的文档

获取您公司所有的文档。

/**
 * @returns \FieldNation\DocumentInterface[]
 */
$documents = $fn->getDocuments();

将跟踪号转换为运输ID

如果您有一个您创建的但未保存Field Nation运输ID的运输跟踪号，您可以在这里获取它。

/**
 * @returns string
 */
$shippingId = $fn->getShippingIdFrom('my-tracking-number');

使用您的类

您可能想知道您是否必须使用我们的PHP类。好消息是您不必！我们使用纯PHP对象实现我们所有的接口，作为一组默认设置，但如果您的类实现了我们的接口，您可以配置SDK使用您的类。我们唯一的严格规则是您的类必须实现您要注入的类型接口。如果您的类没有实现接口，我们将会抛出一个TypeError。

示例：将我们的WorkOrder替换为您的实现WorkOrderInterface的类。

use \FieldNation\SDK;
use \FieldNation\ClassMapFactoryInterface;

SDK::configure(function (ClassMapFactoryInterface $classMap) {
    $classMap->setWorkOrder(\MyBusinessNamespace\MyClass::class);
});

以下是需要注入的所有类的列表。

// Default configuration
SDK::configure(function (ClassMapFactoryInterface $classMap) {
    $classMap->setAdditionalExpense(\FieldNation\AdditionalExpense::class);
    $classMap->setAdditionalField(\FieldNation\AdditionalField::class);
    $classMap->setBlendedPay(\FieldNation\BlendedPay::class);
    $classMap->setCheckInOut(\FieldNation\CheckInOut::class);
    $classMap->setCloseoutRequirement(\FieldNation\CloseoutRequirement::class);
    $classMap->setCustomField(\FieldNation\CustomField::class);
    $classMap->setDocument(\FieldNation\Document::class);
    $classMap->setFixedPay(\FieldNation\FixedPay::class);
    $classMap->setGroup(\FieldNation\Group::class);
    $classMap->setHistory(\FieldNation\History::class);
    $classMap->setLabel(\FieldNation\Label::class);
    $classMap->setMessage(\FieldNation\Message::class);
    $classMap->setPayInfo(\FieldNation\PayInfo::class);
    $classMap->setPaymentDeduction(\FieldNation\PaymentDeduction::class);
    $classMap->setPayment(\FieldNation\Payment::class);
    $classMap->setProblem(\FieldNation\Problem::class);
    $classMap->setProgress(\FieldNation\Progress::class);
    $classMap->setProject(\FieldNation\Project::class);
    $classMap->setRatePay(\FieldNation\RatePay::class);
    $classMap->setServiceDescription(\FieldNation\ServiceDescription::class);
    $classMap->setServiceLocation(\FieldNation\ServiceLocation::class);
    $classMap->setShipmentHistory(\FieldNation\ShipmentHistory::class);
    $classMap->setShipment(\FieldNation\Shipment::class);
    $classMap->setTechnician(\FieldNation\Technician::class);
    $classMap->setTemplate(\FieldNation\Template::class);
    $classMap->setTimeRange(\FieldNation\TimeRange::class);
    $classMap->setWorkLog(\FieldNation\WorkLog::class);
    $classMap->setWorkOrder(\FieldNation\WorkOrder::class);
});

贡献

测试

所有合并请求都需要通过测试。如果测试未通过，或者没有为更改添加新测试，则合并请求将不会获得批准。

$ composer test

编码标准

我们遵循PSR-2编码风格。我们将检查代码，如果合并请求未通过检查，则不会获得批准。您可以使用PHP_CodeSniffer进行检查。

$ composer lint:check

如果您有检查错误或警告，可以尝试使用composer lint:fix自动清理它们。如果错误/警告无法自行解决，您将需要手动修复它们。composer lint:check应始终以0退出。

变更日志

请参阅CHANGELOG或查看发行版。

许可

版权所有 © 2017 Field Nation

根据Apache许可证版本2.0（“许可证”）许可；除非您遵守许可证，否则不得使用此文件。您可以在以下位置获得许可证副本：

https://apache.ac.cn/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则在许可证下分发的软件按“原样”基础分发，不提供任何明示或暗示的保证或条件。请参阅许可证，了解管理许可证权限和限制的特定语言。