README

本地 SDK 支持

此软件包已从 shpasser 版本更改为更兼容本地 GAE SDK。

为 Laravel 5.1 提供的 Google App Engine (GAE) 支持包。

当前支持的功能

生成通用配置文件，
DataStore 持久会话处理器，
邮件服务提供者，
队列服务提供者，
数据库连接，
文件系统，
StackDriver 跟踪 API

有关 Lumen，请参阅 https://github.com/a1comms/GaeSupportLumen。

安装

使用 Composer 引入软件包。

"require": {
    "a1comms/gae-support-l5": "~5.1"
}

然后在 config/app.php 中包含服务提供者。

'providers' => [
    Shpasser\GaeSupportL5\GaeSupportServiceProvider::class
];

使用方法

生成与 GAE 相关的文件/条目。

命令模板

php artisan gae:setup --config --cache-config --bucket="your-bucket-id" --db-socket="cloud-sql-instance-socket-connection-string" --db-name="cloud-sql-database-name" --db-host="cloud-sql-instance-ipv4-address" app-id

参数和选项

php artisan gae:setup [options] [--] app-id

Arguments:
  app-id                     GAE application ID.

Options:
      --config               Generate "app.yaml" and "php.ini" config files.
      --cache-config         Generate cached Laravel config file for use on Google App Engine.
      --bucket=BUCKET        Use the specified GCS-bucket instead of the default one.
      --db-socket=DB-SOCKET  Cloud SQL socket connection string for production environment.
      --db-name=DB-NAME      Cloud SQL database name.
      --db-host=DB-HOST      Cloud SQL database host IPv4 address for local environment.

--cache-config 选项生成 GAE 的缓存配置文件。此选项是必需的，因为由 php artisan config:cache 生成的缓存配置文件不适合在 GAE 上使用。同样，为 GAE 生成的缓存配置文件可能在本地环境中无法使用。应使用此选项在应用部署到 GAE 之前生成缓存配置文件。

--bucket 选项定义应用用于存储的 GCS-bucket ID。除非使用此选项，否则默认配置 GCS 桶。

当定义了 --db-name 选项时，至少应定义 --db-socket 或 --db-host 之一。

--db-socket 使用以下格式设置： /cloudsql/<app-id>:<cloud-sql-instance-name>。其中 <cloud-sql-instance-name> 是 Cloud SQL 实例名称，而 <app-id> 是所属应用的名称。

DataStore 中的持久会话

我们包括了一个使用 DataStore 进行持久性的会话驱动程序，通过 memcache 缓存以提高访问速度并降低账单，在速度和持久性方面为您提供了最佳选择。

要使用它，请在 .env 中设置

SESSION_DRIVER=gae

只要您不进行大量使用，就不需要启用计费即可使用，因为最少的 DataStore 使用是免费的。

您可能还希望启用垃圾回收来清除旧会话，我们建议每天运行一次，以将账单保持在最低水平。这将删除一周内未更新的任何会话。

为此，创建一个 cron.yaml 文件，调用 /gae/sessiongc，例如

cron:
- description: daily session clearout
  url: /gae/sessiongc
  schedule: every day 00:00

如果您不需要持久性并且对纯 memcached 满意，请参阅下面的旧会话文档。

邮件

邮件驱动配置可在 config/mail.php 和 .env.production 文件中找到，这些配置文件由 artisan 命令修改/生成。无需任何自定义配置。所有发出的邮件消息都使用应用程序管理员的发送地址发送，即 admin@your-app-id.appspotmail.com。电子邮件消息的 sender、to、cc、bcc、replyTo、subject、body 和 attachment 部分均受支持。

队列

修改后的队列配置文件 config/queue.php 应包含以下内容：

return array(

	...

	/*
	|--------------------------------------------------------------------------
	| GAE Queue Connection
	|--------------------------------------------------------------------------
	|
	*/

	'connections' => array(

		'gae' => array(
			'driver'	=> 'gae',
			'queue'		=> 'default',
			'url'		=> '/tasks',
			'encrypt'	=> true,
		),

		...

	),

);

