Criar uma app com PHP

ID da região

O REGION_ID é um código abreviado que a Google atribui com base na região que seleciona quando cria a sua app. O código não corresponde a um país ou uma província, embora alguns IDs de regiões possam parecer semelhantes aos códigos de países e províncias usados frequentemente. Para apps criadas após fevereiro de 2020, REGION_ID.r está incluído nos URLs do App Engine. Para apps existentes criadas antes desta data, o ID da região é opcional no URL.

Saiba mais acerca dos IDs de regiões.

OK

Nota: se estiver a implementar um novo serviço Web PHP no Google Cloud, recomendamos que comece a usar o Cloud Run.

Saiba como criar uma app no App Engine com a versão 7.4 ou 8.1 do PHP. A app de exemplo permite que os utilizadores publiquem os títulos, os autores, as descrições, a data de publicação e as imagens dos seus livros favoritos numa página Web. A app armazena os dados textuais numa base de dados do Cloud SQL e as imagens num contentor do Cloud Storage.

Estrutura do guia

1. Crie um Google Cloud projeto através da Google Cloud CLI

2. Transfira a app de exemplo

3. Especifique dependências com o composer.json

4. Inicializar a app e definir controladores frontais

5. Faça a integração com os serviços do Google Cloud

6. Configure a app para o App Engine

7. Implemente a app

Antes de começar

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.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Build API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Build API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Install the Google Cloud CLI.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte comando:

gcloud init

1. Instale o Composer, a ferramenta de gestão de dependências do PHP. Tem de instalar o Composer globalmente em sistemas Linux e Mac OS X.
2. Devido a alterações no comportamento predefinido da forma como o Cloud Build usa as contas de serviço em novos projetos e alterações à política organizacional segura por predefinição, pode ter de conceder funções adicionais à sua conta de serviço de implementação. Para mais informações sobre a concessão de funções específicas, consulte o guia de resolução de problemas.

Transfira a app de exemplo

1. Explore o código no GitHub

2. Transfira ou clone a app.

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

   Em alternativa, transfira o exemplo como um ficheiro ZIP e extraia-o.

3. Navegue para o diretório getting-started.

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

Especifique dependências com o ficheiro composer.json

A app usa um controlador frontal para encaminhar pedidos. O código de exemplo neste guia usa o Slim Framework, mas pode usar um framework Web à sua escolha.

1. Abra o ficheiro composer.json para rever 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 ficheiro composer.lock, execute o seguinte comando:

   composer install
   

   O ficheiro composer.lock ajuda a sua app a obter as mesmas versões dos pacotes que usa em várias compilações e ambientes.

   Nota: uma vez que o Cloud Build opera num ambiente de memória limitada, é recomendável que produza o ficheiro composer.lock localmente. Para mais informações, consulte o artigo Especificar dependências.

Inicializar a app e definir controladores frontais

O ficheiro index.php inicializa a app e encaminha todos os pedidos para os controladores definidos no ficheiro ./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 o processamento de pedidos, leia acerca do início da aplicação e do processamento de pedidos.

Integração com os serviços Google Cloud

O App Engine requer que as apps sejam integradas com sistemas externos para o armazenamento de dados. A app de exemplo armazena dados textuais no Cloud SQL e imagens no Cloud Storage.

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

Usar o Cloud SQL

Na app de exemplo, os utilizadores publicam livros numa página Web. A app usa uma base de dados do Cloud SQL para armazenar os títulos, os autores, a data de publicação e as descrições dos livros.

Tem de criar uma instância do Cloud SQL antes de adicionar conteúdo à base de dados da app.

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 quiser dar o nome bookshelf à sua instância 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 ver informações sobre localizações de instâncias, tipos de máquinas e os respetivos efeitos nos preços, consulte a página de preços do Cloud SQL.

Configurar o utilizador root do MySQL

Pode usar a CLI gcloud para definir a palavra-passe do utilizador root da sua instância do Cloud SQL:

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

Por exemplo, se quiser definir a palavra-passe do utilizador root para a instância do Cloud SQL bookshelf como passw0rd!:

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

Saiba mais: para mais informações, leia o guia de criação e gestão de utilizadores do MySQL do Cloud SQL.

Configurar uma base de dados na instância do Cloud SQL

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

gcloud sql databases create DATABASE_NAME --instance=INSTANCE_NAME

Por exemplo, se quiser criar uma base de dados denominada 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 criação e gestão de bases de dados MySQL do Cloud SQL.

Efetuar a associação à base de dados do Cloud SQL

A app de exemplo usa o PDO do PHP para interagir com a base 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);

Para este tutorial, estes parâmetros são especificados como variáveis de ambiente abaixo em Configurar a app.

Consultar uma única linha

Quando o utilizador clica num livro, a app consulta a base de dados e devolve 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 a partir dos runtimes do PHP, leia o guia Usar o Cloud SQL para MySQL.

Usar o Cloud Storage

A app de exemplo usa o Cloud Storage para armazenar as imagens, que são ficheiros binários, carregadas pelos utilizadores.

Criar um contentor do Cloud Storage

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

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

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

