README

什么是 Yiiron？

Yiiron 是一个 Yii 扩展，它集成了 iron.io 的服务，用于 Yii 框架。

Iron.io 提供三种服务

IronMQ - 云消息队列（每月免费 API 请求 1000 万，无限队列）
IronWorkers - 背景任务运行平台，可并行、大规模运行任务（每月免费 200 小时，即每天超过 6 小时，50 个并发任务，25 个计划作业）
IronCache - 键/值数据缓存（提供：100 MB 存储和每月 1000 万 API 请求）

为什么你应该使用 Yiiron？

如果你有任何这些问题，你可能应该尝试它

我如何轻松地将 MQ 服务集成到我的 Yii 应用中？
嗯，这些 cronjobs 实际上消耗了我的服务器资源。我应该启动另一个服务器来运行 cronjobs 吗？
我的应用开始获得很多关注。我真的需要开始正确缓存，但我不想安装和管理 Memcached 或类似的服务。我 wonder if someone can manage the cache for me?
我真的喜欢 iron.io 的服务，但没有时间开发一个 Yii 组件。
我的网站正在快速增长，我运行的后台任务已无法跟上单线程的运行。有没有办法并行运行我的工作线程，而无需安装和维护类似 gearman.org 的东西？
我在 AWS 上，我想使用 MQ、工作线程或缓存，但我想让其他人管理这些服务的扩展和管理。

要求

您的应用程序需要托管在 AWS 上。这实际上不是一个要求，但所有 iron.io 服务都托管在 AWS 上，为了获得服务的全部速度和尽可能低的延迟，您的应用程序应托管在 AWS 基础设施上。这些服务基于 REST，从理论上讲，您可以从任何连接到互联网的计算机使用它们，例如，向 IronMQ 添加数据通常在跨云环境中具有低延迟。

资源

GitHub 页面（用于分支和问题报告）：https://github.com/br0sk/yiiron
Packagist 页面（用于 Composer 下载）：https://packagist.org.cn/packages/br0sk/yiiron
iron.io 开发中心（包括完整的服务细节和完整的 API 文档）- http://dev.iron.io/

入门

如果您还没有 iron.io 账户，请在此处注册免费账户 here。

转到 hud.iron.io/dashboard 并创建一个新项目。

当创建项目时，点击键图标，并记下令牌和项目ID。

解压缩从Yiiron Yii扩展页面下载的yiiron.zip文件，并将所有文件放入扩展目录。它看起来像这样：/var/www/myapp/protected/extensions/yiiron

注意：您还可以使用Composer安装扩展。它使用新的Yii Composer安装器。如果您使用了zip文件，请将扩展的composer标志设置为false；如果您使用composer安装，请将其设置为true。这是必需的，因为根据安装方式的不同，iron.io类将在不同的位置查找。

将此添加到您的配置文件中（如果您想使用IronWorkers，别忘了将其添加到console.php中）

import'=>array('ext.yiiron.*',)

将其添加到组件部分...

'yiiron'=> array(
	'class' =>'EYiiron',
	'token'  => ‘your_iron_io_token’,
	'projectId'  => 'your_iron_io_project_id',
	'services'   => array('mq','worker',’cache’),
	'composer'	=> false,
	'workerFileCopyOptions' => array('exclude' => array('.git','.csv','.svn', '.zip', "/runtime", "/config")),
	'configFile' => 'config/console_ironworker.php',
	'stack' => 'php-5.5'
 	),

这就全部了！

如您所见，您可以在代码作为IronWorker执行时设置您想要使用的PHP版本。找到有效版本这里。

现在通过将其添加到控制器中的一个动作来测试它

Yii::app()->yiiron->mqPostMessage("yii_demo", "First Value");

在浏览器中加载动作。

现在回到hud.iron.io/dashboard，点击您创建的项目旁边的MQ按钮。如果一切正常，您应该看到“队列”标签。点击它！

您现在应该看到刚刚创建的队列，其中添加了一条消息。

恭喜，一切正常，您现在可以开始使用iron.io服务了！

如何使用服务

现在我们可以调用不同的服务，因为我们已经在上面的“入门”中验证了连接是正常的。

Yiiron使用了iron.io PHP API构建。API的所有公共方法（github.com/iron-io/iron_mq_php，github.com/iron-io/iron_worker_php，github.com/iron-io/iron_cache_php）都已包装在Yiiron组件中。

为了在大多数编辑器中使用自动完成功能，我建议您初始化Yiiron组件一次，并将其保存在局部变量中，如下所示

/**
 * @var $yiiron EYiiron The iron.io connector
 */
 $yiiron = Yii::app()->yiiron;

这样做将使您能够访问变量$yiiron的自动完成。这使得查找包装的API方法变得非常容易。

