README

这是一个方便的 Formstack REST API v2 的 PHP 封装。兼容 Laravel。

请记得星标并关注变化

安装

composer require seunmatt/fstackapi_php

Laravel

安装依赖后，在 config/app.php 中添加服务提供者。

   FormStack\Providers\FSServiceProvider::class,

运行 php artisan vendor:publish 以发布配置文件。配置文件是 formstack.php，并将位于 Laravel 配置文件夹中。在配置文件中设置您的 access_token 并继续。

使用方法

该包围绕 Formstack REST API（v2）构建，因此它以非常简单灵活的方式组织。它有不同类来模拟 Formstack API 的元素。

API 响应

每个 JSON API 响应都被解码为关联数组并返回给调用者。

配置

如果您在 Laravel 中使用此包，只需运行 php artisan vendor:publish 以发布配置文件 formstack.php。如往常一样，它将位于配置文件夹中。

在配置文件中，提供您的 access_token 值。
默认情况下，base_url 设置为 API v2 的。

如果您克隆了存储库或 在 Laravel 之外使用它，那么请在包的根目录中创建一个 formstack.php 文件，其内容如下：

<?php
namespace Config;

return [

    "access_token"=> "your-formstack-application-access-token",
    "base_url" => "https://www.formstack.com/api/v2/"

];

?>

最后，您可以将 access_token 放置在环境中以供使用。在这种情况下，将使用默认的 base_url。

ConfigHelper 类将首先从 env 读取配置，然后尝试 Laravel 配置助手，最后尝试包根目录中的配置文件。

FormStack 对象实例化

创建您想要与之工作的 Formstack 对象的实例，然后您可以在实例上调用方法

//using a no-arg constructor for instatiation
//assumes you have provided your access_token
//and base_url in the config file


$fsForm = new FSForm();

$fsField = new FSField();

$fsSubmision = new FSSubmission();

$fsFolder = new FSFolder();

如果您不想使用配置文件，可以在实例化 Formstack 对象时传递 $token 和 $baseUrl 参数

//initialization if no config file is provided

$token = "your-formstack-app-access-token";
$baseUrl = "https://www.formstack.com/api/v2/";

$fsForm = new FSForm($token, $baseUrl);

$fsField = new FSField($token, $baseUrl);

$fsSubmision = new FSSubmission($token, $baseUrl);

$fsFolder = new FSFolder($token, $baseUrl);

示例

处理表单

        
        $fsForm = new FSForm();
        
        //get all forms available to the authenticated account
        // API docs - https://developers.formstack.com/docs/form-get
        $allForms = $fsForm->all();
        
        //create a new form
        //see the docs for other params that can be sepcified in $body
        // API docs - https://developers.formstack.com/docs/form-post
        $body = ["name" => "Created by API"];
        $newForm = $fsForm->create($body);
              
        $formId = $newForm["id"];
        
        //Getting details for a single form
        // API Docs - https://developers.formstack.com/docs/form-id-get
        $detail = $fsForm->get($formId);

        //Updating the details of a form
        // API Docs - https://developers.formstack.com/docs/form-id-put
        $updatedForm = $fsForm->update($formId, ["name" => "Updated Form Name"]);
        
        //Deleting a form
        // API Docs - https://developers.formstack.com/docs/form-id-delete
        $response = $fsForm->delete($formId);

处理字段

        $fsField = new FSField();

        //Getting all fields for a form
        // API Docs - https://developers.formstack.com/docs/form-id-field-get
        $allFields = $fsField->all($formId);

        //Adding a new field to a form
        //API Doc - https://developers.formstack.com/docs/form-id-field-post
        $param = ["field_type" => "text", "label" => "Dev API Created Field"];
        $field = $fsField->newField($formId, $param);

        $fieldId = $field["id"];

        //Details of a field
        //API Doc - https://developers.formstack.com/docs/field-id-get
        $fieldDetail = $fsField->get($fieldId);

        //Updating the details of a field
        //API Doc - https://developers.formstack.com/docs/field-id-put
        $param = ["field_type" => "text", "label" => "Dev API Updated"];
        $updatedField = $fsField->update($fieldId, $param);

        //Deleting API Created field
        //API Doc - https://developers.formstack.com/docs/field-id-delete
        $response = $fsField->delete($fieldId);

处理提交

提交表单很简单，但可能有点棘手。首先获取您想要提交的表单的所有字段的 id。您可以使用上面显示的 FSField 对象来完成此操作，并将响应存储在您可以稍后引用的地方。

然后您可以继续构建数据数组，并按照以下示例提交表单。

    
        $fsSubmission = new FSSubmission();

        //Submitting to a Form
        //note that you must prefix the field id with "field_x"
        //where x is the id of the field.
        //API Doc - https://developers.formstack.com/docs/form-id-submission-post 
        
        $data = [
            "field_0123943" => "Demo Field Value",
        ];
        $response = $fsSubmission->newSubmission($formId, $data);

        //Counting all Submissions to a Form
        //API Doc - https://developers.formstack.com/docs/form-id-submission-get
        
        $allSubmissions = $fsSubmission->all($formId);
       
       
        //Getting Details of a Single Submission entry
        //e.g. $submissionId = $allSubmissions["submissions"][0]["id"];
        //API Doc - https://developers.formstack.com/docs/submission-id-get
         
        $fsSubmission->get($submissionId);

        //Updating a Submission
        //API Doc - https://developers.formstack.com/docs/submission-id-put
        $data = [
            "field_".$fieldId => "Demo Organization Updated",
        ];
        $updatedSubmission = $fsSubmission->update($submissionId, $data);

        //Deleting a Submission
        //API Doc - https://developers.formstack.com/docs/submission-id-delete
        $fsSubmission->delete($submissionId);

处理文件夹

    
            $fsFolder = new FSFolder();
    
            //All folders for the authenticated user
            //API Doc - https://developers.formstack.com/docs/folder-get
            $allFolders = $fsFolder->all();
    
            //create a new folder
            //API Doc - https://developers.formstack.com/docs/folder-post
            $newFolder = $fsFolder->newFolder("Dev Folder");
    
            //Details of a folder    
            //e.g. $folderId = $newFolder["id"];
            //API Doc - https://developers.formstack.com/docs/folder-id-get
            $folderDetails = $fsFolder->get($folderId);
    
            //Updating a folder details    
            //API Doc - https://developers.formstack.com/docs/folder-id-put
            $updatedFolder = $fsFolder->update($folderId, $newFolderName));
    
            //Deleting a folder
            //API Doc - https://developers.formstack.com/docs/folder-id-delete
            $delResponse = $fsFolder->delete($folderId);

异常

您可以将方法调用包裹在 try...catch 块中，以捕获

GuzzleHttp\Exception\RequestException
FSExceptions\FSException

所有 API 调用的异常都被 GuzzleHttp\Exception\RequestException 捕获

测试

PHPUnit 用于测试，测试文件位于 tests 目录中。如果您分支/克隆了存储库并想运行测试。

首先，确保您已设置了配置，如上所述，然后从包的根目录运行以下命令以运行测试。

拥有一个没有达到表单创建数量限制的账户的 access_token 将是一个好主意。

"./vendor/bin/phpunit"

未涵盖的 API 组件

部分提交
确认电子邮件
通知电子邮件
Webhooks

参考

Formstack API v2 文档： https://developers.formstack.com/docs/api-overview

贡献者

Seun Matt：在推特上 @SeunMatt2

贡献指南

关于贡献，请在此阅读

许可协议

MIT

seunmatt / fstackapi_php

维护者

详细信息