Serverless apps are fantastic for automatic scaling, but there’s a catch: they expect you to be stateless. Most web applications, however, rely on sessions to remember users and persist state. Traditional PHP session handlers store data on the filesystem, which doesn’t play nicely with ephemeral AWS Lambda instances. Your sessions vanish as soon as the instance disappears.

The usual fix? Fire up a Redis cluster. Works, but suddenly you’ve added infrastructure, ongoing maintenance, and extra costs. Your “serverless” app feels a lot less serverless.

What if we could manage sessions without touching Redis or any other server?

In this post, we’ll show you how to build a truly serverless PHP app using Bref, Symfony, and DynamoDB for session management. Along the way, you’ll see:

• A custom DynamoDB-backed session handler that replaces filesystem sessions
• How to deploy your app via Lambda Function URLs using AWS CDK
• Storing CSRF tokens in DynamoDB for fully stateless operation
• Single-table design patterns for efficient multi-entity storage

By the end, you’ll know not just how to implement this architecture, but also when it makes sense and what trade-offs you’re accepting.

The Challenge: Sessions in Serverless

Before we dive into the solution, let’s understand why traditional PHP sessions fail in serverless environments.

1. Ephemeral Storage: Lambda instances can vanish at any time. Writing sessions to /tmp is like storing them in sand. They disappear when the instance is recycled.
2. No Shared Filesystem: Each Lambda invocation runs on its own instance. User A’s session written by instance 1 is invisible to instance 2. That’s a problem if your user expects to stay logged in.
3. Horizontal Scaling Woes: Lambda scales horizontally automatically. Without centralized session storage, each instance is isolated. Consistent session management? Forget it.

The Traditional Solution: Redis/ElastiCache

Most serverless PHP guides suggest Redis. While it works, it comes with headaches:

• Infrastructure complexity: VPCs, subnets, and security groups
• Maintenance burden: Patching, monitoring, capacity planning
• Cold start penalty: VPC-connected Lambdas can take 1–2 extra seconds

Better idea: DynamoDB. It’s fully managed, serverless, and scales automatically. No Redis cluster, no maintenance, just pay for what you use.

Books and Authors App (Serverless Style)

Imagine you’re building a multi-tenant SaaS app, like an internal tool for managing books and authors. Each user needs a session, and each organization manages its own data. DynamoDB’s single-table design can elegantly handle all this. Serverless scaling takes care of traffic spikes automatically.

Here’s what this example demonstrates:

• Multi-entity relationships: Books belong to authors
• CRUD operations: Create, read, update, and delete across related entities
• Session-dependent workflows: Adding/editing books requires authentication
• Real-world complexity: More than a simple counter, less than a full e-commerce platform

Connecting to Real Use Cases

This architecture shines in scenarios like:

• Unpredictable traffic: Seasonal spikes when authors release new books
• Session management: Authors need persistent sessions to edit content
• Cost efficiency: During quiet periods, you pay pennies; during spikes, DynamoDB scales automatically
• Zero maintenance: No Redis clusters to monitor, no database servers to patch

The book management example proves that this approach isn’t just theoretical: it’s production-ready.

Architecture Overview

To build a serverless PHP application that supports sessions, CSRF protection, and persistent data, we follow a stateful/stateless separation pattern. This makes the architecture scalable, cost-efficient, and easy to maintain.

1. Stateful Layer: Persistent Data

This layer is responsible for storing all data that needs to survive beyond a single Lambda invocation.

• DynamoDB Table

  • Uses a single-table design to store sessions, CSRF tokens, users, books, and authors.
  • TTL enabled for automatic session expiration.
  • On-demand billing ensures automatic scaling with traffic.
  • Built-in multi-AZ replication provides high availability.

• Benefits

  • No infrastructure to manage or patch.
  • Automatically scales with unpredictable traffic.
  • Centralized storage simplifies queries and operations.

2. Stateless Layer: Application Logic

This layer runs the application code and handles requests without storing any persistent state locally.

• Lambda Function

  • Runs PHP-FPM via Bref.
  • Handles HTTP requests directly using a Lambda Function URL (HTTPS endpoint).
  • No VPC required to access DynamoDB, reducing cold start latency.

• Static Assets

  • Stored in S3 (optionally served via CloudFront) to keep Lambda stateless.

• Benefits

  • Scales automatically with traffic.
  • Cost-efficient: pay only for actual requests.
  • Stateless logic simplifies deployment and updates.

This design ensures a truly serverless PHP application that handles session state, persistent data, and scalable workloads without the operational overhead of managing Redis or other caching layers.

DynamoDB Session Handler and CSRF Implementation

Session Handler Implementation

In a serverless PHP application, traditional session storage (files or local memory) doesn’t work because Lambda functions are ephemeral. Each invocation may run on a different container, so we need a centralized, persistent session store.

The core of our solution is a custom session handler that implements PHP's SessionHandlerInterface.

How It Works

• Sessions are stored in DynamoDB instead of the filesystem.
• Each session has a unique session_id, which becomes the partition key (PK) in DynamoDB.
• Sessions include the serialized PHP session data and an expiration timestamp (TTL).
• The handler automatically reads/writes session data on session_start() and session_write_close().

Key Features

1. Automatic Expiration
   • DynamoDB TTL ensures sessions are removed automatically after expiration.
2. Atomic Operations
   • PutItem and UpdateItem guarantee consistent writes, even with concurrent requests.
3. Scalable
   • Can handle thousands of concurrent sessions without extra infrastructure.
4. Serverless-friendly
   • No local storage, no Redis, fully compatible with Lambda statelessness.

Implementation

<?php

namespace App\Session;

use AsyncAws\DynamoDb\DynamoDbClient;
use AsyncAws\DynamoDb\Input\DeleteItemInput;
use AsyncAws\DynamoDb\Input\GetItemInput;
use AsyncAws\DynamoDb\Input\PutItemInput;
use AsyncAws\DynamoDb\ValueObject\AttributeValue;

/**
 * A minimal DynamoDB-backed PHP session handler using AsyncAws.
 *
 * Table design (single-table compatible):
 *  - PK: "SESSION"
 *  - SK: "SID#<session_id>"
 *  - data: base64-encoded session payload (string)
 *  - expiresAt: unix epoch seconds (number), enable DynamoDB TTL on this attribute
 *
 * Garbage collection is handled by DynamoDB's TTL, so gc() is a no-op.
 */
class DynamoDbSessionHandler implements \SessionHandlerInterface
{
    private const string PK_VALUE = 'SESSION';
    private const string SK_PREFIX = 'SID#';

    public function __construct(
        private readonly DynamoDbClient $dynamoDb,
        private readonly string $tableName,
        private readonly int $ttlSeconds = 3600,
    ) {}

    public function open(string $path, string $name): bool
    {
        // Nothing to do
        return true;
    }

    public function close(): bool
    {
        // Nothing to do
        return true;
    }

    public function read(string $id): string
    {
        $result = $this->dynamoDb->getItem(new GetItemInput([
            'TableName' => $this->tableName,
            'Key' => [
                'PK' => new AttributeValue(['S' => self::PK_VALUE]),
                'SK' => new AttributeValue(['S' => self::SK_PREFIX . $id]),
            ],
            // Strongly consistent read to reduce stale sessions
            'ConsistentRead' => true,
        ]));

        $item = $result->getItem();
        if (!$item || !isset($item['data'])) {
            return '';
        }

        $encoded = $item['data']->getS();
        if ($encoded === null) {
            return '';
        }

        $payload = base64_decode($encoded, true);
        return $payload === false ? '' : $payload;
    }

    public function write(string $id, string $data): bool
    {
        $expiresAt = time() + $this->ttlSeconds;

        $this->dynamoDb->putItem(new PutItemInput([
            'TableName' => $this->tableName,
            'Item' => [
                'PK' => new AttributeValue(['S' => self::PK_VALUE]),
                'SK' => new AttributeValue(['S' => self::SK_PREFIX . $id]),
                'data' => new AttributeValue(['S' => base64_encode($data)]),
                'expiresAt' => new AttributeValue(['N' => (string) $expiresAt]),
            ],
        ]));

        return true;
    }

    public function destroy(string $id): bool
    {
        $this->dynamoDb->deleteItem(new DeleteItemInput([
            'TableName' => $this->tableName,
            'Key' => [
                'PK' => new AttributeValue(['S' => self::PK_VALUE]),
                'SK' => new AttributeValue(['S' => self::SK_PREFIX . $id]),
            ],
        ]));

        return true;
    }

    public function gc(int $max_lifetime): int|false
    {
        // Rely on DynamoDB TTL to expire items; nothing to scan/delete here.
        return 0;
    }
}

Why it matters?

This approach:

• Keeps your PHP sessions serverless-compatible.
• Avoids cold-start pitfalls associated with local or in-memory session storage.
• Provides a reliable, scalable, and fully managed solution for stateful data in a stateless environment.

CSRF Token Storage

In a serverless environment, CSRF tokens must be handled carefully. Because Lambda executions are stateless, tokens cannot be stored in memory or on the filesystem. Instead, CSRF tokens are persisted in DynamoDB alongside session data.

This approach ensures tokens remain valid and verifiable across multiple Lambda invocations.

How CSRF Tokens Are Stored

Each CSRF token is stored as a dedicated item in the DynamoDB table:

• Tokens are associated with a specific action
• Each token has a unique identifier
• An expiration timestamp is stored for automatic cleanup

This makes CSRF token storage consistent, durable, and serverless-compatible.

Data Model

CSRF tokens follow the same single-table design pattern used elsewhere in the application.

Using a distinct partition key avoids contention and allows tokens to scale independently from session traffic.

Lifecycle

1. A CSRF token is generated when a form is rendered.
2. The token is persisted in DynamoDB.
3. On form submission, the token is retrieved and validated.
4. After validation or expiration, the token is deleted or allowed to expire via TTL.

This lifecycle mirrors traditional CSRF handling while remaining compatible with Lambda’s

Implementation

class DynamoDbCsrfTokenStorage implements CsrfTokenStorageInterface
{
    private const string PK_VALUE = 'CSRF';
    private const string SK_PREFIX = 'TOKEN#';

    public function getToken(string $tokenId): string
    {
        $result = $this->dynamoDb->getItem(new GetItemInput([
            'TableName' => $this->tableName,
            'Key' => [
                'PK' => new AttributeValue(['S' => self::PK_VALUE]),
                'SK' => new AttributeValue(['S' => self::SK_PREFIX . $tokenId]),
            ],
        ]));

        $item = $result->getItem();
        return $item['value']->getS() ?? '';
    }

    public function setToken(string $tokenId, string $token): void
    {
        $expiresAt = time() + $this->ttlSeconds;

        $this->dynamoDb->putItem(new PutItemInput([
            'TableName' => $this->tableName,
            'Item' => [
                'PK' => new AttributeValue(['S' => self::PK_VALUE]),
                'SK' => new AttributeValue(['S' => self::SK_PREFIX . $tokenId]),
                'value' => new AttributeValue(['S' => $token]),
                'expiresAt' => new AttributeValue(['N' => (string) $expiresAt]),
            ],
        ]));
    }
}

This ensures CSRF protection works seamlessly across multiple Lambda invocations.

Symfony Configuration

Configuring Symfony correctly is key for serverless PHP apps to work reliably with Lambda, DynamoDB, and Bref. Here’s how we set it up.

1. Session Storage

We replace the default PHP session handler with our DynamoDBSessionHandler:

# config/packages/framework.yaml
framework:
    session:
        handler_id: App\Session\DynamoDBSessionHandler
        cookie_secure: auto
        cookie_samesite: lax
        cookie_lifetime: 3600  # 1 hour

Notes:

• handler_id points to our custom service.
• cookie_secure: auto ensures HTTPS enforcement on Lambda URLs or custom domains.
• cookie_lifetime aligns with DynamoDB TTL for consistency.

2. Service definition

Register the DynamoDB session handler as a Symfony service:

# config/services.yaml
services:
  App\Session\DynamoDbSessionHandler:
    arguments:
      $tableName: '%book_table_name%'
      $ttlSeconds: '%env(default:session_ttl_seconds:int:SESSION_TTL)%'

• $tableName comes from environment variables to support multiple environments.
• $ttl matches the session lifetime for automatic garbage collection.
  This configuration tells Symfony to use our custom handler for all session operations. The handler is automatically injected with the DynamoDB client through Symfony's autowiring.

3. RequestContextListener

To handle dynamic Lambda Function URLs, we register a listener:

# config/services.yaml
services:
    App\EventListener\RequestContextListener:
        tags:
            - { name: kernel.event_listener, event: kernel.request, method: onKernelRequest }

Purpose:

• Ensures Symfony’s URL generator produces correct URLs.
• Sets proper scheme and host for redirects, forms, and CSRF validation.
• Essential for Lambda Function URLs where host/scheme changes per invocation.

Why It’s Needed

Lambda Function URLs:

