Como criar um app com PHP

ID da região

O REGION_ID é um código abreviado que o Google atribui com base na região que você selecionou ao criar o aplicativo. O código não corresponde a um país ou estado, ainda que alguns IDs de região sejam semelhantes aos códigos de país e estado geralmente usados. Para apps criados após fevereiro de 2020, o REGION_ID.r está incluído nos URLs do App Engine. Para apps existentes criados antes dessa data, o ID da região é opcional no URL.

Saiba mais sobre IDs de região.

OK

Observação: se você estiver implantando um novo serviço da Web PHP no Google Cloud, recomendamos começar com o Cloud Run.

Saiba como criar um app no App Engine usando a versão 7.4 ou 8.1 do PHP. O aplicativo de amostra permite aos usuários postar os títulos, autores, descrições, data de publicação e imagens de seus livros favoritos em uma página da Web. O aplicativo armazena os dados textuais em um banco de dados do Cloud SQL e as imagens em um bucket do Cloud Storage.

Estrutura do guia

1. Criar um projeto do Google Cloud usando a Google Cloud CLI

2. Fazer o download do app de exemplo

3. Especificar dependências com o composer.json

4. Inicializar o app e definir controladores frontais

5. Integrar com os serviços do Google Cloud

6. Configurar o app para o App Engine

7. Implantar o app

Antes de começar

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Cloud Build API.

   Enable the API

5. Install the Google Cloud CLI.

6. To initialize the gcloud CLI, run the following command:

   gcloud init

7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

8. Make sure that billing is enabled for your Google Cloud project.

9. Enable the Cloud Build API.

   Enable the API

10. Install the Google Cloud CLI.

11. To initialize the gcloud CLI, run the following command:

    gcloud init

12. Instale o Composer, a ferramenta de gestão de dependências do PHP. Em sistemas Linux e Mac OS X, instale o Composer globalmente.

Baixar o aplicativo de exemplo

1. Explore o código no GitHub.

2. Faça o download ou clone o aplicativo.

   git clone https://github.com/GoogleCloudPlatform/php-docs-samples.git

   Outra opção é fazer o download da amostra como um arquivo zip e extraí-lo.

3. Navegue até o diretório getting-started.

   cd php-docs-samples/appengine/standard/getting-started

Especificar dependências com o composer.json

O aplicativo usa um controlador frontal para encaminhar solicitações. No código de amostra deste guia, usamos o Slim Framework. No entanto, é possível usar o framework da Web de sua escolha.

1. Abra o arquivo composer.json para analisar todas as dependências diretas:

   {
     "require": {
       "google/cloud-storage": "^1.6",
       "slim/slim": "^4.0",
       "slim/psr7": "^1.0",
       "slim/twig-view": "^3.0",
       "php-di/slim-bridge": "^3.1",
       "symfony/yaml": "^5.2"
     },
     "autoload": {
        "psr-4": {
          "Google\\Cloud\\Samples\\AppEngine\\GettingStarted\\": "src"
        }
     }
   }
   

2. Para instalar as dependências e produzir um arquivo composer.lock, execute o seguinte comando:

   composer install
   

   O arquivo composer.lock ajuda o app a recuperar as mesmas versões dos pacotes que você usa em várias versões e ambientes.

   Observação: como o Cloud Build opera em um ambiente de memória limitado, recomendamos produzir o arquivo composer.lock localmente. Para mais informações, consulte Como especificar dependências.

Como inicializar o app e definir controladores frontais

O arquivo index.php inicializa o aplicativo e encaminha todas as solicitações para os controladores definidos no arquivo ./src/controllers.php.

// Use the composer autoloader to load dependencies.
require_once __DIR__ . '/vendor/autoload.php';

//  Load the application code.
/** @var Slim\App $app */
$app = require __DIR__ . '/src/app.php';
require __DIR__ . '/src/controllers.php';

// Bootstrap the slim framework to handle the request.
$app->run();

