Document failed jobs and other things.

Author: taylorotwell

cache.md

@@ -30,6 +30,8 @@ The cache configuration file also contains various other options, which are docu
 
 	Cache::add('key', 'value', $minutes);
 
+The `add` method will return `true` if the item is actually **added** to the cache. Otherwise, the method will return `false`.
+
 **Checking For Existence In Cache**
 
 	if (Cache::has('key'))

pagination.md

@@ -82,6 +82,14 @@ This will generate URLs that look something like this:
 
 	http://example.com/something?page=2&sort=votes
 
+If you wish to append a "hash fragment" to the paginator's URLs, you may use the `fragment` method:
+
+	<?php echo $users->fragment('foo')->links(); ?>
+
+This method call will generate URLs that look something like this:
+
+	http://example.com/something?page=2#foo
+
 <a name="converting-to-json"></a>
 ## Converting To JSON
 

queries.md

@@ -10,6 +10,7 @@
 - [Updates](#updates)
 - [Deletes](#deletes)
 - [Unions](#unions)
+- [Pessimistic Locking](#pessimistic-locking)
 - [Caching Queries](#caching-queries)
 
 <a name="introduction"></a>
@@ -281,6 +282,19 @@ The query builder also provides a quick way to "union" two queries together:
 
 The `unionAll` method is also available, and has the same method signature as `union`.
 
+<a name="pessimistic-locking"></a>
+## Pessimistic Locking
+
+The query builder includes a few functions to help you do "pessimistic locking" on your SELECT statements.
+
+To run the SELECT statement with a "shared lock", you may use the `sharedLock` method on a query:
+
+	DB::table('users')->where('votes', '>', 100)->sharedLock()->get();
+
+To "lock for update" on a SELECT statement, you may use the `lockForUpdate` method on a query:
+
+	DB::table('users')->where('votes', '>', 100)->lockForUpdate()->get();
+
 <a name="caching-queries"></a>
 ## Caching Queries
 

queues.md

@@ -5,6 +5,7 @@
 - [Queueing Closures](#queueing-closures)
 - [Running The Queue Listener](#running-the-queue-listener)
 - [Push Queues](#push-queues)
+- [Failed Jobs](#failed-jobs)
 
 <a name="configuration"></a>
 ## Configuration
@@ -184,3 +185,39 @@ Now, when you login to your Iron dashboard, you will see your new push queue, as
 	});
 
 The `marshal` method will take care of firing the correct job handler class. To fire jobs onto the push queue, just use the same `Queue::push` method used for conventional queues.
+
+<a name="failed-jobs"></a>
+## Failed Jobs
+
+Since things don't always go as planned, sometimes your queued jobs will fail. Don't worry, it happens to the best of us! Laravel includes a convenient way to specify the maximum number of times a job should be attempted. After a job has exceeded this amount of attempts, it will be inserted into a `failed_jobs` table. The failed jobs table name can be configured via the `app/config/queue.php` configuration file.
+
+To create a migration for the `failed_jobs` table, you may use the `queue:failed-table` command:
+
+	php artisan queue:failed-table
+
+You can specify the maximum number of times a job should be attempted using the `--tries` switch on the `queue:listen` command:
+
+	php artisan queue:listen connection-name --tries=3
+
+If you would like to register an event that will be called when a queue job fails, you may use the `Queue::failing` method. This event is a great opportunity to notify your team via e-mail or [HipChat](https://www.hipchat.com).
+
+	Queue::failing(function($job, $data)
+	{
+		//
+	});
+
+To view all of your failed jobs, you may use the `queue:failed` Artisan command:
+
+	php artisan queue:failed
+
+The `queue:failed` command will list the job ID, connection, queue, and failure time. The job ID may be used to retry the failed job. For instance, to retry a failed job that has an ID of 5, the following command should be issued:
+
+	php artisan queue:retry 5
+
+If you would like to delete a failed job, you may use the `queue:forget` command:
+
+	php artisan queue:forget 5
+
+To delete all of your failed jobs, you may use the `queue:flush` command:
+
+	php artisan queue:flush