-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathqueues.html
197 lines (131 loc) · 8.13 KB
/
queues.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
<!DOCTYPE html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js"> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Queues</title>
<link rel="stylesheet" href="css/style.css">
<link rel="stylesheet" href="css/ubuntu-font.css">
<script src="vendor/modernizr-2.6.2.min.js"></script>
<script type="text/javascript" src="vendor/google-code-prettify/prettify.js"></script>
</head><body><section class="docs-content"><div class="container">
<article class="docs-body"><h1>Queues</h1>
<p><a name="configuration"></a></p>
<h2>Configuration</h2>
<p>The Laravel Queue component provides a unified API across a variety of different queue services. Queues allow you to defer the processing of a time consuming task, such as sending an e-mail, until a later time, thus drastically speeding up the web requests to your application.</p>
<p>The queue configuration file is stored in <code>app/config/queue.php</code>. In this file you will find connection configurations for each of the queue drivers that are included with the framework, which includes a <a href="http://kr.github.com/beanstalkd">Beanstalkd</a>, <a href="http://iron.io">IronMQ</a>, <a href="http://aws.amazon.com/sqs">Amazon SQS</a>, and synchronous (for local use) driver.</p>
<p>The following dependencies are needed for the listed queue drivers:</p>
<ul>
<li>Beanstalkd: <code>pda/pheanstalk</code>
</li>
<li>Amazon SQS: <code>aws/aws-sdk-php</code>
</li>
<li>IronMQ: <code>iron-io/iron_mq</code>
</li>
</ul>
<p><a name="basic-usage"></a></p>
<h2>Basic Usage</h2>
<p>To push a new job onto the queue, use the <code>Queue::push</code> method:</p>
<p><strong>Pushing A Job Onto The Queue</strong></p>
<pre class="prettyprint"><code>Queue::push('SendEmail', array('message' => $message));
</code></pre>
<p>The first argument given to the <code>push</code> method is the name of the class that should be used to process the job. The second argument is an array of data that should be passed to the handler. A job handler should be defined like so:</p>
<p><strong>Defining A Job Handler</strong></p>
<pre class="prettyprint"><code>class SendEmail {
public function fire($job, $data)
{
//
}
}
</code></pre>
<p>Notice the only method that is required is <code>fire</code>, which receives a <code>Job</code> instance as well as the array of <code>data</code> that was pushed onto the queue.</p>
<p>If you want the job to use a method other than <code>fire</code>, you may specify the method when you push the job:</p>
<p><strong>Specifying A Custom Handler Method</strong></p>
<pre class="prettyprint"><code>Queue::push('SendEmail@send', array('message' => $message));
</code></pre>
<p>Once you have processed a job, it must be deleted from the queue, which can be done via the <code>delete</code> method on the <code>Job</code> instance:</p>
<p><strong>Deleting A Processed Job</strong></p>
<pre class="prettyprint"><code>public function fire($job, $data)
{
// Process the job...
$job->delete();
}
</code></pre>
<p>If you wish to release a job back onto the queue, you may do so via the <code>release</code> method:</p>
<p><strong>Releasing A Job Back Onto The Queue</strong></p>
<pre class="prettyprint"><code>public function fire($job, $data)
{
// Process the job...
$job->release();
}
</code></pre>
<p>You may also specify the number of seconds to wait before the job is released:</p>
<pre class="prettyprint"><code>$job->release(5);
</code></pre>
<p>If an exception occurs while the job is being processed, it will automatically be released back onto the queue. You may check the number of attempts that have been made to run the job using the <code>attempts</code> method:</p>
<p><strong>Checking The Number Of Run Attempts</strong></p>
<pre class="prettyprint"><code>if ($job->attempts() > 3)
{
//
}
</code></pre>
<p>You may also access the job identifier:</p>
<p><strong>Accessing The Job ID</strong></p>
<pre class="prettyprint"><code>$job->getJobId();
</code></pre>
<p><a name="queueing-closures"></a></p>
<h2>Queueing Closures</h2>
<p>You may also push a Closure onto the queue. This is very convenient for quick, simple tasks that need to be queued:</p>
<p><strong>Pushing A Closure Onto The Queue</strong></p>
<pre class="prettyprint"><code>Queue::push(function($job) use ($id)
{
Account::delete($id);
$job->delete();
});
</code></pre>
<blockquote>
<p><strong>Note:</strong> When pushing Closures onto the queue, the <code>__DIR__</code> and <code>__FILE__</code> constants should not be used.</p>
</blockquote>
<p>When using Iron.io <a href="#push-queues">push queues</a>, you should take extra precaution queueing Closures. The end-point that receives your queue messages should check for a token to verify that the request is actually from Iron.io. For example, your push queue end-point should be something like: <code>https://yourapp.com/queue/receive?token=SecretToken</code>. You may then check the value of the secret token in your application before marshaling the queue request.</p>
<p><a name="running-the-queue-listener"></a></p>
<h2>Running The Queue Listener</h2>
<p>Laravel includes an Artisan task that will run new jobs as they are pushed onto the queue. You may run this task using the <code>queue:listen</code> command:</p>
<p><strong>Starting The Queue Listener</strong></p>
<pre class="prettyprint"><code>php artisan queue:listen
</code></pre>
<p>You may also specify which queue connection the listener should utilize:</p>
<pre class="prettyprint"><code>php artisan queue:listen connection
</code></pre>
<p>Note that once this task has started, it will continue to run until it is manually stopped. You may use a process monitor such as <a href="http://supervisord.org/">Supervisor</a> to ensure that the queue listener does not stop running.</p>
<p>You may also set the length of time (in seconds) each job should be allowed to run:</p>
<p><strong>Specifying The Job Timeout Parameter</strong></p>
<pre class="prettyprint"><code>php artisan queue:listen --timeout=60
</code></pre>
<p>To process only the first job on the queue, you may use the <code>queue:work</code> command:</p>
<p><strong>Processing The First Job On The Queue</strong></p>
<pre class="prettyprint"><code>php artisan queue:work
</code></pre>
<p><a name="push-queues"></a></p>
<h2>Push Queues</h2>
<p>Push queues allow you to utilize the powerful Laravel 4 queue facilities without running any daemons or background listeners. Currently, push queues are only supported by the <a href="http://iron.io">Iron.io</a> driver. Before getting started, create an Iron.io account, and add your Iron credentials to the <code>app/config/queue.php</code> configuration file.</p>
<p>Next, you may use the <code>queue:subscribe</code> Artisan command to register a URL end-point that will receive newly pushed queue jobs:</p>
<p><strong>Registering A Push Queue Subscriber</strong></p>
<pre class="prettyprint"><code>php artisan queue:subscribe queue_name http://foo.com/queue/receive
</code></pre>
<p>Now, when you login to your Iron dashboard, you will see your new push queue, as well as the subscribed URL. You may subscribe as many URLs as you wish to a given queue. Next, create a route for your <code>queue/receive</code> end-point and return the response from the <code>Queue::marshal</code> method:</p>
<pre class="prettyprint"><code>Route::post('queue/receive', function()
{
return Queue::marshal();
});
</code></pre>
<p>The <code>marshal</code> method will take care of firing the correct job handler class. To fire jobs onto the push queue, just use the same <code>Queue::push</code> method used for conventional queues.</p>
</article><div class="clearfix"></div>
</div>
</section>
<script src="js/jquery.min.js"></script>
<script src="js/plugins.js"></script>
<script type="text/javascript" src="vendor/google-code-prettify/run_prettify.js"></script>
</body></html>