企业官网建设流程全解析

如果要给 Laravel 这十几年挑一个真正的转折点，我会毫不犹豫选 3.x。这个版本在 2012 年前后出现，正好卡在 PHP 5.3 逐渐普及、旧式框架还在“拼字符串”的阶段，Laravel 3 把 IoC 容器、Eloquent ORM、Blade 模板、Artisan 命令行这些后来撑起整个生态的核心概念全部以“可读的形态”做了第一版落地。很多现在写 Laravel 的人已经习惯了 5.x、10.x、11.x 一套套抽象层，回头去读 3.x 源码反而会觉得清爽——因为那会儿一切都还长在明面上。

这篇内容适合三类读者：第一类是正接手老项目、被一段 Laravel 3 代码困住的维护者；第二类是只学过现代 Laravel、想搞明白“服务容器和门面到底怎么来的”的进阶学习者；第三类是喜欢折腾源码、想看看一个流行框架早期架构取舍的技术爱好者。我会尽量把关键特性拆到“能直接照着写”的程度，也顺手讲清楚每个设计背后的原因。

1. 为什么现在还要花时间研究 Laravel 3.x

1.1 3.x 诞生时的 PHP 生态：从“只要能用”到“讲究设计”的过渡期

要理解 3.x 的设计逻辑，得先看一眼当时的 PHP 世界。PHP 5.3 刚把命名空间（namespace）和闭包（Closure）变成日常可用，很多框架还在用“全局函数 + 配置文件 + 手工 include”的老套路。写页面时最典型的问题是：每个页面开头手动 require 一堆公共文件，请求参数、数据库连接、用户登录状态全是全局变量，测试基本靠浏览器。

Laravel 3 的出现在我当时看来，最大的变化不是多了哪个功能，而是它第一次让我感觉到“框架可以有自己的运行时”。路由注册、过滤器、事件、IoC 容器、门面类，这些概念在 3.x 里形成了一套完整的启动流程：请求先打到 public/index.php，经过路由分发，再进入控制器，最后把 View 渲染成响应。这套流程在今天的 PHP 框架里稀松平常，但在那会儿已经是“现代工程化”的味道了。

这个版本面向的场景也特别明确：中小型 Web 应用、内容站、后台管理工具。它没有像后来 4.x、5.x 那样把组件拆成几十个独立包，而是把路由、ORM、模板、迁移、认证、缓存、会话全部内置在一个紧凑的框架目录里。对当时的开发者来说，Laravel 3 的最大价值是“拿来就能跑，目录结构一看就懂”，这恰恰是后来诸多版本逐渐丢失的可读性。

1.2 一张表看懂 3.x 和前后版本的分野

我见过不少人是直接从 Laravel 5.1、5.5 上的手，再去看 3.x 感觉哪哪都对不上。这里整理一个我常用的对照表，方便定位差异：

这张表里最值得记住的一点是：3.x 是一个“单体但清晰”的框架，4.x 之后才走向“组件化 + 生态化”。所以如果你在研究 3.x，别用今天的标准去苛求它，但如果能把 3.x 的架构吃透，后面看 4.x、5.x 的源码反而会觉得亲切，很多概念只是换了一层衣服。

2. IoC 容器：3.x 架构最硬核的部分

2.1 绑定、解析和单例的三板斧

Laravel 3 的 IoC 容器是我愿意称之为“整个框架心脏”的部分。它不复杂：你用 IoC::register 把一个类或闭包绑定到某个名字上，再用 IoC::resolve 取出来。支持三种注册方式：普通绑定（每次解析都重新构建）、singleton（整个生命周期共享一个实例）、instance（直接塞一个现成对象进去）。

实际开发里最常用的场景是“替接口绑定实现”。举个例子，比如你的项目里有一个邮件发送服务，最开始用原生 mail 函数，后来想换成基于日志的调试实现。没有容器的时候，你得在控制器里手动 new 具体的类，到处改代码；有容器之后，只需要在 application/start.php 里写：

// 绑定接口到实现 IoC::register('mailer', function() { if (Config::get('app.debug')) { return new Log_Mailer; } return new Smtp_Mailer(Config::get('mail.host')); }); // 控制器里拿服务 $mailer = IoC::resolve('mailer'); $mailer->send($recipient, $subject, $body);

