danieldstieber/coda-php

CodaPHP 是一个库，它使得在 Web 项目中使用 Coda API 变得更加容易。

维护者

详细信息

github.com/danielstieber/CodaPHP

源代码

问题

安装: 475

依赖者: 3

建议者: 0

安全: 0

星级: 28

关注者: 4

分支: 4

公开问题: 0

0.4.0 2022-08-27 11:33 UTC

Requires

MIT e0db303abec41b526dca740b0a6c4f43d01f2134

apilibrarycoda

This package is auto-updated.

Last update: 2024-09-27 15:45:59 UTC

README

Latest Stable Coda API Version Downloads

CodaPHP 是一个库，通过使用 Coda API，使得在 Web 项目中轻松使用 Coda 文档中的数据。

轻松使用一个库中所有可用的 API 调用，包括

  • 列出所有文档
  • 从表格、公式和控制中读取数据
  • 添加/修改行
  • 管理文档权限
  • 等等

→ 通过此链接注册可获得 Coda 付费计划的 10 美元折扣

快速入门

安装和基本使用

通过 Composer 安装库

php composer.phar require danielstieber/coda-php

并将其添加到您的项目中

require './vendor/autoload.php';
$coda = new CodaPHP\CodaPHP('<YOUR API TOKEN>');

// List all your docs
$result = $coda->listDocs();
var_dump($result);

处理表格数据

假设您在 Coda 文档中有一个名为 'Products' 的表格

产品

// Get the price of the goatmilk
$docId = $coda->getDocId('<YOUR DOC URL>');

// Lists only Products with status 'available' (currently only one filter allowed)
$availableProducts = $coda->listRows($docId, 'Products', ['query' => ['status' => 'available']]);

// Show value of one cell
$result = $coda->getRow($docId, 'Products', 'Goatmilk');
var_dump($result['values']['Price']);
// Will show you 'float(14.90)'

// Add the new product 'Goatcheese'
if($coda->insertRows($docId, 'Products', ['Title' => 'Goatcheese', 'Price' => 23.50, 'Status' => 'available'])) {
  echo 'Product added';
}

// Change the status of the product 'Goatmilk' to 'sold out'
if($coda->insertRows($docId, 'Products', ['Title' => 'Goatmilk', 'Status' => 'sold out'], ['Title'])) {
  echo 'Product updated';
}

触发自动化

自 2022 年 5 月起，Coda 自动化可以通过 webhook 触发 - 以及通过 CodaPHP。要触发自动化，必须将自动化设置为 "Webhook 触发"。要运行自动化，您需要文档 ID 和自动化规则 ID。您可以在点击规则步骤设置上方的三个点（kebap 菜单）时找到规则 ID。

// Trigger the automation
$result = $coda->runAutomation('<YOUR DOC ID>', '<THE RULE ID>');

概述

这是一个个人副项目。如果您有任何建议、发现错误或想要贡献，请随时联系我。您可以使用 官方 Coda 社区 来提问和联系。

令牌

在 Coda 个人资料设置中生成您的令牌。注意：拥有此令牌的任何人都可以完全访问您所有的文档！

方法

方法名称灵感来源于 官方 Coda API 文档 中的措辞，以下列出。

参数

所有参数都可以在 官方 Coda API 文档 中找到。只需将包含您参数的关联数组添加到选定的函数中。在所有 'row' 函数中，参数 useColumnNames 默认设置为 true。以下列出了一些重要的参数。

响应

在成功的情况下，响应基本上未作修改，但已转换为 PHP 数组。例外的是 insertRow() 函数，它在成功时返回布尔值 true。在出错的情况下，响应包括 statusCode 和提供的错误消息，这些也被原样保留并转换为数组。

缓存数据

每个 API 调用可能需要几秒钟。建议存储结果，并在必要时才调用新数据。库提供了一个简单的缓存机制，将接收到的数据存储在 .codaphp_cache 文件夹中。此机制是可选的，需要激活。有关更多信息，请参阅 缓存说明

文档

$coda = new CodaPHP('<YOUR API TOKEN>'); // Create instance of CodaPHP

文档

$coda->getDocId('<YOUR DOC URL>'); // Get the id of a doc