• Provide a direct HTTPS endpoint (e.g., https://xyz.lambda-url.us-east-1.on.aws/)
• Are dynamic and unknown at build time
• Require Symfony to know the scheme and host at runtime to generate correct URLs

Without a listener:

• Redirects may point to HTTP instead of HTTPS
• CSRF tokens may fail
• Session cookies might be rejected
• OAuth or SSO integrations could break

Implementation

<?php

namespace App\EventListener;

use Symfony\Component\EventDispatcher\Attribute\AsEventListener;
use Symfony\Component\HttpKernel\Event\RequestEvent;
use Symfony\Component\HttpKernel\KernelEvents;
use Symfony\Component\Routing\RequestContext;

#[AsEventListener(event: KernelEvents::REQUEST, priority: 1024)]
class RequestContextListener
{
    public function __construct(private RequestContext $requestContext) {}

    public function onKernelRequest(RequestEvent $event): void
    {
        if (!$event->isMainRequest()) {
            return;
        }

        $request = $event->getRequest();

        // Force HTTPS for Lambda URLs and set proper context
        if ($request->headers->get('host') && str_contains($request->headers->get('host'), 'lambda-url')) {
            $this->requestContext->setScheme('https');
            $this->requestContext->setHost($request->headers->get('host'));
            $this->requestContext->setHttpPort(80);
            $this->requestContext->setHttpsPort(443);

            $request->server->set('HTTPS', 'on');
            $request->server->set('SERVER_PORT', 443);
            $request->server->set('REQUEST_SCHEME', 'https');
        }
    }
}

The CDK Output Dilemma:

// CDK can output the Lambda URL after deployment
new CfnOutput(this, 'LambdaURL', { 
    value: statelessStack.monolithLambdaFunctionUrl.url 
});
// But this value is only known AFTER deployment completes
// You can't use it as an environment variable in the SAME deployment

Tip: This listener is only necessary if you use the Lambda Function URL as the production endpoint. If you use a custom domain, this can be simplified or skipped.

With this configuration, Symfony becomes serverless-ready, maintaining sessions, CSRF protection, and routing behavior seamlessly while leveraging DynamoDB and Lambda.

Single-Table Design Pattern

All entities (sessions, CSRF tokens, users, books, authors) live in a single DynamoDB table. This simplifies the architecture and enables atomic operations across different entities.

• Why single-table?
  • Reduces infrastructure complexity.
  • Simplifies monitoring and backup.
  • Supports atomic transactions across multiple entity types.
  • Aligns with AWS best practices for DynamoDB.

AWS CDK Infrastructure with Bref

Deploying a serverless Symfony app requires some AWS setup. Using AWS CDK with Bref makes this smooth, maintainable, and repeatable.

Why CDK?

• Infrastructure as code: Everything is versioned and reproducible.
• Integration with Symfony: Easy to link environment variables, DynamoDB, and Lambda functions.
• Bref-friendly: Deploy PHP Lambda layers without manually configuring Lambda functions.

Stateful Stack: DynamoDB Table

import { NestedStack } from "aws-cdk-lib";
import * as ddb from "aws-cdk-lib/aws-dynamodb";

export class BlogAppStatefulStack extends NestedStack {
  public readonly ddb: ddb.Table;

  constructor(scope: Construct, id: string, props: MyNestedStackProps) {
    super(scope, id, props);

    this.ddb = new ddb.Table(this, 'ddb', {
      tableName: `${id}-table`,
      partitionKey: { name: 'PK', type: ddb.AttributeType.STRING },
      sortKey: { name: 'SK', type: ddb.AttributeType.STRING },
      billingMode: ddb.BillingMode.PAY_PER_REQUEST,
      deletionProtection: props.shared.environment === 'prod',
      timeToLiveAttribute: 'expiresAt',
    });
  }
}

Key features:

• Generic Key Schema: PK and SK enable single-table design
• TTL Enabled: expiresAt attribute automatically removes expired items
• Production Protection: Deletion protection enabled for production environments

Stateless Stack: Lambda Function with Bref

import { packagePhpCode, PhpFpmFunction } from "@bref.sh/constructs";
import * as lambda from "aws-cdk-lib/aws-lambda";
import { FunctionUrl } from "aws-cdk-lib/aws-lambda";

export class BlogAppStatelessStack extends NestedStack {
  public readonly monolithLambda: PhpFpmFunction;
  public monolithLambdaFunctionUrl: FunctionUrl;

  private createLambda(props: MyNestedStackProps, staticAssetsBucket: Bucket, ddb: ddb.Table) {
    const lambdaEnvironment = {
      APP_ENV: props.shared.environment,
      APP_SECRET: appSecret,
      ASSET_URL: `https://${staticAssetsBucket.bucketDomainName}/`,
      AWS_LAMBDA_LOG_FORMAT: 'text',
      BOOK_TABLE_NAME: `${props.shared.stackPrefix}-StatefulStack-table`,
    };

    const monolithLambda = new PhpFpmFunction(this, 'App', {
      handler: 'public/index.php',
      phpVersion: '8.4',
      code: packagePhpCode('php', {
        exclude: ['.env.local', 'bin/'],
      }),
      functionName: `${props.shared.stackPrefix}-App`,
      timeout: Duration.seconds(28),
      memorySize: Size.gibibytes(2).toMebibytes(),
      environment: lambdaEnvironment,
    });

    // Create Function URL with no authentication
    const monolithLambdaFunctionUrl = monolithLambda.addFunctionUrl({ 
      authType: lambda.FunctionUrlAuthType.NONE 
    });

    // Grant DynamoDB permissions
    ddb.grantReadWriteData(monolithLambda);

    return { monolithLambda, monolithLambdaFunctionUrl };
  }
}

Lambda Function URL Configuration

Lambda Function URLs provide a simple HTTPS endpoint without needing API Gateway:

const monolithLambdaFunctionUrl = monolithLambda.addFunctionUrl({ 
  authType: lambda.FunctionUrlAuthType.NONE 
});

Benefits of Lambda URLs:

• Simplicity: Direct HTTPS endpoint without API Gateway complexity
• Cost: No API Gateway charges
• Performance: One less hop in the request path
• Built-in HTTPS: Automatic TLS certificate management

Configuration Options:

• authType: NONE: Public access (suitable for web applications)
• authType: AWS_IAM: Requires AWS signature (for service-to-service communication)

Main Stack: Orchestration

export class BlogApp extends Stack {
  constructor(scope: Construct, id: string, props: MyStackProps) {
    super(scope, id, props);

    const stackPrefix = props.shared.envStackPrefix;

    const statefulStack = new BlogAppStatefulStack(
      this, `${stackPrefix}-StatefulStack`, props
    );

    const statelessStack = new BlogAppStatelessStack(
      this, `${stackPrefix}-StatelessStack`, props, statefulStack
    );

    // Output important values
    new CfnOutput(this, 'Lambda', { 
      value: statelessStack.monolithLambda.functionName 
    });
    new CfnOutput(this, 'LambdaURL', { 
      value: statelessStack.monolithLambdaFunctionUrl.url 
    });
    new CfnOutput(this, 'DynamoDb', { 
      value: statefulStack.ddb.tableName 
    });
  }
}

Deployment with CDK

With the infrastructure defined, deploying the application becomes a repeatable and predictable process. This section focuses on how the application is built, deployed, and updated using AWS CDK.

Local Development Environment

Local development mirrors the production setup as closely as possible while remaining lightweight.

• Docker is used to provide a consistent PHP environment.
• A Makefile abstracts common commands to reduce cognitive load.
• Symfony runs locally with the same session and configuration logic used in Lambda.

You can run:

# Pre-requisite - source your aws profile
make up

You can check logs via make logs. And get into the container with make bash. The application will be available at http://localhost:8000, but it might fail to load as there is no existent DynamoDB to connect with. You can check local .env file for environment variables.

Deploying

Deploy the application using standard CDK commands (inside the container):

# Pre-requisite - Bootstrap CDK if this is your first deployment - npx cdk bootstrap aws://<ACCOUNT_ID>/<REGION>
# Install dependencies
npm run deploy

Alternatively, you can use the Makefile command outsite the container:

make deploy

What Gets Created

The deployment creates:

1. DynamoDB table with TTL enabled
2. Lambda function with PHP 8.4 runtime (via Bref)
3. Lambda Function URL for HTTPS access
4. S3 bucket for static assets
5. IAM roles and permissions

The output should be similar to:

BlogApp (sandbox-blog-app): deploying... [1/1]
sandbox-blog-app: creating CloudFormation changeset...

 ✅  BlogApp (sandbox-blog-app)

✨  Deployment time: 148.76s

Outputs:
BlogApp.AssetsBucket = sandbox-blog-app-sandboxbloga-assetsbucket5cb76180-5lu45xsqvuym
BlogApp.DynamoDb = sandbox-BlogApp-StatefulStack-table
BlogApp.Lambda = sandbox-BlogApp-App
BlogApp.LambdaURL = https://kiv7utcwku6gihqgs4bfkeuzma0oaylo.lambda-url.us-east-1.on.aws/
Stack ARN:
arn:aws:cloudformation:us-east-1:973974862728:stack/sandbox-blog-app/9ba92580-e50b-11f0-a602-0afffb8dc1a9

✨  Total time: 163.03s

In this case, https://kiv7utcwku6gihqgs4bfkeuzma0oaylo.lambda-url.us-east-1.on.aws/ is the Lambda public URL.

When you access the URL, you will see a log-in form. You can use the "Register" link to create a login. Use it and you will be able to manage Authors and Books. Try to log out and access the pages directly.

Internally it will execute a series of commands:

# clean
npm run clean && \
# execute php packaging including composer install and npm build for symfony
npm run package:sandbox && \ 
# deploy as a sandbox not requiring approval
NODE_ENV=sandbox cdk deploy --require-approval never

There is a prod version executing make deploy:prod.

Testing the Session Implementation

The application includes a test endpoint to verify session persistence:

#[Route('/session-test', name: 'session_test')]
public function test(Request $request): JsonResponse
{
    $session = $request->getSession();
    $counter = $session->get('counter', 0);
    $session->set('counter', $counter + 1);

    return new JsonResponse([
        'message' => 'Session test',
        'session_id' => $session->getId(),
        'counter' => $session->get('counter'),
        'handler' => get_class($session->getMetadataBag()->getMetadata('handler')),
    ]);
}

Test with curl:

# First request creates session
curl -i -c cookie.txt https://your-lambda-url/session-test

# Subsequent requests increment counter
curl -i -b cookie.txt https://your-lambda-url/session-test
curl -i -b cookie.txt https://your-lambda-url/session-test

# outputs
➜ curl -i -c cookie.txt https://your-lambda-url/session-test
{"message":"Session incremented","session_id":"02b0c08e1ccd5f3ea015a06c69e29d11","counter":1,"handler":"App\\Session\\DynamoDbSessionHandler"}%

➜ curl -i -b cookie.txt https://your-lambda-url/session-test
{"message":"Session incremented","session_id":"02b0c08e1ccd5f3ea015a06c69e29d11","counter":2,"handler":"App\\Session\\DynamoDbSessionHandler"}%

➜ curl -i -b cookie.txt https://your-lambda-url/session-test
{"message":"Session incremented","session_id":"02b0c08e1ccd5f3ea015a06c69e29d11","counter":3,"handler":"App\\Session\\DynamoDbSessionHandler"}%

Performance Considerations

Cold Start Optimization

1. Memory Allocation: Using 2GB memory reduces cold start times
2. Composer Optimization: --no-dev --optimize-autoloader reduces code size
3. PHP 8.4: Latest PHP version with JIT compiler support

DynamoDB Performance

1. Consistent Reads: Ensures session consistency at the cost of slightly higher latency
2. On-Demand Billing: No capacity planning, automatic scaling
3. TTL: Automatic cleanup without scan operations

The serverless model's primary advantage is alignment of costs with actual usage, particularly beneficial for applications with variable or unpredictable traffic patterns. However, actual costs vary significantly based on traffic patterns, request complexity, and specific use cases. It's recommended to use AWS cost estimation tools and monitor actual usage to understand the financial impact for your specific application.

Security Best Practices

Session Security

1. Secure Flag: Ensures cookies only sent over HTTPS
2. SameSite: Protects against CSRF attacks
3. Regenerate ID: After authentication to prevent session fixation

framework:
    session:
        cookie_httponly: true
        cookie_secure: auto
        cookie_samesite: lax

DynamoDB Permissions

The Lambda function requires minimal permissions:

ddb.grantReadWriteData(monolithLambda);

This grants only:

• dynamodb:GetItem
• dynamodb:PutItem
• dynamodb:DeleteItem
• dynamodb:Query
• dynamodb:Scan

No administrative permissions are granted to the Lambda function.

Limitations

While serverless PHP with DynamoDB sessions offers compelling advantages, it's important to understand the limitations and trade-offs. Here's an honest assessment of where this architecture may not be the best fit:

1. Cold Start Latency

The Reality: Lambda cold starts can add 1-3 seconds to the first request after a function has been idle. In practice this occurs for less than 1% of the calls.

Mitigation Strategies:

• Provisioned Concurrency: Pre-warm Lambda instances to eliminate cold starts (adds ~$15/month per instance)
• Keep-Warm Pings: Use CloudWatch Events to invoke functions every 5-10 minutes (adds minimal cost but doesn't help with scaling)
• Larger Memory Allocation: We use 2GB memory which provides faster CPUs, reducing cold start duration
• Optimize Code: Minimize dependencies, use PHP preloading, optimize autoloader

When it's acceptable: Background jobs, internal tools, APIs with relaxed SLAs
When it's problematic: User-facing e-commerce, real-time chat, gaming applications

2. Request Timeout Constraints

The Reality: Our configuration uses 28 seconds timeout (API Gateway compatible), though Lambda supports up to 15 minutes, which Lambda URLs supports.

Not Suitable For:

• Long-running batch jobs: Data exports, report generation, video processing
• Large file uploads: Direct file uploads over 10MB become unreliable
• Complex data migrations: Multi-step transformations requiring minutes to complete
• WebSocket connections: Not supported by Lambda Function URLs (use API Gateway WebSocket instead)

Recommended Alternatives:

• Keep Lambda URL: If API Gateway specific features are not needed, we can use custom domain with Lambda URLs and process up to 15 minutes
• AWS Step Functions: Orchestrate long-running workflows across multiple Lambda invocations
• ECS/Fargate: For truly long-running processes (hours), use containers instead
• Presigned S3 URLs: For large file uploads, let clients upload directly to S3
• SQS + Background Workers: Offload heavy processing to asynchronous queues

3. Session Consistency Edge Cases

The Reality: DynamoDB is eventually consistent by default, but we use ConsistentRead: true to mitigate this.

Why We Use ConsistentRead:

'ConsistentRead' => true,  // Ensures we always get the latest session data

Rare Race Conditions:
Even with consistent reads, race conditions can occur when:

• Simultaneous Writes: User opens multiple tabs, both modify session simultaneously—last write wins
• Write-then-Read Timing: Session written in one Lambda, immediately read by another—minimal delay possible
• Cross-Region Scenarios: If using Global Tables, replication lag can cause stale reads in remote regions

Practical Impact: In 99.9% of cases, consistent reads solve the problem. Edge cases typically affect power users opening many tabs or distributed teams across continents.

Mitigation: For critical operations (e.g., payment processing), use DynamoDB conditional expressions to ensure atomic updates and detect conflicts.

4. DynamoDB Costs at Scale

DynamoDB's pay-per-request pricing is cost-effective at low-to-moderate traffic but pricing characteristics change at high scale.

Assumptions

DynamoDB:

• On-demand billing: $1.25 per million reads/writes
• 1KB session item size
• 1 read + 1 write per request

Redis (ElastiCache):

• t4g.medium: $0.037/hr (~$27/month)
• 1 node sufficient for low-medium traffic
• High traffic may require bigger node(s)

Cost Table

When Fixed Infrastructure (like Redis/ElastiCache) May Become More Cost-Effective:

• Sustained high traffic volumes where fixed costs are fully utilized
• Long-lived sessions with more reads than writes
• Advanced caching features needed beyond simple session storage

Hidden DynamoDB Cost Factors:

• Consistent reads cost more than eventually consistent reads
• Session writes on every request (even if session data unchanged)
• AWS free tier limitations after 12 months

Start with DynamoDB for simplicity and operational efficiency. Monitor costs monthly as traffic grows. If costs become a concern at high scale, evaluate whether fixed infrastructure or caching optimizations make sense for your specific use case.

These limitations are not dealbreakers but they're trade-offs. For the right use cases (bursty traffic, cost-sensitive, minimal ops), the benefits far outweigh the drawbacks.

Conclusion

Building serverless PHP applications doesn't require sacrificing familiar frameworks or patterns. By implementing a custom DynamoDB session handler, we achieve:

• Truly serverless architecture: No Redis, no EFS, pure AWS managed services
• Production-ready session management: Consistent, scalable, and secure
• Cost-effective: Pay only for actual usage
• Developer-friendly: Standard Symfony application with minimal modifications
• Type-safe infrastructure: AWS CDK with TypeScript
• Modern PHP: PHP 8.4 with all latest features
• Local development: Docker-compose for local testing

The combination of Bref for Lambda PHP support, Symfony for application framework, and DynamoDB for stateful storage creates a robust, scalable, and maintainable serverless application architecture.

When Should You Use This Architecture?

Choose this approach when:

• Traffic is unpredictable or bursty (blogs, seasonal apps, internal tools)
• Cost optimization matters more than absolute performance
• Zero operational overhead is a priority
• You need automatic scaling without capacity planning

Common use cases are:

• CMS - Blogs, documentation sites, and knowledge bases with infrequent or sporadic traffic, when sudden spikes are scaled automatically and quite periods costs pennies
• Admin Panels and Internal Tools - Dashboard interfaces, internal reporting tools, and back-office applications with sporadic usage patterns. DynamoDB maintains session state without requiring Redis or similar infrastructure.
• Multi-Tenant SaaS Applications - B2B platforms where each tenant has independent traffic patterns. DynamoDB's single-table design efficiently manages sessions across all tenants without cross-tenant interference.
• API Services with Session Requirements - REST APIs that need stateful operations like OAuth flows, multi-step workflows, or temporary data caching. No Redis clusters to maintain, no session cleanup cron jobs to manage. DynamoDB TTL handles everything automatically.
• Seasonal Applications - Event registration systems, holiday campaign sites, tax filing applications, and other time-bound services.
• Microservices Requiring Session State - Distributed systems where individual services need temporary state management across invocations.

Consider alternatives when:

• You require consistent sub-100ms response times
• Traffic is predictable and sustained at high levels (>10M requests/month)
• Long-running processes or WebSocket connections are needed

The Bigger Picture

This implementation demonstrates that serverless and stateful aren't mutually exclusive. While serverless advocates often emphasize "stateless functions," real-world applications need state management. The key is choosing the right state storage mechanism, and DynamoDB proves that managed, serverless databases can handle session management as effectively as traditional infrastructure, with far less operational burden.

Whether you're building a content management system, an internal admin panel, or a multi-tenant SaaS application, this architecture provides a production-ready foundation. Start simple, monitor costs and performance, and scale confidently knowing your infrastructure will grow with your application without requiring a dedicated ops team.

Resources

• Bref Documentation
• Bref CDK Constructs
• AsyncAws DynamoDB Client
• Symfony Session Documentation
• Lambda Function URLs
• DynamoDB Single-Table Design

Source Code

The complete source code for this application is available at: rafaelbernard/serverless-php-with-bref-symfony-and-dynamodb-session-management/

For detailed technical implementation notes, test coverage reports, and deployment validation, see IMPLEMENTATION_SUMMARY.md in the repository. This document covers:

• Complete test suite (112 tests across PHP and CDK)
• Infrastructure validation details
• Code quality metrics
• Deployment procedures and best practices

Bonus: Guide to Custom Domain Configuration with Route53

Lambda Function URLs provide a quick way to expose your Lambda function over HTTPS, but the auto-generated URL (e.g., https://abc123xyz.lambda-url.us-east-1.on.aws/) isn't branded or memorable. But you can add a Simple CNAME Mapping: Direct Route53 CNAME to Lambda Function URL (easiest, limited SSL control).

This is the quickest and easiest method. Just create a CNAME record pointing to your Lambda Function URL. Best for internal tools, prototypes, and non-production environments.

Prerequisites

Before configuring custom domains, ensure you have:

1. Domain registered in Route53 (or another registrar with ability to update nameservers)
2. Hosted Zone created in Route53 for your domain

Implementation with CDK

Here's how to add a custom domain CNAME record pointing to your Lambda Function URL using AWS CDK:

import * as route53 from 'aws-cdk-lib/aws-route53';
import * as route53Targets from 'aws-cdk-lib/aws-route53-targets';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import { Construct } from 'constructs';

// Assuming you have a Lambda function with Function URL enabled
const myFunction = new lambda.Function(this, 'MyFunction', {
  // ... function configuration
  functionUrlOptions: {
    authType: lambda.FunctionUrlAuthType.NONE, // or AWS_IAM
  },
});

// Get the hosted zone for your domain
const hostedZone = route53.HostedZone.fromLookup(this, 'HostedZone', {
  domainName: 'yourdomain.com',
});

// Create CNAME record pointing to Lambda URL
new route53.CnameRecord(this, 'LambdaUrlCname', {
  zone: hostedZone,
  recordName: 'api', // Creates api.yourdomain.com
  domainName: cdk.Fn.parseDomainName(myFunction.functionUrl), // Extracts hostname from URL
  ttl: cdk.Duration.minutes(5),
  comment: 'CNAME to Lambda Function URL',
});

// Output the custom domain
new cdk.CfnOutput(this, 'CustomDomainUrl', {
  value: `https://api.yourdomain.com`,
  description: 'Custom domain URL for Lambda function',
});

Testing Your CNAME Setup

After creating the CNAME record, verify it works:

# Check DNS propagation
dig api.yourdomain.com

# Test the endpoint
curl -i https://api.yourdomain.com/

# Verify SSL certificate
openssl s_client -connect api.yourdomain.com:443 -servername api.yourdomain.com | grep subject

Expected Results:

• DNS query returns Lambda Function URL hostname as CNAME target
• HTTP request succeeds with same response as Lambda URL
• SSL certificate shows AWS-managed certificate (not your custom domain)

Managing secrets securely in AWS Lambda functions is crucial for maintaining the integrity and confidentiality of your applications. AWS provides services like AWS Secrets Manager and AWS Systems Manager Parameter Store to manage secrets. However, frequent retrieval of secrets can introduce latency and additional costs. To optimize this, we can cache secrets using a Lambda Extension.

In this article, we will demonstrate how to use a pre-existing Lambda Extension to cache secrets for a PHP Lambda function using the Bref layer and AWS CDK for deployment.

On a high-level, these are the components involved:

Using the AWS Parameter and Secrets Lambda extension to cache parameters and secrets

The new AWS Parameters and Secrets Lambda extension provides a managed parameters and secrets cache for Lambda functions. The extension is distributed as a Lambda layer that provides an in-memory cache for parameters and secrets. It allows functions to persist values through the Lambda execution lifecycle, and provides a configurable time-to-live (TTL) setting.

When you request a parameter or secret in your Lambda function code, the extension retrieves the data from the local in-memory cache, if it is available. If the data is not in the cache or it is stale, the extension fetches the requested parameter or secret from the respective service. This helps to reduce external API calls, which can improve application performance and reduce cost.

Prerequisites

• AWS Account
• AWS CLI configured
• AWS CDK installed
• PHP installed
• Composer installed

If you have Docker, all requirements are being installed by it.

Repository Overview

The code for this project is available in the following GitHub repository: rafaelbernard/serverless-patterns. The relevant files are located in the lambda-extension-ssm-secrets-cdk-php folder.

Step-by-Step Guide

1. Cloning the Repository

First, clone the repository and navigate to the relevant directory:

git clone --branch rafaelbernard-feature-lambda-extension-ssm-secrets-cdk-php https://github.com/rafaelbernard/serverless-patterns.git
cd serverless-patterns/lambda-extension-ssm-secrets-cdk-php

2. Project Structure

The project structure is as follows:

.
├── assets
│   └── lambda
│       └── lambda.php
├── bin
│   └── cdk.ts
├── cdk
│   └── cdk-stack.ts
├── cdk.json
├── docker-compose.yml
├── Dockerfile
├── example-pattern.json
├── Makefile
├── package.json
├── package-lock.json
├── php
│   ├── composer.json
│   ├── composer.lock
│   └── handlers
│       └── lambda.php
├── README.md
├── run-docker.sh
└── tsconfig.json

3. Setting Up the Lambda Function

The main logic for fetching and caching secrets is in php/handlers/lambda.php:

<?php

use Bref\Context\Context;
use Bref\Event\Http\HttpResponse;
use GuzzleHttp\Client;
use Symfony\Component\HttpFoundation\JsonResponse;

// Responsibilities are simplified into one file for demonstration purposes
// We would have have those methods in a Service class

function getParam(string $parameterPath): string
{
    // Set `withDecryption=true if you also want to retrieve SecureString SSMs
    $url = "http://localhost:2773/systemsmanager/parameters/get?name={$parameterPath}&withDecryption=true";

    try {
        $client = new Client();

        $response = $client->get($url, [
            'headers' => [
                'X-Aws-Parameters-Secrets-Token' => getenv('AWS_SESSION_TOKEN'),
            ]
        ]);

        $data = json_decode($response->getBody());
        return $data->Parameter->Value;
    } catch (\Exception $e) {
        error_log('Error getting parameter => ' . print_r($e, true));
    }
}

function getSecret(string $secretName): stdClass
{
    $url = "http://localhost:2773/secretsmanager/get?secretId={$secretName}";

    try {
        $client = new Client();

        $response = $client->get($url, [
            'headers' => [
                'X-Aws-Parameters-Secrets-Token' => getenv('AWS_SESSION_TOKEN'),
            ]
        ]);

        $data = json_decode($response->getBody());
        return json_decode($data->SecretString);
    } catch (\Exception $e) {
        error_log('Error getting secretsmanager => ' . print_r($e, true));
    }
}

return function ($request, Context $context) {
    $secret = getSecret(getenv('THE_SECRET_NAME'));
    $response = new JsonResponse([
        'status' => 'OK',
        getenv('THE_SSM_PARAM_PATH') => getParam(getenv('THE_SSM_PARAM_PATH')),
        getenv('THE_SECRET_NAME') => [
            'password' => $secret->password,
            'username' => $secret->username,
        ],
    ]);

    return (new HttpResponse($response->getContent(), $response->headers->all()))->toApiGatewayFormatV2();
};

4. Setting Up AWS CDK Stack

The AWS CDK stack is defined in cdk/cdk-stack.ts:

import { CfnOutput, CfnParameter, Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { join } from "path";
import { packagePhpCode, PhpFunction } from "@bref.sh/constructs";
import { FunctionUrlAuthType, LayerVersion, Runtime } from "aws-cdk-lib/aws-lambda";
import { StringParameter } from "aws-cdk-lib/aws-ssm";
import { Policy, PolicyStatement } from 'aws-cdk-lib/aws-iam';
import { Secret } from 'aws-cdk-lib/aws-secretsmanager';

export class CdkStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const stackPrefix = id;

    // May be set as parameter new CfnParameter(this, 'parameterStoreExtensionArn', { type: 'String' });
    const parameterStoreExtensionArn = 'arn:aws:lambda:us-east-1:177933569100:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11';
    const parameterStoreExtension = new CfnParameter(this, 'parameterStoreExtensionArn', { type: 'String', default: parameterStoreExtensionArn });

    const paramTheSsmParam = new StringParameter(this, `${stackPrefix}-TheSsmParam`, {
      parameterName: `/${stackPrefix.toLowerCase()}/ssm/param`,
      stringValue: 'the-value-here',
    });

    // CDK cannot create SecureString
    // You would create the SecureString out of CDK and use the param name here
    // const paramAnSsmSecureStringParam = StringParameter.fromSecureStringParameterAttributes(this, `${stackPrefix}-AnSsmSecureStringParam`, {
    //   parameterName: `/${stackPrefix.toLowerCase()}/ssm/secure-string/params`,
    // });

    const templatedSecret = new Secret(this, 'TemplatedSecret', {
      generateSecretString: {
        secretStringTemplate: JSON.stringify({ username: 'postgres' }),
        generateStringKey: 'password',
        excludeCharacters: '/@"',
      },
    });

    // The param path that will be used to retrieve value by the lambda
    const lambdaEnvironment = {
      THE_SSM_PARAM_PATH: paramTheSsmParam.parameterName,
      THE_SECRET_NAME: templatedSecret.secretName,
      // If you create the SecureString
      // THE_SECURE_SSMPARAM_PATH: paramAnSsmSecureStringParam.parameterName,
    };

    const functionName = `${id}-lambda`;
    const theLambda = new PhpFunction(this, `${stackPrefix}${functionName}`, {
      handler: 'lambda.php',
      phpVersion: '8.3',
      runtime: Runtime.PROVIDED_AL2,
      code: packagePhpCode(join(__dirname, `../assets/lambda`)),
      functionName,
      environment: lambdaEnvironment,
    });

    // Add extension layer
    theLambda.addLayers(
      LayerVersion.fromLayerVersionArn(this, 'ParameterStoreExtension', parameterStoreExtension.valueAsString)
    );

    // Set additional permissions for parameter store
    theLambda.role?.attachInlinePolicy(
      new Policy(this, 'additionalPermissionsForParameterStore', {
        statements: [
          new PolicyStatement({
            actions: ['ssm:GetParameter'],
            resources: [
              paramTheSsmParam.parameterArn,
              // If you create the SecureString
              // paramAnSsmSecureStringParam.parameterArn,
            ],
          }),
        ],
      }),
    )

    templatedSecret.grantRead(theLambda);

    const fnUrl = theLambda.addFunctionUrl({ authType: FunctionUrlAuthType.NONE });

    new CfnOutput(this, 'LambdaUrl', { value: fnUrl.url });
  }
}

5. Deploying with AWS CDK

Make sure you have already AWS variables set and run below command to install required dependancies:

# Using docker -- check run-docker.sh
make up

or

# Using local
npm ci
cd php && composer install --no-scripts && cd -

After that, you will have all dependencies installed. Deploy it executing:

# Using docker
make deploy

or

# Using local
npm run deploy

6. Testing the Lambda Function

The CDK output will have the Lambda function URL, which you can use to test and retrieve the values:

Outputs:
LambdaExtensionSsmSecretsCdkPhpStack.LambdaUrl = https://keamdws766oqzr6dbiindaix3a0fdojb.lambda-url.us-east-1.on.aws/

You should see the secret value and parameter value returned by the Lambda function. Subsequent invocations should retrieve the values from the cache, reducing latency and cost.

{
  "status": "OK",
  "/lambdaextensionssmsecretscdkphpstack/ssm/param": "the-value-here",
  "TemplatedSecret3D98B577-4jOWSbUMCHmF": {
    "password": "!o9GpBzpa>dYdo.Gx3J2!<zd(s-Fg;ev",
    "username": "postgres"
  }
}

Performance benefits

A similar example application written in Python performed three tests, reducing API calls ~98%. I am quoting their findings, as the benefits are the same for this PHP Lambda:

To evaluate the performance benefits of the Lambda extension cache, three tests were run using the open source tool Artillery to load test the Lambda function.

config:
 target: "https://lambda.us-east-1.amazonaws.com"
phases:
  -
duration: 60
arrivalRate: 10
rampTo: 40

Test 1: The extension cache is disabled by setting the TTL environment variable to 0. This results in 1650 GetParameter API calls to Parameter Store over 60 seconds.

Test 2: The extension cache is enabled with a TTL of 1 second. This results in 106 GetParameter API calls over 60 seconds.
Test 3: The extension is enabled with a TTL value of 300 seconds. This results in only 18 GetParameter API calls over 60 seconds.

In test 3, the TTL value is longer than the test duration. The 18 GetParameter calls correspond to the number of Lambda execution environments created by Lambda to run requests in parallel. Each execution environment has its own in-memory cache and so each one needs to make the GetParameter API call.

In this test, using the extension has reduced API calls by ~98%. Reduced API calls results in reduced function execution time, and therefore reduced cost.

7. Clean up

To delete the stack, run:

make bash
npm run destroy

Conclusion

In this article, we demonstrated how to use a pre-existing Lambda Extension to cache secrets for a PHP Lambda function using the Bref layer and AWS CDK for deployment. By caching secrets, we can improve the performance and reduce the cost of our serverless applications. The approach detailed here can be adapted to various use cases, enhancing the efficiency of your AWS Lambda functions.

For more information on the Parameter Store, Secrets Manager, and Lambda extensions, refer to:

• Using Parameter Store parameters in AWS Lambda functions
• Use AWS Secrets Manager secrets in AWS Lambda functions
• Introducing AWS Lambda Extensions
• Caching data and configuration settings with AWS Lambda extensions
• AWS blog on using Lambda Extensions to cache secrets

For more serverless learning resources, visit Serverless Land.

Part 3 is to show the upgrade path to Bref 2 and to achieve more coverage of the AWS resources. We will use DynamoDB, a powerful database for serverless architectures.

Some of those topics seem straightforward to some people, but I would like to avoid guessing that this is known to the audience since I have experienced some PHP developers struggling to put all these together for the first time due to the paradigm change. It should be fun.

Table of contents:

1. What else are we doing?
2. Describing more AWS services - Adding a DynamoDB table
3. Bref upgrade
4. Testing CDK
5. PHP and AWS Services
6. Wrap-up

What else are we doing?

In this section, we'll explore additional functionalities and enhancements to our serverless application. Building upon the foundation laid in Part 2, we'll introduce new features and integrations to further extend the capabilities of our AWS PHP application.

The Part 2 uses the result of the Fibonacci of a provided integer or a random integer from 400 to 1000 (to get a good image and not to overflow integer). This integer is the number of pixels of an image from the bucket and an arbitrary request metadata we are creating. If the image does not exist, the lambda will fetch a random image from the web with that number of pixels, save it and generate the metadata.

The computing complexity is irrelevant because it could be very complex logic or very simple, and the topics we are discussing in this part of the series will use the same design.

The lambda will now search the metadata in a DynamoDB table, saving the metadata when it does not exist. DynamoDB is largely used in Lambda code.

Get the part-3 source-code on GitHub and the diff from part-2.

Describing more AWS services - Adding a DynamoDB Table

DynamoDB plays a crucial role in serverless architectures, offering scalable and high-performance NoSQL database capabilities. In this section, we'll delve into the process of integrating DynamoDB into our AWS CDK stack, expanding our application's data storage and retrieval capabilities.

DynamoDB is a fully managed NoSQL database service provided by AWS, offering seamless integration with other AWS services, automatic scaling, and built-in security features. Its scalability, low latency, and flexible data model make it well-suited for serverless architectures and applications with varying throughput requirements.

    const table = new Table(this, TableName, {
      partitionKey: { name: 'PK', type: AttributeType.STRING },
      sortKey: { name: 'SK', type: AttributeType.STRING },
      removalPolicy: RemovalPolicy.DESTROY,
      tableName: TableName,
    });

Following the same principles for creating other AWS resources, we utilize the AWS CDK to define a DynamoDB table within our stack. Let's dive into the key parameters of the Table constructor:

• partitionKey: This parameter defines the primary key attribute for the DynamoDB table, used to distribute items across partitions for scalability. In our example, { name: 'PK', type: AttributeType.STRING } specifies a partition key named 'PK' with a string type. The naming convention ('PK') is arbitrary and can be tailored to suit your application's needs.
• sortKey: For tables requiring a composite primary key (partition key and sort key), the sortKey parameter comes into play. Here, { name: 'SK', type: AttributeType.STRING } defines a sort key named 'SK' with a string type. Like the partition key, the name and type of the sort key can be customized based on your data model.
• removalPolicy: This parameter determines the behaviour of the DynamoDB table when the CloudFormation stack is deleted. By setting RemovalPolicy.DESTROY, we specify that the table should be deleted (destroyed) along with the stack. Alternatively, you can opt for RemovalPolicy.RETAIN to preserve the table post-stack deletion, which may be useful for retaining data.

By decoupling configuration from implementation, we adhere to SOLID principles, ensuring cleaner and more robust code. This approach fosters flexibility, allowing our code to seamlessly adapt to changes, such as modifications to the table name while maintaining its functionality.

The implementation code is aware that the name will come from an environment variable and will work with that (yes, if you think that test will be easy to write, you are right):

    const lambdaEnvironment = {
      TableName,
      TableArn: table.tableArn,
      BucketName: brefBucket.bucketName,
    };

Bref Upgrade

Bref, the PHP runtime for AWS Lambda, continually evolves to provide developers with the latest features and optimizations. In this section, we'll discuss the upgrade to Bref 2.0 and explore how it enhances the deployment process and performance of our serverless PHP applications.

In this section, we're upgrading our usage of Bref, a PHP runtime for AWS Lambda, to version 2.0. Bref simplifies the deployment of PHP applications to AWS Lambda, enabling us to run PHP code serverlessly.

The upgrade involves modifying our AWS CDK code to utilize the new features and improvements introduced in Bref 2.0. One notable improvement is the automatic selection of the latest layer of the PHP version, which simplifies the deployment process and ensures that our Lambda functions run on the most up-to-date PHP environment available.

  const getLambda = new PhpFunction(this, ${stackPrefix}${functionName}, {
    handler: 'get.php',
    phpVersion: '8.3',
    runtime: Runtime.PROVIDED_AL2,
    code: packagePhpCode(join(__dirname, ../assets/get), {
      exclude: ['test', 'tests'],
    }),
    functionName,
    environment: lambdaEnvironment,
  });

• `PhpFunction` Constructor: We're using the `PhpFunction` constructor provided by Bref to define our Lambda function. This constructor allows us to specify parameters such as the handler file, PHP version, runtime, code location, function name, and environment variables.
• `handler`: Specifies the entry point file for our Lambda function, where the execution starts.
• `phpVersion`: Defines the PHP version to be used by the Lambda function. In this case, we're using PHP version 8.3.
• `runtime`: Indicates the Lambda runtime environment. Here, `Runtime.PROVIDED_AL2` signifies the use of the Amazon Linux 2 operating system.
• `code`: Specifies the location of the PHP code to be deployed to Lambda.
• `functionName`: Sets the name of the Lambda function.
• `environment`: Allows us to define environment variables required by the Lambda function, such as database connection strings or configuration settings.

By upgrading to Bref 2.0 and configuring our Lambda function accordingly, we ensure compatibility with the latest enhancements and optimizations provided by Bref, thereby improving the performance and reliability of our serverless PHP applications on AWS Lambda.

Testing CDK

Ensuring the correctness and reliability of our AWS CDK infrastructure is crucial for maintaining a robust serverless architecture. In this section, we'll delve into testing our CDK resources, focusing on the DynamoDB table we added in the previous section.

As described earlier, we utilized the AWS CDK to provision a DynamoDB table within our serverless stack. Now, let's ensure that the table is configured correctly and behaves as expected by writing tests using the CDK's testing framework.

First, let's revisit how we added the DynamoDB table:

const table = new Table(this, TableName, {
  partitionKey: { name: 'PK', type: AttributeType.STRING },
  sortKey: { name: 'SK', type: AttributeType.STRING },
  removalPolicy: RemovalPolicy.DESTROY,
  tableName: TableName,
});

In this code snippet, we define a DynamoDB table with specified attributes such as partition key, sort key, removal policy, and table name. Now, to ensure that this table is created with the correct configuration, we'll write tests using CDK's testing constructs.

Check the following thest:

test('Should have DynamoDB', () => {
  expectCDK(stack).to(
    haveResource(
      'AWS::DynamoDB::Table',
      {
        "DeletionPolicy": "Delete",
        "Properties": {
          "AttributeDefinitions": [
            {
              "AttributeName": "PK",
              "AttributeType": "S",
            },
            {
              "AttributeName": "SK",
              "AttributeType": "S",
            },
          ],
          "KeySchema": [
            {
              "AttributeName": "PK",
              "KeyType": "HASH",
            },
            {
              "AttributeName": "SK",
              "KeyType": "RANGE",
            },
          ],
          "ProvisionedThroughput": {
            "ReadCapacityUnits": 5,
            "WriteCapacityUnits": 5,
          },
          "TableName": "BrefStory-table",
        },
        "Type": "AWS::DynamoDB::Table",
        "UpdateReplacePolicy": "Delete",
      },
      ResourcePart.CompleteDefinition,
    )
  );
});

This test ensures that the DynamoDB table is created with the correct attribute definitions, key schema, provisioned throughput, table name, and other properties specified during its creation. By writing such tests, we validate that our CDK infrastructure is provisioned accurately and functions as intended.

PHP and AWS Services

Leveraging PHP in a serverless environment opens up new possibilities for interacting with AWS services. In this section, we'll examine how PHP code seamlessly integrates with various AWS services, following best practices for maintaining clean and modular code architecture.

This is the part where we have fewer serverless needs impacting the code, as the PHP code will follow the same logic we might be using to communicate with AWS services on any other platform overall (there are always some specific use cases).

The reuse of the same existing logic is excellent. It leverages the decision to keep using PHP when moving that workload to Serverless, as the bulk of the knowledge and already proven code would remain as-is. We may escape the trap of classifying that PHP code as legacy as if it should be avoided, terminated or halted.

As a side note, a few external layers of our software architecture are touched if a good software architecture was applied before. Therefore, during the implementation of this architectural change, it should be quick to realise how beneficial and time-saving it is to have a well-architectured application with a balanced decision for patterns, principles, and designs to be applied, ultimately giving flexibility to the application and its features.

The handler is simplified now and should accommodate everything to a class in the direction of following SRP, a principle that we are bringing to the code during the code bites:

Applications, domains, infrastructure, etc

Our `PicsumPhotoService` is still orchestrating the business logic. The Single Responsibility Principle and Inversion of Control are applied. We are injecting the specialized services in the constructor:

// readonly class PicsumPhotoService
    public function __construct(
        private HttpClientInterface $httpClient,
        private ImageStorageService $storageService,
        private ImageRepository $repository,
    )
    {
    }

Each specialized service has all its dependencies injected in the constructor as well. We can see the factory instantiation:

    public static function createPicsumPhotoService(): PicsumPhotoService
    {
        return new PicsumPhotoService(
            HttpClient::create(),
            new S3ImageService(
                new S3Client(),
                getenv('BucketName'),
            ),
            new DynamoDbImageRepository(
                new DynamoDbClient(),
                getenv('TableName'),
            ),
        );
    }

The `ImageStorageService` will handle all image operations, connecting to the AWS Service when appropriate and observing business logic details. This is a slim interface:

interface ImageStorageService
{
    public function getImageFromBucket(int $imagePixels): ?array;

    public function saveImage(int $imagePixels, mixed $fetchedImage): void;

    public function createAndPutMetadata(int $imagePixels, array $metadata): PutObjectOutput;
}

Instead of `: PutObjectOutput`, usually we would return a domain object, to not couple the interface with implementation details of using S3 Services, but for simplicity, I did not create a domain object here. It would be preferable though.

The `ImageRepository` will handle all metadata operations. It will save into a repository and observe logic details as well. Following the same principles, this is a slim interface:

interface ImageRepository
{
    public function findImage(int $imagePixels): ImageMetadataItem;

    public function addImageMetadata(ImageMetadataItem $imageMetadataItem): PutItemOutput;
}

The `ImageMetadataItem` is a representation of one of the domain objects we have in our codebase.

readonly class ImageMetadataItem
{
    public function __construct(public int $imagePixels, public array $metadata)
    {
    }

    public function toDynamoDbItem(): array
    {
        return [
            'PK' => new AttributeValue(['S' => 'IMAGE']),
            'SK' => new AttributeValue(['S' => "PIXELS#{$this->imagePixels}"]),
            'pixels' => new AttributeValue(['N' => "{$this->imagePixels}"]),
            'metadata' => new AttributeValue(['S' => json_encode($this->metadata)]),
            ...ConvertToDynamoDb::item($this->metadata),
        ];
    }

    /**
     * @param array $item
     */
    public static function fromDynamoDb(array $item): static
    {
        return new static(
            (int) $item['pixels']->getN(),
            (array) json_decode($item['metadata']->getS()),
        );
    }
}

If you check the implementation details, it operates transparently with all the services, business logic and AWS Services without any high couple with them. There are two utility functions:

• toDynamoDbItem: to transform the object into a valid DynamoDb Item to be added
• fromDynamoDb: to perform the opposite operation, transforming a DynamoDb Item into a domain object

The scope of the operation is very clear and does not bring the domain into dependency on those services, as the domain object can be used independently. It does not block any other way of dealing with it, giving the usage with other types of services, such as different databases or APIs. This is very important to the maintainability of the application without sacrificing the ease of readiness as it keeps the context of the utilities in the right place.

If you check all PHP code carefully, Bref is such a great abstraction layer that, removing the code from the handler file, any other line of code can be used as a lambda or a web application interchangeably without changing any line of code. This is very powerful, as you can imagine how you can leverage and migrate some of the existing code to lambda by just creating a handler that will trigger your existing code, if the code is well structured.

Wrap-up

It would be simple like that. Check more details in the source code, install it and try it yourself. This project is ready to:

• Extend lambda function using Bref
• Upgrade to use Bref 2.0
• Create a DynamoDB table
• Test the stack Cloudformation code
• Separate the PHP logic
• Have PHP communicating with AWS Services

Links:

• https://rafael.bernard-araujo.com/tag/bref-php-aws-story
• https://bref.sh
• https://dev.to/rafaelbernard/a-bref-aws-php-history-part-1-2agn
• https://dev.to/rafaelbernard/a-bref-aws-php-story-part-2-1dhe
• https://github.com/rafaelbernard/bref-initial-php-aws-story/tree/part-3
• https://github.com/rafaelbernard/bref-initial-php-aws-story/compare/tag-part-2...tag-part-3
• https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Introduction.html

Part 2 is to show how CDK will describe more AWS resource dependencies; how policies and roles are involved in this process; how to test if they are applied as expected; and how PHP services will use those resources.

Some of those topics seem straightforward to some people, but I would like to avoid guessing that this is known to the audience since I have experienced some PHP developers struggling to put all these together for the first time due to the paradigm change. It should be fun.

Table of contents:

1. What else are we doing?
2. Describing more AWS services - Adding an S3 bucket
3. Services permissions
4. Testing CDK
5. PHP and AWS Services
   1. Handlers
   2. Application, Domain, Infrastructure, etc
6. Wrap-up
7. P.S.: Stats

What else are we doing?

The Part 1 function was returning a Fibonacci result from an int. Very simple. We will keep it simple for now to focus on putting the PHP code into a lambda and allowing PHP code to interact with AWS Services.

The computing complexity is irrelevant because it could be very complex logic or very simple, and the topics we are discussing in this part of the series will use the same design.

The lambda will now use the result of the Fibonacci of a provided integer or a random integer from 400 to 1000 (to get a good image and not to overflow integer). This integer is the number of pixels of an image from the bucket and an arbitrary request metadata we are creating. If the image does not exist, the lambda will fetch a random image from the web with that number of pixels, save it and generate the metadata.

Get the part-2 source-code on GitHub and the diff from part-1.

Describing more AWS services - Adding an S3 bucket

S3 buckets are simple yet compelling services for multipurpose workloads. It will be added to the series as a basic storage mechanism. The lambda function, now called GetFibonacciImage function, will need some permissions to manage the bucket.

Starting from the bucket definition, CDK give fantastic constructs, and it goes like this:

cdk-stack.ts

    const brefBucket = new Bucket(this, `${stackPrefix}Bucket`, {
      autoDeleteObjects: true,
      removalPolicy: RemovalPolicy.DESTROY,
    });

By default, buckets will not be deleted during a CDK destroy because they need to be empty. So you will have a hanging bucket in your account. I don't want to keep those contents if the lambda no longer exists. Then autoDeleteObjects and removalPolicy options are selected to enable the destruction of the buckets and their contents if I execute a stack destroy.

We want to decouple the configuration from the implementation to have a more SOLID code. That way, we avoid hard-coded configuration, making our code cleaner and more robust. Then, the code is ready to work, no matter the bucket name.

The implementation code is aware that the name will come from an environment variable and will work with that (yes, if you think that test will be easy to write, you are right):

cdk-stack.ts

and

      environment: {
        BUCKET_NAME: brefBucket.bucketName,
      }

Services permissions

There is a Lambda Function and an S3 Bucket. The described use case determines that the lambda needs read and write permissions to the bucket. And nothing more. It is a good practice to give the minimum necessary permission to a resource:

cdk-stack.ts

    brefBucket.grantReadWrite(getLambda);

The result is a list of actions added to the policy recommended by AWS for operations requiring only read and write.

          Action: [
            "s3:GetObject*",
            "s3:GetBucket*",
            "s3:List*",
            "s3:DeleteObject*",
            "s3:PutObject",
            "s3:PutObjectLegalHold",
            "s3:PutObjectRetention",
            "s3:PutObjectTagging",
            "s3:PutObjectVersionTagging",
            "s3:Abort*",
          ],

Testing CDK

Testing is a great feature of CDK, and we can see how tests can verify our changes with npm t:

That there is a function

  const functionName = 'GetFibonacciImage';
  /* ... */
  it('Should have a lambda function to get fibonacci', () => {
    template.hasResourceProperties('AWS::Lambda::Function', {
      Layers: [Cdk.CdkStack.brefLayerFunctionArn],
      FunctionName: functionName,
    });
  });

And if only the permissions the lambda needs were granted:

  it('Should have a policy for S3', () => {
    template.hasResourceProperties('AWS::IAM::Policy', {
      PolicyName: Match.stringLikeRegexp(`^${stackPrefix}${functionName}ServiceRoleDefaultPolicy`),
      PolicyDocument: {
        Statement: [{
          Action: [
            "s3:GetObject*",
            "s3:GetBucket*",
            "s3:List*",
            "s3:DeleteObject*",
            "s3:PutObject",
            "s3:PutObjectLegalHold",
            "s3:PutObjectRetention",
            "s3:PutObjectTagging",
            "s3:PutObjectVersionTagging",
            "s3:Abort*",
          ],
        }],
      },
    });
  });

You may want to check cdk-stack.test.ts to see more details.

PHP and AWS Services

This is the part where we have fewer serverless needs impacting the code, as the PHP code will follow the same logic we might be using to communicate with AWS services on any other platform overall (there are always some specific use cases).

The reuse of the same existing logic is excellent. It leverages the decision to keep using PHP when moving that workload to Serverless, as the bulk of the knowledge and already proven code would remain as-is. We may escape the trap of classifying that PHP code as legacy as if it should be avoided, terminated or hated.

As a side note, a few external layers of our software architecture are touched if a good software architecture was applied before. Therefore, during the implementation of this architectural change, it should be quick to realise how beneficial and time-saving it is to have a well-architectured application with a balanced decision for patterns, principles, and designs to be applied, ultimately giving flexibility to the application and its features.

The handler is simplified now and should accommodate everything to a class in the direction of following SRP, a principle that we are bringing to the code during the code bites:

Handlers

php/handler/get.php

return function ($request, $context) {
    return \BrefStory\Application\ServiceFactory::createGetFibonacciImageHandler()
        ->handle($request, $context)
        ->toApiGatewayFormatV2();
};

To handle the request details, the Fibonacci code now lives in a proper event handler (implements Bref\Event\Handler).

php/src/Event/Handler/GetFibonacciImageHandler.php

    public function handle($event, Context $context): HttpResponse
    {
        $int = (int) (
            $event['queryStringParameters']['int'] ?? random_int(
                self::MIN_PIXELS_FOR_REASONABLE_IMAGE_AND_NOT_BIG_FIBONACCI,
                self::MAX_PIXELS_FOR_REASONABLE_IMAGE_AND_NOT_BIG_FIBONACCI
            )
        );

        $metadata = $this->photoService->getJpegImageFor($int);

        $responseBody = [
            'context' => $context,
            'now' => $this->dateTimeImmutable()->format('Y-m-d H:i:s'),
            'int' => $int,
            'fibonacci' => $this->fibonacci($int),
            'metadata' => $metadata,
        ];

        $response = new JsonResponse($responseBody);

        return new HttpResponse($response->getContent(), $response->headers->all());
    }

We would also like to start testing the PHP code. As the Event Handler might be a new layer (although very similar to widely used controllers), php/tests/unit/Event/Handler/GetFibonacciImageHandlerTest.php test class was created for that. The part-2 will only focus on this test class to avoid overloading with too many changes, but we would usually have test coverage for all the code in the repository.

Applications, domains, infrastructure, etc

Finally, we are inside the layers where we are most used to. To fit our purposes, the Event Handler will depend on and call an Application layer service that will orchestrate all the steps to fetch the image metadata.

php/src/Application/PicsumPhotoService.php#L34-L42

    public function getJpegImageFor(int $imagePixels): array
    {
        try {
            return $this->getImageFromBucket($imagePixels);
        } catch (NoSuchKeyException) {
            // do nothing
        }

        return $this->fetchAndSaveImageToBucket($imagePixels);
    }

The interesting thing to mention about using AWS Services is how simple S3Client is instantiated. There is a factory to create service:

php/src/Application/ServiceFactory.php#L22-L29

    public static function createPicsumPhotoService(): PicsumPhotoService
    {
        return new PicsumPhotoService(
            HttpClient::create(),
            new S3Client(),
            getenv('BUCKET_NAME'),
        );
    }

• new S3Client is all we need because the environment will use AWS credentials, provided to lambda at execution time, as an assumed role that will carry the policies we defined in the CDK constructs stack, i.e., with read and write permissions to the bucket
• getenv('BUCKET_NAME'), which is gracefully provided by CDK when creating our bucket with any dynamic name it pleases to

I asked ChatGPT about this class:

The PicsumPhotoService class seems to be following the Single Responsibility Principle (SRP) as it has only one responsibility, which is to provide methods for fetching and saving JPEG images from the Picsum website.

The class has methods to fetch the image from an S3 bucket, and if it's not available, fetches it from the Picsum website, saves it to the S3 bucket, and creates and puts metadata for the image in the S3 bucket.

The class has a clear separation of concerns, where the S3Client and HttpClientInterface are injected through the constructor, and the different functionalities are implemented in separate private methods. Additionally, each method is doing a single task, which makes the code easy to read, test, and maintain.

Therefore, it can be concluded that the PicsumPhotoService class follows SRP.

Wrap-up

It would be simple like that. Check more details in the source code, install it and try it yourself. This project is ready to:

• Create a lambda function using Bref
• Create an S3 Bucket with read and write permissions to the lambda
• Test the stack Cloudformation code
• Separate the PHP logic
• Have PHP communicating with AWS Services
• Start PHP testing

P.S.: Stats

I did not plan to talk widely about stats now, but I think I can share the most two significant measures I had with this simple code so far.

[Update 22/03/23] Using https://k6.io/

1 - With a brand new stack and a cold lambda:

scenarios: (100.00%) 1 scenario, 200 max VUs, 2m30s max duration (incl. graceful stop):
           * default: 200 looping VUs for 2m0s (gracefulStop: 30s)

     data_received..................: 49 MB  409 kB/s
     data_sent......................: 7.8 MB 65 kB/s
     http_req_blocked...............: avg=2.36ms   min=671ns    med=2.27µs   max=581.87ms p(90)=4.18µs   p(95)=7µs
     http_req_connecting............: avg=712.63µs min=0s       med=0s       max=193.34ms p(90)=0s       p(95)=0s
     http_req_duration..............: avg=531.51ms min=204.46ms med=485.24ms max=3.81s    p(90)=517.98ms p(95)=534.3ms
       { expected_response:true }...: avg=513.6ms  min=204.46ms med=485.07ms max=3.67s    p(90)=516.62ms p(95)=531.5ms
     http_req_failed................: 0.60%  ✓ 272        ✗ 44761
     http_req_receiving.............: avg=123.76µs min=13.77µs  med=44.04µs  max=16.78ms  p(90)=71.27µs  p(95)=85.71µs
     http_req_sending...............: avg=14.79µs  min=4.27µs   med=12.43µs  max=402.74µs p(90)=23.97µs  p(95)=31.4µs
     http_req_tls_handshaking.......: avg=1.37ms   min=0s       med=0s       max=330.58ms p(90)=0s       p(95)=0s
     http_req_waiting...............: avg=531.37ms min=204.36ms med=485.11ms max=3.81s    p(90)=517.77ms p(95)=534.13ms
     http_reqs......................: 45033  373.683517/s
     iteration_duration.............: avg=533.96ms min=204.55ms med=485.34ms max=4.37s    p(90)=518.07ms p(95)=534.4ms
     iterations.....................: 45033  373.683517/s
     vus............................: 200    min=200      max=200
     vus_max........................: 200    min=200      max=200

running (2m00.5s), 000/200 VUs, 45033 complete and 0 interrupted iterations

2 - After the first initial execution, cold lambda and all available images already saved to the bucket, where we got ~3K more requests being served for the same time

scenarios: (100.00%) 1 scenario, 200 max VUs, 2m30s max duration (incl. graceful stop):
           * default: 200 looping VUs for 2m0s (gracefulStop: 30s)

     data_received..................: 53 MB  442 kB/s
     data_sent......................: 8.4 MB 70 kB/s
     http_req_blocked...............: avg=2.26ms   min=631ns    med=2.24µs   max=612.22ms p(90)=4.04µs   p(95)=6.47µs
     http_req_connecting............: avg=663.23µs min=0s       med=0s       max=215.19ms p(90)=0s       p(95)=0s
     http_req_duration..............: avg=490.8ms  min=199.95ms med=484.02ms max=3.17s    p(90)=514.86ms p(95)=527ms
       { expected_response:true }...: avg=490.53ms min=199.95ms med=484.02ms max=2.4s     p(90)=514.85ms p(95)=526.99ms
     http_req_failed................: 0.01%  ✓ 5         ✗ 48754
     http_req_receiving.............: avg=108.86µs min=12.44µs  med=42.68µs  max=17.62ms  p(90)=69.23µs  p(95)=81.87µs
     http_req_sending...............: avg=14.42µs  min=3.9µs    med=12.14µs  max=786.01µs p(90)=23.03µs  p(95)=30.35µs
     http_req_tls_handshaking.......: avg=1.27ms   min=0s       med=0s       max=332.34ms p(90)=0s       p(95)=0s
     http_req_waiting...............: avg=490.68ms min=199.9ms  med=483.91ms max=3.17s    p(90)=514.75ms p(95)=526.89ms
     http_reqs......................: 48759  404.56812/s
     iteration_duration.............: avg=493.16ms min=200.05ms med=484.11ms max=3.17s    p(90)=514.96ms p(95)=527.1ms
     iterations.....................: 48759  404.56812/s
     vus............................: 200    min=200     max=200
     vus_max........................: 200    min=200     max=200

running (2m00.5s), 000/200 VUs, 48759 complete and 0 interrupted iterations

We don't need to look at PHP as a language that could not run inside a modernized stack. We can move some of this code without total refactoring to Serverless applications, benefiting from an already proven successful code. And we know we all have flows suitable to run as a lambda function.

And not only legacy code. New features are also perfect candidates to be run in PHP and lambdas due to the team's experience, consistency of the technology stack, speed, etc. PHP has served the world well and will remain operating well. PHP is alive.

Table of contents:

1. The series
2. Functions
3. Code
   1. Requirements
   2. The lambda
4. Wrap-up

The Serie

I am starting a series as a walkthrough for PHP into Serverless, specifically to run as lambdas functions.

We will use Bref, a composer package, to deploy PHP applications to AWS.

Bref (which means "brief" in french) comes as an open source Composer package and helps you deploy PHP applications to AWS and run them on AWS Lambda.
https://bref.sh/docs/

Bref relies on the Serverless framework and AWS access keys to deploy applications.
https://bref.sh/docs/installation.html

The Serverless framework is excellent, but I am more of a fan of AWS CDK. Mainly because it is designed to use an imperative programming framework that speeds up the required infrastructure with excellent constructs on different levels (reasonable defaults), and its output can be run against a test framework (predictability).

There are already some CDK constructs for PHP, but, as far as I see, they are intended to be used by Web Apps lambdas (i.e. using frameworks such as Laravel and Symfony). However, the purpose of this series is to run Event-Driven functions, so I will start using pure CDK constructs.

Functions

As a walkthrough, we will digest the series in affordable bites, starting from simple functions that we will improve as the series continues and we use more AWS resources.

Code

Let's start our PHP lambda function. First, it will begin as an HTTP-based lambda, expecting a request and returning a response. Then, it will execute a trivial piece of computing code: it will return fibonacci.

Get the part 1 source-code in GitHub.

Requirements

• node 18
• PHP 8.2

(optional) There is a Dockerfile and a docker-compose.yml file for your convenience if you prefer to use docker. It will require you to set AWS environment variables for use by the container.

The lambda

You can check the complete source code for part 1, and we will highlight essential parts from the CDK code, as the PHP code has a few different things from what we are used to code.

The stack creator

In our case, it will create the serverless Stack and related infrastructure, i.e., IAM, lambda function, and URL. If anything else we need, it would be defined and requested by this class.

bin/cdk-stack.ts

export class CdkStack extends Stack {

  // Get Bref layer ARN from https://runtimes.bref.sh/
  public static brefLayerFunctionArn = 'arn:aws:lambda:us-east-1:209497400698:layer:php-82:16';

  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const layer = LayerVersion.fromLayerVersionArn(this, 'php-layer', CdkStack.brefLayerFunctionArn);

    const getLambda = new LambdaFunction(this, 'get', {
      layers: [layer],
      handler: 'get.php',
      runtime: Runtime.PROVIDED_AL2,
      code: Code.fromAsset(join(__dirname, `../assets/get`)),
      functionName: 'part1-get',
    });

    const fnUrl = getLambda.addFunctionUrl({authType: FunctionUrlAuthType.NONE});

    new CfnOutput(this, 'TheUrl', {
      // The .url attributes will return the unique Function URL
      value: fnUrl.url,
    });
  }
}

Highlights

The bref php layer:

public static brefLayerFunctionArn = 'arn:aws:lambda:us-east-1:209497400698:layer:php-82:16';

Where you point your entry point and source code:

      handler: 'get.php',
      runtime: Runtime.PROVIDED_AL2,
      code: Code.fromAsset(join(__dirname, `../assets/get`)), // get.php file inside the zip file located at this path

Using AWS Lambda built-int function URL (we will change to API Gateway later if needed):

    const fnUrl = getLambda.addFunctionUrl({authType: FunctionUrlAuthType.NONE});

Output

You would see CDK outputting the lambda function URL you will use to run your application. Something like:

Outputs:
CdkStack.TheUrl = https://6eoftivwkq4ht65d2h2fwlmsga0vnpfs.lambda-url.us-east-1.on.aws/

The handler

The PHP entry point has usually named a handler to the code. Its responsibility would be to forward the request to a controller or service that will perform the business rules and prepare the response to be returned. This is an HTTP-based lambda; the response should be an HTTP-valid response.

Obs.: You can note by the words above that any existing code that fits in the lambda computing model can be the controller or service to be called by the handler. Theoretically, you only need to create the handler compatible with the lambda environment, instantiate your controller or service, pass whatever it requires as an argument, and then return the expected response.

php/handlers/get.php

<?php
return function ($request) {
    $int = (int) ($request['queryStringParameters']['int'] ?? random_int(1, 300));

    $responseBody = [
        'response' => 'OK. Time: ' . time(),
        'now' => date('Y-m-d H:i:s'),
        'int' => $int,
        'result' => fibonacci($int),
    ];

    $response = new \Symfony\Component\HttpFoundation\JsonResponse($responseBody);

    return (new \Bref\Event\Http\HttpResponse($response->getContent(), $response->headers->all()))->toApiGatewayFormatV2();
};

Highlights

All handlers receive a request object. This is how to access /?int=myValue query string param.

    $int = (int) ($request['queryStringParameters']['int'] ?? random_int(1, 300));

The call to the function fibonacci() is how we would call any other controller or service.

'result' => fibonacci($int),

Using the Symfony Response to validate and prepare a valid HTTP response:

$response = new \Symfony\Component\HttpFoundation\JsonResponse($responseBody);

AWS API Gateway requires a certain Response shape. To be sure to have a valid API Gateway response:

    return (new \Bref\Event\Http\HttpResponse($response->getContent(), $response->headers->all()))->toApiGatewayFormatV2();

And that is it. You can now use your lambda function URL as in the output of the CDK stack above and call it with or without the query string param ?/int=.

➜   curl https://6eoftivwkq4ht65d2h2fwlmsga0vnpfs.lambda-url.us-east-1.on.aws/
{"response":"OK. Time: 1674612343","now":"2023-01-25 02:05:43","int":273,"result":5.05988662735923e+56}%

➜   curl https://6eoftivwkq4ht65d2h2fwlmsga0vnpfs.lambda-url.us-east-1.on.aws/\?int\=500
{"response":"OK. Time: 1674612353","now":"2023-01-25 02:05:53","int":500,"result":1.394232245616977e+104}%

➜   curl https://6eoftivwkq4ht65d2h2fwlmsga0vnpfs.lambda-url.us-east-1.on.aws/\?int\=500
{"response":"OK. Time: 1674612356","now":"2023-01-25 02:05:56","int":500,"result":1.394232245616977e+104}%

The test

We can predict the resources we create via CDK and check if those resources are as expected. The output of the CDK is a CloudFormation template, which we can put under test. That is solid, as unexpected behaviour or changes will fail in our CI pipeline test step.

test/cdk.test.ts

test('Lambda created', () => {
  const app = new cdk.App();
    // WHEN
  const Stack = new Cdk.CdkStack(app, 'MyTestStack');
    // THEN
  const template = Template.fromStack(stack);

  template.hasResourceProperties('AWS::Lambda::Function', {
    Layers: [Cdk.CdkStack.brefLayerFunctionArn]
  });
});

Highlights

We are checking if there is a lambda function and if that function is using the expected specific bref layer:

  template.hasResourceProperties('AWS::Lambda::Function', {
    Layers: [Cdk.CdkStack.brefLayerFunctionArn]
  });

Wrap-up

We have created our Stack and our first simple HTTP-based PHP lambda function using CDK (with tests). Next, we will improve our lambda to use more AWS resources and communication with more complex application services.

What does it mean?

(Checkout code at https://github.com/rafaelbernard/blog-value-objects)

Value Objects are first described in Evans' Domain-Driven Design book, and further explained in Smith and Lerman's Domain-Driven Design Fundamentals course. It is an immutable type that is distinguishable only by the state of its properties. Unlike an Entity¹, a class type with a unique identifier and remains distinct even if its properties are otherwise identical, two Value Objects with the same properties can be considered equal.

We would use Value Object classes to represent a type strictly and encapsulate the validation rules of that type. Think of age or a card from a poker deck. They can seem sufficiently represented by primitive types such as integer and string, but in reality, they are managed by strict business rules². For example, you would like to ensure that a particular age value is a non-negative integer. Or a picked card has a value not greater than 10, not 1, i.e., there is a range of allowed numbers or unique letters combined within four allowed suits.

To translate it to code, you could think of a Person class as a guest application to map a person's name and age. Usually, we would say a name is a string and age is an int.

class Person
{
    private string $name;
    private int $age;

    public function __constructor(string $name, int $age)
    {
        $this->name = $name;
        $this->age = $age;
    }
}

Although we can think that the specification above is good and we are just instantiating a Person object with all the required attributes, we may have some problems with the implementation because negative values are also int and would be allowed:

$personOk = new Person('John Doe', 18);
$notARealPerson = new Person('Benjamin Button', -18); // -18 year? no way!

The code above will not fail and is very common that some business logic is performed to assert age will never be negative:

// if from a form
$age = (int) $_POST['age'];

if ($age < 0) {
    throw new \Exception('Age could not be negative');
}

// but you need to copy the check everywhere a Person class is used. What if someone overlooks it?
$person = new Person('John Doe', $age);

When using Value Objects, you leverage your class with the exact type you need, correctly applying business logic. I will give more details later, but a hint of how the Person class would be with a Value Object:

use App\Domain;

class Person
{
    private string $name;
    private Age $age;

    public function __construct(string $name, Age $age)
    {
        $this->name = $name;
        $this->age = $age;
    }
}

And now we are always sure that Person objects will have a valid age. Bear with me and understand how Age Value Object class should look.

Samples of Value Objects

You may have already realized that we have many cases where we need similar things on every application. They are used to validate patterns to an expected format, a set of possible values to simulate an enum (only present on PHP 8) or to extend this set of values to be validated against some more rules.

I will be using PHP 7.4 compatible code in this blog. If you have applications using older versions, changing them should not be too complicated. Let me know in the comments if you need samples about how to write to an older version.

Some examples:

Validating a format:

Our Age class should be implemented as:

<?php

namespace App\Domain;

class Age
{
    private int $value;

    /**
     * @param int $value
     */
    public function __construct(int $value)
    {
        if (!$value < 0) {
            throw new \UnexpectedValueException('Negative numbers are not a valid age.');
        }

        $this->value = $value;
    }

    public function value(): int
    {
        return $this->value;
    }
}

Or a richer example with card suits:

<?php

namespace App\Domain;

class CardSuit
{
    const HEARTS = 'H';
    const DIAMONDS = 'D';
    const CLUBS = 'C';
    const SPADES = 'S';

    const SUITS = [
        self::HEARTS,
        self::DIAMONDS,
        self::CLUBS,
        self::SPADES,
    ];

    private string $value;

    public function __construct(string $value)
    {
        if (!in_array($value, self::SUITS)) {
            throw new \InvalidArgumentException("`$value` is not a valid card suit.");
        }

        $this->value = $value;
    }

    public function __toString()
    {
        return $this->value;
    }

    public function value(): string
    {
        return $this->value;
    }
}

Validating a set and its rules:

Observe rules when checking grade with isAlumni() from a given ClassYear. Ideally, we would have a Grade class, but I kept it more straightforward to simplify understanding the check, and I have a similar example with poker cards classes above.

<?php

namespace App\Domain;

class ClassYear
{
    private int $value;

    /**
     * @param int $value
     */
    public function __construct(int $value)
    {
        // For class year, our business rules is from 1901-2999
        if (!preg_match('/^((19\d{2})|(2)\d{3})$/', $value)) {
            throw new \InvalidArgumentException('Invalid year');
        }

        $this->value = $value;
    }

    public static function fromNow(): self
    {
        return new self(date('Y'));
    }

    public function value(): int
    {
        return $this->value;
    }

    public function isAlumni(): bool
    {
        return date('Y') - $this->value >= 13;
    }
}

Enum-like validation:

Observe that it encapsulates some Enum values, but also a simple rule (isGreaterThan), and it enriches the type with a simple business rule support that the application can also use.

<?php

namespace App\Domain;

class CardRank
{
    const ACE = 'A';
    const KING = 'K';
    const QUEEN = 'Q';
    const JACK = 'J';
    const TEN = 'X';
    const NINE = '9';
    const EIGHT = '8';
    const SEVEN = '7';
    const SIX = '6';
    const FIVE = '5';
    const FOUR = '4';
    const THREE = '3';
    const TWO = '2';

    const RANKS = [
        self::ACE,
        self::KING,
        self::QUEEN,
        self::JACK,
        self::TEN,
        self::NINE,
        self::EIGHT,
        self::SEVEN,
        self::SIX,
        self::FIVE,
        self::FOUR,
        self::THREE,
        self::TWO
    ];

    const WEIGHTS = [
        self::ACE => 20,
        self::KING => 13,
        self::QUEEN => 12,
        self::JACK => 11,
        self::TEN => 10,
        self::NINE => 9,
        self::EIGHT => 8,
        self::SEVEN => 7,
        self::SIX => 6,
        self::FIVE => 5,
        self::FOUR => 4,
        self::THREE => 3,
        self::TWO => 2
    ];

    private string $value;

    public function __construct(string $value)
    {
        if (!in_array($value, self::RANKS)) {
            throw new \InvalidArgumentException("`$value` is not a valid card rank.");
        }

        $this->value = $value;
    }

    public function __toString()
    {
        return $this->value;
    }

    public function value(): string
    {
        return $this->value;
    }

    public function weight()
    {
        return self::WEIGHTS[$this->value];
    }

    public function isGreaterThan(CardRank $cardRank): bool
    {
        return $this->weight() > $cardRank->weight();
    }

    // Some static helper functions can be created to be more readable

    public static function two(): CardRank
    {
        return new self(self::TWO);
    }

    public static function ace(): CardRank
    {
        return new self(self::ACE);
    }
}

When to use it

Create and use the Value Objects whenever you see that it fits "encapsulate the business rules for a given type" and "it represents an object similar to a primitive type". This will directly understand the expected type of code and instantly validate capabilities.

Some examples:

// a
$person = new Person('John Doe', new Age(20));
public function saveGuest(Person $person);

// b
$currentUserClassYear = ClassYear::fromNow();
if (!$currentUserClassYear->isAlumni()) {
    // do something for a non-alumni user
}

// c
$pickedCard = new Card(new CardSuit(CardSuit::SPADES), new CardRank(CardRank::ACE));

// d
$aceSpade = new Card(CardSuit::spades(), CardRank::ace());
$twoSpade = new Card(CardSuit::spades(), CardRank::two());
if ($aceSpace->isGreaterThan($twoSpade)) {
    // do something when greater, such as sum the weight to count points
}

A code-base that uses Value Objects avoids repetition code to validate a type that is not represented by native types, improves readability, and keeps consistency about business rules (no one could overlook or forget to "copy the validation code check"). Value Objects has a built-in validation, making it superior to validation classes and creating a relationship with your business domain rules. It then keeps the code clean and lean.

You can see all related code at https://github.com/rafaelbernard/blog-value-objects.

Glossary

1. Entity: An entity may be defined as a thing capable of an independent existence that can be uniquely identified. An entity is an abstraction from the complexities of a domain. When we speak of an entity, we normally speak of some aspect of the real world that can be distinguished from other aspects of the real world. [(from Wikipedia)]
2. Business rule: A business rule defines or constrains some aspect of business and always resolves to either true or false. Business rules are intended to assert business structure or to control or influence the behavior of the business.
3. Object-oriented programming (OOP) is a programming paradigm based on the concept of "objects", which can contain data and code: data in the form of fields (often known as attributes or properties), and code, in the form of procedures (often known as methods).

PHP 8.1 adds a feature that might seem like a small detail, but one that I think will have a significant day-by-day impact on many people.

When I see this new feature, lots of places that use Dependency Injection^[3] come to my focus as candidates to be impacted, such as application or infrastructure service classes. As a result, we will write a much cleaner and leaner code without giving up on good practices to write modular, maintainable and testable software.

The Dependency Inversion Principle^[4] gives us decoupling powers. But we know that many classes will receive the same concrete implementation most of (if not all) the time.

So this is very common to see some variation of this code:

$someDependencyToBeInjected = FactoryClass::create();
$someService = new SomeServiceClass($someDependencyToBeInjected);

Important note: I will ignore for now Service Containers and frameworks features that deal with service instantiation, auto wiring, etc.

Think of a database query service class: you depend on a connection object. Every time you need to instantiate your database service class, you need to prepare the connection dependency and inject it at the service class. Database connections are a great example when you use the same concrete implementation more than 90% of the time.

The same applies to a Service class that you use to handle business logic and depends on QueryService and CommandHandler interfaces to do its job.

Before PHP 8.1 we have code like this:

// service class to apply business logic
// most standard
class DefaultLeadRecordService implements LeadRecordService
{
    public function __construct(
        private LeadQueryService $queryService,
        private LeadCommandHandler $commandHandler
    ) {
    }
}

// infrastructure class to match the interface -- a DBAL concrete class
// sneakily allowing a "default" value, but also open to Dependency Injection
// but not that great
class DbalLeadQueryService implements LeadQueryService
{
    public function __construct(private ?Connection $connection = null)
    {
        if (!$this->connection) {
            $this->connection = Core::getConnection();
        }
    }
}

// instantiation would be something like -- given you have $connection already instantiated
$connection =  \Doctrine\DBAL\DriverManager::getConnection($connectionParams, $config);

$service = new \Blog\Application\DefaultLeadRecordService(
    new \Blog\Infrastructure\DbalLeadQueryService($connection),
    new \Blog\Infrastructure\DbalLeadCommandHandler($connection),
);

// if we allow construct get default value
$service = new \Blog\Application\DefaultLeadRecordService(
    new \Blog\Infrastructure\DbalLeadQueryService(),
    new \Blog\Infrastructure\DbalLeadCommandHandler(),
);

While on PHP 8.1, you will be able to write it like so:

class DefaultLeadRecordService implements LeadRecordService
{
    public function __construct(
        private LeadQueryService $queryService = new DbalLeadQueryService(),
        private LeadCommandHandler $commandHandler = new DbalLeadCommandHandler()
    ) {
    }
}

// we see there is still room for new features here
// still not that great
class DbalLeadQueryService implements LeadQueryService
{
    public function __construct(private ?Connection $connection = null)
    {
        // waiting when new initializers feature allows static function as default parameters
        if (!$this->connection) {
            $this->connection = Core::getConnection();
        }
    }
}

$service = new \Blog\Application\DefaultLeadRecordService();

One liner! That saves a lot of typing, and the code remains very well structured. This is the type of significant impact we will have on our day-to-day work. We will write a more straightforward, robust and meaningful code, and we will ship features faster with high-quality code.

If you want to see a full implementation of this, check the code at https://github.com/rafaelbernard/blog-php-81-new-initializers

Test, our faithful friend

Writing tests is a must-have for any repository where quality is a requirement. However, the "New in initializers" feature does not force us to give up on a complete suite of tests. We still have all powers of unit or integration tests.

For application code, we would write unit tests and all the expectations for concrete dependencies:

<?php

namespace Test\Unit\Blog\Application;

use Blog\Application\DefaultLeadRecordService;
use Blog\Domain\LeadCommandHandler;
use Blog\Domain\LeadQueryService;
use PHPUnit\Framework\MockObject\MockObject;
use Test\TestCase;

class DefaultLeadRecordServiceTest extends TestCase
{
    private const EMAIL = 'fake@email.com';

    private LeadQueryService|MockObject $leadQueryServiceMock;
    private LeadCommandHandler|MockObject $leadCommandHandlerMock;

    private DefaultLeadRecordService $service;

    protected function setUp(): void
    {
        parent::setUp();

        $this->leadQueryServiceMock = $this->getMockBuilder(LeadQueryService::class)->getMock();
        $this->leadCommandHandlerMock = $this->getMockBuilder(LeadCommandHandler::class)->getMock();

        $this->service = new DefaultLeadRecordService($this->leadQueryServiceMock, $this->leadCommandHandlerMock);
    }

    public function testCanAdd()
    {
        $this->leadQueryServiceMock
            ->expects(self::once())
            ->method('getByEmail')
            ->with(self::EMAIL)
            ->willReturn(false);

        $this->leadCommandHandlerMock
            ->expects(self::once())
            ->method('add')
            ->with(self::EMAIL)
            ->willReturn(1);

        $result = $this->service->add(self::EMAIL);

        self::assertEquals(1, $result);
    }

    public function testAddExistentReturnsFalse()
    {
        $this->leadQueryServiceMock
            ->expects(self::once())
            ->method('getByEmail')
            ->with(self::EMAIL)
            ->willReturn(['email' => self::EMAIL]);

        $this->leadCommandHandlerMock
            ->expects(self::never())
            ->method('add');

        $result = $this->service->add(self::EMAIL);

        self::assertFalse($result);
    }

    public function testCanGetAll()
    {
        $unsorted = [
            ['email' => 'z@email.com'],
            ['email' => 'a@email.com'],
            ['email' => 'b@email.com'],
        ];

        $this->leadQueryServiceMock
            ->expects(self::once())
            ->method('getAll')
            ->willReturn($unsorted);

        $fetched = $this->service->getAll();

        $expected = $unsorted;
        asort($expected);

        self::assertEquals($expected, $fetched);
    }
}

Integration tests can be written for infrastructure code. For instance, we can use an SQLite database file to assert the logic for database operations.

Be aware that I am creating an SQLite temp database file on-demand for each test execution with $this->databaseFilePath = '/tmp/test-' . time(); and, thanks to the Dbal library, we can be confident that operations could work for any database.

-> It is highly recommended that, as an alternative, create a container with a seeded database that is compatible with your production database system.

<?php

namespace Test\Integration\Blog\Infrastructure;

use Blog\Infrastructure\DbalLeadQueryService;
use Doctrine\DBAL\Connection;
use Faker\Factory;
use Faker\Generator;
use Test\TestCase;

class DbalLeadQueryServiceTest extends TestCase
{
    private string $databaseFilePath;

    private Generator $faker;
    private Connection $connection;

    private DbalLeadQueryService $service;

    public function testCanGetAll()
    {
        $this->addEmail($email1 = $this->faker->email());
        $this->addEmail($email2 = $this->faker->email());
        $this->addEmail($email3 = $this->faker->email());

        $expected = [
            ['email' => $email1],
            ['email' => $email2],
            ['email' => $email3],
        ];

        $fetched = $this->service->getAll();

        self::assertEquals($expected, $fetched);
    }

    protected function setUp(): void
    {
        parent::setUp();

        $this->faker = Factory::create();

        $this->createLeadTable();

        $this->service = new DbalLeadQueryService($this->connection());
    }

    protected function tearDown(): void
    {
        parent::tearDown();

        $this->dropDatabase();
    }

    private function connection(): Connection
    {
        if (!isset($this->connection)) {
            $this->databaseFilePath = '/tmp/test-' . time();

            $config = new \Doctrine\DBAL\Configuration();
            $connectionParams = [
                'url' => "sqlite:///{$this->databaseFilePath}",
            ];

            $this->connection = DriverManager::getConnection($connectionParams, $config);
        }

        return $this->connection;
    }

    private function dropDatabase()
    {
        @unlink($this->databaseFilePath);
    }

    private function createLeadTable(): void
    {
        $this->connection()->executeQuery('CREATE TABLE IF NOT EXISTS leads ( email VARCHAR )');
    }

    private function addEmail(string $email): int
    {
        return $this->connection()->insert('leads', ['email' => $email]);
    }
}

Conclusion

PHP is evolving very quickly, with new features that enable more quality software, help developers and is even more committed to the fact that most of the web run flavours of PHP code. New features improve readability, software architecture, test coverage and performance. Those are all proof of a mature and live language.

Upgrade to PHP 8.1 and use "new in initializers" as soon as possible. You will not regret it.

If there is something you want to discuss more, let me know in the comments.

Links:

1. New in initializers RFC
2. Road to PHP 8.1
3. Dependency Injection
4. Dependency inversion principle
5. Interface segregation principle
6. Solid relevance
7. SOLID principles

A definition of DDD as a software design discipline

How to refactor without overtime and missed deadlines

A lot of software engineers, including myself, are passionate about code quality. This striving for a well-shaped codebase, while getting things done could cost one quite a few hours and nerves, though. I'm constantly looking for ways to achieve these two goals without significant trade-offs. Stand by for the current state.

How to test a PHP app? PHP unit testing and more

Do you really need to create tests? Of course, there are many reasons to do so – improved quality of software, decreased risks while making changes in the code, identifying errors, checking business requirements, improving security…I could go on and on with that. The point is – tests do make a difference.

Application Modernization Isn’t Just Fighting Legacy Tech

When radical innovations were rare, businesses could afford to treat application modernization as a sporadic reaction to change. A decade ago, most organizations modernized only when they were compelled to.

However, in the era of open-source and continuous innovation, modernization can’t be an isolated, one-off project. Businesses need to embrace a culture that celebrates change to thrive in the digital age. According to a report by F5, the past year has witnessed 133% growth in application modernization.

Responsible tech playbook

As technology becomes more central to peoples' lives, and to what businesses do, and how they succeed, the ethics of technology must come into sharper focus.

Despite technology becoming a critical part of what enterprizes do, it's not always clear how to approach and apply technology in an ethical or responsible way.

The Responsible tech playbook is a collection of tools, methods, and frameworks that help you to assess, model and mitigate values and risks of the software you are creating with a special emphasis on the impact of your work on the individual and society.

I am also keeping this page for a reference to my future self because we cannot rely too much on our memory, and that will be a good reference I want to re-visit. I will make constant updates on this page.

Use objects with declared properties over array

Arrays have a larger footprint to avoid constant memory pointers reassignments. It then reserves large amounts of memory when more elements or indexes are added.

Be careful to self-referencing that would prevent garbage collector from work

Garbage collector is working as expected when the internal reference count (how may times a value is used) reaches zero:

$x = "foobar";    // refcount = 1
$y = $x;            // refcount = 2
unset($x);      // refcount = 1
unset($y);      // refcount = 0 -> garbage collector will be happy ==> Destroy!

But self-referencing can be tricky:

$x = [];            // refcount = 1
$x[0] =& $x;    // refcount = 2
unset($x);      // refcount = 1
                    // It will never come to zero due to cycle

The cycle collector will eventually destroy it, but it will hang on memory for a while anyway.

Sprintf vs double/single quote concatenation

A very common use case is string concatenation or interpolation when you want to add a variable into a static string. It is interesting to note that:

If you have PHP < 7.4, use double-quote interpolation or single quote concatenation over sprintf function.

<?php 

$this->start($loop);

ob_start();

for ($i = 0; $i < $this->loop; ++$i) {
    print 'Lorem '.$i.' ipsum dolor sit amet, consectetur adipiscing elit. Proin malesuada, nisl sit amet congue blandit';
}

ob_end_clean();

return $this->end();

If you have PHP greater than 7.4, use sprintf:

<?php 

$this->start($loop);

for ($i = 0; $i < $this->loop; ++$i) {
    $value = sprintf('Lorem %s ipsum dolor sit amet, consectetur adipiscing elit. Proin malesuada, nisl sit amet congue blandit', $i);
}

return $this->end();

• https://php.lito.com.es/test/compare/SprintfTest/PrintSingleQuoteCodeConcatTest
• https://php.lito.com.es/test/compare/SprintfTest/PrintDoubleQuoteCodeTest

PHP Benchmarking

PHPBench.com was constructed as a way to open people's eyes to the fact that not every PHP code snippet will run at the same speed. You may be surprised at the results that this page generates, but that is ok. This page was also created so that you would be able to find discovery in these statistics and then maybe re-run these tests in your own server environment to play around with this idea yourself, by using the code examples (these code examples are automatically generated and as the code in my .php files change, so do they).

PHP benchmarks and optimizations

Collection of tests and benchmarks for common operations in PHP. Tests run on several versions of PHP. There is an option to compare different solutions for the same problem to compare performances between them, such as checking values with isset against !empty.

In computer science, code coverage is a measure used to describe the degree to which the source code of a program is tested by a particular test suite. A program with high code coverage has been more thoroughly tested and has a lower chance of containing software bugs than a program with low code coverage.

Testing is an unavoidable process for building a trustful software. Unfortunately, in PHP world we have a massive number of legacy software still running today that are very valuable but born in an age where testing was skipped for various reasons.

As today we are refactoring those untested systems into tested ones or we are creating new projects already focusing on having tests, we can go one step further and measure the code coverage, leveraging bug protection and code quality.

You can use these steps for a legacy project, a new project, a well-covered project, a poorly covered project; no matter the state of your project.

We are considering a PHP project using Bitbucket Pipelines as our CI and Codacy for monitoring our test coverage reports but the main concepts could be easily used when using other tools.

Table of contents:

1. Dependencies installation
2. PHPUnit configuration
3. Set up Codacy project API token
4. Pipelines configuration

1. Dependencies installation

Use composer to install dependencies:

composer require --dev phpunit/php-code-coverage codacy/coverage

Installation results would be similar to:

Using version ^1.4 for codacy/coverage
./composer.json has been updated
Loading composer repositories with package information
Updating dependencies (including require-dev)
Package operations: 3 installs, 0 updates, 0 removals
  - Installing symfony/process (v5.0.4): Downloading (100%)
  - Installing gitonomy/gitlib (v1.2.0): Downloading (100%)
  - Installing codacy/coverage (1.4.3): Downloading (100%)
Writing lock file
Generating autoload files
ocramius/package-versions:  Generating version class...
ocramius/package-versions: ...done generating version class

2. PHPUnit configuration

We need to configure at least whitelist and logging sections. They are required to code coverage.

Whitelist is the section that determines which files will be considered as your available code and how existent tests cover this code.

As I want that all my code loaded and analyzes by PHPUnit, I will set processUncoveredFilesFromWhitelist. Considering that all my code is under ./src folder:

<phpunit>
    <!-- ... -->
    <filter>
        <!-- ... -->
        <whitelist processUncoveredFilesFromWhitelist="true">
            <directory suffix=".php">./src</directory>
        </whitelist>
    </filter>
</phpunit>

Logging is where we configure logging of the test execution. Clover configuration is enough for now:

<phpunit>
    <!-- ... -->
    <logging>
      <log type="coverage-clover" target="/tmp/coverage.xml"/>
    </logging>
</phpunit>

You should now run your tests locally to ensure that you can fix everything that will be analyzed by PHPUnit. All errors have to be fixed. One example that might appear:

Fatal error: Interface 'InterfaceClass' not found in /var/www/src/Example/Application/ClassService.php on line 5

Oops.

<?php

namespace Example;

class ClassService implements InterfaceClass {
    /* */
}

I have a class extending from another but I missed the import for the parent class.

<?php

namespace Example;

use Example\Domain\InterfaceClass;

class ClassService implements InterfaceClass {
    /* */
}

And now I am good. After fixing all errors that might appear (and discovering some dead classes...), we test results and report generation message:

OK (10 tests, 17 assertions)

Generating code coverage report in Clover XML format ... done [5.71 seconds]

This has already configured code coverage. We will use Codacy as a tool to keep track of code coverage status, representing them in a beautiful dashboard and some other tools such as a check for new pull requests.

3. Set up Codacy project API token

For sending coverage results to Codacy, we need the project API token. This is located at Settings > Integrations tab.

If there is already a code, you can use it. Otherwise, generate one. A project token would look like something as:

a9564ebc3289b7a14551baf8ad5ec60a // not real

We will use this as an environment variable at Bitbucket. At your project in Bitbucket, go to Configurations > Pipelines > Repository Variables. In my case, I used:

Name: CODACY_PROJECT_TOKEN
Value: a9564ebc3289b7a14551baf8ad5ec60a

I want the value securely encrypted. Then I mark "Secure".

Right now we have Codacy token and the value enabled to use as an environment variable at our pipeline.

4. Pipelines configuration

For Pipelines now you should provide API token as an environment variable:

variables:
  - CODACY_PROJECT_TOKEN: $CODACY_PROJECT_TOKEN

Enable xdebug:

  - pecl install xdebug-2.9.2 && docker-php-ext-enable xdebug

And execute codacycoverage to send saved report to Codacy:

  - src/vendor/bin/codacycoverage clover /tmp/coverage.xml

Considering one of my legacy projects that I am adding code coverage, this could be my unit test step:

• using alpine
• source code (whitelisted) at site/src
• logfile generated at /tmp/unit-clover.xml
• g++ gcc make git php7-dev are required to install and enable xdebug

    - step: &step-unit-tests
        name: unit tests
        image: php:7.2-alpine
        variables:
          - CODACY_PROJECT_TOKEN: $CODACY_PROJECT_TOKEN
        caches:
          - composer
        script:
          - apk add --no-cache g++ gcc make git php7-dev
          - pecl install xdebug-2.9.2 && docker-php-ext-enable xdebug
          - site/src/vendor/bin/phpunit -c tests/Unit/phpunit.xml
          - site/src/vendor/bin/codacycoverage clover /tmp/unit-clover.xml

After being successfully executed by pipelines, you may see the results at your Codacy dashboard.

Now code with love.
And coverage.

Useful links:

• https://en.wikipedia.org/wiki/Code_coverage
• https://xdebug.org/
• https://docs.phpunit.de/en/11.3/code-coverage.html
• https://phpunit.readthedocs.io/en/8.5/code-coverage-analysis.html#whitelisting-files
• https://phpunit.readthedocs.io/en/8.5/configuration.html#the-logging-element
• https://en.wikipedia.org/wiki/Test-driven_development