企业官网建设流程全解析

• 示例工程
• 数据库
• 教程
• 后端

导读

本文以 Microsoft SQL Server 官方示例仓库中 laravel 示例应用（Myboard 待办看板）所依赖的 Illuminate Database 组件文档 为主体，系统讲解 Laravel 数据库层的完整技术栈：独立于框架使用的Capsule 管理器、流式查询构造器、Schema 构建器与Eloquent ORM，并结合仓库源码剖析其连接 SQL Server 的底层机制（DSN 生成、PDO 驱动选择、事务语义）。读完本文，你将掌握如何在不依赖完整 Laravel 框架的情况下用 Illuminate Database 直连 SQL Server，也能够在 Laravel 应用中正确配置sqlsrv连接并完成迁移与 CRUD。

Illuminate Database：既是 Laravel 的数据库内核，也是可独立使用的工具包

Illuminate Database 是 Laravel PHP 框架的数据库层组件，同时也是一个可以脱离框架单独分发的完整数据库工具包。组件文档开门见山地给出了它的能力边界（README.md）：

• 提供富有表达力的查询构造器（expressive query builder），支持链式where、orderBy、join等操作；
• 提供ActiveRecord 风格的 ORM——即 Eloquent，通过模型类直接映射数据表；
• 提供Schema 构建器，用 PHP 代码声明式地建表、改表；
• 当前内置支持MySQL、Postgres、SQL Server、SQLite四种数据库。

在本仓库的 laravel 示例中，composer.json 声明了"laravel/framework": "5.1.*"，并运行在 PHP 7 之上，通过 Microsoft PHP SQL Server Driver 与 Microsoft ODBC SQL Server Driver 连接 SQL Server。这意味着 Illuminate Database 的完整能力——Capsule、查询构造器、Schema 构建器、Eloquent——都可以直接作用于 SQL Server 实例。

用 Capsule 在 Laravel 之外使用 Illuminate Database

组件文档的核心场景是：你不想引入整个 Laravel 框架，只想用它的数据库能力。这时 Capsule（胶囊）管理器就是官方推荐的入口。Capsule 的目标是“把配置库并用于 Laravel 框架之外这件事变得尽可能简单”（README.md）。

最小可运行示例

use Illuminate\Database\Capsule\Manager as Capsule; $capsule = new Capsule; $capsule->addConnection([ 'driver' => 'mysql', 'host' => 'localhost', 'database' => 'database', 'username' => 'root', 'password' => 'password', 'charset' => 'utf8', 'collation' => 'utf8_unicode_ci', 'prefix' => '', ]); // 设置 Eloquent 模型使用的事件分发器...（可选） use Illuminate\Events\Dispatcher; use Illuminate\Container\Container; $capsule->setEventDispatcher(new Dispatcher(new Container)); // 让这个 Capsule 实例可通过静态方法全局访问...（可选） $capsule->setAsGlobal(); // 启动 Eloquent ORM...（可选；除非你已调用 setEventDispatcher()） $capsule->bootEloquent();

Capsule 的源码级工作流程

从 Capsule\Manager.php 的实现可以看到它的启动序列：

1. 构造函数创建（或注入）一个 IoC 容器Container，随后调用setupDefaultConfiguration()与setupManager()；
2. setupDefaultConfiguration()设置默认取行模式PDO::FETCH_OBJ与默认连接名default；
3. setupManager()构建ConnectionFactory并由此创建DatabaseManager——也就是说，Capsule 内部复用的正是 Laravel 全栈场景下的同一套连接管理机制；
4. addConnection(array $config, $name = 'default')把连接配置写入容器的database.connections数组，支持为同一 Capsule 注册多个命名连接；
5. bootEloquent()把DatabaseManager注册为 Eloquent 的 connection resolver，并把事件分发器（若已设置）注册为 Eloquent 的事件分发器，使模型事件（如 observer、创建/更新回调）得以工作；
6. __callStatic魔术方法把未定义的静态调用转发到默认连接，这是Capsule::table()、Capsule::select()能直接可用的根本原因。

