Download the PHP package terranc/laravel-s without Composer

🚀 LaravelS is an out-of-the-box adapter between Swoole and Laravel/Lumen.

Please Watch this repository to get the latest updates.

中文文档

Table of Contents

• Features
• Benchmark
• Requirements
• Install
• Run
• Deploy
• Cooperate with Nginx (Recommended)
• Cooperate with Apache
• Enable WebSocket server
• Listen events
  • System events
  • Customized asynchronous events
• Asynchronous task queue
• Millisecond cron job
• Automatically reload after modifying code
• Get the instance of SwooleServer in your project
• Use SwooleTable
• Multi-port mixed protocol
• Coroutine
• Custom process
• Common components
  • Apollo
• Other features
  • Configure Swoole events
  • Serverless
• Important notices
• Users and cases
• Alternatives
• Sponsor
• License

Features

• Built-in Http/WebSocket server

• Multi-port mixed protocol

• Custom process

• Memory resident

• Asynchronous event listening

• Asynchronous task queue

• Millisecond cron job

• Common Components

• Gracefully reload

• Automatically reload after modifying code

• Support Laravel/Lumen both, good compatibility

• Simple & Out of the box

Benchmark

• Which is the fastest ?

• Web Framework Benchmarks

Requirements

Install

1.Require package via Composer(packagist).

2.Register service provider(pick one of two).

• Laravel: in config/app.php file, Laravel 5.5+ supports package discovery automatically, you should skip this step

• Lumen: in bootstrap/app.php file

3.Publish configuration and binaries.

After upgrading LaravelS, you need to republish; click here to see the change notes of each version.

4.Change config/laravels.php: listen_ip, listen_port, refer Settings.

5.Performance tuning

• Adjust kernel parameters

• Number of Workers: LaravelS uses Swoole's Synchronous IO mode, so the larger the worker_num setting, the better the concurrency performance, but it will also cause more memory usage and process switching overhead, so incremental pressure testing is needed to get the bestworker_num.

• Number of Task Workers

Run

Please read the notices carefully before running, Important notices(IMPORTANT).

• Commands: php bin/laravels {start|stop|restart|reload|info|help}.

• Boot options for the commands start and restart.

• Runtime files: start will automatically execute php artisan laravels config and generate these files, developers generally don't need to pay attention to them, it's recommended to add them to .gitignore.

Deploy

It is recommended to supervise the main process through Supervisord, the premise is without option -d and to set swoole.daemonize to false.

Cooperate with Nginx (Recommended)

Demo.

Cooperate with Apache

Enable WebSocket server

The Listening address of WebSocket Sever is the same as Http Server.

1.Create WebSocket Handler class, and implement interface WebSocketHandlerInterface.The instant is automatically instantiated when start, you do not need to manually create it.

2.Modify config/laravels.php.

3.Use SwooleTable to bind FD & UserId, optional, Swoole Table Demo. Also you can use the other global storage services, like Redis/Memcached/MySQL, but be careful that FD will be possible conflicting between multiple Swoole Servers.

4.Cooperate with Nginx (Recommended)

Refer WebSocket Proxy

5.Heartbeat setting

• Heartbeat setting of Swoole

• Proxy read timeout of Nginx

6.Push data in controller

Listen events

System events

Usually, you can reset/destroy some global/static variables, or change the current Request/Response object.

• laravels.received_request After LaravelS parsed Swoole\Http\Request to Illuminate\Http\Request, before Laravel's Kernel handles this request.

• laravels.generated_response After Laravel's Kernel handled the request, before LaravelS parses Illuminate\Http\Response to Swoole\Http\Response.

Customized asynchronous events

This feature depends on AsyncTask of Swoole, your need to set swoole.task_worker_num in config/laravels.php firstly. The performance of asynchronous event processing is influenced by number of Swoole task process, you need to set task_worker_num appropriately.

1.Create event class.

2.Create listener class.

3.Fire event.

Asynchronous task queue

This feature depends on AsyncTask of Swoole, your need to set swoole.task_worker_num in config/laravels.php firstly. The performance of task processing is influenced by number of Swoole task process, you need to set task_worker_num appropriately.

1.Create task class.

2.Deliver task.

Millisecond cron job

Wrapper cron job base on Swoole's Millisecond Timer, replace Linux Crontab.

1.Create cron job class.

2.Register cron job.

3.Note: it will launch multiple timers when build the server cluster, so you need to make sure that launch one timer only to avoid running repetitive task.

4.LaravelS v3.4.0 starts to support the hot restart [Reload] Timer process. After LaravelS receives the SIGUSR1 signal, it waits for max_wait_time(default 5) seconds to end the process, then the Manager process will pull up the Timer process again.

5.If you only need to use minute-level scheduled tasks, it is recommended to enable Hhxsv5\LaravelS\Illuminate\LaravelScheduleJob instead of Linux Crontab, so that you can follow the coding habits of Laravel task scheduling and configure Kernel.

Automatically reload after modifying code

• Via inotify, support Linux only.

  1.Install inotify extension.

  2.Turn on the switch in Settings.

  3.Notice: Modify the file only in Linux to receive the file change events. It's recommended to use the latest Docker. Vagrant Solution.

• Via fswatch, support OS X/Linux/Windows.

  1.Install fswatch.

  2.Run command in your project root directory.

• Via inotifywait, support Linux.

  1.Install inotify-tools.

  2.Run command in your project root directory.

