欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页  >  php教程

Yii源码阅读笔记

程序员文章站 2022-05-06 14:50:25
...

概述 通常我们会使用模板引擎来渲染HTML页面,而不是使用HTML代码中插入PHP代码的方式来编写动态页面。Yii框架中模板引擎也是作为组件引入的,默认ID为viewRenderer,但从Yii源码阅读笔记 - 组件集成可以看到Yii Web应用加载的核心组件中并没有viewRenderer

概述

通常我们会使用模板引擎来渲染HTML页面,而不是使用HTML代码中插入PHP代码的方式来编写动态页面。Yii框架中模板引擎也是作为组件引入的,默认ID为viewRenderer, 但从Yii源码阅读笔记 - 组件集成可以看到Yii Web应用加载的核心组件中并没有viewRenderer,所以需要自己配置。 Yii提供了一个直接可用的模板引擎组件类CPradoViewRenderer(见文件yii/framework/web/renderers/CPradoViewRenderer.php),该模板引擎类让开发者可以使用类Prado框架的模板语法。

如果你想使用Smarty这种第三方模板引擎,有两种方式将模板引擎引入Yii中使用(以Smarty为例):

  1. 将Smarty封装成一个Yii的普通组件,然后配置加载到Yii::app()。假设组件ID为smarty,那么就可以通过Yii::app()->smarty来调用组件。
  2. 参考CPradoViewRenderer类的实现,将Smarty封装成一个模板引擎组件,并以ID为viewRenderer进行配置加载。

相比而言,第二种方式更好。原因是:第一种方式由于每种第三方模板引擎的接口不一样,如果应用要替换模板引擎,就需要修改控制器类中的代码。而第二种方式由于第三方组件统一封装成Yii框架定义的模板引擎接口形式, 所以如果要替换模板引擎,只需修改自定义模板引擎组件类的接口实现就可以了。这样调用模板引擎的代码逻辑就只依赖接口形式,而不是依赖于接口实现,从而实现解耦。

本文主要分析第二种方式的实现。

分析

Yii中对页面模板进行渲染可以调用CController类(见文件yii/framework/web/CController.php)的方法render,实现如下:

/**
 * Renders a view with a layout.
 *
 * This method first calls {@link renderPartial} to render the view (called content view).
 * It then renders the layout view which may embed the content view at appropriate place.
 * In the layout view, the content view rendering result can be accessed via variable
 * $content. At the end, it calls {@link processOutput} to insert scripts
 * and dynamic contents if they are available.
 *
 * By default, the layout view script is "protected/views/layouts/main.php".
 * This may be customized by changing {@link layout}.
 *
 * @param string $view name of the view to be rendered. See {@link getViewFile} for details
 * about how the view script is resolved.
 * @param array $data data to be extracted into PHP variables and made available to the view script
 * @param boolean $return whether the rendering result should be returned instead of being displayed to end users.
 * @return string the rendering result. Null if the rendering result is not required.
 * @see renderPartial
 * @see getLayoutFile
 */
public function render($view,$data=null,$return=false)
{
    // beforeRender默认返回true,
    // 可以在自定义controller类中重写该方法,实现渲染之前的预处理
    // 但和beforeAction一样,应该要返回true或false
    if($this->beforeRender($view))
    {
        // 渲染真正的内容部分
        $output=$this->renderPartial($view,$data,true);
        // 获取布局文件
        if(($layoutFile=$this->getLayoutFile($this->layout))!==false)
            // 渲染整个页面
            $output=$this->renderFile($layoutFile,array('content'=>$output),true);
        // 渲染的后处理,默认为空,在processOutput之前调用
        $this->afterRender($view,$output);
        // 对渲染结果进行处理
        $output=$this->processOutput($output);
        // 可以将渲染结果作为方法的返回值返回,或者直接输出到用户浏览器
        if($return)
            return $output;
        else
            echo $output;
    }
}

其中方法renderPartial的实现如下所示:

/**
 * Renders a view.
 *
 * The named view refers to a PHP script (resolved via {@link getViewFile})
 * that is included by this method. If $data is an associative array,
 * it will be extracted as PHP variables and made available to the script.
 *
 * This method differs from {@link render()} in that it does not
 * apply a layout to the rendered result. It is thus mostly used
 * in rendering a partial view, or an AJAX response.
 *
 * @param string $view name of the view to be rendered. See {@link getViewFile} for details
 * about how the view script is resolved.
 * @param array $data data to be extracted into PHP variables and made available to the view script
 * @param boolean $return whether the rendering result should be returned instead of being displayed to end users
 * @param boolean $processOutput whether the rendering result should be postprocessed using {@link processOutput}.
 * @return string the rendering result. Null if the rendering result is not required.
 * @throws CException if the view does not exist
 * @see getViewFile
 * @see processOutput
 * @see render
 */
