README

由 Colin Seymour 编写
项目主页: http://phpSmug.com/

phpSmug 是 SmugMug API 的 PHP 封装类，基于 Dan Coulter 在 phpFlickr 中的工作

基于 GNU 通用公共许可证版本 3

版权 (C) 2008 Colin Seymour

This file is part of phpSmug.

 phpSmug is free software: you can redistribute it and/or modify it under
 the terms of the GNU General Public License as published by the Free
 Software Foundation, either version 3 of the License, or (at your option)
 any later version.

 phpSmug is distributed in the hope that it will be useful, but WITHOUT ANY
 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
 details.

 You should have received a copy of the GNU General Public License along
 with phpSmug.  If not, see <https://gnu.ac.cn/licenses/>.

有关类和即将使用 phpSmug 的工具和应用程序的更多信息，请访问 http://phpsmug.com/。

请通过进行捐赠来支持 phpSmug 的维护和开发。

phpSmug 3.5 的新功能

phpSmug 3.5 引入了通过引入新的方法 signResource() 将未标记为可外部链接的图像（在您的 SmugMug 相册设置中“外部链接”设置为“否”）嵌入外部网站的能力。

请参阅下面的显示不可链接图像部分以获取更多详细信息。

此 README 文件现在采用 Markdown 格式，而不是纯文本格式。

要求

phpSmug 使用 PHP 编写，并利用 PHP 5.2 及更高版本提供的功能，并可选地使用 PEAR。

从 PHP 的角度来看，唯一的要求是 PHP 5.2 编译时启用 GD 和可选的 curl 支持。

如果您想使用数据库进行缓存，还需要以下 PEAR 软件包

• MDB2 2.5.0b3 或更高版本。
• 您要使用的数据库的相应 MDB2_Driver_*。

请参阅上述链接以获取有关安装 PEAR 模块的信息。

安装

将安装包中的文件复制到您的服务器上的一个文件夹中。它们需要由您的 web 服务器读取。如果您喜欢，可以将它们放入在您的 php.ini 文件中定义的 include 文件夹中，但这不是必需的。

使用方法

要使用 phpSmug，您只需在您的 PHP 脚本中包含该文件并创建一个实例。例如

 require_once("phpSmug/phpSmug.php");
 $f = new phpSmug(... arguments go here ...);

构造函数最多接受五个参数，具体取决于您希望使用哪个 SmugMug API 终端和身份验证机制

• APIKey - 所有端点都需要

  这是您从 http://www.smugmug.com/hack/apikeys 为您的应用程序获得的 API 密钥。

• OAuthSecret - OAuth 身份验证需要（1.2.2 终端仅限）
  默认值：NULL

  这是分配给您的 API 密钥的秘密，在 SmugMug 控制面板的“设置”选项卡中显示。如果没有显示秘密，请选择应用程序将使用的 API 密钥旁边的“更改”，然后单击“保存”。将为您生成一个秘密。

  如果您不使用 OAuth 身份验证，则无需担心此参数。

• AppName - 可选
  默认值：NULL

  这是您使用 phpSmug 构建的应用程序的名称、版本和 URL。没有要求格式，但像

   "My Cool App/1.0 (http://my.url.com)"
  

  ... 这样的内容将非常有用。

  虽然这不是强制性的，但建议这样做，因为它有助于SmugMug识别在用户在SmugMug论坛报告问题时调用API的应用程序。

• APIVer - 可选
  默认：1.2.0

  使用此参数设置您希望使用的端点。默认为1.2.0，因为这是SmugMug提供的最新“稳定”端点。

所有phpSmug方法的参数都必须以一系列字符串或关联数组的形式提供。例如

• 作为字符串的参数

      $f = new phpSmug("APIKey=12345678",
           "AppName=My Cool App/1.0 (http://app.com)",
           "APIVer=1.2.2");
  

• 作为关联数组的参数

      $f = new phpSmug(array("APIKey" => "12345678",
           "AppName" => "My Cool App/1.0 (http://app.com)",
           "APIVer" => "1.2.2")
           );
  

当然，您可以在实例化对象之前预定义数组，只需传递数组变量即可。

