README

WordPress 开发者插件，允许通过短信或电子邮件分享网站链接。它使用 Twilio 提供短信服务，Amazon SES 提供电子邮件服务，官方 WordPress Bit.ly 插件 用于 URL 缩短，Timber 用于电子邮件模板渲染，以及 WordPress 多语言插件 用于翻译电子邮件内容。

使用 Composer 安装

$1 此软件包使用 Composer Installers 将软件包安装在 必须使用 插件目录中（/wp-content/mu-plugins）

composer require nyco/wp-send-me-nyc

未使用 Composer？ 下载代码存档并将其放入 mu-plugins 目录。但是，其他依赖项需要单独下载和安装。

$2 在 mu-plugins 目录内创建一个代理 PHP 加载器文件，或 使用插件中包含的示例

mv wp-content/mu-plugins/wp-send-me-nyc/autoloader-sample.php wp-content/mu-plugins/send-me-nyc.php

初始化

示例自动加载器包含初始化插件所需的基本代码。它将...

• 需要包含类和辅助函数的所有文件。
• 初始化 SMNYC\ContactMe、SMNYC\SmsMe 和 SMNYC\EmailMe 类。
• 注册发送消息的 admin 动作。
• 注册 自定义帖子类型 用于自定义短信和电子邮件内容（SMNYC 电子邮件和 SMNYC 短信）。
• 在 设置 > Send Me NYC 下创建一个 admin 设置页面进行 配置。

注意： SMNYC\SmsMe 和 SMNYC\EmailMe 类扩展了 SMNYC\ContactMe 类。这三个类中的任何一个都可以进一步扩展或修改其属性以适应自定义设置或服务。

配置

每个设置部分对应于需要配置以与您的 WordPress 安装一起工作的特定服务。这些可以在 WordPress 管理设置中配置，也可以作为 PHP 常量。如果同时设置了选项的 WordPress 管理设置和 PHP 常量设置，则首选 WordPress 管理设置。

Bitly 服务设置用于 URL 缩短

官方WordPress Bit.ly 插件用于管理 Bit.ly 的 API 版本和认证。安装后，在 WordPress 管理菜单的“设置 > 写作”下可以找到 Bit.ly 设置。认证需要访问 Bit.ly 账户或访问令牌。访问令牌可以通过开发者设置中的 Bit.ly 用户账户生成。要使用 Oauth，需要通过程序或命令行生成令牌。有关更多信息，请参阅API 认证文档。

可以使用 PHP 常量 SMNYC_WPBITLY_OAUTH_TOKEN 来定义令牌。此插件将自动设置 WordPress Bit.ly 令牌并隐藏认证按钮。

SMS 的 Twilio 服务设置

Twilio 集成使用 API 密钥，可以在“账户 > API 密钥 & 令牌”页面下生成。有关 Twilio API 密钥的更多信息，请参阅此处。

Amazon SES 邮件设置

注意：此插件与NYCO WordPress Config插件配合良好。

自定义帖子类型

这些自定义帖子类型创建用于存储可重复使用的 SMS 和电子邮件内容，这些内容将发送到我们的消息中。

SMNYC SMS

帖子内容的示例可能包括以下内容；

提醒：您可能有资格参加以下 NYC 项目：{{ BITLY_URL }}

模板标签 {{ BITLY_URL }} 将被替换为要与收件人共享的缩短后的 Bitly URL。SMNYC SMS 帖子类型不需要特定的模板。

对于更动态的内容，您可以在 sharetext 中包含一个输入，并在帖子内容中包含模板标签 {{ SHARE_TEXT }}。

{{ SHARE_TEXT }} {{ BITLY_URL }}

SMNYC 电子邮件

帖子内容的示例可能类似于 SMS，但您可能不需要使用 Bitly 缩短 URL。在这种情况下，将 {{ BITLY_URL }} 替换为 {{ URL }}。

提醒：您可能有资格参加以下 NYC 项目：{{ URL }}

SMNYC 电子邮件帖子类型需要扩展 Timber\Post 类的模板控制器和一个包含将内容渲染为 HTML 电子邮件的模板的 Twig 文件。示例控制器包含一个扩展 Timber\Post 的有效类。将该文件移动到活动主题目录的根目录。

mv wp-content/mu-plugins/nyco-wp-send-me-nyc/controllers/smnyc-email-single-sample.php wp-content/themes/theme/smnyc-email.php