这段代码在当时的杀伤力很大，因为它让“对象怎么创建”从业务代码里剥了出来。控制器不再关心 Smtp_Mailer 的构造参数到底是从哪来的，只关心我拿到的东西有 send 方法就行。这也是依赖注入思想在 PHP 框架里的第一次大规模普及。

我自己的经验是：3.x 的 IoC 容器虽然功能简单，但它的注册表是全局的、保存在容器静态属性里，这意味着你可以在任何地方 Register，也可以在路由过滤器、事件监听里随时 Resolve。这个设计有好处也有坑，好处是扩展非常自由，坏处是如果项目大起来，绑定之间的依赖关系会变得隐晦。我后来从 3.x 迁到 4.x 时，最大的工作量之一就是把散落在各处的 IoC::register 聚集到 ServiceProvider 里。

2.2 门面类：静态方法背后的容器调度

用过 Laravel 的人都知道 DB::table()、Cache::get()、Auth::check() 这种静态写法。在 3.x，这些门面类（Facade）的本质是 IoC 容器的“静态代理”。所谓代理，就是你在代码里写 DB::query()，实际上门面类会去容器里找到真正处理数据库的对象，再调用对应方法。

以 DB 门面为例，它的简化实现思路是这样的：

class DB { public static function __callStatic($method, $parameters) { $connection = IoC::resolve('db'); return call_user_func_array(array($connection, $method), $parameters); } }

也就是说，DB::table('users') 等价于 IoC::resolve('db')->table('users')。门面给了你便捷的静态调用，同时不破坏底层的依赖注入结构。很多刚接触的人会误以为“门面就是全局函数”，其实门面后面挂着的永远是容器里的真实对象。

我在教别人看 3.x 源码时经常说：遇到一个静态调用就想两层，第一层是门面类本身的 __callStatic，第二层是它 resolve 出来的真实类。想通了这两层，Laravel 的“魔法”就少了一半。这个版本里几乎每个核心组件都有对应的门面：Config、Cache、Session、Auth、Event、Validator、Form、HTML、File、Input 等等，整个应用做起来就像是“容器 + 门面 + 业务代码”三层结构。

2.3 控制器和模型怎么接入依赖注入

3.x 的控制器没有像现代 Laravel 那样在构造方法里直接写参数类型就能自动注入，它更多是靠门面 + 手动 IoC::resolve 来获取依赖。但框架也留了一个很巧妙的入口：路由参数可以自动传入控制器方法。比如这样定义：

Route::get('user/{id}', 'user@show'); // application/controllers/user.php class User_Controller extends Base_Controller { public function action_show($id) { $user = User::find($id); return View::make('user.profile')->with('user', $user); } }

控制器方法名用 action_ 前缀区分 HTTP 动作，参数按路由顺序注入，这套约定当时用起来很顺手。至于依赖注入，3.x 时代的普遍做法是在构造函数里拿容器：