phpSmug实现了SmugMug API中所有文档记录的方法和参数文档。

要调用方法，请从名称中删除“smugmug.”部分，并将任何句点替换为下划线。例如，而不是smugmug.images.get，您将调用images_get()。

记住：所有函数名称和参数都是区分大小写的。

无需将SessionID或oauth_token*参数传递给各种方法，因为phpSmug会自动在这些方法中传递这些参数（除非有其他说明）。例外情况是使用phpSmug进行OAuth授权过程。

images_upload()不使用API上传，而是使用SmugMug推荐的HTTP PUT方法http://wiki.smugmug.net/display/SmugMug/Uploading

选择HTTP PUT是因为它比其他方法更快、更易于使用且更可靠。

身份验证

您必须通过SmugMug进行身份验证才能使用API。

随着SmugMug API 1.2.2版本的发布，现在有两种方法可以与SmugMug进行身份验证：标准电子邮件/密码或用户ID/哈希或OAuth。phpSmug允许您在应用程序中实现任何一种方法。

注意：1.3.0 API端点仅支持OAuth身份验证。

• 方法1：电子邮件地址/密码或用户ID/哈希

  此方法设置了使用此身份验证方法与API交互所需的会话ID。

  login()不带任何参数将匿名登录，并允许您访问任何公共相册、图像或共享组。

  如果您想访问私有相册和图像、上传或更改设置，您需要通过提供电子邮件地址/密码或用户ID/哈希组合进行登录。

  例如，使用电子邮件地址和密码登录

   $f->login("EmailAddress=you@domain.com", "Password=secretpassword");
  

  使用用户ID和密码哈希（从前一个电子邮件/密码登录中获取）登录

   $f->login("UserID=<value>", "PasswordHash=<value>");
  

  两种方法都将使用HTTPS/SSL来确保您的用户名和密码信息被加密。

  使用用户ID和哈希可能是最安全的方法，因为您无法从哈希中确定您的电子邮件和密码。但是，为了获取哈希和用户ID，您需要至少使用电子邮件地址/密码组合通过login()登录一次。

• 方法2：OAuth

  这是所有方法中最安全的，因为您的用户名和密码只在SmugMug网站上输入。如果您使用过Flickr的API，这非常类似于Flickr使用的授权功能。

  使用OAuth进行身份验证是一个3步过程。

  • 首先，您需要请求一个未授权的请求令牌

       $resp = $f->auth_getRequestToken();
    

    一旦您获得令牌，您需要使用它将用户重定向到SmugMug以授权您的应用程序。您可以通过多种方式完成此操作。作为应用程序的开发人员，您可以选择哪种方法最适合您。最终，您需要将用户重定向到http://api.smugmug.com/services/oauth/authorize.mg，并带有所需的“访问”、“权限”和“oauth_token”参数。

    phpSmug提供了一个简单的方法，可以生成您用于重定向或用户点击的链接（它还负责传递OAuth令牌）

       echo '<a href="'.$f->authorize("Access=[Public|Full]", "Permissions=[Read|Add|Modify]").'">Authorize</a>';
    

    "公共"和"读取"是访问和权限的默认选项，所以如果您只需要这些权限，可以省略它们。

  • 一旦用户授权了您的应用程序，您就需要请求访问令牌和访问令牌密钥（再次提醒，phpSmug会处理传递相关的OAuth令牌）。

       $token = $f->auth_getAccessToken();
    

    您需要将auth_getAccessToken()调用返回的令牌和令牌密钥保存在自己的位置，以便以后使用。

  • 一旦保存了令牌和令牌密钥，您就不再需要使用上述任何认证方法。只需调用setToken("id=<value>", "Secret=<value>")，并在创建对象实例后立即传递令牌ID和令牌密钥。

    例如

       $f = new phpSmug(array("APIKey" => "12345678",
          "AppName" => "My Cool App/1.0 (http://app.com)",
          "APIVer" => "1.2.2")
          );
       $f->setToken("id=<value>", "Secret=<value>");
    

    默认情况下，phpSmug使用HMAC-SHA1签名方法。这是最安全的签名方法。如果您想使用PLAINTEXT，只需将类变量oauth_signature_method设置为PLAINTEXT。

       $f->oauth_signature_method = 'PLAINTEXT';
    

