Android source code learning yii2 source code learning notes 17)

<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> 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> }