前言

当路由与请求进行正则匹配后，各个路由的参数就获得了它们各自的数值。然而，有些路由参数变量，我们还想要把它转化为特定的对象，这时候就需要中间件的帮助。 SubstituteBindings 中间件就是一个将路由参数转化为特定对象的组件，它默认可以将特定名称的路由参数转化数据库模型对象，可以转化已绑定的路由参数为把绑定的对象。

SubstituteBindings 中间件的使用

数据库模型隐性转化

首先我们定义了一个带有路由参数的路由：

  1. Route::put('user/{userid}', 'UserController@update');

然后我们在路由的控制器方法中或者路由闭包函数中定义一个数据库模型类型的参数，这个参数名与路由参数相同：

  1. class UserController extends Controller
  2. {
  3.     public function update(UserModel $userid)
  4.     {
  5.         $userid->name = 'taylor';
  6.         $userid->update();
  7.     }
  8. }

这时，路由的参数会被中间件隐性地转化为 UserModel，且模型变量 $userid 的主键值为参数变量 {userid} 正则匹配后的数值。

综合测试样例：

  1. public function testImplicitBindingsWithOptionalParameter()
  2. {
  3.     unset($_SERVER['__test.controller_callAction_parameters']);
  4.     $router->get(($str = str_random()).'/{user}/{defaultNull?}/{team?}', [
  5.         'middleware' => SubstituteBindings::class,
  6.         'uses' => 'Illuminate\Tests\Routing\RouteTestAnotherControllerWithParameterStub@withModels',
  7.     ]);
  9.     $router->dispatch(Request::create($str.'/1', 'GET'));
  11.     $values = array_values($_SERVER['__test.controller_callAction_parameters']);
  13.     $this->assertEquals(1, $values[0]->value);
  14. }
  17. class RouteTestAnotherControllerWithParameterStub extends Controller
  18. {
  19.     public function callAction($method, $parameters)
  20.     {
  21.         $_SERVER['__test.controller_callAction_parameters'] = $parameters;
  22.     }
  24.     public function withModels(RoutingTestUserModel $user)
  25.     {
  26.     }
  27. }
  29. class RoutingTestUserModel extends Model
  30. {
  31.     public function getRouteKeyName()
  32.     {
  33.         return 'id';
  34.     }
  36.     public function where($key, $value)
  37.     {
  38.         $this->value = $value;
  40.         return $this;
  41.     }
  43.     public function first()
  44.     {
  45.         return $this;
  46.     }
  48.     public function firstOrFail()
  49.     {
  50.         return $this;
  51.     }
  52. }

路由显示绑定

除了隐示地转化路由参数外，我们还可以给路由参数显示提供绑定。显示绑定有 bind、model 两种方法。

  • 通过 bind 为参数绑定闭包函数：
  1. public function testRouteBinding()
  2. {
  3.     $router = $this->getRouter();
  4.     $router->get('foo/{bar}', ['middleware' => SubstituteBindings::class, 'uses' => function ($name) {
  5.          return $name;
  6.     }]);
  7.     $router->bind('bar', function ($value) {
  8.         return strtoupper($value);
  9.     });
  10.     $this->assertEquals('TAYLOR', $router->dispatch(Request::create('foo/taylor', 'GET'))->getContent());
  11. }
  • 通过 bind 为参数绑定类方法，可以指定 classname@method，也可以直接使用类名，默认会调用类的 bind 函数：
  1. public function testRouteClassBinding()
  2. {
  3.     $router = $this->getRouter();
  4.     $router->get('foo/{bar}', ['middleware' => SubstituteBindings::class, 'uses' => function ($name) {
  5.         return $name;
  6.     }]);
  7.     $router->bind('bar', 'Illuminate\Tests\Routing\RouteBindingStub');
  8.     $this->assertEquals('TAYLOR', $router->dispatch(Request::create('foo/taylor', 'GET'))->getContent());
  9. }
  11. public function testRouteClassMethodBinding()
  12. {
  13.     $router = $this->getRouter();
  14.     $router->get('foo/{bar}', ['middleware' => SubstituteBindings::class, 'uses' => function ($name) {
  15.         return $name;
  16.     }]);
  17.     $router->bind('bar', 'Illuminate\Tests\Routing\RouteBindingStub@find');
  18.     $this->assertEquals('dragon', $router->dispatch(Request::create('foo/Dragon', 'GET'))->getContent());
  19. }
  21. class RouteBindingStub
  22. {
  23.     public function bind($value, $route)
  24.     {
  25.         return strtoupper($value);
  26.     }
  28.     public function find($value, $route)
  29.     {
  30.         return strtolower($value);
  31.     }
  32. }
  • 通过 model 为参数绑定数据库模型，路由的参数就不需要和控制器方法中的变量名相同，laravel 会利用路由参数的值去调用 where 方法查找对应记录：
  1. if ($model = $instance->where($instance->getRouteKeyName(), $value)->first()) {
  2.      return $model;
  3. }