我已经将包装方法分别以mq、worker和cache为前缀。

因此，要获取IronMQ的所有方法，只需键入

$yiiron->mq

然后自动完成应该显示所有以mq开头的方法。

对于IronWorkers键入

$yiiron->worker

然后自动完成应该显示所有以worker开头的方法。

对于IronCache

$yiiron->cache

然后自动完成应该显示所有以cache开头的方法。

提示：如果您不想使用我的包装函数，您可以直接这样引用每个服务。

$myWorker = Yii::app()->yiiron->getRawWorker();
$myCache = Yii::app()->yiiron->getRawCache();
$myMq = Yii::app()->yiiron->getRawMq();

如何使用IronMQ

要使用IronMQ，您可以简单地调用所有以mq开头的方法。以下是一个通用MQ（put/get/delete）最常见场景的示例。

/**
 * @var $yiiron EYiiron The iron.io connector
 */
$yiiron = Yii::app()->yiiron;
  
//Adds a message to the queue
$yiiron->mqPostMessage("yii_demo", "First Value");

//Get the message from the queue and reserve it for 10 seconds(default is 60 seconds)
$message = $yiiron->mqGetMessage("yii_demo",10);

//Print the body and id of the message to the screen
echo("Message id=".$message->id." message body=". $message->body);

//The message has been consumed now remove it from the queue so it is not put back on the queue when the time out of 10 seconds have passed
$yiiron->mqDeleteMessage("yii_demo", $message_get_after_release->id);

有关更多示例，请查看单元测试类。

如何使用IronWorkers

您可以使用两种方式使用IronWorkers。第一种方式是直接使用包装的API。如果您在Yiiron之上编写自己的集成或具有非常具体的使用场景，您可能想这样做。

使用IronWorkers的第二种且推荐的方法是将其作为Yii命令行应用程序运行（请参阅Yii CLI文档）。通过扩展类 EIronWorkersCommand 而不是直接扩展 CConsoleCommand，您现在可以访问额外的功能，这允许您直接运行命令行操作作为IronWorker，而无需对Yii API进行任何更改。

这基本上意味着您只需更改扩展的类，就可以将现有的命令操作作为IronWorkers运行。

以下是一个实际步骤示例。

创建一个名为 console_ironworker.php 的独立配置文件，并将其放置在应用程序的配置文件夹中。这是该文件的简单版本。

<?php
// This is the configuration for yiic console application.
// Any writable CConsoleApplication properties can be configured here.
return array(
	'basePath'=>dirname(__FILE__).DIRECTORY_SEPARATOR.'..',
  	'name'=>'Iron workers',

  	//Autoloading model and component classes
  	'import'=>array(
	'application.models.*',
	'application.components.*',
	'application.extensions.yiiron.*',
 	),
  	
	// application components
  	'components'=>array(
  	),

  // application-level parameters that can be accessed
  // using Yii::app()->params['paramName']
  	'params'=>array(
	// this is used in contact page
		'adminEmail'=>'webmaster@example.com',
  	),
);

在更高级的应用程序中，您可能希望向该配置文件添加更多内容，甚至将其与 console.php 文件合并。请注意，IronWorker运行环境可能不支持生产服务器支持的所有内容，有关运行环境的更多详细信息，请参阅这里和这里。

提示：从版本1.0.4开始，您可以使用参数 configFile 设置Yiiron使用的配置文件路径。它始终默认为 config/console_ironworker.php。

现在创建一个命令行应用程序，创建一个名为 CronjobsCommand.php 的文件（这只是一个示例，它适用于Yii允许的任何命令文件名），并将其保存在Yii的命令文件夹中，例如 /var/www/myapp/protected/commands/CronjobsCommand.php。

将以下代码添加到文件中

class CronjobsCommand extends EIronWorkersCommand
{
public function actionMyAction()
  	{
		echo("My Action Finished!\n");
  	}
}

我们已创建了一个非常简单的操作，该操作将文本输出到屏幕。

本地运行它

转到应用程序的基本文件夹，例如 /var/www/myapp/protected。
现在运行 ./yiic cronjobs myAction。这应该在屏幕上打印“我的操作已完成！”。

现在开始神奇的部分。

运行命令 ./yiic cronjobs uploadIronWorker。这将在屏幕上输出一些跟踪信息，并且运行时间可能会很长，尤其是在慢速连接的情况下。此命令将您的应用程序和Yii框架打包到一个zip文件中，并将其发布到IronWorkers。
注意：从版本1.0.4开始，配置文件不再包含在zip包中，而是使用上传函数中的配置参数。这意味着您在配置文件中存储的凭据将不再可用于上传到IronWorkers的zip文件。这是一种更安全地处理配置文件中凭据的方法。
完成后，您应该可以像这样远程运行myTask命令作为IronWorker ./yiic cronjobs myAction --ironWorker=true。
现在转到hud.iron.io仪表板。
单击我们之前创建的项目旁边的IronWorker按钮。按钮上有一个齿轮图标。
转到任务选项卡。您将看到一个名为cronjobs的新任务。
单击该任务。这将显示已执行的任务列表。您应该有一个带有圆形绿色图标的任务。如果它失败，您可以检查日志并尝试找出错误原因，然后再次运行命令 ./yiic cronjobs myAction --ironWorker=true。

