Skip to content

Commit 9597217

Browse files
programbeginnerTWprogrambeginnerTW
committed
translation finished
1 parent 0ef9c27 commit 9597217

2 files changed

Lines changed: 282 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,3 +59,216 @@ static:
5959
forbid: [".php", ".htaccess"]
6060
```
6161
You can create your configuration file according to the [Roadrunner document](https://roadrunner.dev/docs).
62+
63+
## Development Suggestions
64+
65+
### Automatic reload
66+
67+
In the default circumstance of RoadRunner, you must restart the server everytime after you revised any PHP files so that your revision will effective.
68+
It seems not that friendly during development.
69+
70+
You can revise your `.rr.yaml` configuration file, add the settings below and start the development mode with `-v -d`.
71+
RoadRunner Server will detect if the PHP files were revised or not, automatically, and reload the Worker instantly.
72+
73+
```yaml
74+
# reload can reset rr servers when files change
75+
reload:
76+
#refresh interval (default 1s)
77+
interval: 1s
78+
#file extensions to watch, defaults to [.php]
79+
patterns: [".php"]
80+
```
81+
82+
The `reload` function is very resource-intensive, please do not activate the option in the formal environment.
83+
84+
### Using Codeigniter4 Request and Response object
85+
86+
Codeigniter4 does not implement the complete [HTTP message interface](https://www.php-fig.org/psr/psr-7/), hence this library focuses on the synchronize of `PSR-7 interface` and `Codeigniter4 HTTP interface`.
87+
88+
Base on the reasons above, You should use `$this->request`, provided by Codeigniter4, or the global function `/Config/Services::('request')` to fetch the correct request object; Use `$this->response` or `/Config/Services::('response')` to fetch the correct response object.
89+
90+
Please be noticed, while constructing response for the users during developing, you should prevent using PHP built-in methods to conduct `header` or `set-cookies` settings. Using the `setHeader()` and `setCookie()`, provided by the [Codeigniter4 Response Object](https://codeigniter.tw/user_guide/outgoing/response.html), to conduct setting.
91+
92+
### Use return to stop controller logic
93+
94+
Inside the Controller, try using return to stop the controller logic. No matter the response of view or API, reduce the `echo` output usage can avoid lets of errors, just like ths:
95+
96+
```php
97+
<?php namespace App\Controllers;
98+
99+
use CodeIgniter\API\ResponseTrait;
100+
101+
class Home extends BaseController
102+
{
103+
use ResponseTrait;
104+
105+
public function index()
106+
{
107+
//Don't use :
108+
//echo view('welcome_message');
109+
return view('welcome_message');
110+
}
111+
112+
/**
113+
* send header
114+
*/
115+
public function sendHeader()
116+
{
117+
$this->response->setHeader("X-Set-Auth-Token", uniqid());
118+
return $this->respond(["status"=>true]);
119+
}
120+
121+
}
122+
```
123+
124+
### Use the built-in Session library
125+
126+
We only focus on supporting the Codeigniter4 built-in [Session library](https://codeigniter.tw/user_guide/libraries/sessions.html), and do not guarantee if using `session_start()` and `$_SEEEION` can work as normal. So, you should avoid using the PHP built-in Session method, change to the Codeigniter4 framework built-in library.
127+
128+
### Developing and debugging in a environment with only one Worker
129+
130+
Since the RoadRunner has fundamentally difference with other server software(i.e. Nginx, Apache), every Codeigniter4 will persist inside RAMs as the form of Worker, HTTP requests will reuse these Workers to process. Hence, we have better develop and test stability under the circumstance with only one Worker to prove it can also work properly under serveral Workers in the formal environment.
131+
132+
You can reference the `.rr.yaml` settings below to lower the amount of Worker to the minimum:
133+
134+
```yaml
135+
http:
136+
address: 0.0.0.0:8080
137+
workers:
138+
command: "php psr-worker.php"
139+
pool:
140+
numWorkers: 1
141+
maxJobs: 1
142+
```
143+
144+
# Global Methods
145+
146+
We offer some Global methods to help you develop your projects more smoothly.
147+
148+
### Dealing with the file uploading
149+
150+
Since the RoadRunner Worker can not transfer the correct `$_FILES` context, the Codeigniter4 file upload class will not be able to work properly. To solve this, we offered a file upload class corresponding the PSR-7 standard for you to deal with file uploading correctly within RoadRunner. Even if you switched your project to another server environment(i.e. spark serve, Apache, Nginx), this class can still work properly, and doesn't need any code modification.
151+
152+
You can fetch the uploaded files by means of `SDPMlab\Ci4Roadrunner\UploadedFileBridge::getPsr7UploadedFiles()` in the controller (or any other places). This method will return an array, consist of Uploaded File objects. The available methods of this object is identical as the regulation of [PSR-7 Uploaded File Interface](https://www.php-fig.org/psr/psr-7/#36-psrhttpmessageuploadedfileinterface).
153+
154+
```php
155+
<?php namespace App\Controllers;
156+
157+
use CodeIgniter\API\ResponseTrait;
158+
use SDPMlab\Ci4Roadrunner\UploadedFileBridge;
159+
160+
class FileUploadTest extends BaseController
161+
{
162+
use ResponseTrait;
163+
164+
protected $format = "json";
165+
/**
166+
* form-data
167+
*/
168+
public function fileUpload(){
169+
$files = UploadedFileBridge::getPsr7UploadedFiles();
170+
$data = [];
171+
foreach ($files as $file) {
172+
$fileEx = array_pop(
173+
explode('.', $file->getClientFilename())
174+
);
175+
$newFileName = uniqid(rand()).".".$fileEx;
176+
$newFilePath = WRITEPATH.'uploads'.DIRECTORY_SEPARATOR.$newFileName;
177+
$file->moveTo($newFilePath);
178+
$data[$file->getClientFilename()] = md5_file($newFilePath);
179+
}
180+
return $this->respondCreated($data);
181+
}
182+
183+
/**
184+
* form-data multiple upload
185+
*/
186+
public function fileMultipleUpload(){
187+
$files = UploadedFileBridge::getPsr7UploadedFiles()["data"];
188+
$data = [];
189+
foreach ($files as $file) {
190+
$fileEx = array_pop(
191+
explode('.', $file->getClientFilename())
192+
);
193+
$newFileName = uniqid(rand()).".".$fileEx;
194+
$newFilePath = WRITEPATH.'uploads'.DIRECTORY_SEPARATOR.$newFileName;
195+
$file->moveTo($newFilePath);
196+
$data[$file->getClientFilename()] = md5_file($newFilePath);
197+
}
198+
return $this->respondCreated($data);
199+
}
200+
```
201+
202+
### Dealing with thrown errors
203+
204+
If you encountered some variables or object content that needed to be confirmed in `-v -d` development mode, you can use the global function `dump()` to throw errors onto the terminal no matter where the program is.
205+
206+
```php
207+
/**
208+
* Dump given value into target output.
209+
*
210+
* @param mixed $value Variable
211+
* @param string $target Possible options: OUTPUT, RETURN, ERROR_LOG, LOGGER.
212+
* @return string|null
213+
*/
214+
function dump($value,string $target = "ERROR_LOG") : ?string;
215+
```
216+
217+
## Avaliable commands
218+
219+
### ciroad:init
220+
221+
Initiallize RoadRunner and its needed files.
222+
223+
* Use
224+
```
225+
$ php spark ciroad:init
226+
```
227+
228+
### ciroad:start
229+
230+
Start RoadRunner Server
231+
232+
* Use
233+
```
234+
$ php spark ciroad:start [Options]
235+
```
236+
237+
* Options:
238+
```
239+
-d During debugging mode, HTTP requests details will be listed on the terminal
240+
-b run in the background
241+
-v output details
242+
```
243+
244+
### ciroad:stop
245+
246+
Kill the RoadRunner running in the background.
247+
248+
* Use
249+
```
250+
$ php spark ciroad:stop
251+
```
252+
253+
### ciroad:reset
254+
255+
Force reload all the HTTP Workers.
256+
257+
* Use
258+
```
259+
$ php spark ciroad:reset
260+
```
261+
262+
### ciroad:status
263+
264+
Check the current Worker operating status
265+
266+
* Use
267+
```
268+
$ php spark ciroad:status [Options]
269+
```
270+
271+
* Options:
272+
```
273+
-i output status continuously per second
274+
```

‎test/README.md‎

Lines changed: 69 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,69 @@
1-
Test Case
1+
# Test Case
2+
3+
This is the Codeigniter4-RoadRunner test case project, it is built by Codeigniter4, and has loaded the Codeigniter4-Roadrunner library class inside the upper directory included in the `src` in.
4+
5+
You can run the test right after you modified the Codeigniter4-Roadrunner project files, verify if the funtions are complete; Or wirte some related program logic in this project to assist your development.
6+
7+
## Test Range
8+
9+
This test case takes the acutal sent CURL Request as test approach, because what Codeigniter4-Roadrunner provide is the synchronization on HTTP Request and Response objects of Roadrunner-Worker and Codeigniter4 (Since Codeigniter4 doesn't implement PSR-7 interface standard). In other words, we just have to verify if the server workes as what we wanted under the actual HTTP connection.
10+
11+
1. BasicTest：Test HTTP `GET`、`POST`、`query`、`form-data`, and the `php echo` output command, and if `header` can process normally and give us outputs.
12+
2. FileUploadTest：Test if file upload class can work correctly and move files.
13+
3. RestTest：Test if Codeigniter4 RESTful library can work properly and can parse every verbs
14+
4. SessionTest：Test if the Session mode, triggered by the file system can work properly.
15+
16+
## Requirements
17+
18+
We recommend you to use the latest PHPUnit. While we're writing scripts, the version we're running at is version `8.5.8`. You might need to use Composer to download the library your project needed back to your develop environment.
19+
20+
```
21+
composer install
22+
```
23+
24+
Next, you must initiallize the environment that Roadrunner needed.
25+
26+
```
27+
php spark ciroad:init
28+
```
29+
30+
Finally, please confirm if the directory has these threee files including `rr`(if your developing under Windows, you will see `rr.exe`), `rr.yaml`, `psr-worker.php`.
31+
32+
## Run Tests
33+
34+
Before running tests, please open `rr.yaml` file first, and ensure this configuration file has these settings:
35+
36+
```yaml
37+
http:
38+
address: 0.0.0.0:8080
39+
workers:
40+
command: "php psr-worker.php"
41+
pool:
42+
numWorkers: 1
43+
maxJobs: 1
44+
45+
static:
46+
enable: true
47+
dir: "public"
48+
forbid: [".php", ".htaccess"]
49+
```
50+
51+
Since Roadrunner-Worker lasts inside RAMs, HTTP requests will reuse Workers to process. Hence we need to test the stability under the environment with only one worker to prove that it can work properly under several workers.
52+
53+
Next, you have to open a terminal and cd to the root directory, type the commands below to run the Roadrunner server:
54+
55+
```
56+
php spark ciroad:start -v -d
57+
```
58+
59+
Finally, open another new terminal and cd to the test project, type the commands below to run tests:
60+
61+
```
62+
./vendor/bin/phpunit
63+
```
64+
65+
If you're running tests under Windows CMD, your command should be like this:
66+
67+
```
68+
vendor\bin\phpunit
69+
```

0 commit comments

Comments
 (0)