测试样例如下：

  1. public function testModelBinding()
  2. {
  3.     $router = $this->getRouter();
  4.     $router->get('foo/{bar}', ['middleware' => SubstituteBindings::class, 'uses' => function ($name) {
  5.         return $name;
  6.     }]);
  7.     $router->model('bar', 'Illuminate\Tests\Routing\RouteModelBindingStub');
  8.     $this->assertEquals('TAYLOR', $router->dispatch(Request::create('foo/taylor', 'GET'))->getContent());
  9. }
  11. class RouteModelBindingStub
  12. {
  13.     public function getRouteKeyName()
  14.     {
  15.         return 'id';
  16.     }
  18.     public function where($key, $value)
  19.     {
  20.         $this->value = $value;
  22.         return $this;
  23.     }
  25.     public function first()
  26.     {
  27.         return strtoupper($this->value);
  28.     }
  29. }
  • 若绑定的 model 并没有找到对应路由参数的记录，可以在 model 中定义一个闭包函数，路由参数会调用闭包函数：
  1. public function testModelBindingWithCustomNullReturn()
  2. {
  3.     $router = $this->getRouter();
  4.     $router->get('foo/{bar}', ['middleware' => SubstituteBindings::class, 'uses' => function ($name) {
  5.         return $name;
  6.     }]);
  7.     $router->model('bar', 'Illuminate\Tests\Routing\RouteModelBindingNullStub', function () {
  8.         return 'missing';
  9.     });
  10.     $this->assertEquals('missing', $router->dispatch(Request::create('foo/taylor', 'GET'))->getContent());
  11. }
  13. public function testModelBindingWithBindingClosure()
  14. {
  15.     $router = $this->getRouter();
  16.     $router->get('foo/{bar}', ['middleware' => SubstituteBindings::class, 'uses' => function ($name) {
  17.         return $name;
  18.     }]);
  19.     $router->model('bar', 'Illuminate\Tests\Routing\RouteModelBindingNullStub', function ($value) {
  20.         return (new RouteModelBindingClosureStub())->findAlternate($value);
  21.     });
  22.     $this->assertEquals('tayloralt', $router->dispatch(Request::create('foo/TAYLOR', 'GET'))->getContent());
  23. }
  25. class RouteModelBindingNullStub
  26. {
  27.     public function getRouteKeyName()
  28.     {
  29.         return 'id';
  30.     }
  32.     public function where($key, $value)
  33.     {
  34.         return $this;
  35.     }
  37.     public function first()
  38.     {
  39.     }
  40. }
  42. class RouteModelBindingClosureStub
  43. {
  44.     public function findAlternate($value)
  45.     {
  46.         return strtolower($value).'alt';
  47.     }
  48. }

SubstituteBindings 中间件的源码解析

  1. class SubstituteBindings
  2. {
  3.     public function handle($request, Closure $next)
  4.     {
  5.         $this->router->substituteBindings($route = $request->route());
  7.         $this->router->substituteImplicitBindings($route);
  9.         return $next($request);
  10.     }
  11. }

从代码来看，substituteBindings 用于显示的参数转化，substituteImplicitBindings 用于隐性的参数转化。

隐性参数转化源码解析

进行隐性参数转化，其步骤为：

  • 扫描控制器方法或者闭包函数所有的参数，提取出数据库模型类型对象
  • 根据模型类型对象的 name，找出与模型对象命名相同的路由参数
  • 根据模型类型对象的 classname，构建数据库模型类型对象，根据路由参数的数值在数据库中执行 sql 语句查询
  1. public function substituteImplicitBindings($route)
  2. {
  3.     ImplicitRouteBinding::resolveForRoute($this->container, $route);
  4. }
  6. class ImplicitRouteBinding
  7. {
  8.     public static function resolveForRoute($container, $route)
  9.     {
  10.         $parameters = $route->parameters();
  12.         foreach ($route->signatureParameters(Model::class) as $parameter) {
  13.             $class = $parameter->getClass();
  15.             if (array_key_exists($parameter->name, $parameters) &&
  16.                 ! $route->parameter($parameter->name) instanceof Model) {
  17.                 $method = $parameter->isDefaultValueAvailable() ? 'first' : 'firstOrFail';
  19.                 $model = $container->make($class->name);
  21.                 $route->setParameter(
  22.                     $parameter->name, $model->where(
  23.                         $model->getRouteKeyName(), $parameters[$parameter->name]
  24.                     )->{$method}()
  25.                 );
  26.             }
  27.         }
  28.     }
  29. }