$coda->listDocs(); // List all docs you have access to
$coda->listDocs(['query' => 'todo']);  // List docs filtered by searchquery 'todo'
$coda->getDoc('<DOC ID>'); // Get a specific doc
$coda->createDoc('My new doc'); // Create a new doc
$coda->createDoc('Copy of my old doc', '<DOC ID>'); // Copy a doc

页面（前身为文件夹 & 部分）

$coda->listPages('<DOC ID>'); // List all sections in a doc
$coda->getPage('<DOC ID>', '<PAGE NAME OR ID>'); // Get a section in a doc

表格/视图、列和行

$coda->listTables('<DOC ID>'); // List all tables in a doc
$coda->getTable('<DOC ID>', '<TABLE/VIEW NAME OR ID>'); // Get a table in a doc

$coda->listColumns('<DOC ID>', '<TABLE/VIEW NAME OR ID>'); // List all columns in a table
$coda->getColumn('<DOC ID>', '<TABLE/VIEW NAME OR ID>', '<COLUMN NAME OR ID>'); // Get a column in a table

$coda->listRows('<DOC ID>', '<TABLE/VIEW NAME OR ID>'); // List all row in a table
$coda->insertRows('<DOC ID>', '<TABLE/VIEW NAME OR ID>', [['<COLUMN ID OR NAME>' => '<VALUE>']], ['<KEYCOLUMN>']); // Insert/updates a row in a table

// Examples:
$coda->insertRows('<DOC ID>', 'todos', ['title' => 'Shower']); // Adds one row to 'todo'
$coda->insertRows('<DOC ID>', 'todos', [['title' => 'Wash dishes'], ['title' => 'Clean car']]); // Adds two rows to 'todo'
$coda->insertRows('<DOC ID>', 'todos', [['title' => 'Shower', 'status' => 'done'], ['title' => 'Buy goatcheese']], ['title']); // Updates the status of 'Shower' and inserts a new todo

$coda->updateRow('<DOC ID>', '<TABLE/VIEW NAME OR ID>', '<ROW NAME OR ID>', ['<COLUMN ID OR NAME>' => '<VALUE>']); // Updates a row in a table
$coda->getRow('<DOC ID>', '<TABLE/VIEW NAME OR ID>', '<ROW NAME OR ID>'); // Get a row in a table
$coda->deleteRow('<DOC ID>', '<TABLE/VIEW NAME OR ID>', '<ROW NAME OR ID>'); // Deletes a row in a table

使用视图

自Coda API版本1.0.0起，没有独立的视图方法。所有视图操作都可以通过表格方法完成。

推送按钮

$coda->pushButton('<DOC ID>', '<TABLE/VIEW NAME OR ID>', '<ROW NAME OR ID>', '<COLUMN NAME OR ID'>); // Pushes the button on the given column in a table

公式和控制

$coda->listFormulas('<DOC ID>'); // List all formulas in a doc
$coda->getFormula('<DOC ID>', '<FORMULA NAME OR ID>'); // Get a formula in a doc

$coda->listControls('<DOC ID>'); // List all controls in a doc
$coda->getControl('<DOC ID>', '<CONTROL NAME OR ID>'); //Get a control in a doc

管理权限

$coda->listPermissions('<DOC ID>'); // Get information about users & permissions for a doc
$coda->addUser('<DOC ID>', '<EMAIL>'); // Add a user to a doc (default permissions are 'write')
$coda->addUser('<DOC ID>', '<EMAIL>', 'readonly', true); // Add a 'readonly' user and notify via email
$coda->deleteUser('<DOC ID>', '<EMAIL>'); // Removes a user from the doc
$coda->addPermission('<DOC ID>', '<PERMISSION TYPE>', '<PRINCIPAL>', '<NOTIFY>'); // Add a permission to a doc
$coda->deletePermission('<DOC ID>', '<PERMISSION ID>'); // Remove a permission from a doc
$coda->getACLMetadata('<DOC ID>'); // Returns the ACL metadata of a doc

通过API了解更多关于权限设置的详细信息这里。

运行自动化/触发webhook

$coda->runAutomation('<YOUR DOC ID>', '<THE RULE ID>');

账户和其他