缓存

缓存对于项目来说可能非常重要，因为它可以极大地提高应用程序的性能。

phpSmug具有缓存功能，可以将数据缓存到数据库或文件中，您只需启用它即可。

建议在创建新的phpSmug实例后立即启用缓存，并在调用任何其他phpSmug方法之前进行。

要启用缓存，请使用enableCache()函数。

enableCache()函数需要4个参数

• type - 必需
  这是数据库的"db"或文件系统的"fs"。

• dsn - 对于类型=db是必需的
  这是一个PEAR::MDB2 DSN连接字符串，例如

   mysql://user:password@server/database
  

  如果使用基于数据库的缓存，phpSmug使用MDB2 PEAR模块与数据库交互。phpSmug不提供必要的PEAR模块。如果您想使用数据库进行缓存，您需要自己下载和安装PEAR，MDB2 PEAR模块和相应的数据库驱动程序。有关详细信息，请参阅MDB2手册。

• cache_dir - 对于类型=fs是必需的

  这是网络服务器具有写入权限的文件夹/目录。此目录必须已存在。

  为了获得最佳结果，请使用绝对路径，因为相对路径可能会出现意外行为。它们通常可以正常工作，但您可能需要测试它们。

  您可能不想允许世界查看缓存过程中创建的文件。如果想要隐藏这些信息，请确保权限设置正确，或者阻止网络服务器显示*.cache文件。

  在Apache中，您可以在配置文件或使用以下指令的 .htaccess 文件中指定此操作

   <FilesMatch "\.cache$">
      Deny from all
   </FilesMatch>
  

  或者，您可以指定一个位于网络服务器文档根之外的目录。

• cache_expire - 可选
  默认值：3600

  这是每个缓存条目最大年龄（以秒为单位）。

• table - 可选
  默认值：smugmug_cache

  这是用于存储缓存数据的数据库表名。这仅适用于数据库（db）缓存，如果用于文件系统（fs）缓存则会被忽略。

  如果表不存在，phpSmug将尝试创建它。

每个缓存方法都可以按以下方式启用

基于文件系统的缓存

 $f->enableCache("type=fs", "cache_dir=/tmp", "cache_expire=86400" );

基于数据库的缓存

 $f->enableCache("type=db", "dsn=mysql://USERNAME:PASSWORD_database", "cache_expire=86400");

如果您启用了缓存，并进行了更改，那么调用clearCache()以刷新缓存，使您的更改立即反映出来是个好主意。

显示不可删除的图像

注意：此选项仅在您使用OAuth认证时可用。

默认情况下，当您在SmugMug中创建一个新的相册时，您将能够在外部网站上显示/嵌入该相册中的图片。如果您更改相册设置并将“外部链接”设置为“否”，则将无法再这样做。

但是，如果您使用OAuth身份验证，您可以使用signResource()使用您的OAuth凭据签名图像URL，并在外部网站上显示这些图像。

例如，您可以使用以下方法显示您的“无法取消链接”的图片：

 <img src=" . $f->signResource( $img['TinyURL'] ) . " />

查看example-external-links.php以获取完整的实现示例。

请注意，这些链接基于时间，因此每次页面加载时都需要重新生成链接。这可能会影响包含这些“签名”图片的页面的渲染性能。

由于这些链接基于时间，您无法缓存HTML输出，但您仍然可以使用phpSmug提供的缓存机制来缓存原始API数据。

上传

上传非常简单。您可以从您的本地系统上传图片，或从网络上的位置上传。

为了上传，您需要已登录到SmugMug，并且需要您要上传到的相册的相册ID。

然后只需调用带有各种可选参数的方法即可。

例如，使用以下方法上传本地文件：

 $f->images_upload("AlbumID=123456", "File=/path/to/image.jpg");

... 或者从远程网站使用：

 $f->images_uploadFromURL("AlbumID=123456", "URL=http://my.site.com/image.jpg");