值得注意的是，显示参数转化的优先级要高于隐性转化，如果当前参数已经被 model 函数显示转化，那么该参数并不会进行隐性转化，也就是上面语句 ! $route->parameter($parameter->name) instanceof Model 的作用。

其中扫描控制器方法参数的功能主要利用反射机制：

  1. public function signatureParameters($subClass = null)
  2. {
  3.     return RouteSignatureParameters::fromAction($this->action, $subClass);
  4. }
  6. class RouteSignatureParameters
  7. {
  8.     public static function fromAction(array $action, $subClass = null)
  9.     {
  10.         $parameters = is_string($action['uses'])
  11.                         ? static::fromClassMethodString($action['uses'])
  12.                         : (new ReflectionFunction($action['uses']))->getParameters();
  14.         return is_null($subClass) ? $parameters : array_filter($parameters, function ($p) use ($subClass) {
  15.             return $p->getClass() && $p->getClass()->isSubclassOf($subClass);
  16.         });
  17.     }
  19.     protected static function fromClassMethodString($uses)
  20.     {
  21.         list($class, $method) = Str::parseCallback($uses);
  23.         return (new ReflectionMethod($class, $method))->getParameters();
  24.     }
  25. }

bind 显示参数绑定

路由的 bind 功能由专门的 binders 数组负责，这个数组中保存着所有的需要显示转化的路由参数与他们的转化闭包函数：

  1. public function bind($key, $binder)
  2. {
  3.     $this->binders[str_replace('-', '_', $key)] = RouteBinding::forCallback(
  4.         $this->container, $binder
  5.     );
  6. }
  8. class RouteBinding
  9. {
  10.     public static function forCallback($container, $binder)
  11.     {
  12.         if (is_string($binder)) {
  13.             return static::createClassBinding($container, $binder);
  14.         }
  16.         return $binder;
  17.     }
  19.     protected static function createClassBinding($container, $binding)
  20.     {
  21.         return function ($value, $route) use ($container, $binding) {
  22.             list($class, $method) = Str::parseCallback($binding, 'bind');
  24.             $callable = [$container->make($class), $method];
  26.             return call_user_func($callable, $value, $route);
  27.         };
  28.     }
  29. }

可以看出，bind 函数可以绑定闭包、classname@method、classname，如果仅仅绑定了一个类名，那么程序默认调用类中 bind 方法。

model 显示参数绑定

model 调用 bind 函数，赋给 bind 函数一个提前包装好的闭包函数：

  1. public function model($key, $class, Closure $callback = null)
  2. {
  3.     $this->bind($key, RouteBinding::forModel($this->container, $class, $callback));
  4. }
  6. class RouteBinding
  7. {
  8.     public static function forModel($container, $class, $callback = null)
  9.     {
  10.         return function ($value) use ($container, $class, $callback) {
  11.             if (is_null($value)) {
  12.                 return;
  13.             }
  15.             $instance = $container->make($class);
  17.             if ($model = $instance->where($instance->getRouteKeyName(), $value)->first()) {
  18.                 return $model;
  19.             }
  21.             if ($callback instanceof Closure) {
  22.                 return call_user_func($callback, $value);
  23.             }
  25.             throw (new ModelNotFoundException)->setModel($class);
  26.         };
  27.     }
  28. }

可以看出，这个闭包函数与隐性转化很相似，都是首先创建数据库模型对象，再利用路由参数值来查询数据库，返回对象。 model 还可以提供默认的闭包函数，以供查询不到数据库时调用。

显示路由参数转化

当运行中间件 SubstituteBindings 时，就会将先前绑定的各个闭包函数执行，并对路由参数进行转化：

  1. public function substituteBindings($route)
  2. {
  3.     foreach ($route->parameters() as $key => $value) {
  4.         if (isset($this->binders[$key])) {
  5.             $route->setParameter($key, $this->performBinding($key, $value, $route));
  6.         }
  7.     }
  9.     return $route;
  10. }
  12. protected function performBinding($key, $value, $route)
  13. {
  14.     return call_user_func($this->binders[$key], $value, $route);
  15. }
  17. public function setParameter($name, $value)
  18. {
  19.     $this->parameters();
  21.     $this->parameters[$name] = $value;
  22. }