learnpress / inc / libraries / wp-background-process / README.md

README.md in LearnPress – WordPress LMS Plugin for Create and Sell Online Courses 4.4.8, at inc/libraries/wp-background-process/README.md

173 lines 5.1 KB

Raw Download Zip

1	# WP Background Processing
2
3	WP Background Processing can be used to fire off non-blocking asynchronous requests or as a background processing tool, allowing you to queue tasks. Check out the [](https://github.com/A5hleyRich/wp-background-processing-exampleexample plugin](https://github.com/A5hleyRich/wp-background-processing-example](https://github.com/A5hleyRich/wp-background-processing-example) or read the [](https://deliciousbrains.com/background-processing-wordpress/accompanying article](https://deliciousbrains.com/background-processing-wordpress/](https://deliciousbrains.com/background-processing-wordpress/).
4
5	Inspired by [](https://github.com/techcrunch/wp-async-taskTechCrunch WP Asynchronous Tasks](https://github.com/techcrunch/wp-async-task](https://github.com/techcrunch/wp-async-task).
6
7	__Requires PHP 5.2+__
8
9	## Install
10
11	The recommended way to install this library in your project is by loading it through Composer:
12
13	```
14	composer require deliciousbrains/wp-background-processing
15	```
16
17	It is highly recommended to prefix wrap the library class files using [](https://packagist.org/packages/coenjacobs/mozartthe Mozart package](https://packagist.org/packages/coenjacobs/mozart](https://packagist.org/packages/coenjacobs/mozart), to prevent collisions with other projects using this same library.
18
19	## Usage
20
21	### Async Request
22
23	Async requests are useful for pushing slow one-off tasks such as sending emails to a background process. Once the request has been dispatched it will process in the background instantly.
24
25	Extend the `WP_Async_Request` class:
26
27	```php
28	class WP_Example_Request extends WP_Async_Request {
29
30	/**
31	* @var string
32	*/
33	protected $action = 'example_request';
34
35	/**
36	* Handle
37	*
38	* Override this method to perform any actions required
39	* during the async request.
40	*/
41	protected function handle() {
42	// Actions to perform
43	}
44
45	}
46	```
47
48	##### `protected $action`
49
50	Should be set to a unique name.
51
52	##### `protected function handle()`
53
54	Should contain any logic to perform during the non-blocking request. The data passed to the request will be accessible via `$_POST`.
55
56	##### Dispatching Requests
57
58	Instantiate your request:
59
60	`$this->example_request = new WP_Example_Request();`
61
62	Add data to the request if required:
63
64	`$this->example_request->data( array( 'value1' => $value1, 'value2' => $value2 ) );`
65
66	Fire off the request:
67
68	`$this->example_request->dispatch();`
69
70	Chaining is also supported:
71
72	`$this->example_request->data( array( 'data' => $data ) )->dispatch();`
73
74	### Background Process
75
76	Background processes work in a similar fashion to async requests but they allow you to queue tasks. Items pushed onto the queue will be processed in the background once the queue has been dispatched. Queues will also scale based on available server resources, so higher end servers will process more items per batch. Once a batch has completed the next batch will start instantly.
77
78	Health checks run by default every 5 minutes to ensure the queue is running when queued items exist. If the queue has failed it will be restarted.
79
80	Queues work on a first in first out basis, which allows additional items to be pushed to the queue even if it’s already processing.
81
82	Extend the `WP_Background_Process` class:
83
84	```php
85	class WP_Example_Process extends WP_Background_Process {
86
87	/**
88	* @var string
89	*/
90	protected $action = 'example_process';
91
92	/**
93	* Task
94	*
95	* Override this method to perform any actions required on each
96	* queue item. Return the modified item for further processing
97	* in the next pass through. Or, return false to remove the
98	* item from the queue.
99	*
100	* @param mixed $item Queue item to iterate over
101	*
102	* @return mixed
103	*/
104	protected function task( $item ) {
105	// Actions to perform
106
107	return false;
108	}
109
110	/**
111	* Complete
112	*
113	* Override if applicable, but ensure that the below actions are
114	* performed, or, call parent::complete().
115	*/
116	protected function complete() {
117	parent::complete();
118
119	// Show notice to user or perform some other arbitrary task...
120	}
121
122	}
123	```
124
125	##### `protected $action`
126
127	Should be set to a unique name.
128
129	##### `protected function task( $item )`
130
131	Should contain any logic to perform on the queued item. Return `false` to remove the item from the queue or return `$item` to push it back onto the queue for further processing. If the item has been modified and is pushed back onto the queue the current state will be saved before the batch is exited.
132
133	##### `protected function complete()`
134
135	Optionally contain any logic to perform once the queue has completed.
136
137	##### Dispatching Processes
138
139	Instantiate your process:
140
141	`$this->example_process = new WP_Example_Process();`
142
143	Note: You must instantiate your process unconditionally. All requests should do this, even if nothing is pushed to the queue.
144
145	Push items to the queue:
146
147	```php
148	foreach ( $items as $item ) {
149	$this->example_process->push_to_queue( $item );
150	}
151	```
152
153	Save and dispatch the queue:
154
155	`$this->example_process->save()->dispatch();`
156
157	### BasicAuth
158
159	If your site is behind BasicAuth, both async requests and background processes will fail to complete. This is because WP Background Processing relies on the [](http://codex.wordpress.org/HTTP_APIWordPress HTTP API](http://codex.wordpress.org/HTTP_API](http://codex.wordpress.org/HTTP_API), which requires you to attach your BasicAuth credentials to requests. The easiest way to do this is using the following filter:
160
161	```php
162	function wpbp_http_request_args( $r, $url ) {
163	$r['headers']['Authorization'] = 'Basic ' . base64_encode( USERNAME . ':' . PASSWORD );
164
165	return $r;
166	}
167	add_filter( 'http_request_args', 'wpbp_http_request_args', 10, 2);
168	```
169
170	## License
171
172	[](http://www.gnu.org/licenses/gpl-2.0.htmlGPLv2+](http://www.gnu.org/licenses/gpl-2.0.html](http://www.gnu.org/licenses/gpl-2.0.html)
173