如果您希望文件在SmugMug上具有特定的名称，请添加可选的“FileName”参数。如果您没有指定文件名，则将使用源文件名。

您可以在API文档页面上找到可选参数的列表，如标题和关键词。

替换照片

替换照片与上传相同。唯一不同的是您需要指定您要替换的图片的ImageID。

其他说明

• 默认情况下，如果Curl可用，phpSmug将尝试使用Curl与SmugMug API端点通信。如果不可用，它将回退到使用基于套接字的通信，使用fsockopen()。如果您想强制使用套接字，可以在实例化实例后立即使用phpSmug提供的`setAdapter()`。

   $f = new phpSmug("APIKey=<value>"); 
   $f->setAdapter("socket");
  

  有效的参数是“curl”（默认）和“socket”。

• 有些人需要从代理服务器后面使用phpSmug。您可以使用setProxy()方法设置适当的代理设置。

  例如

   $f = new phpSmug("APIKey=<value>");
   $f->setProxy("server=<proxy_server>", "port=<value>");
  

  然后您的所有调用都将通过指定端口上的指定代理进行。

  如果您的代理服务器需要用户名和密码，请将它们添加到setProxy()方法参数中。

  例如

   $f = new phpSmug("APIKey=<value>");
   $f->setProxy("server=<proxy_server>",
       "port=<value>",
       "username=<proxy_username>",
       "password=<proxy_password>");
  

• 默认情况下，phpSmug仅使用HTTPS进行与身份验证相关的方法，如所有login*()和*Token()方法。但是，您可以强制所有API调用（上传除外）使用HTTPS，通过在实例化对象后立即调用setSecureOnly()。

  例如

   $f = new phpSmug("APIKey=<value>");
   $f->setSecureOnly();
  

  注意：强制所有API通信使用HTTPS可能会影响性能，因为HTTPS本质上是比HTTP慢的。

• 如果phpSmug遇到错误，或者SmugMug返回“失败”响应，将抛出异常，并且您的应用程序将停止执行。如果与端点通信有问题，将抛出HttpRequestException。如果检测到其他错误，将抛出PhpSmugException。

  建议您配置您的应用程序以捕获phpSmug的异常。

• SmugMug有时会将SmugMug网站设置为只读模式以进行维护。SmugMug的模式现在存储在模式对象变量中（例如，对于检查SmugMug状态，$f->mode）。注意，这不会为login()方法设置，因为当SmugMug处于只读模式时，无法登录。如果SmugMug不是只读模式，则此变量为空。

示例

phpSmug自带3个示例来帮助您入门。这3个示例执行相同的功能，只是使用了不同的认证方法。它们都显示了相应认证方法找到的第一个专辑的缩略图。

• example-login.php示例演示了用户名/密码登录。

• example-anon.php示例演示了匿名登录。

• example-oauth.php示例演示了OAuth登录。

• example-external-links.php示例演示了显示无法取消链接的图片。

您可以在http://phpsmug.com/examples查看匿名和OAuth登录示例的实际效果。

这就结束了。

请访问它的新专用网站http://phpsmug.com/以获取关于phpSmug的最新发展和改进。

如果您在使用phpSmug时遇到任何问题，请查看http://phpsmug.com/bugs上关于phpSmug及其API的已知问题列表。

如果您正在使用phpSmug并希望让全世界知道，请通过http://phpsmug.com/about上的联系表单与我联系，或使用#phpSmug标签发推文，我将在http://phpsmug.com/的侧边栏中添加链接和简要描述。

如果您使用并发现phpSmug很有用，请通过捐赠来帮助支持其维护和发展。

此文档还可在http://phpsmug.com/docs上在线查看。

变更历史

• 3.5 - 2013年3月2日

  • 增加了使用OAuth认证参数对图像URL进行签名的能力，以允许在外部站点内嵌入“非外部”图像。修复了问题#16。
  • 增加了example-external-links.php示例以演示上述功能。
  • 将README文件切换为使用Markdown。

• 3.4 - 2011年6月21日

  • 添加了缺失的应隐藏的图像上传头信息。修复了问题#12。

