jublonet/shapecode-php

PHP的Shapeways API库。

维护者

详细信息

github.com/jublo/shapecode-php

主页

源代码

问题

安装: 17

依赖: 0

建议: 0

安全: 0

星标: 0

关注者: 4

分支: 1

1.1.2 2016-08-10 00:10 UTC

Requires

LGPL-3.0+ f7dbcb7e36df8b782ff9b75879379d634fc9d0b5

apimodelingprintingshapeways3d

This package is not auto-updated.

Last update: 2024-09-25 01:07:07 UTC

README

PHP的Shapeways API库。

版权（C）2014-2016 Jublo Solutions support@jublo.net

本程序是免费软件：您可以自由分发和/或修改它，只要您遵守自由软件基金会按照GNU Lesser General Public License发布的许可条款，许可证版本为3，或（根据您的选择）任何更新版本。

本程序的发布是希望它对您有用，但没有任何保证；甚至没有关于其适销性或适用于特定用途的暗示保证。有关详细信息，请参阅GNU General Public License。

您应该已经收到了一份GNU General Public License副本。如果没有，请参阅https://gnu.ac.cn/licenses/。

需求

  • PHP 5.5.0或更高版本
  • JSON扩展
  • OpenSSL扩展

认证

要代表某个Shapeways用户（遵循OAuth 1.0a）进行API请求认证，请参考以下步骤

require_once ('shapecode.php');
Shapecode::setConsumerKey('YOURKEY', 'YOURSECRET'); // static, see 'Using multiple Shapecode instances'

$sc = Shapecode::getInstance();

如果您已经有了OAuth令牌和密钥，您可以设置它们

$sc->setToken('YOURTOKEN', 'YOURTOKENSECRET');

或者您可以这样进行认证

session_start();

if (! isset($_SESSION['oauth_token'])) {
    // get the request token
    $reply = $sc->oauth1_requestToken(array(
        'oauth_callback' => 'http://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI']
    ));

    // store the token
    $_SESSION['oauth_token'] = $reply->oauth_token;
    $_SESSION['oauth_token_secret'] = $reply->oauth_token_secret;
    $_SESSION['oauth_verify'] = true;

    // redirect to auth website
    header('Location: ' . $reply->authentication_url);
    die();

} elseif (isset($_GET['oauth_verifier']) && isset($_SESSION['oauth_verify'])) {
    // verify the token
    $sc->setToken($_SESSION['oauth_token'], $_SESSION['oauth_token_secret']);
    unset($_SESSION['oauth_verify']);

    // get the access token
    $reply = $sc->oauth1_accessToken(array(
        'oauth_verifier' => $_GET['oauth_verifier']
    ));

    // store the token (which is different from the request token!)
    $_SESSION['oauth_token'] = $reply->oauth_token;
    $_SESSION['oauth_token_secret'] = $reply->oauth_token_secret;

    // send to same URL, without oauth GET parameters
    header('Location: ' . basename(__FILE__));
    die();
}

// assign access token on each page load
$sc->setToken($_SESSION['oauth_token'], $_SESSION['oauth_token_secret']);

使用示例

当您有访问令牌时，调用API非常简单

$sc->setToken($_SESSION['oauth_token'], $_SESSION['oauth_token_secret']); // see above

$reply = (array) $sc->api();
print_r($reply);

将模型添加到购物车就像这样简单

$reply = $sc->orders_cart('modelId=480903');

对于更复杂的参数（请参阅Shapeways API文档），也支持在数组中提供所有参数

$params = array(
    'modelId' => '480903',
    'materialId' => 61,
    'quantity' => 3
);
$reply = $sc->orders_cart($params);

当将文件上传到Shapeways时，只需提供文件路径

$params = array(
    'file' => 'in-some-folder/there-is/the-model.stl',
    'fileName' => 'the-model.stl',
    'hasRightsToModel' => 1,
    'acceptTermsAndConditions' => 1,
    'title' => 'My great model',
    'description' => 'Lorem ipsum dolor sit amet',
    'isPublic' => 1,
    'isForSale' => 1,
    'isDownloadable' => 0,
    'tags' => array(
        'ideas',
        'miniatures',
        'stuff'
    )
);
$reply = $sc->models($params); // required HTTP POST is auto-detected

将API方法映射到Shapecode函数调用