• When the above methods does not work, the ultimate solution: set max_request=1,worker_num=1, so that Worker process will restart after processing a request. The performance of this method is very poor, so only development environment use.

Get the instance of SwooleServer in your project

Use SwooleTable

1.Define Table, support multiple.

All defined tables will be created before Swoole starting.

2.Access Table: all table instances will be bound on SwooleServer, access by app('swoole')->xxxTable.

Multi-port mixed protocol

For more information, please refer to Swoole Server AddListener

To make our main server support more protocols not just Http and WebSocket, we bring the feature multi-port mixed protocol of Swoole in LaravelS and name it Socket. Now, you can build TCP/UDP applications easily on top of Laravel.

1. Create Socket handler class, and extend Hhxsv5\LaravelS\Swoole\Socket\{TcpSocket|UdpSocket|Http|WebSocket}.

   These Socket connections share the same worker processes with your HTTP/WebSocket connections. So it won't be a problem at all if you want to deliver tasks, use SwooleTable, even Laravel components such as DB, Eloquent and so on. At the same time, you can access Swoole\Server\Port object directly by member property swoolePort.

2. Register Sockets.

   About the heartbeat configuration, it can only be set on the main server and cannot be configured on Socket, but the Socket inherits the heartbeat configuration of the main server.

   For TCP socket, onConnect and onClose events will be blocked when dispatch_mode of Swoole is 1/3, so if you want to unblock these two events please set dispatch_mode to 2/4/5.

3. Test.

• TCP: telnet 127.0.0.1 5291

• UDP: [Linux] echo "Hello LaravelS" > /dev/udp/127.0.0.1/5292

4. Register example of other protocols.

   • UDP

   • Http

   • WebSocket: The main server must turn on WebSocket, that is, set websocket.enable to true.

Coroutine

Swoole Coroutine

• Warning: The order of code execution in the coroutine is out of order. The data of the request level should be isolated by the coroutine ID. However, there are many singleton and static attributes in Laravel/Lumen, the data between different requests will affect each other, it's Unsafe. For example, the database connection is a singleton, the same database connection shares the same PDO resource. This is fine in the synchronous blocking mode, but it does not work in the asynchronous coroutine mode. Each query needs to create different connections and maintain IO state of different connections, which requires a connection pool.

• DO NOT enable the coroutine, only the custom process can use the coroutine.

Custom process

Support developers to create special work processes for monitoring, reporting, or other special tasks. Refer addProcess.

1. Create Proccess class, implements CustomProcessInterface.

2. Register TestProcess.

3. Note: The callback() cannot quit. If quit, the Manager process will re-create the process.

4. Example: Write data to a custom process.

Common components

Apollo

LaravelS will pull the Apollo configuration and write it to the .env file when starting. At the same time, LaravelS will start the custom process apollo to monitor the configuration and automatically reload when the configuration changes.

1. Enable Apollo: add --enable-apollo and Apollo parameters to the startup parameters.

2. Support hot updates(optional).

3. List of available parameters.

Other features

Configure Swoole events

Supported events:

1.Create an event class to implement the corresponding interface.

2.Configuration.

Serverless

Alibaba Cloud Function Compute

Function Compute.

1.Modify bootstrap/app.php and set the storage directory. Because the project directory is read-only, the /tmp directory can only be read and written.

2.Create a shell script laravels_bootstrap and grant executable permission.

3.Configure template.xml.

Important notices

• Singleton Issue

  • Under FPM mode, singleton instances will be instantiated and recycled in every request, request start=>instantiate instance=>request end=>recycled instance.

  • Under Swoole Server, All singleton instances will be held in memory, different lifetime from FPM, request start=>instantiate instance=>request end=>do not recycle singleton instance. So need developer to maintain status of singleton instances in every request.

  • Common solutions:

    1. Write a XxxCleaner class to clean up the singleton object state. This class implements the interface Hhxsv5\LaravelS\Illuminate\Cleaners\CleanerInterface and then registers it in cleaners of laravels.php.

    2. Reset status of singleton instances by Middleware.

    3. Re-register ServiceProvider, add XxxServiceProvider into register_providers of file laravels.php. So that reinitialize singleton instances in every request Refer.
  • LaravelS has built in some cleaners.

• Known issues: a package of known issues and solutions.

• Debugging method: Logging, Laravel Dump Server(Laravel 5.7 has been integrated by default).

• Should get all request information from Illuminate\Http\Request Object, $_ENV is readable, $_SERVER is partially readable, CANNOT USE $_GET/$_POST/$_FILES/$_COOKIE/$_REQUEST/$_SESSION/$GLOBALS.

• Respond by Illuminate\Http\Response Object, compatible with echo/vardump()/print_r()，CANNOT USE functions dd()/exit()/die()/header()/setcookie()/http_response_code().

• The various singleton connections will be memory resident, recommend to enable persistent connection.
  1. Database connection, it will reconnect automatically immediately after disconnect.

2. Redis connection, it won't reconnect automatically immediately after disconnect, and will throw an exception about lost connection, reconnect next time. You need to make sure that SELECT DB correctly before operating Redis every time.

• global, static variables which you declared are need to destroy(reset) manually.

• Infinitely appending element into static/global variable will lead to OOM(Out of Memory).

• Linux kernel parameter adjustment

• Pressure test

Alternatives

• swooletw/laravel-swoole

Sponsor

• PayPal

• BTC

• Gitee

License

MIT