public function renderPartial($view,$data=null,$return=false,$processOutput=false)
{
    // 获取目标模板文件
    $viewFile=$this->getViewFile($view);
    echo (basename(__FILE__).':'.__LINE__.':'.__FUNCTION__.'() $viewFile '. var_export($viewFile, true));
    if(($viewFile)!==false)
    {
        // 渲染
        $output=$this->renderFile($viewFile,$data,true);
        // 如果$processOutput为真,则也会对结果进行后处理
        if($processOutput)
            $output=$this->processOutput($output);
        if($return)
            return $output;
        else
            echo $output;
    }
    else
        throw new CException(Yii::t('yii','{controller} cannot find the requested view "{view}".',
            array('{controller}'=>get_class($this), '{view}'=>$view)));
}

renderPartial方法并不会渲染出一个完整的页面,只是渲染页面的一部分,通常是主体部分,或者为AJAX请求渲染出响应结果。 其中调用的getViewFile方法实现如下:

public function getViewFile($viewName)
{
    // 如果未配置theme项,即表示不使用theme,那么getTheme方法返回null
    if(($theme=Yii::app()->getTheme())!==null && ($viewFile=$theme->getViewFile($this,$viewName))!==false)
        return $viewFile;
    // viewPath默认为views,可配置
    $moduleViewPath=$basePath=Yii::app()->getViewPath();
    echo (basename(__FILE__).':'.__LINE__.':'.__FUNCTION__.'() $moduleViewPath '. var_export($moduleViewPath, true)),"\n";
    // 模块化,如果没有,则getModule返回null
    if(($module=$this->getModule())!==null)
        $moduleViewPath=$module->getViewPath();
    // $this->getViewPath()得到的路径相比$moduleViewPath就是多了controller的ID一级
    return $this->resolveViewFile($viewName,$this->getViewPath(),$basePath,$moduleViewPath);
}

代码中$this->getViewPath()方法的实现如下:

public function getViewPath()
{
    if(($module=$this->getModule())===null)
        $module=Yii::app();
    // $this->getId()是得到当前controller的ID,这个ID是在controller实例化时构造方法中赋值给属性_id的。
    // 这也就意味着页面模板文件需要按照controller的ID分目录存放
    return $module->getViewPath().DIRECTORY_SEPARATOR.$this->getId();
}

getViewFile中最后调用的方法resolveViewFile实现如下所示:

public function resolveViewFile($viewName,$viewPath,$basePath,$moduleViewPath=null)
{
    // 连模板文件名都不给,还玩个屁啊
    if(empty($viewName))
        return false;
    // 若$moduleViewPath未设置,则在应用的页面模板的根目录下找
    if($moduleViewPath===null)
        $moduleViewPath=$basePath;
    // 获取设置的模板渲染引擎,其实就是加载ID为viewRenderer的组件
    if(($renderer=Yii::app()->getViewRenderer())!==null)
        // 模板文件的扩展类型默认为'.php',可配置
        $extension=$renderer->fileExtension;
    else
        $extension='.php';
    echo (basename(__FILE__).':'.__LINE__.':'.__FUNCTION__.'() $extension '. var_export($extension, true)),"\n";
    // 如果指定的模板文件名以/开始
    if($viewName[0]==='/')
    {
        // 如果指定的模板文件名以//开始,则表示在模板的根目录下查找
        if(strncmp($viewName,'//',2)===0)
            $viewFile=$basePath.$viewName;
        // 否则(以单个/开始)在模块的模板目录下查找
        else
            $viewFile=$moduleViewPath.$viewName;
    }
    // 如果模板文件名中存在.且.不出现在第一个位置,则认为这是一个路径别名,需要转换真正的路径
    elseif(strpos($viewName,'.'))
        $viewFile=Yii::getPathOfAlias($viewName);
    else
        // 否则在当前controller的模板目录下找
        $viewFile=$viewPath.DIRECTORY_SEPARATOR.$viewName;
    // 可能站点是需要国际化的
    // 所以在找到默认的模板文件后,尝试找一下对应用户目标语言的模板文件
    if(is_file($viewFile.$extension))
        return Yii::app()->findLocalizedFile($viewFile.$extension);
    // 如果不存在指定扩展类型的模板文件,且扩展类型不为'.php',则看一下'.php'类型的模板文件是否存在
    elseif($extension!=='.php' && is_file($viewFile.'.php'))
        return Yii::app()->findLocalizedFile($viewFile.'.php');
    else
        return false;
}

方法resolveViewFile中最后调用的方法findLocalizedFile,定义于抽象类CApplication中,实现如下:

public function findLocalizedFile($srcFile,$srcLanguage=null,$language=null)
{
    if($srcLanguage===null)
        // sourceLanguage为public的属性,可配置,默认为en_us
        $srcLanguage=$this->sourceLanguage;
    if($language===null)
        // getLanguage的实现:$this->_language===null ? $this->sourceLanguage : $this->_language
        // 默认_language为未赋值,即null,所以取到的还是sourceLanguage属性值。
        // 但因为__set,所以也是可赋值的,这个赋值不应该是配置造成的,应该是根据用户的cookie中指定的语言选项,在请求处理时设置的,表示用户的目标语言
        $language=$this->getLanguage();
    // 如果用户的目标语言(或者用户选择的是默认语言),则直接返回默认模板文件的路径
    if($language===$srcLanguage)
        return $srcFile;
    // 否则取到对应目标语言的模板文件
    $desiredFile=dirname($srcFile).DIRECTORY_SEPARATOR.$language.DIRECTORY_SEPARATOR.basename($srcFile);
    // 如果对应目标语言的模板文件不存在,则还是返回默认的模板文件
    return is_file($desiredFile) ? $desiredFile : $srcFile;
}