注意：如果您对任何代码进行任何更改，则需要使用命令 ./yiic cronjobs uploadIronWorker 再次上传代码。

提示：由于我们可以从命令行运行部署脚本，因此从您的部署脚本/系统中运行它非常完美。为了这个目的，我使用Phing.info。在我的phing live命令中，我确保执行./yiic cronjobs uploadIronWorker命令。这样，我就知道我的部署代码在我的生产服务器上和IronWorkers环境中始终相同。请记住，您必须为每个创建的命令文件都这样做。这是因为IronWorkers要求您为每个创建的任务上传一个单独的代码包。

太好了，现在您有一个远程服务器运行着之前使您的服务器负担沉重的重任务。您现在只需在运行命令的cronjob的末尾添加标志--ironWorker=true，它就会神奇地在IronWorkers上执行。

提示：如果需要，您也可以这样设置优先级、超时、延迟和任务标签

./yiic cronjobs myAction --ironWorker=true --ironWorkerPriority=0 --ironWorkerTimeout=20 --ironWorkerDelay=30  --ironWorkerTaskLabel=MyLabel

从1.0.3版本开始，您现在可以直接在任何代码中运行命令行操作。您使用名为workerRunYiiAction()的方法来做到这一点。

此方法可以像IronWorker一样执行任何命令行操作。命令行操作通常在shell中直接执行。我们构建此方法是为了可以直接从任何Yii代码中触发命令行操作。这样，我们就不需要只是为了将操作推送到IronWorkers而启动进程。

以下是一个示例

这就是我们如何从命令行运行命令并将其推送到IronWorkers的方式

./yiic cronjobs myAction --param1=34 --ironWorker=true

要直接从例如控制器中运行此操作，您可以这样做

$yiiron = Yii::app()->yiiron;
$yiiron->workerRunYiiAction('cronjobs', 'myAction', array('--param1=34', '--ironWorker=true'));

提示：如果您省略了'--ironWorker=true'，则可以运行相同的命令，但本地运行，而不是将其推送到IronWorkers。

注意：从1.0.4版本开始，当使用选项ironWorker=true运行时，方法workerRunYiiAction现在返回IronWorker任务ID。这样，您就可以使用ID来取消任务或检查进度。

有关参数的更多文档可以在类EIronWorkersCommand中找到。

如何使用IronCache

IronCache也可以以多种方式使用。要么是独立的，使用这样的包装API

Yii::app()->yiiron->cachePutItem(‘cache_name’, ‘cache_value’, array(
    "value" => $value,
    'expires_in' => $expire
  ));

或者使用我实现的Yii缓存组件的首选方式。要使用该组件，请将以下内容添加到配置文件中的组件部分

'cache'=>array(
	'class'=>'EIronCache',
  	'yiironCacheName'=>'demo_cache’),

当然，您还需要用于其他服务的Yiiron设置。

当您像那样添加了EIronCache类后，您就可以像通常在您的应用程序中使用缓存一样使用缓存，并且它将使用IronCache作为存储方法。如果您不想设置自己的MemCached服务器，这很棒。

Yiiron限制

目前，Yiiron仅支持AWS。IronMQ存在于Rackspace，我将在不久的将来添加对该服务的支持。
仅在Linux上进行测试
尚未进行内存泄漏检查。我将在不久的将来将其添加到单元测试中。
单元测试还没有完整的覆盖率
您可能无法在运行代码时使用您通常使用的所有PHP模块作为IronWorker。有关IronWorker运行时环境的更多信息，请参阅这里。

单元测试

Yiiron有一个测试套件。它可以像Yii中的任何其他测试套件一样运行。我使用了一个基于Composer的PHPUnit安装。我不得不改变导入iron.io类的方式。基于Composer的安装似乎会加载类两次，如果不这样做就会失败。如果你有一个基于PEAR的PHPUnit安装，你可能需要删除类顶部的方法if(Yii::app()->getComponent('fixture') === null)来使其能够运行测试。我还不得不更改测试用例的基本类，以解决通过Composer安装PHPUnit时遇到的其他问题。同样，如果你使用的是通过PEAR安装的PHPUnit，你可能需要在运行测试之前将其改回标准的Yii测试用例类。

br0sk / yiiron

维护者

详细信息