README

MvcCore 路由扩展，用于在URL中管理网站媒体版本，以便在请求、控制器和视图中渲染不同的模板、CSS和js文件，为手机、平板或桌面。

概述

1. 安装
2. 功能
   2.1. 功能 - 路由
   2.2. 功能 - URL生成
3. 工作原理
   3.1. 工作原理 - 路由
   3.2. 工作原理 - URL完成
4. 用法
   4.1. 用法 - Bootstrap 初始化
   4.2. 用法 - 媒体URL前缀和允许的媒体版本
5. 高级配置
   5.1. 高级配置 - 会话过期
   5.2. 高级配置 - 严格会话模式
   5.3. 高级配置 - 仅路由GET请求

1. 安装

composer require mvccore/ext-router-media

回到顶部

2. 功能

2.1. 功能 - 路由

• 路由器与带有媒体站点版本前缀的URL地址的请求一起工作，前缀是可配置的。
• 路由器通过HTTP头User-Agent和第三方\Mobile_Detect库，在第一个请求中识别用户设备为3个预定义版本 - full、tablet或mobile。
• 如果需要，路由器将第一个请求重定向到更好的媒体前缀的URL地址，其中包含适合识别设备的更多内容。
• 路由器将识别的设备版本字符串存储在其自己的会话命名空间中，并具有可配置的过期时间（以避免在每个请求中再次处理\Mobile_Detect识别）。
• 路由器将请求路径中可能找到的媒体前缀子串替换为空字符串。它每次都保持请求路径的相同形式，以便像平常一样处理路由。
• 路由器将$request->GetMediaSiteVersion()的值填充为字符串：full、tablet或mobile，以便在任何地方在您的应用程序中使用。
• 媒体站点版本的会话严格模式（可配置），通过会话值严格驱动应用程序的媒体版本。

回到顶部

2.2. 功能 - URL生成

• 路由器将内置的Url()方法生成的每个应用程序URL（或每个配置的GET URL）与请求的媒体版本或作为第二个参数数组的媒体版本前缀结合，以包含URL参数的Url()方法。
• 还可以配置URL媒体版本前缀。

回到顶部

3. 工作原理

3.1. 工作原理 - 路由

• 路由器从以下来源完成媒体站点版本
  • 来自请求的URL（如果没有媒体站点前缀在URL中，则完成到full）。
  • 来自会话（如果没有内容，则保持为NULL）。
  • 来自特殊的$_GET参数以在会话严格模式下切换媒体站点版本（也可能是NULL）。
• 如果需要，路由器将根据源数据处理预路由重定向
  • 如果特殊$_GET切换参数中有允许的值：- 新媒体站点版本存储在会话中，并且请求通过特殊切换参数重定向到新媒体站点版本。
  • 如果没有会话中的媒体站点版本来自任何先前的请求：- 通过第三方库\Mobile_Detect识别媒体站点版本并将其存储在会话中以供后续请求使用。
    • 如果检测到的版本与请求的版本相同，则还完成了完成标志。
  • 如果配置了严格会话模式为FALSE（默认值）
    • 如果请求是第一个（会话中没有来自先前请求的内容）
      • 如果检测到的版本与请求版本不同
        • 将用户重定向到检测到的版本
      • 否则，稍后以标准方式路由请求，不处理任何重定向。
    • 否则，稍后以标准方式路由请求，不处理任何重定向。
  • 如果配置了严格会话模式为TRUE
    • 如果请求的媒体站点版本与会话版本不同
      • 将用户重定向到会话版本。
    • 否则，稍后以标准方式路由请求，不处理任何重定向。
• 路由器删除任何找到的媒体站点版本URL前缀，以处理具有相同请求路径的任何媒体站点版本的路由。
• 然后，路由器以标准方式路由请求。

回到顶部

3.2. 工作原理 - URL完成

• 路由器始终以请求的媒体站点版本相同的媒体站点版本生成URL地址
  • 对于没有定义重写路由的地址，会添加有关媒体站点版本的信息到查询字符串中（&media_version=...）。
  • 对于具有定义的重写路由的地址，路由器会根据配置添加媒体站点版本URL前缀。