从上述模板文件的寻找过程可以看到,最后返回的目标模板文件的路径是一个相对路径,以动态脚本根目录(默认为protected)开始。

方法renderPartial中在得到目标模板文件相对路径后,即调用renderFile方法(定义于CBaseController类中)来渲染模板,该方法的实现如下:

public function renderFile($viewFile,$data=null,$return=false)
{
    $widgetCount=count($this->_widgetStack);
    // Yii::app()->getViewRenderer() 获取模板引擎组件
    if(($renderer=Yii::app()->getViewRenderer())!==null && $renderer->fileExtension==='.'.CFileHelper::getExtension($viewFile))
        $content=$renderer->renderFile($this,$viewFile,$data,$return);
    else
        // 如果没法用模板引擎来渲染(可能不是模板引擎的目标模板,也可能是没设置模板引擎组件),则当前普通的PHP文件(HTML代码中夹杂着PHP代码)来渲染
        $content=$this->renderInternal($viewFile,$data,$return);
    if(count($this->_widgetStack)===$widgetCount)
        return $content;
    else
    {
        $widget=end($this->_widgetStack);
        throw new CException(Yii::t('yii','{controller} contains improperly nested widget tags in its view "{view}". A {widget} widget does not have an endWidget() call.',
            array('{controller}'=>get_class($this), '{view}'=>$viewFile, '{widget}'=>get_class($widget))));
    }
}

renderFile$content=$renderer->renderFile($this,$viewFile,$data,$return);一行调用的renderFile方法,在抽象类CViewRenderer中定义如下:

public function renderFile($context,$sourceFile,$data,$return)
{
    if(!is_file($sourceFile) || ($file=realpath($sourceFile))===false)
        throw new CException(Yii::t('yii','View file "{file}" does not exist.',array('{file}'=>$sourceFile)));
    // 尝试从runtime目录中获取已编译好的模板,如果编译好的模板不是同一存放在runtime目录下,则默认和未编译的模板文件在同一个目录下,并且文件名多一个"c"后缀
    // 得到$viewFile可能并不存在,第一次请求该模板
    $viewFile=$this->getViewFile($sourceFile);
    // 如果相比已编译好的模板文件,未编译的模板已发生变更,则需要重新编译
    // 如果已编译好的模板文件不存在,则@filemtime($viewFile)返回的是false,这个条件也是返回true
    if(@filemtime($sourceFile)>@filemtime($viewFile))
    {
        // 抽象类CViewRenderer中generateViewFile方法并未实现,所以自己封装模板引擎组件时需要实现该方法
        $this->generateViewFile($sourceFile,$viewFile);
        // 设置编译好的模板文件的访问权限,默认是0755 (owner rwx, group rx and others rx)
        @chmod($viewFile,$this->filePermission);
    }
    // 编译好的模板文件其实就是一个PHP脚本(HTML代码中夹杂PHP代码),所以还需要渲染一下
    return $context->renderInternal($viewFile,$data,$return);
}

CControllerrender方法在调用renderPartial得到渲染结果后,取得页面布局模板文件,然后将renderPartial的渲染结果作为数据渲染布局模板,从而得到一个完整HTML页面。 获取布局模板文件路径的方法getLayoutFile实现如下所示(定义于类CController中):

public function getLayoutFile($layoutName)
{
    if($layoutName===false)
        return false;
    if(($theme=Yii::app()->getTheme())!==null && ($layoutFile=$theme->getLayoutFile($this,$layoutName))!==false)
        return $layoutFile;
    if(empty($layoutName))
    {
        $module=$this->getModule();
        // 递归向父级模板查找布局文件
        while($module!==null)
        {
            if($module->layout===false)
                return false;
            if(!empty($module->layout))
                break;
            $module=$module->getParentModule();
        }
        // 如果当前controller不属于某个module
        if($module===null)
            $module=Yii::app();
        // 默认为main,可配置
        $layoutName=$module->layout;
    }
    elseif(($module=$this->getModule())===null)
        $module=Yii::app();
    return $this->resolveViewFile($layoutName,$module->getLayoutPath(),Yii::app()->getViewPath(),$module->getViewPath());
}

其逻辑与方法getViewFile类似。


由上述分析可知,将第三方模板引擎封装成Yii框架的模板引擎组件,可以继承自抽象类CViewRenderer,并实现其方法generateViewFile,然后配置该组件的ID为viewRenderer。 对于模板文件的存放,需要考虑Web应用是否分模块、应用是否国际化、模板文件相关controller的ID等,模板文件名的扩展类型应与模板引擎组件配置的一样。