组件文档特别标注了一条依赖前提：需要使用 Eloquent observer 时，必须额外安装illuminate/events包（composer require "illuminate/events"），因为事件分发器来自该独立包。

配置参数逐项解读

addConnection的配置数组是连接一切的基础。以文档中的 MySQL 配置为例，逐项说明：

在本仓库 laravel 应用中，sqlsrv连接配置位于 config/database.php，结构完全一致：

'sqlsrv' => [ 'driver' => 'sqlsrv', 'host' => '10.211.55.5', 'database' => env('DB_DATABASE', 'demotekdb'), 'username' => env('DB_USERNAME', 'sa'), 'password' => env('DB_PASSWORD', 'channelV1'), 'prefix' => '', ],

注意其中database、username、password均通过env()读取，分别对应.env中的DB_DATABASE、DB_USERNAME、DB_PASSWORD，并提供了默认值——这是 Laravel 应用推荐的做法，避免把凭据硬编码进配置文件。同一个文件中还保留了sqlite、mysql、pgsql的完整连接模板（含charset、collation、strict、schema等扩展参数），并默认'default' => env('DB_CONNECTION', 'sqlsrv')，即该示例应用默认使用 SQL Server 连接。

对于 SQL Server，SqlServerConnector还额外支持port与appname两个可选参数：设置port时会在 DSN 中拼接端口号；设置appname时对应 DSN 中的APP=项（见下文源码分析）。

三种核心数据库 API

查询构造器（Query Builder）

注册好 Capsule 后，即可使用静态代理调用查询构造器：

$users = Capsule::table('users')->where('votes', '>', 100)->get();

Capsule::table()经由静态转发取得默认连接的查询构造器，where('votes', '>', 100)会被编译为带参数绑定的 SQL（防止注入），get()返回结果集合。

原生 SQL 查询

与 Laravel 的DB门面一致，Capsule 也直接暴露原生查询方法：

$results = Capsule::select('select * from users where id = ?', array(1));

select()第一个参数是原生 SQL，第二个参数是绑定参数数组，?占位符会被安全地替换。这类方法由__callStatic转发到连接实例执行。

Schema 构建器

用 PHP 代码声明式地建表：

Capsule::schema()->create('users', function($table) { $table->increments('id'); $table->string('email')->unique(); $table->timestamps(); });

increments('id')生成自增主键，string('email')->unique()生成带唯一索引的字符串列，timestamps()自动生成created_at/updated_at两个时间戳列。Schema 构建器会依据当前连接驱动（如SqlServerGrammar）把这些声明编译成对应的CREATE TABLE语句——这正是“同一套代码适配多数据库”的关键。

Eloquent ORM

Eloquent 模型只需继承基类即可获得全部能力：

class User extends Illuminate\Database\Eloquent\Model {} $users = User::where('votes', '>', 1)->get();

模型按类名推断表名（User→users）。在本仓库的 laravel 示例中，app/Todo.php 展示了 Eloquent 模型的标准写法：