• 3.3 - 2011年6月3日

  • 绕过了PHP的implode()和http_build_query()处理空值关联数组键时的奇怪行为。修复了问题#11。

• 3.2 - 2011年5月30日

  • 改进了对1.3.0 API端点的支持（问题#10）
  • 实现了强制所有API通信通过HTTPS进行的安全通信。仅OAuth。问题#9
  • phpSmug现在使用文档化的secure.smugmug.com API端点（问题#8）
  • 更新了OAuth示例，以使用新的专辑URL并删除了其使用已弃用的session_unregister() PHP函数。

• 3.1 - 2011年3月28日

  • phpSmug现在默认使用1.2.2 API端点。所有较早的端点仍然可用，但根据SmugMug的说法，在技术上已弃用。
  • 删除了在设置适配器时错误地重新实例化处理器的情况。
  • 更正了对safe_dir OR open_basedir的检查，以便正确地切换到套接字连接
  • 改进了连接设置

• 3.0 - 2010年11月13日

  • 现在setProxy()方法允许您设置代理用户名和密码。
  • OAuth令牌设置现在再次正确工作（问题#7）。
  • phpSmug不再依赖于PEAR，因此不再提供任何PEAR模块。
  • phpSmug现在是100% PHP 5 E_STRICT兼容的（问题#2）。
  • phpSmug现在根据GPLv3许可证授权。

• 2.2 - 2010年7月21日

  • 强制使用HTTPS进行所有使用PLAINTEXT签名方法的OAuth调用。警告：如果您使用PLAINTEXT（这不是默认设置），则API会拒绝上传。
  • 不再缓存失败的上传响应和smugmug.auth.*方法响应。
  • 上传文件名现在被编码以确保正确处理空格和非ASCII字符。
  • images_upload()现在尊重任何早期的setProxy()调用，以便可以通过该代理进行上传。
  • clearCache() 现在接受一个布尔参数来表示在清除缓存时是否要删除缓存位置。默认为 FALSE，即缓存位置不会被删除。
  • 添加了处理 API 提供的 login.* 方法的方法，当使用这些方法而不是 phpSmug 提供的单个 login() 方法时。（问题单 #6）
  • 为了我自己方便，我现在实现了一个完整的 PHPUnit 测试套件，用于检查 phpSmug 的所有功能。

• 2.1 - 2009 年 9 月 27 日

  • 将 image_upload 方法改为上传到 upload.smugmug.com 而不是 api.smugmug.com。SmugMug 进行了更改，强制使用 upload.smugmug.com，因为上传到 api.smugmug.com 造成了问题。（问题单 #5）
  • 解决了缓存数据重新缓存的问题（问题单 #4）。
  • SmugMug 的模式（即只读等）现在存储在 $obj->mode 中，以便轻松检查 SmugMug 的状态。
  • 在 README 文件中更正了 "使用散列登录" 的示例。

• 2.0.2 - 2009 年 2 月 22 日

  • 整理了代码，使 phpSmug.php 符合 E_STRICT，并且不会报告任何通知消息。
  • 由于 PEAR 模块的限制，将错误日志级别强制设置为低于 E_STRICT（参见问题单 #2 的注释）。
  • 解决了 clearCache() 函数过于激进的问题（问题单 #3）。

• 2.0.1 - 2008 年 11 月 7 日

  • 解决了错误代码未传递到第 350 行的 Exception() 的问题（问题单 #1）。

• 2.0 - 2008 年 10 月 30 日

  • 为了支持异常，移除了 die_on_error 功能。
  • 移除 getErrorCode() 和 getErrorMsg() 函数，因为它们不再提供 die_on_error 功能。错误代码和消息通过异常传递。
  • 整理了包含的 PEAR 包，只包含基本的最小包（这些包提供以简化实现）
  • 更新 HTTP_Request 到 1.4.3
  • 为 1.2.2 端点添加了 OAuth 支持。默认使用 HMAC-SHA1，因为它是最安全的，性能问题最小。
  • phpSmug 2.0 的初始版本 - 废弃了所有之前的 phpSmug 版本。