默认使用 'default' 队列和加密。为了使用队列，您的 app/Http/routes.php 文件应包含以下路由

Route::post('tasks', array('as' => 'tasks',
function()
{
	return Queue::marshal();
}));

此路由将由 GAE 队列用于推送作业。请注意，路由和 GAE 队列连接的 'url' 参数指向相同的 URL。由于通过路由提交的请求由 GAE 本身发出，因此不能受到 CSRF 保护。有关更多信息，请参阅 https://laravel.net.cn/docs/5.0/queues#push-queues。

缓存、会话和日志

通过使用特定的驱动/处理器支持缓存、会话和日志组件。

缓存 - 使用 'memcached' 驱动程序；
会话 - 使用 'memcached' 驱动程序（或 'gae' 用于 DataStore 支持的持久性，见上文），
日志 - 使用 'syslog' 处理器。

提到的驱动/处理器的配置选项由 artisan 命令生成，并可在 .env.production 配置文件中找到。

数据库

通过 Laravel 的 MySql 驱动程序支持 Google Cloud SQL。连接配置由 artisan 命令添加到 config/database.php 下的 cloudsql。可以通过 artisan 命令使用 --db-socket、--db-name 和 --db-host 选项来配置连接参数。

数据库相关环境变量在 .env.production 和 .env.local 文件中设置。

production 环境配置为使用套接字连接，而 local 配置为通过 Google Cloud SQL 实例的 IPv4 地址连接。使用 Google 开发者控制台以获取套接字连接字符串并启用数据库实例的 IPv4 地址。

仅在工作在 local 环境时支持迁移。

要使用 production 或 local 环境，请将相应的文件重命名为 .env。

文件系统

为了在 GAE 上支持 Laravel 文件系统，artisan 命令修改 config/filesystem.php 以包括额外的磁盘

'gae' => [
    'driver' => 'gae',
    'root'   => storage_path().'/app',
],

并在 .env.production 文件中添加以下行

FILESYSTEM = gae

优化

优化允许应用程序减少对 GCS 的使用，GCS 是目前 GAE 平台上唯一的读写存储。

为了优化视图编译，可以使用包含的 cachefs 文件系统来使用 memcached 服务存储编译后的视图。由于视图可以重新编译而不会丢失任何信息，因此使用 cachefs 存储编译后的视图是合适的。

cachefs 具有以下结构

/
+-- bootstrap
    +-- cache
+-- framework
    +-- views

'/framework/views' 用于存储编译后的视图。

要启用此功能，请使用以下选项在 .env.production 和/或 .env.local 文件中

CACHE_COMPILED_VIEWS = true

'/bootstrap/cache' 用于存储 services.json、config.php 和 routes.php 文件，要控制这些文件的缓存，请使用以下选项在 .env.production 和/或 .env.local 文件中

CACHE_SERVICES_FILE = true
CACHE_CONFIG_FILE = true
CACHE_ROUTES_FILE = true

要使用 config.php，首先使用 php artisan gae:setup 命令的 --cache-config 选项生成它。routes.php 必须使用 php artisan route:cache 命令生成。

与缓存相关的选项

只要存在 memcached 服务，就支持在 GAE 和/或在本地环境中使用
在执行 php artisan gae:setup 命令时禁用

此外，可以跳过 GSC 存储桶的初始化以提高性能。为此，请在 app.yaml 文件中设置以下选项

env_variables:
        GAE_SKIP_GCS_INIT: true

存储路径将设置为 GCS 存储桶的 /storage 目录，并将跳过存储目录结构的创建。

如果没有使用，则可以删除文件系统初始化以最大限度地减少 GCS 使用。为此，请从 .env.production 文件中删除以下行

FILESYSTEM = gae

App Engine 上的 Google Trace API

在 App Engine 上运行时，每个实例每秒会采样 0.1 请求的 StackDriver Trace 工具（https://cloud.google.com/trace/docs/faq）。

