ModStart开发文档

# Laravel 版本差异

ModStart 同时维护 Laravel 5.1、Laravel 9、Laravel 13 三条产品线，功能与开发方式保持一致，差异集中在运行环境、.env 变量名、队列进程的启动方式以及少量框架写法上。本页集中说明这些差异，其他章节不再按版本重复描述。

# 版本对照

项目 Laravel 5.1 版 Laravel 9 版 Laravel 13 版
PHP 5.6 7.0 8.0 8.1 8.3 8.4
队列驱动配置 QUEUE_DRIVER QUEUE_DRIVER QUEUE_CONNECTION
队列默认连接 sync sync database（未配置 QUEUE_CONNECTION 时）
队列进程 queue:work 只处理一个任务，queue:listen 常驻 queue:work 常驻，--once 处理一个任务 与 Laravel 9 相同
缓存驱动配置 CACHE_DRIVER CACHE_DRIVER CACHE_STORE
默认 Session 驱动 file file database（部署时显式设置 file）
迁移文件写法 具名类 支持匿名类，产品仍使用具名类 支持匿名类，产品仍使用具名类
应用启动与中间件 app/Http/Kernel.php app/Http/Kernel.php bootstrap/app.php
Blade 指令 不支持 @php 支持 支持

# .env 配置差异

# Laravel 5 / 9
QUEUE_DRIVER=database
QUEUE_CONNECTION=database
CACHE_DRIVER=file
SESSION_DRIVER=file

# Laravel 13
QUEUE_CONNECTION=database
CACHE_STORE=file
SESSION_DRIVER=file
1
2
3
4
5
6
7
8
9
10
  • QUEUE_DRIVER、CACHE_DRIVER 在 Laravel 13 中已不生效（写入不会报错，但会被忽略），必须使用 QUEUE_CONNECTION、CACHE_STORE
  • Laravel 5 / 9 的队列默认连接读取 QUEUE_DRIVER，所以同时写两套变量后，同一份 .env 可以在三个版本间通用
  • Laravel 13 中 QUEUE_CONNECTION、SESSION_DRIVER 缺省值都是 database（缓存已在 config/cache.php 中改回 file），数据库还没建表时会直接 500，部署前请显式写入 sync / file

一键安装、迁移等部署流程请参考 安装说明，Redis 缓存配置请参考 如何开启 Redis 作为缓存驱动。

# 队列启动方式

队列相关命令（queue:table、queue:failed-table、queue:work、queue:listen、queue:flush 等）三个版本写法完全一致，Laravel 9 与 Laravel 13 的命令和参数也完全相同，区别只有两点：

  • Laravel 5.1 的 queue:work 没有 --daemon 时只处理一个任务就退出，也没有 --once、--timeout 参数
  • Laravel 9 / Laravel 13 的 queue:work 默认常驻运行，只处理一个任务需要显式加 --once

# 测试运行一个任务

# Laravel 5.1：不带 --daemon 时处理一个任务后退出，可直接用于测试
/xxx/bin/php /www/example.com/artisan queue:work database --queue=default --sleep=3 --tries=1

# Laravel 9 / Laravel 13：work 默认常驻，测试时加 --once
/xxx/bin/php /www/example.com/artisan queue:work database --queue=default --once --sleep=3 --tries=1 --timeout=86400
1
2
3
4
5

# Supervisor 守护配置

# Laravel 5.1 使用 queue:listen 常驻
command=/xxx/bin/php /www/example.com/artisan queue:listen database --queue=default --sleep=5 --memory=4096 --tries=1 --timeout=86400

# Laravel 9 / Laravel 13 使用 queue:work 常驻（性能更好；queue:listen 同样可用）
command=/xxx/bin/php /www/example.com/artisan queue:work database --queue=default --sleep=5 --memory=4096 --tries=1 --timeout=86400
1
2
3
4
5
  • --queue=default 为队列名称，默认 default，此外还有文档转换 FileConvert、大模型任务 Aigc 等
  • Laravel 13 中 queue:table / queue:failed-table 是 make:queue-table / make:queue-failed-table 的别名，命令写法不变

队列驱动配置、队列表迁移和 Supervisor 的完整步骤见 队列调度。

# 数据库迁移写法

<?php
// Laravel 5.1：具名类，类名与文件名对应
class CreateXxx extends Migration
{
    public function up()
    {
        // ...
    }
}
1
2
3
4
5
6
7
8
9
<?php
// Laravel 9 / Laravel 13：可以使用匿名类
use Illuminate\Database\Migrations\Migration;

return new class extends Migration
{
    public function up(): void
    {
        // ...
    }
};
1
2
3
4
5
6
7
8
9
10
11
  • Laravel 9 / Laravel 13 支持匿名类迁移，但 ModStart 产品和模块的迁移仍然使用具名类（类名与文件名一一对应），保证三个版本通用
  • 迁移文件命名统一为 {日期}_{序号}_{表名}_{操作}.php，三个版本一致

# 应用启动与中间件

Laravel 13 使用 bootstrap/app.php 统一配置路由、中间件、异常和命令：

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__ . '/../routes/web.php',
        commands: __DIR__ . '/../routes/console.php',
    )
    ->withMiddleware(function (Middleware $middleware): void {
        // 全局中间件
    })
    ->withExceptions(function (Exceptions $exceptions): void {
        // 异常上报与渲染
    })
    ->create();
1
2
3
4
5
6
7
8
9
10
11
12
  • Laravel 5.1 / 9 在 app/Http/Kernel.php 中调整中间件，Laravel 13 改到 bootstrap/app.php 的 withMiddleware
  • Laravel 13 中 app/Http/Kernel.php、app/Console/Kernel.php 已不再生效（即使目录中保留了同名文件），中间件、异常、命令注册都以 bootstrap/app.php 为准
  • ModStart 的模块路由在 ModuleServiceProvider 中直接注册，因此 Cookie、Session 中间件在 Laravel 13 中以全局中间件方式挂载

# Blade 与 PHP 语法

模块需要同时兼容三个版本，编写代码时以最低版本为准：

  • Laravel 5.1 不支持 @php / @endphp，模板内嵌 PHP 使用 <?php ?>
  • Blade 输出默认值的 or 写法（如 $param or '默认值'）只在 Laravel 5.1 可用，统一写成三元表达式（见 模块开发兼容性问题）
  • Laravel 5.1 运行在 PHP 5.6 上，禁止使用 ??、?->、fn()、数组解构等 PHP 7+ 语法，在 Laravel 13 上单测通过不代表能在 Laravel 5.1 运行
  • 事件触发统一使用 \ModStart\Core\Util\EventUtil::fire()，不要直接调用 Event::fire() / Event::dispatch()

更多兼容写法见 模块开发兼容性问题。

Last Updated: 27 minutes ago