class Todo extends Model { protected $table = 'todos'; // 显式指定表名 protected $fillable = ['name', 'user_id']; // 允许批量赋值的字段，防 Mass Assignment protected $casts = ['complete' => 'boolean']; // 属性类型转换 }

$fillable白名单机制用于防护批量赋值漏洞，$casts则让complete字段在读取时自动转换为布尔型——这些正是把 SQL Server 中的 BIT 字段映射到 PHP 布尔值的实用手法。

源码级原理：Illuminate Database 如何连接 SQL Server

驱动分发：ConnectionFactory

ConnectionFactory.php 负责把配置变成真实连接：

• createConnector()根据driver分发：mysql→MySqlConnector、pgsql→PostgresConnector、sqlite→SQLiteConnector、sqlsrv→SqlServerConnector；未指定driver或遇到未知驱动会抛出InvalidArgumentException（“A driver must be specified.” / “Unsupported driver [...]”）；
• createConnection()同样按driver返回对应的连接实现类，sqlsrv对应SqlServerConnection；
• make()中若配置含read键，则创建读写分离连接（createReadWriteConnection），读连接的主机数组支持随机挑选——该机制同样适用于 SQL Server 的只读副本场景。

DSN 生成：sqlsrv 与 dblib 双路径

SqlServerConnector.php 是 SQL Server 连接的咽喉，它根据当前 PHP 环境可用的 PDO 驱动自动选择 DSN 格式：

• 若PDO::getAvailableDrivers()包含dblib（即安装了 FreeTDS），则走getDblibDsn()，生成形如dblib:host=HOST;dbname=DB的 DSN；
• 否则走getSqlSrvDsn()，生成形如sqlsrv:Server=HOST;Database=DB;APP=appname的 DSN，主机与端口用逗号分隔（buildHostString($config, ',')）。

同时该类定义了默认 PDO 选项：ATTR_CASE => CASE_NATURAL（保留列名原始大小写）、ATTR_ERRMODE => ERRMODE_EXCEPTION（异常模式报错）、ATTR_ORACLE_NULLS => NULL_NATURAL、ATTR_STRINGIFY_FETCHES => false（不把数值列转为字符串）。这解释了为什么在 Linux 上使用 Microsoft 的sqlsrvPDO 扩展或 FreeTDSdblib驱动都能被 Illuminate Database 自动适配。

事务语义：SqlServerConnection

SqlServerConnection.php 对事务做了针对 SQL Server 的定制：

• 当 PDO 驱动名为sqlsrv时，直接复用父类基于beginTransaction/commit/rollBack的标准事务流程；
• 当驱动为dblib时，则手工执行BEGIN TRAN/COMMIT TRAN/ROLLBACK TRAN，并在捕获异常（含Throwable）后回滚并重新抛出，确保任何情况下都不会残留未提交事务。

这也意味着：同样的DB::transaction(fn () => ...)代码在两种驱动下都能获得正确的事务保证。此外该类还通过SqlServerGrammar（查询/架构语法）与SqlServerProcessor提供 SQL Server 专属的 SQL 方言编译（例如分页、标识列处理），并接入 Doctrine DBAL 的PDOSqlsrv驱动用于 Schema 内省。

在 Laravel 应用中落地：Myboard 示例的完整链路

本仓库的 laravel 示例（Myboard）演示了从配置到运行的全流程（README.md）：

1. 安装前置：Composer、PHP 7、Microsoft PHP SQL Server Driver、Microsoft ODBC SQL Server Driver、Apache，以及mcrypt、mbstring扩展；
2. 安装依赖：在项目根目录执行composer install；
3. 配置数据库：按上文sqlsrv配置段修改 config/database.php；
4. 执行迁移：php artisan migrate，随后chmod 777 -R storage赋予存储目录写权限；
5. 启动应用：php artisan serve。

其中php artisan migrate走的是 Illuminate Database 的 Migrations 子系统（Migrator、MigrationCreator、DatabaseMigrationRepository），迁移记录写入配置的migrations表（本示例中为migrations），从而在 SQL Server 上实现可追踪、可回滚的 Schema 演进。应用层的Todo模型通过 app/Todo.php 映射todos表，配合控制器完成“创建待办、标记状态”两个核心功能，构成了“Schema 构建器建表 → Eloquent 模型读写 → SQL Server 持久化”的完整闭环。

注意事项与适用前提

• 本文所述代码基于仓库中 Laravel 5.1 时代的 Illuminate Database（composer.json声明laravel/framework: 5.1.*），配置键（如strict、schema等）在后续 Laravel 版本中有所演进，升级时需对照新版文档；
• SQL Server 连接的 DSN 形态取决于 PHP 环境实际可用的 PDO 驱动（sqlsrv或dblib），Linux 场景下请确保正确安装对应驱动扩展；
• 在 Laravel 框架外使用 Capsule 时，若需要 Eloquent observer 等事件能力，务必额外composer require "illuminate/events"；
• 连接配置中的凭据建议通过环境变量注入，避免把明文密码写入版本库。

• 示例工程
• 数据库
• 教程
• 后端