示例电子邮件包含一个有效的电子邮件 twig 模板。使用此文件或创建一个名为 emails/single.twig 的文件，并将其放入您的 Timber 视图 目录中。这是您电子邮件的 HTML 标记将被放置的位置。

自定义

控制器文件路径和类内容可以使用原样或根据需要进行修改。默认情况下，SMNYC\EmailMe 需要一个位于激活的 WordPress 主题根目录中的名为 smnyc-email.php 的文件，其中包含控制器类。但是，可以在 自动加载 时将不同的路径传递给 SMNYC\EmailMe 类。

$email = new SMNYC\EmailMe('controllers/smnyc-email.php');

检查 smnyc-email.php 文件，我们可以看到该类有一个模板常量。

/** The twig template for emails */
const TEMPLATE = 'emails/single.twig';

这是存储电子邮件模板的 views 目录路径。如果需要，可以修改字符串以使用不同的路径。"smnyc-email.php" 文件还包含一个名为 ->addToPost() 的方法，可以在渲染视图时添加可编程的帖子内容。

发送消息

WordPress Admin Ajax 用于将前端数据发送到插件。当插件初始化时，实例化的 SMNYC\EmailMe 和 SMNYC\SmsMe 对象的 createEndpoints() 方法将添加 Ajax 动作。已注册使用 wp_ajax_{$_REQUEST['action']} 和 wp_ajax_nopriv_{$_REQUEST['action']} 的动作。可以使用隐藏的输入来配置通过以下脚本发送的数据。

{# .twig #}

<form action="https://mysite.com/wp-admin/admin-ajax.php" method="post" data-js="smnyc">
  <input type="hidden" readonly name="action" value="sms_send" />
  <input type="hidden" readonly name="url" value="https://mysite.com/my-url-to-share/" />
  <input type="hidden" readonly name="template" value="my-sms-post-template" />
  <input type="hidden" readonly name="lan" value="en" />
  <input type="hidden" readonly name="sharetext" value="{{ message }}" />
  <input type="hidden" readonly name="hash" value="{{ hash }}" />

  <input name="to" placeholder="Phone Number" required="true" type="tel" />
  <button class="btn btn-primary btn-small" type="submit">Share</button>
</form>

下面列出了用于使用 SMS 和电子邮件服务的默认动作。

值

SMNYC\hash()

/* php */

// Retrieving a hash using the SMNYC helper function.
$context['hash'] = SMNYC\hash('https://mysite.com/my-to-share/');

以下是一个示例脚本，它为表单添加了提交事件监听器，在提交时 序列化 表单数据，并将数据作为 JSON 对象传递给 Fetch API。

/* JavaScript */

// https://npmjs.net.cn/package/form-serialize
import FormSerialize from 'form-serialize';

let FORM = document.querySelector('[data-js="smnyc"]');

FORM.addEventListener('submit', (event) => {
  // To send the data with the application/x-www-form-urlencoded header
  // we need to use URLSearchParams(); instead of FormData(); which uses
  // multipart/form-data
  let formData = new URLSearchParams();

  // Serialize the form data.
  let data = FormSerialize(FORM, {hash: true});

  // Iterate over our serialized data and append to formData.
  Object.keys(data).map(k => {
    formData.append(k, data[k]);
  });

  // Send the request via the Fetch API.
  fetch(FORM.getAttribute('action'), {
    method: FORM.getAttribute('method'),
    body: formData
  }).then(response => response.json())
    .then(response => {
      // My Response handler
    }).catch(data => {
      // My Error handler
    });
});

响应代码

以下是 Email/SMS 服务返回的各个响应代码及其含义。

动作

smnyc_message_sent

在消息发送成功后触发此动作。

...参数

• String $type 电子邮件/SMS/类的类型。
• String $to 消息的接收者。
• String $guid 会话 GUID。
• String $url 已共享的 URL。
• String $msg 消息正文。

示例

add_action('smnyc_message_sent', function($type, $to, $uid, $url, $message) {
  // Successful message sent handler
}, 10, 5);

纽约市经济机会办公室致力于共享我们在产品中使用的开源软件。请随时提问和分享反馈。 有兴趣贡献吗？ 请查看我们的开放职位 buildwithnyc.github.io。关注我们的团队在 GitHub 上的 @nycopportunity 和 @cityofnewyork:nycopportunity 或 在 Github 上浏览我们的工作。