GCP has recently added support for PHP 7.4 in Cloud Functions. This post will give you a quick introduction to how it works, and a few pasisng thoughts.

## Prerequisites

If you haven't setup a GCP project before you'll need to go through the sign up process and configure a billing account.

Additionally you'll need to install the `gcloud` CLI: https://cloud.google.com/sdk/docs/install

Once the gcloud cli is installed you'll be able to authenticate with the following command:
```
gcloud auth login
```

## Your first function

Let's start by creating a file named `index.php` with the following:

```php
<?php
use Psr\Http\Message\ServerRequestInterface;

function helloHttp(ServerRequestInterface $request): string
{
    $queryString = $request->getQueryParams();
    $name = $queryString['name'] ?? $name;

    return sprintf('Hello, %s!', $name);
}
```

Hit save. Then open up a terminal in the same directory. To deploy this function we'll run the following:

```
gcloud functions deploy http-php-function \
  --runtime php74 \
  --trigger-http \
  --entry-point helloHttp
```

Feel free to replace `http-php-function` with a suitable name for your test function. It needs to be unique within your GCP project.

As this is a HTTP invoked function the first time you deploy a function it will ask you if you want to allow unauthenticated invocations of the functions. Say yes here for this example.

The command above will output various details, including the trigger url. This will look a little like this:

```
https://us-central1-[your-gcp-project-id].cloudfunctions.net/http-php-function
```

And there it is. Your first PHP function has been deployed on GCP!

If you want to view the logs after invoking the function you can do so with this command:

```
gcloud functions logs read http-php-function
```

> Note: It might take a minute for logs to appear, as there is a slight delay.

### Headers and response codes

By default, if your application code throws an exception then a 500 status code will be returned, otherwise it'll be treated as a 200.

To send different status codes, and headers we'll need our function to return an instance compatible with `Psr\Http\Message\ResponseInterface`. We can use Guzzle PSR7 response object for this.

```
composer require guzzlehttp/guzzle:^7.0
```

Then our updated function will look like this:

```php
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use GuzzleHttp\Psr7\Response;

function helloHttp(ServerRequestInterface $request): ResponseInterface {
    $queryString = $request->getQueryParams();
    $name = $queryString['name'] ?? 'world';

    // Sending a 418 I'm a teapot response:
    return new Response(
      418,
      ['content-type' => 'application/json'],
      json_encode(["message" => sprintf('Hello, %s!', $name) ])
    );
}
```

### Third party packages

