README

重要： 此库已废弃。
请使用 LM-Commons/LmcCors。

LmcCors

LmcCors是一个简单的Laminas MVC模块，帮助您处理跨源资源共享（CORS）。

什么是LmcCors？

LmcCors是一个Laminas MVC模块，允许您轻松配置Laminas MVC应用程序，以便它自动构建遵循CORS文档的HTTP响应。

安装

通过输入以下命令安装模块（或将其添加到您的composer.json文件中）

$ php composer.phar require laminas-commons/lmc-cors

然后，通过在application.config.php或modules.config.php文件中添加"LmcCors"来启用它。

默认情况下，LmcCors配置为拒绝所有CORS请求。要更改此设置，您需要将config/lmc_cors.global.php.dist文件复制到您的autoload文件夹中（移除.dist扩展名），并根据您的需求进行修改。

文档

什么是CORS？

CORS是一种机制，允许浏览器执行跨源请求。

例如，假设您的网站托管在http://example.com域。默认情况下，出于安全原因，用户代理不允许执行到另一个域的AJAX请求（例如http://funny-domain.com）。

使用CORS，您可以允许您的服务器响应此类请求。

您可以在网上找到关于CORS如何工作的更详细文档

事件注册

LmcCors使用优先级为-1的LmcCors\Mvc\CorsRequestListener在MvcEvent::EVENT_ROUTE事件上注册，这意味着此监听器在路由匹配后执行。

配置模块

默认情况下，所有选项都是全局设置的，适用于所有路由

allowed_origins: （数组）允许的源列表。要允许任何源，您可以使用通配符（*）字符。如果指定了多个源，LmcCors将自动检查"Origin"头部的值，并在"Allow-Access-Control-Origin"响应头部中返回允许的域（如果有）。要允许任何子域，您可以使用通配符字符作为域的前缀（例如*.example.com）。请注意，您不需要添加您的宿主URI（因此，如果您的网站托管为"example.com"，"example.com"将自动允许）。
allowed_methods： (数组) 允许的 HTTP 方法列表。这些方法将在预检请求中返回，以指示哪些方法允许用户代理使用。您甚至可以指定自定义的 HTTP 动词。
allowed_headers： (数组) 将返回用于预检请求的允许的头部信息列表。这表明用户代理在执行实际请求时可以发送哪些头部信息。
max_age： (整数) 预检请求应被用户代理缓存的最大年龄（秒）。这防止用户代理对每个请求都发送预检请求。
exposed_headers： (数组) 允许在用户代理中读取的响应头部信息列表。请注意，某些浏览器可能没有正确实现此功能。
allowed_credentials： (布尔值) 如果为 true，则允许浏览器在请求中发送 cookie。

如果您想配置特定的路由，可以向您的路由配置中添加 ZfrCors\Options\CorsOptions::ROUTE_PARAM。

<?php

return [
    'lmc_cors' => [
        'allowed_origins' => ['*'],
        'allowed_methods' => ['GET', 'POST', 'DELETE'],
    ],
    'router' => [
        'routes' => [
            'readOnlyRoute' => [
                'type' => 'literal',
                'options' => [
                    'route' => '/foo/bar',
                    'defaults' => [
                        // This will replace allowed_methods configuration to only allow GET requests
                        // and only allow a specific origin instead of the wildcard origin
                        LmcCors\Options\CorsOptions::ROUTE_PARAM => [
                            'allowed_origins' => ['http://example.org'],
                            'allowed_methods' => ['GET'],
                        ],
                    ],
                ],
            ],
            'someAjaxCalls' => [
                'type' => 'literal',
                'options' => [
                    'route' => '/ajax',
                    'defaults' => [
                        // This overrides the wildcard origin
                        LmcCors\Options\CorsOptions::ROUTE_PARAM => [
                            'allowed_origins' => ['http://example.org'],
                        ],
                    ],
                ],
                'may_terminate' => false,
                'child_routes' => [
                    'blog' => [
                        'type' => 'literal',
                        'options' => [
                            'route' => '/blogpost',
                            'defaults' => [
                                // This would only allow `http://example.org` to GET this route
                                \LmcCors\Options\CorsOptions::ROUTE_PARAM => [
                                    'allowed_methods' => ['GET'],
                                ],
                            ],
                        ],
                        'may_terminate' => true,
                        'child_routes' => [
                            'delete' => [
                                'type' => 'segment',
                                'options' => [
                                    'route' => ':id',
                                    // This would only allow origin `http://example.org` to apply DELETE on this route
                                    'defaults' => [
                                        \LmcCors\Options\CorsOptions::ROUTE_PARAM => [
                                            'allowed_methods' => ['DELETE'],
                                        ],
                                    ],
                                ],
                            ],
                        ],
                    ],
                ],
            ],
        ],
    ],
];

预检请求

如果 LmcCors 侦测到预检 CORS 请求，将创建一个新的 HTTP 响应，并根据您的配置发送适当的头部信息。响应将以 200 状态码（OK）发送。

请注意，这也会阻止进一步的 MVC 步骤执行，因为所有后续的 MVC 步骤都将跳过，直到 Laminas\Mvc\MvcEvent::EVENT_FINISH，该事件负责实际发送响应。

实际请求

当进行实际请求时，LmcCors 首先检查源是否允许。如果不允许，则创建一个新的响应，并带有 403 状态码（禁止）发送。

请注意，这也会阻止进一步的 MVC 步骤执行，因为所有后续的 MVC 步骤都将跳过，直到 Laminas\Mvc\MvcEvent::EVENT_FINISH，该事件负责实际发送响应。

如果源允许，LmcCors 将只向由 Laminas\Mvc 产生的请求中添加适当的头部信息。

安全注意事项

不要使用此模块来保护您的应用程序！您必须使用合适的授权模块，例如 BjyAuthorize、LmcRbacMvc 或 SpiffyAuthorize。

LmcCors 只允许接受或拒绝跨源请求。

自定义协议

内部，LmcCors 使用 Laminas\Uri\UriFactory 类。如果您使用自定义协议（例如，如果您正在使用某些 Google Chrome 扩展来测试您的 API），则需要通过将它们添加到 UriFactory 配置来支持这些协议（请参阅文档）。

示例

要将 chrome-extension 自定义协议注册到您的 API 中，只需将以下内容添加到 module/Application/Module.php 中的 onBootstrap() 方法中：

use Laminas\Uri\UriFactory;

UriFactory::registerScheme('chrome-extension', 'Laminas\Uri\Uri');

以这种方式注册 chrome-extension 自定义协议允许您使用 Google Chrome 扩展来测试您的 API。

laminas-commons / lmc-cors

维护者

详细信息