class User_Controller extends Base_Controller { private $mailer; public function __construct() { parent::__construct(); $this->mailer = IoC::resolve('mailer'); } public function action_create() { // ... $this->mailer->send($email, '欢迎', '内容'); } }

这种写法比直接 new 好很多，因为绑定关系集中在 start.php，切换邮件实现不用改控制器。但它也确实没有现代 Laravel 的“自动解析”那么爽。如果你是从 5.x 回来学 3.x，可以把它理解成“手动版依赖注入”，容器负责创建和共享，开发者负责按需取用。

3. Eloquent ORM 的成型期：会写模型也得会避坑

3.1 模型定义、时间戳和查询构造器的正确姿势

Eloquent 在 3.x 里已经具备后来绝大多数核心能力，但写法上更“原始”。定义一个模型非常简单，不需要继承复杂的基类，只要继承 Eloquent 并指定表名：

class Post extends Eloquent { public static $table = 'posts'; public static $timestamps = true; }

如果表名是模型名的复数形式，可以省略 $table。$timestamps 开启后，模型在创建和更新时会自动维护 created_at 和 updated_at 两个字段。这里有个我踩过的坑：3.x 默认时间戳格式是 datetime，但如果你的表字段设计成 int 类型，还想用 $timestamps，就必须在模型里处理格式，或者干脆自己维护时间字段，否则写入的 0000-00-00 会让你查数据时一头雾水。

查询构造器在 3.x 里也相当能打。它比 Eloquent 更贴近数据库，适合复杂条件查询：

$users = DB::table('users') ->where('active', 1) ->order_by('last_login', 'desc') ->take(15) ->get(); $count = DB::table('users')->where('active', 1)->count();

注意这里的方法名是 order_by / take / get，全是下划线风格。Laravel 4 之后才改成 orderBy / take / get。老项目里如果混用写法，直接报 BadMethodCallException，这是我帮别人排查时最高频的错误之一。

3.2 关联关系与预加载的写法和性能要点

3.x 的 Eloquent 关联定义也是方法 + 下划线命名。一对多、一对一、多对多都有对应方法：

class Post extends Eloquent { public function comments() { return $this->has_many('Comment'); } public function author() { return $this->belongs_to('User'); } }

用起来和现代版本大致一样：$post->comments()->get()、$post->comments 也能触发延迟加载。这里真正值得展开的是预加载。N+1 查询问题从 3.x 就存在，解决方式也一样，用 with：

$posts = Post::with('comments', 'author')->get(); foreach ($posts as $post) { echo $post->author->username . '<br>'; foreach ($post->comments as $comment) { echo $comment->content . '<br>'; } }

with 会让 Eloquent 一次性把关联数据查出来，再按外键映射到对应模型上，把 N+1 次查询压缩到 2~3 次。我在 3.x 项目里做列表页时，基本规则就是：列表展示里用到的关联全塞进 with，绝不靠延迟加载一层层捞。原因很简单，那时候的数据库连接和索引优化远不如今天，一条循环里多个查询很容易把页面拖到几百毫秒以上。

3.3 批量赋值保护：3.2 之后必须养成的习惯

讲 3.x 的 Eloquent，不能漏掉批量赋值保护。这个机制在 3.2 版本里被强化，原因是很多开发者直接用 Input::all() 传给模型创建，导致用户可以通过表单里多塞一个 is_admin 字段把自己变成管理员。3.x 的做法是让模型声明允许或禁止的字段：

class User extends Eloquent { public static $accessible = array('name', 'email', 'password'); }

这样当你做 User::create($input) 时，只有 accessible 里声明的字段会被写进数据库，其余字段全部被丢弃。另一种写法是用 $guarded 声明禁止项，比如：

public static $guarded = array('id', 'is_admin');

习惯上我倾向用 $accessible 白名单，更稳妥，新加的字段默认不可写，不会因为你忘了在 guarded 里加而出现漏洞。现在看这个机制，其实就是现代 Laravel 的 $fillable。所以如果你维护的是老项目，升级时把 $accessible 改成 $fillable 就能平滑过渡。

4. 路由、Artisan 与 Blade：一天下来最常用的三件套

4.1 路由过滤器和控制器路由怎么组织

Laravel 3 的路由系统和业务代码的绑定非常紧密。最基础的写法是把匿名函数塞给闭包路由：

Route::get('/', function() { return 'Hello Laravel 3'; }); Route::post('user/login', function() { // 处理登录表单 });

但真实项目里我更推荐用控制器路由，把逻辑收进控制器方法：

Route::get('user/profile', 'user@profile'); Route::post('user/update', 'user@update');

3.x 还支持 RESTful 控制器，Route::controller('admin') 之后，控制器里的 action_get_index、action_post_login 方法会自动对应 GET /admin/index、POST /admin/login。这在写管理后台时特别省事，不用为每个动作单独注册路由。

过滤器是 3.x 路由层另一个亮点。它允许你在路由执行前/后挂逻辑，比如认证检查、日志记录、CSRF 校验：

Route::filter('auth', function() { if ( ! Auth::check()) { return Redirect::to('login'); } }); Route::get('dashboard', array('before' => 'auth', 'uses' => 'dashboard@index'));

这段代码把“用户是否登录”这个横切关注点从控制器里抽了出去。Controller 只关心业务逻辑，过滤器负责前置条件。后来我维护老项目时，也习惯把权限判断尽量做成过滤器，而不是散落在各个 action 里，这样新增页面时加一行路由配置就能带上权限，不容易漏。

4.2 Artisan：迁移、种子、任务的统一工作流

Artisan 在 3.x 已经是一个相当完整的命令行工具。我第一次用 php artisan migrate 时，最大的感受是“原来数据库结构也能进版本管理”。3.x 的迁移类是一个普通 PHP 类，包含 up 和 down 两个方法：

// application/migrations/2012_03_10_create_users.php class Create_Users { public function up() { Schema::create('users', function($table) { $table->increments('id'); $table->string('username', 32); $table->string('password', 64); $table->timestamps(); }); } public function down() { Schema::drop('users'); } }

生成迁移文件的命令是 php artisan migrate:make create_users。执行迁移是 php artisan migrate，回滚是 php artisan migrate:rollback。有一个细节很容易踩坑：第一次执行 migrate 前，需要先跑 php artisan migrate:install 才会建 migration 记录表，否则 Artisan 会提示找不到迁移历史表。

种子数据（Seeder）在 3.x 中也已经存在，配合迁移可以做完整的初始化：php artisan db:seed 会执行 application/seeders/ 下的种子类。再加上任务（Task）系统——php artisan task:run 可以执行 application/tasks 里定义的任务——Artisan 在 3.x 就已经是一个能支撑“建表、灌数据、跑定时任务”的统一入口。这在当时大大提升了部署效率，我那时候从开发环境到生产环境的流程，基本就是三行命令：migrate、seed、再清缓存。

4.3 Blade 模板三段式：编译原理和缓存清理

Blade 模板引擎是 3.x 的另一项重要创新。很多人第一次把 .blade.php 扔进 views 目录时的反应是：这不就是 PHP 模板做了层语法糖吗？但它做得很聪明。Blade 引擎会把模板编译成原生 PHP 文件，存放在 storage/views 目录，之后每次渲染直接用编译后的 PHP 文件，完全不影响性能。

布局模板和区块这两个概念在 3.x 已经成熟。主布局用 yield 占位，子视图用 section 填充：

// views/layout.blade.php <html> <head><title>我的站</title></head> <body> @yield('content') @yield('sidebar', '默认侧边栏内容') </body> </html> // views/home.blade.php @extends('layout') @section('content') <h1>欢迎</h1> @endsection

控制流语法也和现代版本一脉相承：

@if ($user) <p>{{ $user->username }}</p> @else <p>请登录</p> @endif @foreach ($posts as $post) <h2>{{ $post->title }}</h2> @endforeach

需要特别提醒：3.x 的 {{ }} 并不会像 4.x 那样默认做 HTML 转义，官方推荐的输出转义是 e() 辅助函数。如果你拿到的是来自用户提交的数据，最好写成 {{ e($user->bio) }}，否则有 XSS 风险。这是我在老项目安全审查时必查的一处。另外，因为 Blade 有编译缓存，修改了模板但页面没变化时，先去清 storage/views 下的文件，别急着怀疑服务器没更新。

5. 应用基础设施：缓存、会话、认证与 Bundle

5.1 缓存和会话驱动怎么选：一张表讲清

3.x 的缓存组件提供了一套统一的 API：Cache::put(key, value, minutes)、Cache::get(key)、Cache::forget(key)。这套接口背后支持多种驱动，我在不同项目里实测后的选型建议如下：

我自己的习惯是：开发环境一律 file，生产单机用 memcached 或 redis，数据库驱动只在没有内存服务可用时兜底。还有一点，3.x 的缓存是把数据序列化后存储的，所以如果你缓存一个很大的对象数组，要注意序列化开销。遇到“缓存读写慢”的问题，先看是不是缓存了过大的结构。

会话驱动和缓存驱动几乎一一对应。Cookie 驱动是 3.x 特有的轻量方案，适合只存少量数据，但浏览器 Cookie 有 4KB 上限，塞多了会静默失败。我在用 Session::flash('status', '保存成功') 这种一次性消息时，更喜欢 file 或 database 驱动，回跳后仍然能取到。

5.2 认证系统工作机制

3.x 的认证系统是集成在 Auth 门面里的，核心逻辑围绕 attempts 和 user 两个概念进行。登录时，把表单数据交给 Auth::attempt，框架会拿用户名 + 密码去查表，并用 Hash::check 验证密码哈希：

if (Auth::attempt(array('username' => Input::get('username'), 'password' => Input::get('password')))) { return Redirect::to('dashboard'); } else { return Redirect::to('login')->with('error', '账号或密码错误'); }

登录成功后，可以通过 Auth::user() 拿到当前用户模型，Auth::check() 判断是否已登录，Auth::logout() 退出登录。密码存储用的是 PHP 自带的 hash 算法（3.x 里 Hash::make 默认使用 bcrypt 的前身实现），这在当时已经是很规范的安全实践，比很多项目里裸存明文密码强得多。

如果你要在老项目里扩展认证逻辑，比如“登录后记录最后登录时间”，3.x 的事件系统很合适：

Event::listen('auth.login', function($user) { $user->last_login = time(); $user->save(); });

这比把逻辑写死在控制器里强太多。事件监听可以在任何地方挂载（比如起始文件或 Bundle 里），实现解耦，也方便第三方扩展接管认证后的动作。

5.3 Bundle：Laravel 最早的模块化扩展玩法

3.x 时期还没有 Composer 一统天下的局面，Laravel 用 Bundle 来解决代码复用和模块化问题。一个 Bundle 就是一个独立目录，里面可以有路由、控制器、模型、视图、迁移、任务，甚至自己的配置。要注册一个 Bundle，在 application/bundles.php 里加一行：

return array( 'admin' => array('auto' => true, 'handles' => 'admin'), 'forum' => array('auto' => false), );

auto 为 true 表示框架启动时自动加载，handles 表示该 Bundle 接管某个 URL 前缀的路由。跨 Bundle 引用时，视图可以写 View::make('forum::thread.list')，路由可以写 Route::get('thread/{id}', 'forum::thread@show')。

Bundle 的思想后来被 Composer Package + ServiceProvider 取代，但它让我养成了一个好习惯：不同业务域尽量拆开，别把所有控制器、模型全堆在 application 里。我见过 3.x 项目几百个控制器堆在一个目录里的惨状，后来维护成本极高。如果你仍在使用老版本，可以从现在开始把明显的功能域拆成 Bundle，哪怕不发布，也能让项目清爽不少。

6. 实战排坑记录与升级迁移参考

6.1 七问七答：Laravel 3.x 故障排查实录

这里把我在老项目维护中遇到的高频问题整理成速查表，基本覆盖了从路由到模板、从 ORM 到命令行的大部分坑：

说一个我印象很深的案例：有个老项目上线后用户反馈登录时不时失败，排查半天发现是会话驱动用了 Cookie，而项目里的多域名跳转把部分 Cookie 丢弃了，导致 Auth 状态在不同域名间不同步。改成 database 驱动后问题彻底消失。这个教训告诉我，老项目选型时多考虑部署形态，别只看开发环境顺手。

6.2 从 3.x 迁移到现代版本时最容易踩的映射坑

如果你接手的是一个 3.x 老项目，最终大概率要迁到 5.x 或更高版本。这个过程中最磨人的不是 SQL 或业务逻辑，而是一堆命名、类结构和包管理的差异。这里分享几个我在迁移时踩过的映射坑。

第一，静态调用变门面。3.x 里很多全局的 Helper 函数在升级后会移除或改名，比如 Input::get 到 request()->input，Redirect::to 到 redirect()。迁移时别盲目改，先建一个调用映射表，把老函数逐一对应到新 API。第二，Bundle 要拆成 ServiceProvider，然后把原来 Bundle 里的路由、事件、命令注册逻辑搬进 provider 的 register/boot 方法。第三，模板语法要细查，3.x 的 @yield('content') 基本不变，但 {{ }} 的转义行为和 4.x 之后不再一样，老页面里所有直接输出用户数据的地方都要确认是否需要加转义。

迁移过程里我个人的建议是：分步骤走，先搭新框架 + 导入老数据库 + 跑通核心路由，再逐步迁移控制器和模板。别追求一次性迁完，因为 3.x 到 5.x 的跨度太大，一次提交太容易出现“哪都改过、但哪都没验证”的失控状态。每次迁完一个模块，就用老的测试数据跑一遍关键路径。

最后说一点我个人在反复折腾老版本后的体会：Laravel 3.x 的代码虽然老，但它把“框架的骨架”暴露得很清楚——容器怎么组装对象、门面怎么代理调用、Eloquent 怎么映射关系、Blade 怎么编译模板。如果你现在有时间，翻一翻它在 public/index.php、laravel/ 核心目录里的实现，比看十篇架构分析文章都有用。老版本不是拿来生产环境继续扛的，而是拿来当教材的。真遇到项目必须升级，也尽量找一条“理解优先、分批搬迁”的路，别被表面的语法差异吓住。