When your function is deployed if it contains a `composer.json` file then the dependencies will be installed within Cloud Build. If you use a private package registry, then credentials will need to be provided to that context using build environment variables. [https://cloud.google.com/functions/docs/env-var#using_build_environment_variables](https://cloud.google.com/functions/docs/env-var#using_build_environment_variables).

For this you'll want to use the `COMPOSER_AUTH` environment variable. [https://getcomposer.org/doc/articles/authentication-for-private-packages.md#authentication-using-the-composer-auth-environment-variable](https://getcomposer.org/doc/articles/authentication-for-private-packages.md#authentication-using-the-composer-auth-environment-variable)

If the package is listed on packagist then you don't need to do anything else.

Next up I'll touch on local development using GCP's Functions Framework, other ways to invoke functions, and handling application logging.

## Local development

The best way right now to get going locally is to run GCP's Functions Framework. Let's get started by installing the composer dependency into our existing project:

```
composer init -q --name ashsmith/cloudfunctions-php
composer require google/cloud-functions-framework
```

To run your function locally you can just run this:

```
export FUNCTION_TARGET=helloHttp
php -S localhost:8080 vendor/bin/router.php
```

Note that the `FUNCTION_TARGET` environment variable needs to be set, and this needs to match the function you wish to invoke.

You can find out more about the Functions Framework from GitHub: [https://github.com/GoogleCloudPlatform/functions-framework-php](https://github.com/GoogleCloudPlatform/functions-framework-php)

## Application Logging

When you're running serverless stacks you do not have access to the runtime, so it's best to instrument your code with logging to give you plenty of visibility.

GCP has a logging tool called Cloud Logging. In PHP we can write to `stderr` and the logs will appear in Cloud Logging. You can also use the Cloud Logging SDK.

### Writing logs to stderr

```php
<?php

$log = fopen('php://stderr', 'wb');

// Simple log entry.
fwrite($log, "Hello world\n");
```

### Using the Cloud Logging SDK

There are a few drawbacks to using the SDK, namely you need to instrument the invocation id of the function yourself and if you want support with Cloud Trace then you'll also need to include the trace id, as well as specifying the function name and region. Writing to stderr will include all of these attributes automatically. Without them, you'll need to write custom queries to retrieve them from Cloud Logging and they won't appear when viewing logs for your function (it'll need the resource type, function name, and region at the very least).

First up you'll need to install the SDK with composer like so:

```
composer require google/cloud-logging
```

Then here's a basic example with the bare minimum to get logs appearing in the right place:
```php
use Google\Cloud\Logging\LoggingClient;
$logging = new LoggingClient();
$logger = $logging->psrLogger('app', [
  'resource' => [
    'type' => 'cloud_function',
    'labels' => [
      'function_name' => 'your-function-name',
      'region' => 'some-region',
    ],
  ],
]);

$logger->error("hello world");
```

You can grab the function name using the `K_SERVICE` environment variable, but the region you'd need to configure yourself as GCP Cloud Functions do not expose an environment variable for this. You could add a custom environment variable to grab that value (instead of hard coding, as you might want to deploy to multiple regions).

More info on the logging SDK can be found here: [https://github.com/googleapis/google-cloud-php-logging](https://github.com/googleapis/google-cloud-php-logging)

If you want to see a complete example which shows you how to include the function invocation ID, and Cloud Trace ID then here's a gist for you: [https://gist.github.com/ashsmith/69541dc0e406d767e3fa3de978d66677](https://gist.github.com/ashsmith/69541dc0e406d767e3fa3de978d66677)

## Invoke functions using different events

At the time of writing Cloud Functions PHP 7.4 supports HTTP and CloudEvents. What are CloudEvents? In esence they allow us to respond to events trigger within GCP. For example Pub/Sub, Cloud Storage or Firestore. CloudEvents use the [cloudevents.io](https://cloudevents.io/) standard to describe events in a consistent manner.

Let's create a function that responds to messages from Pub/Sub:

First up, create your pubsub topic:
```
gcloud pubsub topics create ash-test
```

Then add to the following function to your existing `index.php` file:

```php
use Google\CloudFunctions\CloudEvent;
function helloEvent(CloudEvent $event): void {
  $log = fopen('php://stderr', 'wb');

  $cloudEventData = $event->getData();
  $pubSubData = base64_decode($cloudEventData['message']['data']);

  $name = 'World';
  if ($pubSubData) {
      $name = htmlspecialchars($pubSubData);
  }

  $result = 'Hello, ' . $name . '!';
  fwrite($log, $result . PHP_EOL);
}
```

Now we can deploy the function with the following:

```
gcloud functions deploy ash-test-event \
  --runtime php74 \
  --trigger-topic ash-test \
  --entry-point helloEvent
```

Once thats deployed we can publish a message:

```
gcloud pubsub topics publish ash-test --message="ash"
```

And we can check the logs of our function:

```
gcloud functions logs read ash-test-event
```

## My thoughts...

Having first-class support for PHP is fantastic. So far you have only been able to run PHP in serverless functions on AWS and Azure, so support coming to GCP is a good thing!

It seems odd to me that they have added PHP 7.4 support and not PHP 8.0 considering thats the latest release. But this has happened with other runtimes in the past. My guess is we'll have support before 7.4 is deprecated..

The logging leaves a lot to be desired right now too. Documentation suggests that structured logs are possible, but I've not been able to get this to work. I think this is due PHP adding additional text to the output:

```
[25-Apr-2021 17:03:09] WARNING: [pool app] child 19 said into stderr: "{"message":"Structured log with error severity","severity":"ERROR"}" 
```

The json string should have been parsed by Cloud Logging, but it still treated it as a plain string. Without being able to at least control the severity in this way makes logging and log-based metrics pretty much useless in a production application.

The alternative is to use to logging SDK I mentioned earlier, but this has drawbacks as I mentioned, and would require significant work to get it where you need it to be useful.

I recongise that PHP 7.4 support is in preview, so hopefully these problems will be resolved in the future.

If you want to use PHP and serverless infrastructure I recommend [bref.sh](https://bref.sh/), it's for AWS Lambda. It uses the serverless framework and a custom Lambda Layer to provide the PHP runtime.

Cloud Functions and PHP

In this post I'll show you how you can configure SSH keys for your custom Bitbucket Pipe. This requires a tiny bit of setup, as there is no `~/.ssh` directory on the docker container. This makes using SSH a little more tricky, especially when you're using tools like git or other deployment tools that hide the actual SSH configuration.

Quick rant: who the heck named custom pipeline tasks "pipes". It's pretty much impossible to Google! I just get pipeline results.

In your shell script you'll just need to add the following:

```bash
mkdir -p ~/.ssh
cp /opt/atlassian/pipelines/agent/ssh/id_rsa_tmp ~/.ssh/id_rsa
cp /opt/atlassian/pipelines/agent/ssh/known_hosts ~/.ssh/known_hosts
chmod -R go-rwx ~/.ssh/
```

It's important to copy the `id_rsa_tmp` AND `known_hosts`. Without the known hosts file you'll be unable to connect to remote origins. The `id_rsa_tmp` represents the custom private SSH key that is added into bitbucket pipelines when you follow their guide here: https://support.atlassian.com/bitbucket-cloud/docs/variables-and-secrets/#Use-SSH-keys-in-Bitbucket-Pipelines

Make sure ssh is installed on your docker image of course too!

Setting up SSH on custom Bitbucket Pipes

This weekend I created a [Terraform provider for BigCommerce](https://registry.terraform.io/providers/ashsmith/bigcommerce/latest/docs). The reason for doing is so that you can declaritively define certain aspects of BigCommerce configuration in code. At the moment the provider only supports managing webhooks.

It looks like this:

```
terraform {
  required_providers {
    bigcommerce = {
      source = "ashsmith/bigcommerce"
      version = "0.0.4"
    }
  }
}

provider "bigcommerce" {
 client_id    = "your_stores_client_id" # env var: BIGCOMMERCE_CLIENT_ID
 access_token = "your_stores_access_token" # env var: BIGCOMMERCE_CLIENT_ID
 store_hash   = "your_store_hash" # env var: BIGCOMMERCE_STORE_HASH
}

resource "bigcommerce_webhook" "orders_webhooks" {
  # What scope of events are you listening for.
  scope = "store/order/*" # listens to all order events.

  # Where the webhook event payload will be sent:
  destination = "https://api.myawesomeapi.com/webhooks"

  is_active = true
}
```

Why define webhooks as terraform resources?

This allows us to declaratively define what events are are being consumed, which makes it easy for us to reason our applications infrastructure and it's dependencies. Additionally this terraform code can be applied to multiple environments so that we can ensure they are setup exactly the same.

We can take this a step further when combined with other terraform resources. For example, we can define the `destination` of our webhook to map directly to a HTTP-triggered GCP Cloud Function that will consume the webhook events:

```terraform
# (I have omitted other GCP resources here for brevity)
# Full example of GCP Cloud Function: 
# https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/cloudfunctions_function#example-usage---public-function
resource "google_cloudfunctions_function" "function" {
  name        = "function-test"
  description = "My function"
  runtime     = "nodejs10"

  available_memory_mb   = 128
  source_archive_bucket = google_storage_bucket.bucket.name
  source_archive_object = google_storage_bucket_object.archive.name
  trigger_http          = true
  entry_point           = "testing"
}

resource "bigcommerce_webhook" "orders_webhooks" {
  scope       = "store/order/*"
  destination = google_cloudfunctions_function.function.https_trigger_url
  is_active   = true
}
```

Just like that we'll have all order events sent to a newly provisioned Cloud Function. This is repeatable, and as mentioned before can be applied to multiple environment to ensure consistency in our configuration.

The source code is available on Github:

- https://github.com/ashsmith/terraform-provider-bigcommerce/
- https://github.com/ashsmith/bigcommerce-api-go/

And the Terraform provider is available in the registry here: 

- https://registry.terraform.io/providers/ashsmith/bigcommerce/latest


Terraform provider for BigCommerce

Today I created a small CLI utility called `ssl-gen`. When developing sites or APIs locally, having a trusted SSL certificate locally is always difficult. I can never remember all the parameters, and usually write some horrid bash script. To solve this problem I've created `ssl-gen`. It will generate your certificate and add it to Keychain so that it is registered as a trusted certificate (getting around those annoying invalid cert errors in your browser!).

You can view it on GitHub here: https://github.com/ashsmith/ssl-gen

Installation is with Homebrew:

```bash
brew tap ashsmith/ssl-gen
brew install ssl-gen
```

Then, to use it you provide your desired certificate name followed by the domains you wish to be on the certificate. The first domain will be the used as the common name.

```
# ssl-gen new [cert-name] [domains...]
ssl-gen new ashs-awesome-cert ashsmith.test www.ashsmith.test someothersite.test
```

This will generate `ashs-awesome-cert.crt` and `ashs-awesome-cert.key`. These can be used on your webserver such as nginx or apache to serve your local development site on HTTPS.

`ssl-gen new` also accepts `-o` / `--output` which allows you to specify where the certificate will be saved:

```bash
ssl-gen new ashs-cert ashsmith.test -o ~/.certs
```

Now your certificate will be saved to: `~/.certs/ashs-cert.crt`.

Happy hacking.

Introducing ssl-gen a CLI utility for generating self-signed certificates for macOS

Typescript can be really powerful way of enhancing your react components to ensure the correct props are provided with expected values. Sometimes however you may want some props to required based on what other props have been provided!

Let's dive into an example:

```jsx
const Image = ({ src, width, height, layout, ...rest }) => (
  <img
    src={src}
    width={width}
    height={height}
    className={`layout-${layout}`}
    {...rest}
  />
);
```

Now, our `layout` prop here might only be able to accept certain values. For example: `responsive` or `fill`. So let's convert this example into Typescript:

```tsx
import React, { FC } from 'react';

type Layout = 'responsive' | 'fill';

type ImageProps = Omit<JSX.IntrinsicElements['img'], 'src' | 'width' | 'height'> & {
  src: string;
  width: string | number;
  height: string | number;
  layout: Layout;
};

const Image: FC<ImageProps> = ({
  src, width, height, layout, ...rest
}) => (
  <img
    src={src}
    width={width}
    height={height}
    className={`layout-${layout}`}
    {...rest}
  />
);

export default Image;
```

So now we have correct typed the correct values, what if we wanted to enforce a rule that when `layout="fill"` is provided you are NOT allowed to define the `width` or `height` props. But when `layout="responsive"` is provided you MUST set them.

Well, to do that we can change our `ImageProps` type to support exactly this.

```ts
type ImageProps = Omit<JSX.IntrinsicElements['img'], 'src' | 'width' | 'height'> & {
  src: string;
} & ({
  layout: 'fill';
  width?: never;
  height?: never;
} | {
  layout?: Exclude<Layout, 'fill'>;
  width: string | number;
  height: string | number;
});
```

Let's break this down slightly:

Using the `Omit` utility type we are retrieving all the props that an `img` element can have, then omitting the `src`, `width` and `height` props. This allows us to redefine them in our type.

```ts
Omit<JSX.IntrinsicElements['img'], 'src' | 'width' | 'height'>
```

Next up we define the `src` prop as a required string value. The `&` will merge this with the previous  type.

```ts
& {
  src: string;
}
```

Next up is where the magic happens. We're defining a conditional type, where we're saying that when `layout` is provided with the `'fill'` value it will use the first. Otherwise it'll use the second type.

The `Exclude` utility type is similar to `Omit`. 

```ts
& ({
  layout: 'fill';
  width?: never;
  height?: never;
} | {
  layout?: Exclude<Layout, 'fill'>;
  width: string | number;
  height: string | number;
})
```

Below is the completed example. You'll notice there is also the `toInt` function in order to catch when `width` or `height` is the `never` type instead of passing it directly into the `img` component. 

```tsx
import React, { FC } from 'react';

function toInt(value: unknown): number | undefined {
  if (typeof value === 'number') {
    return value;
  }

  if (typeof value === 'string') {
    return parseInt(value, 10);
  }

  return undefined;
}

type Layout = 'responsive' | 'fill';

type ImageProps = Omit<JSX.IntrinsicElements['img'], 'src' | 'width' | 'height'> & {
  src: string;
} & ({
  layout: 'fill';
  width?: never;
  height?: never;
} | {
  layout?: Exclude<Layout, 'fill'>;
  width: string | number;
  height: string | number;
});

const Image: FC<ImageProps> = ({
  src, width, height, layout, ...rest
}) => {
  const widthInt = toInt(width);
  const heightInt = toInt(height);
  return (
  <img
    src={src}
    width={widthInt}
    height={heightInt}
    className={`layout-${layout}`}
    {...rest}
  />);
}

export default Image;
```

I found this pattern whilst exploring NextJS' Image component: https://github.com/vercel/next.js/blob/canary/packages/next/client/image.tsx, I have attempted to simplify the example here for demonstration purposes.

In this post I also touched on Utility Types (`Exclude` and `Omit` specifically). If you'd like to learn more about them you can see the Typescript documentation: https://www.typescriptlang.org/docs/handbook/utility-types.html

Conditionally required props with Typescript in React

One of the things I like from other languages like PHP is how you can throw and catch specific exceptions. Replicating this in JS/TS however requires a little extra work.

Here's a PHP example for reference:

```php
<?php
class MyException extends Exception { }

function myFunction() {
  throw new MyException('some reason');
}

try {
  myFunction();
} catch (MyException $e) {
  // Handle MyException specifically...
} catch (Exception $e) {
  // Handle all other exceptions
}
```

Now over in JS/TS environments the `try/catch` block doesn't support handling different instances of errors. Instead we'd need to add `if`/`else` or `switch` conditions inside the body of the `catch` in order to handle different cases.

However, in Typescript you cannot simply extend `Error` and expect to be able to use: `if (error instanceof MyError) { }`... Since Typescript 2.1 extending built-ins like `Error`, `Array` and `Map` may not work as you'd expect.

The workaround for this is to call: `Object.setPrototypeOf(this, MyError.prototype)` from within your consructor. Like so:

```ts
class MyError extends Error {
  constructor(message: string) {
    super(message);
    Object.setPrototypeOf(this, MyError.prototype)
  }
}
```

Now the following code will work:

```ts
const myFunction = () => {
  throw new MyError('some reason');
}

try {
  myFunction();
} catch (error) {
  if (error instanceof MyError) {
    // Handle MyError....
  }
}
```

Previously you would have received an instance of `Error` instead of `MyError`.

This is due to how [Typescript handles generating the constructor](https://github.com/Microsoft/TypeScript/wiki/Breaking-Changes#generated-constructor-code-substitutes-the-return-value-of-super-calls-as-this).

This approach to handling errors can produce a bit of nesting in your `catch` block, however it allows to handle each error differently. I find this useful when you're handling multiple scenarios where an error could be thrown, in some instances you may wish to ignore it or hide it.

Consider the following:

```ts
import axios from 'axios';

class JSONAPIError extends Error {
  constructor(message: string) {
    super(message);
    Object.setPrototypeOf(this, MyError.prototype)
  }

  public static fromAxiosError(error: AxiosError) {
    // Surface the detailed error result from our JSON:API compliant api.
    // This error could be more useful to end users
    // Axios error.message contains the status and statusText which
    // isnt useful to users.
    return new JSONAPIError(error.response?.data?.errors[0].detail ?? error.message);
  }
}

const makeApiCall = async (method, url) => {
  try {
    const response = await axios.request({ method, url });
  } catch(error) {
    if (error.response.status === 500) {
      // Notify your error handling system.
      console.error(error);
      // Throw again with a bett
      throw new Error('Internal server error, please try again or contact support');
    }

    throw JSONAPIError.fromAxiosError(error);
  }
}

try {
  const result = await makeApiCall('GET', 'https://google.com/');
  return result;
} catch(error) {
  // A consistent API for handling errors with half decent messages 😍
  window.alert(error.message);
}

```

The above example shows us how we can better control error messages that could be displayed to an end user. Furthermore I'm still exposing the same API you'd expect from `Error`. Axios in this case adds the `response` property where we can access the response from the call that was made, if our code could throw two different errors we'd have the muddy our application logic with checks if certain properties exist. However, I've tucked this away within a function that can be used for making those api calls. Our client that is rendering the error only needs to care about accessing `error.message`. 

Ash Smith

Cloud & Serverless Developer

👋 Hey, I’m Ash!

Software Engineer and keen triathlete.

Here's some recent posts of mine...

Cloud Functions and PHP

Setting up SSH on custom Bitbucket Pipes

Terraform provider for BigCommerce

Introducing ssl-gen a CLI utility for generating self-signed certificates for macOS

Conditionally required props with Typescript in React

Handling custom error classes in Typescript