如您从最后一个示例中看到，有一种通用的方法将Shapeways API方法映射到Shapecode函数调用。一般规则是

  1. 在函数名中省略版本信息。

    示例：/v1不是Shapecode函数调用的一部分。

  2. 对于Shapeways API方法中的每个斜杠，在Shapecode函数中使用下划线。

    示例：orders/cart/v1映射到Shapecode::orders_cart()。

  3. 对于Shapeways API方法中的每个下划线，在Shapecode函数中使用驼峰命名。

    示例：oauth1/request_token/v1映射到Shapecode::oauth1_requestToken()。

  4. 对于方法中的每个参数模板，在Shapecode函数中使用大写字母。同时，别忘了在参数列表中包含该参数。

    示例

    • materials/{materialId}/v1映射到Shapecode::materials_MATERIALID('materialId=73')。

HTTP方法（GET、POST、DELETE等）

在调用Shapeways API时，无需关心使用哪种HTTP方法（动词）。Shapecode足够智能，可以自己找出。要确保自动检测正常工作，请务必使用如Shapeways API文档中概述的正确所需参数。

上述例外情况是DELETE models/{modelId}方法。要调用它，请使用delete=1参数。它将触发DELETE方法，但不会发送到API。

响应代码

API返回的HTTP响应代码包含在任何返回值中。您可以在返回对象的httpstatus属性中找到它。

要检查您的API调用是否成功，请检查$reply->result字符串，它将读取为success或failure。

返回格式

API调用的默认返回格式是PHP对象。根据您的选择，您也可以直接获得PHP数组。

$sc->setReturnFormat(SHAPECODE_RETURNFORMAT_ARRAY);

Shapeways API 默认以 JSON（JS 对象表示法）格式响应 API 调用。要获取 JSON 字符串，请设置相应的返回格式。

$sc->setReturnFormat(SHAPECODE_RETURNFORMAT_JSON);

使用多个 Shapecode 实例

默认情况下，Shapecode 只与一个实例一起工作。这种编程范式被称为 单例。

获取主 Shapecode 对象的方式如下

$sc = Shapecode::getInstance();

如果您需要一次性对多个用户运行对 Shapeways API 的请求，Shapecode 也支持这一点。不要像上面那样获取实例，而是创建一个新的对象

$sc1 = new Shapecode;
$sc2 = new Shapecode;

请注意，您的 OAuth 消费者密钥和密钥在多个 Shapecode 实例中是共享的，而 OAuth 请求和访问令牌及其密钥则 不 共享。

我该如何……？

……遍历分页结果？

Shapeways API 利用一种称为“分页”的技术来处理大量结果集。分页将结果分为每次不超过 36 个结果的页面，并提供了一种在页面之间前后移动的方法。

以下是使用 Shapecode 遍历分页结果的方法。

  1. 获取分页方法的第一个结果集
$page = 1;
$result1 = $sc->models();
  1. 要向前导航，增加 $page
$page++;
  1. 如果 $nextCursor 不是 0，则使用此光标请求下一个结果页面
    $result2 = $sc->models("page=$page");

使用循环使用页面可能更有意义。但是，请注意不要在速率限制时间范围内发送超过允许数量的请求，否则您将遇到速率限制。

……cacert.pem 是什么？

Shapeways API 的连接是通过安全的 SSL 连接完成的。Shapecode-php 会检查 Shapeways API 服务器是否有有效的 SSL 证书。有效的证书具有正确的签名链。cacert.pem 文件包含所有根证书颁发机构公共证书的列表。您可以在 http://curl.haxx.se/docs/caextract.html 上找到更多关于此文件的信息。

……为 Shapeways API 请求设置超时？

对于连接到 Shapeways，Shapecode 使用可用的 cURL 库。您可以使用毫秒指定连接超时和请求超时

$sc->setConnectionTimeout(2000);
$sc->setTimeout(5000);

如果您未指定超时，Shapecode 将使用以下值

  • 连接时间 = 5000 毫秒 = 5 秒
  • 超时 = 2000 毫秒 = 2 秒

……禁用 cURL？

Shapecode 会自动检测您是否启用了 PHP cURL 扩展。如果没有，库将尝试通过套接字连接到 Shapeways API。为了使其工作，PHP 设置 allow_url_fopen 必须启用。

您还可以手动禁用 cURL。使用以下调用

$sc->setUseCurl(false);