Para mais informações sobre processamento de solicitações, leia sobre inicialização de aplicativos e processamento de solicitações.

Como integrar com os serviços do Google Cloud

O App Engine requer aplicativos para integração com sistemas externos de armazenamento de dados. O aplicativo de exemplo armazena dados textuais no Cloud SQL e imagens no Cloud Storage.

Consulte a página Como escolher uma opção de armazenamento para todas as opções de armazenamento do Google Cloud.

Uso do Cloud SQL

No aplicativo de amostra, os usuários postam livros em uma página da Web. O aplicativo usa um banco de dados do Cloud SQL para armazenar os títulos, autores, data de publicação e descrições dos livros.

É necessário criar uma instância do Cloud SQL antes de adicionar conteúdo ao banco de dados do aplicativo.

criar uma instância do Cloud SQL;

Use a CLI gcloud para criar uma instância do Cloud SQL:

gcloud sql instances create INSTANCE_NAME --tier=MACHINE_TYPE --region=REGION

Por exemplo, se você quiser nomear sua instância bookshelf e usar o tipo de máquina db-n1-standard-2 na região central dos Estados Unidos:

gcloud sql instances create bookshelf --tier=db-n1-standard-2 --region=us-central1

Saiba mais:

• Para mais informações sobre como criar uma instância do Cloud SQL, leia o guia de criação de instâncias do Cloud SQL.
• Para informações sobre locais de instâncias, tipos de máquinas e seus efeitos nos preços, consulte a página de preços do Cloud SQL.

Como configurar o usuário raiz do MySQL

Use a CLI gcloud para definir a senha do usuário raiz da instância do Cloud SQL:

gcloud sql users set-password USER --host=HOST --instance=INSTANCE_NAME --password=PASSWORD

Por exemplo, se você quiser definir a senha do usuário raiz da instância do Cloud SQL bookshelf para passw0rd!:

gcloud sql users set-password root --host=% --instance=bookshelf --password=passw0rd!

Saiba mais: para mais informações, leia o guia do Cloud SQL para criar e gerenciar usuários do MySQL.

Como configurar um banco de dados na instância do Cloud SQL

Para armazenar os autores, títulos, data de publicação e descrições dos livros, crie um banco de dados MySQL:

gcloud sql databases create DATABASE_NAME --instance=INSTANCE_NAME

Por exemplo, se você quiser criar um banco de dados chamado book-data na instância do Cloud SQL bookshelf:

gcloud sql databases create book-data --instance=bookshelf

Saiba mais: para mais informações, leia o guia de bancos de dados do MySQL para criar e gerenciar o Cloud SQ.

Como conectar-se ao banco de dados do Cloud SQL

O aplicativo de amostra usa o PDO do PHP para interagir com o banco de dados MySQL.

// Fill the variables below to match your Cloud SQL configuration.
// $dbConn = 'YOUR_CLOUDSQL_CONNECTION_NAME';
// $dbName = 'YOUR_CLOUDSQL_DATABASE_NAME';
// $dbUser = 'YOUR_CLOUDSQL_USER';
// $dbPass = 'YOUR_CLOUDSQL_PASSWORD';
$dsn = "mysql:unix_socket=/cloudsql/{$dbConn};dbname={$dbName}";
$pdo = new PDO($dsn, $dbUser, $dbPass);

Neste tutorial, esses parâmetros são especificados como as variáveis de ambiente a seguir em Como configurar o aplicativo.

Como consultar uma única linha

Quando o usuário clica em um livro, o aplicativo consulta o banco de dados e retorna uma única linha que inclui o título, o autor, a data de publicação e a descrição do livro.

$statement = $pdo->prepare('SELECT * FROM books WHERE id = :id');
$statement->bindValue('id', $id, PDO::PARAM_INT);
$statement->execute();
$result = $statement->fetch(PDO::FETCH_ASSOC);