Por exemplo, se quiser criar um contentor denominado picture-storage na região us-central1:

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

Nota: picture-storage não vai estar disponível como nome de contentor, uma vez que já foi usado. Veja os requisitos de nomenclatura de contentores

• Se tiver êxito, vê o seguinte resultado:

  Creating gs://BUCKET_NAME/

• Se não for bem-sucedido, pode ver o seguinte resultado:

  ServiceException: 409 Bucket BUCKET_NAME already exists

  Tente novamente com um nome de contentor diferente.

  Saiba mais: para mais informações, leia o artigo Crie contentores.

Associar um projeto a um contentor do Cloud Storage

Para usar o Cloud Storage, tem de especificar a biblioteca do Cloud Storage.

use Google\Cloud\Storage\StorageClient;

Armazenar imagens

Agora que criou um contentor do Cloud Storage e configurou uma associação, pode armazenar imagens. As imagens podem ser carregadas com listas de controlo de acesso (LCA) predefinidas para controlar o acesso às imagens.

Nesta app de exemplo, as imagens carregadas têm a ACL predefinida public-read. Pode aceder ao URL público através da propriedade mediaLink do seu objeto do Cloud Storage. Pode usar este URL numa etiqueta 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 obter instruções sobre como ler um objeto privado do Cloud Storage, consulte a página de transferência de objetos.

A eliminar imagens

Quando um utilizador elimina um livro da app, este código remove a imagem do contentor do Cloud Storage.

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

Configurar a app

Configura as aplicações para serem executadas no App Engine através de um ficheiro app.yaml, que especifica o tempo de execução, as variáveis de ambiente e outras definições da aplicação.

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

PHP 8.1

runtime: php81

PHP 7.4

runtime: php74

Pode adicionar mais opções de configuração e variáveis de ambiente específicas da aplicação ao ficheiro de configuração app.yaml.

Adicionar variáveis de ambiente

O ficheiro app.yaml é onde a configuração do ambiente é fornecida à app. O exemplo de estante de livros usado neste guia precisa de configuração fornecida como variáveis de ambiente para saber como estabelecer ligação à instância do Cloud SQL e ao contentor do Cloud Storage corretos.

Para implementar a sua app, tem de editar o app.yaml ficheiro de configuração:

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

runtime: php84

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 com o nome do seu contentor do Cloud Storage.

2. Defina a variável CLOUDSQL_CONNECTION_NAME como app-name:region:instance-name Pode obter os detalhes necessários através do seguinte comando gcloud:

   gcloud sql instances describe INSTANCE

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

3. Descomente e defina a variável CLOUD_SQL_DATABASE_NAME se a base de dados que criou tiver um nome diferente de bookshelf. Neste exemplo, a base de dados foi criada com o nome book-data.

4. Reveja o ficheiro app.yaml, que deve ter um aspeto semelhante ao seguinte:

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

Nota: deve encriptar dados confidenciais, como palavras-passe, e não os colocar no app.yaml como texto simples. Para apps de produção, use o Cloud Key Management Service para armazenar credenciais.

Implementar a aplicação

1. Para implementar a aplicação, navegue para o diretório getting-started e execute o seguinte comando:

   gcloud app deploy

2. Quando for apresentado o pedido de localização, escolha uma localização perto dos utilizadores da sua app. O App Engine é regional, o que significa que a infraestrutura que executa a sua app está localizada numa área geográfica específica. Por exemplo, este tutorial usou a região us-central1 para implementar os respetivos recursos de armazenamento. Implemente a app na mesma região para diminuir a latência e melhorar o desempenho.

   Em geral, escolher uma localização perto dos seus utilizadores é uma boa ideia, mas existem casos em que é recomendado implementar a sua aplicação perto da localização dos respetivos recursos. Leia acerca das localizações do App Engine disponíveis e das localizações de recursos.

3. Veja a aplicação:

   gcloud app browse

Limpar

Elimine o projeto Google Cloud para parar a faturação dos recursos usados no projeto.

Nota: não pode eliminar a app predefinida.
Aviso: a eliminação de um projeto tem as seguintes consequências:
• Se usou um projeto existente, também elimina qualquer outro trabalho que tenha feito no projeto.
• Não pode reutilizar o ID do projeto de um projeto eliminado. Se criou um ID do projeto personalizado que planeia usar no futuro, elimine os recursos no projeto. Isto garante que os URLs com o ID do projeto, como https://PROJECT_ID.REGION_ID.r.appspot.com, permanecem disponíveis.

Para eliminar o seu projeto com o seguinte comando:

gcloud projects delete PROJECT_ID

Para verificar se o projeto foi eliminado, liste os seus projetos:

gcloud projects list

O que se segue?

• Saiba como autenticar utilizadores.
• Saiba mais sobre como escrever registos de aplicações e interpretar registos do sistema em Ler e escrever registos de aplicações.
• Saiba como realizar tarefas em segundo plano de forma assíncrona após o seu pedido através do Cloud Tasks.
• Leia acerca do processamento de pedidos e do encaminhamento de pedidos.
• Para uma análise mais detalhada do funcionamento do App Engine, consulte o ambiente de execução do PHP.