yii2源码学习笔记(十七），yii2源码学习笔记

yii2源码学习笔记(十七），yii2源码学习笔记

Theme 类，应用的主题，通过替换路径实现主题的应用，方法为获取根路径和根链接：yii2\base\Theme.php

<span>  1</span> <?<span>php
</span><span>  2</span> <span>/*</span><span>*
</span><span>  3</span> <span> * @link </span><span>http://www.yiiframework.com/</span>
<span>  4</span> <span> * @copyright Copyright (c) 2008 Yii Software LLC
</span><span>  5</span> <span> * @license </span><span>http://www.yiiframework.com/license/</span>
<span>  6</span>  <span>*/</span>
<span>  7</span> 
<span>  8</span> <span>namespace</span> yii\<span>base</span><span>;
</span><span>  9</span> 
<span> 10</span> <span>use Yii;
</span><span> 11</span> <span>use yii\helpers\FileHelper;
</span><span> 12</span> 
<span> 13</span> <span>/*</span><span>*
</span><span> 14</span> <span> * Theme represents an application theme.
</span><span> 15</span> <span> * Theme 类，应用的主题
</span><span> 16</span> <span> * When [[View]] renders a view file, it will check the [[View::theme|active theme]]
</span><span> 17</span> <span> * to see if there is a themed version of the view file exists. If so, the themed version will be rendered instead.
</span><span> 18</span> <span> * 视图对象[[View]]渲染视图文件的时候，会检查视图的主题是否存在，如果存在则渲染主题取代默认样式
</span><span> 19</span> <span> * A theme is a directory consisting of view files which are meant to replace their non-themed counterparts.
</span><span> 20</span> <span> *
</span><span> 21</span> <span> * Theme uses [[pathMap]] to achieve the view file replacement:
</span><span> 22</span> <span> *
</span><span> 23</span> <span> * 1. It first looks for a key in [[pathMap]] that is a substring of the given view file path;
</span><span> 24</span> <span> *  首先查找关键字，关键字是一个给定的视图路径的字符串
</span><span> 25</span> <span> * 2. If such a key exists, the corresponding value will be used to replace the corresponding part
</span><span> 26</span> <span> *    in the view file path;关键字存在，则用对应值替换给定的视图文件路径中对应的部分
</span><span> 27</span> <span> * 3. It will then check if the updated view file exists or not. If so, that file will be used
</span><span> 28</span> <span> *    to replace the original view file.检查替换后的路径对应的文件是否存在，存在就替换原文件
</span><span> 29</span> <span> * 4. If Step 2 or 3 fails, the original view file will be used.
</span><span> 30</span> <span> * 2和3失败的话，返回原来的路径
</span><span> 31</span> <span> * For example, if [[pathMap]] is `['@app/views' => '@app/themes/basic']`,
</span><span> 32</span> <span> * then the themed version for a view file `@app/views/site/index.php` will be
</span><span> 33</span> <span> * `@app/themes/basic/site/index.php`.
</span><span> 34</span> <span> *
</span><span> 35</span> <span> * It is possible to map a single path to multiple paths. For example,
</span><span> 36</span> <span> *
</span><span> 37</span> <span> * ~~~
</span><span> 38</span> <span> * 'pathMap' => [
</span><span> 39</span> <span> *     '@app/views' => [
</span><span> 40</span> <span> *         '@app/themes/christmas',
</span><span> 41</span> <span> *         '@app/themes/basic',
</span><span> 42</span> <span> *     ],
</span><span> 43</span> <span> * ]
</span><span> 44</span> <span> * ~~~
</span><span> 45</span> <span> *
</span><span> 46</span> <span> * In this case, the themed version could be either `@app/themes/christmas/site/index.php` or
</span><span> 47</span> <span> * `@app/themes/basic/site/index.php`. The former has precedence over the latter if both files exist.
</span><span> 48</span> <span> *
</span><span> 49</span> <span> * To use a theme, you should configure the [[View::theme|theme]] property of the "view" application
</span><span> 50</span> <span> * component like the following:
</span><span> 51</span> <span> *
</span><span> 52</span> <span> * ~~~
</span><span> 53</span> <span> * 'view' => [
</span><span> 54</span> <span> *     'theme' => [
</span><span> 55</span> <span> *         'basePath' => '@app/themes/basic',
</span><span> 56</span> <span> *         'baseUrl' => '@web/themes/basic',
</span><span> 57</span> <span> *     ],
</span><span> 58</span> <span> * ],
</span><span> 59</span> <span> * ~~~
</span><span> 60</span> <span> *
</span><span> 61</span> <span> * The above configuration specifies a theme located under the "themes/basic" directory of the Web folder
</span><span> 62</span> <span> * that contains the entry script of the application. If your theme is designed to handle modules,
</span><span> 63</span> <span> * you may configure the [[pathMap]] property like described above.
</span><span> 64</span> <span> *
</span><span> 65</span> <span> * @property string $basePath The root path of this theme. All resources of this theme are located under this
</span><span> 66</span> <span> * directory.
</span><span> 67</span> <span> * @property string $baseUrl The base URL (without ending slash) for this theme. All resources of this theme
</span><span> 68</span> <span> * are considered to be under this base URL. This property is read-only.
</span><span> 69</span> <span> *
</span><span> 70</span> <span> * @author Qiang Xue <qiang.xue@gmail.com>
</span><span> 71</span> <span> * @since 2.0
</span><span> 72</span>  <span>*/</span>
<span> 73</span> <span>class</span><span> Theme extends Component
</span><span> 74</span> <span>{
</span><span> 75</span>     <span>/*</span><span>*
</span><span> 76</span> <span>     * @var array the mapping between view directories and their corresponding themed versions.
</span><span> 77</span> <span>     * This property is used by [[applyTo()]] when a view is trying to apply the theme.
</span><span> 78</span> <span>     * Path aliases can be used when specifying directories.
</span><span> 79</span> <span>     * 路径映射属性 设置替换映射关系
</span><span> 80</span> <span>     * If this property is empty or not set, a mapping [[Application::basePath]] to [[basePath]] will be used.
</span><span> 81</span>      <span>*/</span>
<span> 82</span>     <span>public</span><span> $pathMap;
</span><span> 83</span> 
<span> 84</span>     <span>private</span> $_baseUrl;<span>//</span><span>设置要访问资源的url</span>
<span> 85</span> 
<span> 86</span>     <span>/*</span><span>*
</span><span> 87</span> <span>     * @return string the base URL (without ending slash) for this theme. All resources of this theme are considered
</span><span> 88</span> <span>     * to be under this base URL. 返回当前主题的基础链接，其他资源都在链接里
</span><span> 89</span>      <span>*/</span>
<span> 90</span>     <span>public</span><span> function getBaseUrl()
</span><span> 91</span> <span>    {
</span><span> 92</span>         <span>return</span> $<span>this</span>-><span>_baseUrl;
</span><span> 93</span> <span>    }
</span><span> 94</span> 
<span> 95</span>     <span>/*</span><span>*
</span><span> 96</span> <span>     * @param $url string the base URL or path alias for this theme. All resources of this theme are considered
</span><span> 97</span> <span>     * to be under this base URL. 设置基础链接
</span><span> 98</span>      <span>*/</span>
<span> 99</span>     <span>public</span><span> function setBaseUrl($url)
</span><span>100</span> <span>    {
</span><span>101</span>         $<span>this</span>->_baseUrl = rtrim(Yii::getAlias($url), <span>'</span><span>/</span><span>'</span><span>);
</span><span>102</span> <span>    }
</span><span>103</span> 
<span>104</span>     <span>private</span> $_basePath;<span>//</span><span>根路径</span>
<span>105</span> 
<span>106</span>     <span>/*</span><span>*
</span><span>107</span> <span>     * @return string the root path of this theme. All resources of this theme are located under this directory.
</span><span>108</span> <span>     * 得到当前主题的根路径
</span><span>109</span> <span>     * @see pathMap
</span><span>110</span>      <span>*/</span>
<span>111</span>     <span>public</span><span> function getBasePath()
</span><span>112</span> <span>    {
</span><span>113</span>         <span>return</span> $<span>this</span>-><span>_basePath;
</span><span>114</span> <span>    }
</span><span>115</span> 
<span>116</span>     <span>/*</span><span>*
</span><span>117</span> <span>     * @param string $path the root path or path alias of this theme. All resources of this theme are located
</span><span>118</span> <span>     * under this directory. 设置当前主题根路径
</span><span>119</span> <span>     * @see pathMap
</span><span>120</span>      <span>*/</span>
<span>121</span>     <span>public</span><span> function setBasePath($path)
</span><span>122</span> <span>    {
</span><span>123</span>         $<span>this</span>->_basePath =<span> Yii::getAlias($path);
</span><span>124</span> <span>    }
</span><span>125</span> 
<span>126</span>     <span>/*</span><span>*
</span><span>127</span> <span>     * Converts a file to a themed file if possible. 将一个文件替换主题文件
</span><span>128</span> <span>     * If there is no corresponding themed file, the original file will be returned.
</span><span>129</span> <span>     * 没有相应的主题文件，返回原文件。
</span><span>130</span> <span>     * @param string $path the file to be themed
</span><span>131</span> <span>     * @return string the themed file, or the original file if the themed version is not available.
</span><span>132</span> <span>     * @throws InvalidConfigException if [[basePath]] is not set
</span><span>133</span>      <span>*/</span>
<span>134</span>     <span>public</span><span> function applyTo($path)
</span><span>135</span> <span>    {
</span><span>136</span>         $pathMap = $<span>this</span>->pathMap; <span>//</span><span>取得路径映射</span>
<span>137</span>         <span>if</span> (empty($pathMap)) {<span>//</span><span>没有设置值 抛出异常</span>
<span>138</span>             <span>if</span> (($basePath = $<span>this</span>->getBasePath()) === <span>null</span><span>) {
</span><span>139</span>                 <span>throw</span> <span>new</span> InvalidConfigException(<span>'</span><span>The "basePath" property must be set.</span><span>'</span><span>);
</span><span>140</span> <span>            }
</span><span>141</span>             <span>//</span><span>设置值为[模块根路径=>主题根路径]的形式</span>
<span>142</span>             $pathMap = [Yii::$app->getBasePath() =><span> [$basePath]];
</span><span>143</span> <span>        }
</span><span>144</span> 
<span>145</span>         $path = FileHelper::normalizePath($path);<span>//</span><span>对路径中的"/"."\"进行统一</span>
<span>146</span> 
<span>147</span>         <span>foreach</span> ($pathMap <span>as</span> $<span>from</span> =><span> $tos) {
</span><span>148</span>             <span>//</span><span>映射数组中的来源</span>
<span>149</span>             $<span>from</span> = FileHelper::normalizePath(Yii::getAlias($<span>from</span><span>)) . DIRECTORY_SEPARATOR;
</span><span>150</span>             <span>if</span> (strpos($path, $<span>from</span>) === <span>0</span>) {<span>//</span><span>如果在$path中有可替换的旧值</span>
<span>151</span>                 $n = strlen($<span>from</span><span>);
</span><span>152</span>                 <span>foreach</span> ((array) $tos <span>as</span><span> $to) {
</span><span>153</span>                     $to =<span> FileHelper::normalizePath(Yii::getAlias($to)) . DIRECTORY_SEPARATOR;
</span><span>154</span>                     $file = $to . substr($path, $n);<span>//</span><span>把$path中的$from替换为$to</span>
<span>155</span>                     <span>if</span><span> (is_file($file)) {
</span><span>156</span>                         <span>return</span> $file; <span>//</span><span>是文件直接返回</span>
<span>157</span> <span>                    }
</span><span>158</span> <span>                }
</span><span>159</span> <span>            }
</span><span>160</span> <span>        }
</span><span>161</span> 
<span>162</span>         <span>return</span><span> $path;
</span><span>163</span> <span>    }
</span><span>164</span> 
<span>165</span>     <span>/*</span><span>*
</span><span>166</span> <span>     * Converts a relative URL into an absolute URL using [[baseUrl]].
</span><span>167</span> <span>     * 将一个相对URL转换为绝对URL
</span><span>168</span> <span>     * @param string $url the relative URL to be converted.要转换的相对URL
</span><span>169</span> <span>     * @return string the absolute URL  替换后的绝对URL
</span><span>170</span> <span>     * @throws InvalidConfigException if [[baseUrl]] is not set
</span><span>171</span>      <span>*/</span>
<span>172</span>     <span>public</span><span> function getUrl($url)
</span><span>173</span> <span>    {
</span><span>174</span>         <span>if</span> (($baseUrl = $<span>this</span>->getBaseUrl()) !== <span>null</span>) {<span>//</span><span>URL存在，进行转换</span>
<span>175</span>             <span>return</span> $baseUrl . <span>'</span><span>/</span><span>'</span> . ltrim($url, <span>'</span><span>/</span><span>'</span><span>);
</span><span>176</span>         } <span>else</span> {<span>//</span><span>不存在抛出异常</span>
<span>177</span>             <span>throw</span> <span>new</span> InvalidConfigException(<span>'</span><span>The "baseUrl" property must be set.</span><span>'</span><span>);
</span><span>178</span> <span>        }
</span><span>179</span> <span>    }
</span><span>180</span> 
<span>181</span>     <span>/*</span><span>*
</span><span>182</span> <span>     * Converts a relative file path into an absolute one using [[basePath]].
</span><span>183</span> <span>     * 通过相对路径生成绝对路径
</span><span>184</span> <span>     * @param string $path the relative file path to be converted. 要转换的相对文件路径。
</span><span>185</span> <span>     * @return string the absolute file path 转换后的绝对路径
</span><span>186</span> <span>     * @throws InvalidConfigException if [[baseUrl]] is not set
</span><span>187</span>      <span>*/</span>
<span>188</span>     <span>public</span><span> function getPath($path)
</span><span>189</span> <span>    {
</span><span>190</span>         <span>if</span> (($basePath = $<span>this</span>->getBasePath()) !== <span>null</span><span>) {
</span><span>191</span>             <span>//</span><span>返回拼接的路径</span>
<span>192</span>             <span>return</span> $basePath . DIRECTORY_SEPARATOR . ltrim($path, <span>'</span><span>/\\</span><span>'</span><span>);
</span><span>193</span>         } <span>else</span><span> {
</span><span>194</span>             <span>throw</span> <span>new</span> InvalidConfigException(<span>'</span><span>The "basePath" property must be set.</span><span>'</span><span>);
</span><span>195</span> <span>        }
</span><span>196</span> <span>    }
</span><span>197</span> }