Saiba mais: para mais informações sobre como usar o Cloud SQL nos ambientes de execução do PHP, leia o guia de uso do Cloud SQL para MySQL.

Como usar o Cloud Storage

O aplicativo de amostra usa o Cloud Storage para armazenar as imagens, que são arquivos binários, carregadas pelos usuários.

Como criar um bucket do Cloud Storage

O Cloud Storage usa buckets para organizar e controlar o acesso aos dados.

Use a CLI gcloud para criar um bucket do Cloud Storage:

gcloud storage buckets create gs://BUCKET_NAME/ --location=BUCKET_REGION

Por exemplo, se você quiser criar um bucket chamado picture-storage na região us-central1:

gcloud storage buckets create gs://picture-storage/ --location=us-central1

Observação: picture-storage não estará disponível como um nome de bucket porque já foi usado. Consulte os requisitos de nomenclatura de bucket

• Se tiver êxito, você verá a seguinte saída:

  Creating gs://BUCKET_NAME/

• Caso contrário, você talvez veja a seguinte saída:

  ServiceException: 409 Bucket BUCKET_NAME already exists

  Tente novamente com outro nome de bucket.

  Saiba mais: para mais informações, leia Criar buckets.

Como conectar um projeto a um bucket do Cloud Storage

Para usar o Cloud Storage, especifique a biblioteca do Cloud Storage.

use Google\Cloud\Storage\StorageClient;

Como armazenar imagens

Após criar um bucket do Cloud Storage e configurar uma conexão, será possível armazenar imagens. As imagens podem ser carregadas com listas de controles de acesso (ACL, na sigla em inglês) predefinidas para controlar o acesso às imagens.

Neste aplicativo de amostra, as imagens enviadas terão a ACL predefinida public-read. O URL público pode ser acessado por meio da propriedade mediaLink do seu objeto do Cloud Storage. Você pode usar esse URL em uma tag de imagem HTML.

// Set your own image file path and content type below to upload an
// image to Cloud Storage.
// $imageStream = fopen('/path/to/your_image.jpg', 'r');
// $imageContentType = 'image/jpg';
$object = $bucket->upload($imageStream, [
    'metadata' => ['contentType' => $imageContentType],
    'predefinedAcl' => 'publicRead',
]);
$imageUrl = $object->info()['mediaLink'];

Para ver instruções sobre como ler um objeto particular do Cloud Storage, consulte a página Como fazer o download de objetos.

Como excluir imagens

Quando um usuário exclui um livro do aplicativo, esse código remove a imagem do bucket do Cloud Storage.

$object = $bucket->object($objectName);
$object->delete();

Como configurar o app

Configure aplicativos para serem executados no App Engine usando um arquivo app.yaml, que especifica o ambiente de execução, as variáveis de ambiente e outras configurações do aplicativo.

Para um aplicativo com requisitos mínimos de configuração, o arquivo app.yaml pode ser uma única linha:

PHP 8.1

runtime: php81

PHP 7.4

runtime: php74

É possível adicionar outras opções de configuração e variáveis de ambiente específicas do aplicativo ao arquivo de configuração app.yaml.

Como adicionar variáveis de ambiente

O arquivo app.yaml é onde a configuração do ambiente é fornecida ao aplicativo. O exemplo de estante de livros usado neste guia precisa da configuração fornecida como variáveis de ambiente para saber como se conectar à instância correta do Cloud SQL e ao bucket do Cloud Storage.

Para implantar o aplicativo, você precisa editar o arquivo de configuração app.yaml:

# See https://cloud.google.com/appengine/docs/standard/php/config/appref for a
# complete list of `app.yaml` directives.

runtime: php81

env_variables:
    GOOGLE_STORAGE_BUCKET: ""
    # populate these to use the "mysql" or "postres" backends
    CLOUDSQL_CONNECTION_NAME: ""
    CLOUDSQL_USER: ""
    CLOUDSQL_PASSWORD: ""
    ## Uncomment to give your database a name other than "bookshelf"
    # CLOUDSQL_DATABASE_NAME: ""