• 如果请求的版本是full（默认值为full），则不需要将任何附加数据放入URL地址中，因此对于full版本，始终是相同的原始URL字符串，没有特殊参数或前缀。
• 如果您在构建内Url()方法的第二个参数数组中定义了与请求版本不同的媒体站点版本，则会在结果URL字符串查询参数或媒体站点URL前缀中添加。
• 如果配置了会话严格模式，则自动添加特殊的$_GET切换参数。

回到顶部

4. 使用方法

4.1. 使用方法 - Bootstrap 初始化

将其添加到/App/Bootstrap.php或到应用程序开始处，在应用路由或任何其他扩展配置之前使用路由器进行任何目的之前

$app = \MvcCore\Application::GetInstance();
$app->SetRouterClass('\MvcCore\Ext\Routers\Media');
...
// to get router instance for next configuration:
/** @var \MvcCore\Ext\Routers\Media $router */
$router = \MvcCore\Router::GetInstance();

回到顶部

4.2. 使用方法 - 媒体URL前缀和允许的媒体版本

默认情况下，已配置三个媒体站点版本，具有URL地址前缀

use \MvcCore\Ext\Routers;
...
$router->SetAllowedMediaVersionsAndUrlValues([
    Routers\Media::MEDIA_VERSION_MOBILE	=> 'm',
    Routers\Media::MEDIA_VERSION_TABLET	=> 't',
    Routers\Media::MEDIA_VERSION_FULL	=> '',
]);

要允许仅选择媒体站点版本并配置URL前缀，可以使用

// to allow only mobile version (with url prefix '/mobile') 
// and full version (with no url prefix):
use \MvcCore\Ext\Routers;
...
// now, tablet version is not allowed:
$router->SetAllowedMediaVersionsAndUrlValues([
    Routers\Media::MEDIA_VERSION_MOBILE	=> 'mobile',
    // if you are using an empty string url prefix for full version, 
    // you need to define it as the last item!
    Routers\Media::MEDIA_VERSION_FULL	=> '',
]);

回到顶部

5. 高级配置

5.1. 高级配置 - 会话过期

可以更改会话过期时间，关于检测到的媒体网站版本值的设置，以避免每次请求时在URL前缀不存在的情况下识别媒体网站版本，因为处理 \Mobile_Detect 库中的所有正则表达式可能需要一些时间。默认情况下为 1小时。您可以通过以下方式更改它：

$router->SetSessionExpirationSeconds(
    \MvcCore\Session::EXPIRATION_SECONDS_DAY
);

回到顶部

5.2. 高级配置 - 严格会话模式

在会话严格模式下，不能仅通过在URL中请求不同的媒体网站版本前缀来更改媒体网站版本。 严格会话模式是路由模式，当媒体网站版本由首次请求识别的会话值管理时。所有请求到与会话中版本不同的媒体网站版本的请求将自动重定向到会话中存储的媒体网站版本。

通常情况下，可以通过请求不同的媒体网站版本URL前缀来获取不同的媒体网站版本。例如 - 要获取 full 版本的另一个版本，例如，获取 mobile 版本，只需要请求带有配置的 mobile 前缀的应用程序，如下所示：/mobile/any/application/request/path。

在会话严格模式下，只能通过媒体版本导航中的特殊 $_GET 参数来更改媒体网站版本。例如 - 要从 full 版本获取不同的版本，例如 mobile 版本，需要在查询字符串参数中添加如下所示：/any/application/request/path?switch_media_version=mobile 然后，更改后的媒体网站版本存储在会话中，并且用户会被重定向到带有移动URL前缀的移动应用程序版本。

要启用此会话严格模式，您只需要通过以下方式配置路由器：

$router->SetStricModeBySession(TRUE);

回到顶部

5.3. 高级配置 - 仅路由 GET 请求

路由器仅管理 GET 请求的媒体网站版本。这意味着在会话严格模式下重定向到适当的版本，或者重定向到识别的媒体网站版本的第一请求。对于管理媒体网站版本的其他请求方法（如 POST 请求），没有意义。对于这些请求，您仍然可以在会话中保留媒体网站版本记录，并且可以在任何时候使用它。但为了处理所有请求方法，您可以配置路由器如下操作：

$router->SetRouteGetRequestsOnly(FALSE);

回到顶部