$coda->whoAmI(); // Get information about the current account
$coda->resolveLink('<DOC URL>'); // Resolves a link 
$coda->getMutationStatus('<REQUEST ID>'); // Resolves a link

分析

$coda->listDocAnalytics(); // List all docs with analytics data
$coda->listDocAnalytics(['query' => 'Goats', 'sinceDate' => '2022-08-02', 'sinceDate' => '2022-08-04']); // List docs about "Goats" with analytics data between 2nd and 4th of August 2022
// All parameters for all methods can be found in the official API docs: https://coda.io/developers/apis/v1#tag/Analytics/operation/listDocAnalytics
$coda->listPageAnalytics('<DOC ID>'); // List analytics data on page level of given doc
$coda->listPackAnalytics(); // List all packs where user has edit rights with analytics data
$coda->listPackAnalytics(['workspaceId' => 'ws-123Ave']); // List all packs where user has edit rights with analytics data from workspace ws-123Ave
$coda->listPackFormulaAnalytics('<PACK ID'); // List analytisc data on formula level of given pack

$coda->getDocAnalyticsSummery(); // Returns summarized analytics data for available docs.
$coda->getPackAnalyticsSummery(); // Returns summarized analytics data for available packs.

$coda->getAnalyticsUpdatedDay(); // Returns days based on Pacific Standard Time when analytics were last updated. Usually 1 day ago PST.

缓存

库可以在JSON文件中缓存API请求。如果启用了缓存，库将尝试在项目根目录中创建一个.codaphp_cache文件夹。如果无法创建或找不到文件夹，它将禁用缓存。您也可以自己创建文件夹，并设置CHMOD以便库可以读取和写入其中的文件。只有文档数据和内容会被缓存，没有权限、链接或突变状态！

$coda = new CodaPHP('<YOUR API TOKEN>', '<ACTIVATE CACHE>', '<EXPIRY TIME IN SECONDS>'); // Instance creation with otptional caching & expiry time
$coda = new CodaPHP('<YOUR API TOKEN>', true); // Instance with activated caching

默认情况下，缓存将在7天后过期。您可以手动更改过期时间。

$coda = new CodaPHP('<YOUR API TOKEN>', true, 86400); // Activate caching and set cache to 1 day (in seconds)

您还可以手动清除缓存

$coda->clearCache(); // Clears the whole cache

在文档中控制缓存

从Coda文档中控制缓存状态的一个简单方法是使用一个触发清除缓存方法的按钮。

$coda = new CodaPHP('<YOUR API TOKEN>', true);
if(isset($_GET['clearCache'])) {
	$coda->clearCache();
}

现在您可以在文档中添加一个“打开超链接”按钮，它将打开https://yourdomain.com/?clearCache。点击按钮后，网站将接收最新数据并将其再次保存到缓存中。clear cache button

变更日志

0.4.0 (2022年8月28日)

  • 更新到API版本1.3.0
  • 新功能
    • 添加了分析端点
  • 修复了错误
    • 改进了getDocId()正则表达式以获得更好的匹配

0.3.0 (2022年5月24日)

  • 更新到API版本1.2.6。
  • 新功能
    • 触发“Webhook调用”自动化

0.2.0 (2021年1月3日)

  • 更新到API版本1.1.0。
  • 新功能
    • 添加了ACL权限管理
    • 添加了可选的缓存

0.1.0 (2020年8月15日)

  • 更新到API版本1.0.0。
  • 破坏性更改
    • 部分和文件夹已被页面替代
    • 移除了'视图'方法。您可以通过表格方法访问视图。
  • 新功能
    • 添加了突变状态方法 您可以在此处了解更多关于API版本1.0.0的信息

0.0.4 (2020年2月16日)

  • 更新到API版本0.2.4-beta。新功能
    • 在表格和视图中推送按钮
    • 获取和交互视图
    • 在文件夹中创建文档
    • 禁用单元格值解析的能力

0.0.3 (2019年3月16日)

  • 修复了在listRows中使用查询的问题（感谢Al Chen从Coda指出这个问题）

0.0.2 (2018年11月15日)

  • 修复了有关特殊字符的表名的问题（感谢Coda的Oleg指出这个问题）

0.0.1 (2018年11月11日)

  • 基于Coda API的v0.1.1-beta的初始版本