1. Defina a variável GOOGLE_STORAGE_BUCKET como o nome do bucket do Cloud Storage.

2. Defina a variável CLOUDSQL_CONNECTION_NAME como app-name:region:instance-name Você pode recuperar os detalhes necessários usando o seguinte comando gcloud:

   gcloud sql instances describe INSTANCE

   Para uma instância de segunda geração do Cloud SQL, o CLOUDSQL_CONNECTION_NAME estará no seguinte formato: your_project_name:your_region:your_instance

3. Remova o comentário e defina a variável CLOUD_SQL_DATABASE_NAME se o banco de dados que você criou tiver um nome diferente de bookshelf. Neste exemplo, o banco de dados foi criado com o nome book-data.

4. Revise seu arquivo app.yaml, que precisa ser semelhante a:

PHP 8.1

runtime: php81

env_variables:
  GOOGLE_STORAGE_BUCKET: picture-storage
  CLOUDSQL_CONNECTION_NAME: sample-application:us-central1:bookshelf
  CLOUDSQL_USER: root
  CLOUDSQL_PASSWORD: passw0rd!
  CLOUDSQL_DATABASE_NAME: book-data

PHP 7.4

runtime: php74

env_variables:
  GOOGLE_STORAGE_BUCKET: picture-storage
  CLOUDSQL_CONNECTION_NAME: sample-application:us-central1:bookshelf
  CLOUDSQL_USER: root
  CLOUDSQL_PASSWORD: passw0rd!
  CLOUDSQL_DATABASE_NAME: book-data

Observação: criptografe dados confidenciais, como senhas, e não os coloque em app.yaml como texto simples. Para aplicativos de produção, use o Cloud Key Management Service para armazenar credenciais.

Como implantar o aplicativo

1. Para implantar o aplicativo, navegue até o diretório getting-started e execute o seguinte comando:

   gcloud app deploy

2. Quando o prompt de localização aparecer, escolha um local próximo aos usuários do aplicativo. O App Engine é regional, o que significa que a infraestrutura que executa o aplicativo está localizada em uma área geográfica específica. Por exemplo, neste tutorial foi usada a região us-central1 para implantar os recursos de armazenamento. Implante o aplicativo na mesma região para diminuir a latência e melhorar o desempenho.

   Em geral, é recomendável escolher um local próximo aos usuários, mas há casos em que é recomendável implantar o aplicativo perto de onde seus recursos estão localizados. Leia sobre os locais do App Engine e os locais de recursos disponíveis.

3. Confira o aplicativo:

   gcloud app browse

Limpeza

Exclua o projeto do Google Cloud para interromper o faturamento dos recursos usados no projeto.

Observação: não é possível excluir o app padrão.

Aviso: a exclusão de um projeto tem as seguintes consequências:

• Se você usou um projeto atual, exclua também qualquer outro trabalho feito no projeto.
• Não é possível reutilizar o código de um projeto excluído. Se você criou um ID de projeto personalizado e pretende usá-lo no futuro, exclua os recursos contidos no projeto. Isso garante que os URLs com o ID do projeto, como https://PROJECT_ID.REGION_ID.r.appspot.com, permaneçam disponíveis.

Para excluir o projeto, use o seguinte comando:

gcloud projects delete PROJECT_ID

Para verificar se o projeto foi excluído, liste os projetos:

gcloud projects list

Próximas etapas

• Saiba como autenticar usuários.
• Saiba mais sobre como gravar registros de aplicativos e interpretar registros de sistema em Como ler e gravar registros de aplicativos.
• Saiba como trabalhar em segundo plano de forma assíncrona após a solicitação usando o Cloud Tasks.
• Leia sobre como processar e como rotear solicitações.
• Para saber mais sobre o funcionamento do App Engine, consulte Ambiente de execução do PHP.