使用 Trace API，我们可以提交自定义的时间跨度，以在 GAE 上运行时调试性能。

要使用，您首先需要在 bootstrap/autoload.php 中初始化该类。

在以下内容下方

require __DIR__.'/../vendor/autoload.php';

添加以下行

/*
|--------------------------------------------------------------------------
| Start our GAE time tracing.
|--------------------------------------------------------------------------
|
| Initiate our GAETrace class to allow us to time trace our code.
| Starting things here will make sure we can trace as much code as possible,
| while ensuring the destructor will always run.
|
*/
use \Shpasser\GaeSupportL5\Trace\GAETrace;
$gae_trace = new GAETrace();

如注释中所述，这将确保代码退出时运行析构函数，将 Trace 数据提交到 API。

在此之后，类的使用是静态的，可以在应用程序的任何地方使用。

use \Shpasser\GaeSupportL5\Trace\GAETrace;

//...

$span_id = GAETrace::startSpan("FriendlyName");

//...code here...

GAETrace::endSpan($span_id);

Google 建议异步提交数据到 Trace API，我们可以在 App Engine 上通过 Push Queue 来实现。

为此，请在 app.yaml 中添加以下内容

    - url: /gae/trace_submit
      script: public/trace.php
      login: admin
      secure: always

如果不存在，则创建 queue.yaml 并包含以下内容

queue:
- name: trace
  rate: 5/s
  retry_parameters:
    task_retry_limit: 7
    task_age_limit: 2d

并创建文件 public/trace.php 并包含以下内容

<?php

/*
|--------------------------------------------------------------------------
| Register The Composer Auto Loader
|--------------------------------------------------------------------------
|
| Composer provides a convenient, automatically generated class loader
| for our application. We just need to utilize it! We'll require it
| into the script here so that we do not have to worry about the
| loading of any our classes "manually". Feels great to relax.
|
*/

require __DIR__.'/../vendor/autoload.php';

use \Shpasser\GaeSupportL5\Trace\GAETrace;
GAETrace::submitTraceAsync();

我们使用不同的非 Laravel 入口点来确保在提交跟踪时没有递归，如果在核心跟踪之前发生错误，则可能发生这种情况。

App Engine 的 Artisan 控制台

为了在 GAE 上支持 artisan 命令，该包提供了 Artisan Console for GAE。出于安全原因，控制台作为单独的服务实现，默认不启用。为了安全地使用控制台，必须保护 /artisan 路由。

安装

在 config/app.php 中包含服务提供程序。

'providers' => [
    Shpasser\GaeSupportL5\GaeArtisanConsoleServiceProvider::class
];

如果未自动添加，请将 /gae/.* URL 处理程序添加到 app.yaml 文件中。

handlers:

        - url: /gae/.*
          script: public/index.php
          login: admin
          secure: always

        - url: /.*
          script: public/index.php

/gae/.* URL 处理程序必须出现在最后一个处理程序（url: /.*）之前，否则将被 GAE 忽略。建议的处理程序使用 GAE URL 安全选项来保护路由。有关更多信息，请参阅 https://cloud.google.com/appengine/docs/php/config/appconfig#PHP_app_yaml_Secure_URLs。

用法

在浏览器中输入URL http://your-app-id.appspot.com/gae/artisan 并使用显示的表单提交 artisan 命令。由于GAE的文件系统为只读，命令将无法对其执行写/更新操作。由于同样的原因，在部署之前必须在本地开发环境中准备迁移。由于控制台并非真正交互式，所有命令都在非交互模式下执行（通过自动添加-n选项）。

部署

如有需要，备份现有的.env文件，并在部署您的应用之前将生成的.env.production重命名为.env。

下载并安装PHP的GAE SDK，然后部署您的应用。

已知问题

截至目前，在GAE上运行时，Laravel计划中的命令不受支持。为了使用Artisan Console for GAE，需要编辑应用类app/Console/Kernel，并删除使用其schedule()函数计划的所有命令。

a1comms / gae-support-l5

维护者

详细信息