fakecloud

PHP client SDK for fakecloud — a local AWS cloud emulator.

Provides typed access to the fakecloud introspection and simulation API (/_fakecloud/* endpoints), letting you inspect emulator state and trigger time-based processors in tests.

Requires PHP 8.1+. Uses the built-in curl extension and json_decode/json_encode. No external dependencies.

Installation

composer require fakecloud/fakecloud

Quick start

use FakeCloud\FakeCloud;

$fc = new FakeCloud('http://localhost:4566');

// Check server health
$health = $fc->health();
echo $health->version . ' ' . implode(', ', $health->services);

// Reset all state between tests
$fc->reset();

// Inspect SES emails sent during a test
$emails = $fc->ses()->getEmails()->emails;
echo 'Sent ' . count($emails) . ' emails';

// Inspect SNS messages
$messages = $fc->sns()->getMessages()->messages;

// Inspect SQS messages across all queues
$queues = $fc->sqs()->getMessages()->queues;

// Advance DynamoDB TTL processor
$expired = $fc->dynamodb()->tickTtl()->expiredItems;

// Advance S3 lifecycle processor
$expiredObjects = $fc->s3()->tickLifecycle()->expiredObjects;

API reference

`FakeCloud`

$fc = new FakeCloud();                        // defaults to http://localhost:4566
$fc = new FakeCloud('http://localhost:4566'); // explicit base URL

Method	Description
`baseUrl()`	Return the configured base URL
`health()`	Server health check
`reset()`	Reset all service state
`resetService($service)`	Reset a single service
`credentials()`	Fetch container/instance credentials (`GET /_fakecloud/credentials`)
`instanceIdentityDocument()`	EC2 instance identity document (`/latest/dynamic/instance-identity/document`)
`dnsResolve($name, $type)`	Resolve a name against Route 53 records like the `--dns` resolver (`GET /_fakecloud/dns/resolve`)
`createAdmin($accountId, $userName, $organizationId = null)`	Bootstrap an admin IAM user in an additional account (standalone unless an organization is named)

`$fc->lambda()`

Method	Description
`getInvocations()`	List recorded Lambda invocations
`getWarmContainers()`	List warm (cached) Lambda containers
`evictContainer($functionName)`	Evict a warm container
`downloadFunctionCode($accountId, $functionName, $qualifier)`	Download a function's stored zip bundle (raw bytes)
`downloadLayerContent($accountId, $layerName, $version)`	Download a layer version's stored zip (raw bytes)

`$fc->rds()`

Method	Description
`getInstances()`	List RDS instances with runtime metadata
`lambdaInvoke($req)`	Bridge endpoint for the PostgreSQL `aws_lambda` extension
`s3Import($req)`	Bridge endpoint for the PostgreSQL `aws_s3` extension (S3 -> DB)
`s3Export($req)`	Bridge endpoint for the PostgreSQL `aws_s3` extension (DB -> S3 PutObject)

`$fc->elasticache()`

Method	Description
`getClusters()`	List ElastiCache cache clusters
`getReplicationGroups()`	List ElastiCache replication groups
`getServerlessCaches()`	List ElastiCache serverless caches
`getElastiCacheAcls()`	List ElastiCache user ACLs

`$fc->ec2()`

Method	Description
`getInstances()`	List EC2 instances with control-plane + runtime metadata
`getInstanceNetworks()`	Inspect each instance's backing network (Docker/Podman network or k8s NetworkPolicy), container IP, isolation backend, and whether security-group enforcement is active

`$fc->ecr()`

Method	Description
`getRepositories()`	List ECR repositories
`getImages($repositoryName = null)`	List ECR images (optionally per repo)
`getPullThroughRules()`	List ECR pull-through cache rules

`$fc->logs()`

Method	Description
`injectAnomaly($req)`	Inject a CloudWatch Logs anomaly for tests
`getDeliveryConfig()`	Get the current Logs delivery config snapshot
`getFieldIndexes($logGroupName)`	Get configured field indexes for a log group

`$fc->ses()`

Method	Description
`getEmails()`	List all sent emails
`simulateInbound($req)`	Simulate an inbound email (drive receipt rules)
`getMetrics()`	Get SES send/bounce/complaint metrics
`setMailFromStatus($identity, $status)`	Force a MAIL FROM domain verification status
`getDkimPublicKey($identity)`	Get the simulated DKIM public key for an identity
`setSandbox($sandbox)`	Toggle sandbox mode for the account
`getBounces()`	List recorded SES bounce events
`getMessageInsights($messageId)`	Get SES message insights for a sent message
`getSmtpSubmissions()`	List messages submitted via the SMTP submission endpoint
`getEventDestinationDeliveries()`	List deliveries fanned out to configuration set destinations

`$fc->sns()`

Method	Description
`getMessages()`	List all published messages
`getPendingConfirmations()`	List subscriptions pending confirmation
`confirmSubscription($req)`	Confirm a pending subscription
`getSigningCertPem()`	Get the PEM body served by the SNS signing-cert endpoint
`getSmsMessages()`	List SMS messages dispatched via SNS

`$fc->sqs()`

Method	Description
`getMessages()`	List all messages across all queues
`tickExpiration()`	Tick the message expiration processor
`forceDlq($queueName, ?$accountId, ?$region)`	Force all messages to the queue's DLQ (default account/region: the server's)

`$fc->applicationAutoscaling()`

Method	Description
`tick()`	Tick the Application Auto Scaling metric/policy processor
`scheduledTick()`	Tick the scheduled-action processor

`$fc->athena()`

Method	Description
`getNamedQueries()`	List all stored Athena named queries

`$fc->events()`

Method	Description
`getHistory()`	Get event history and delivery records
`fireRule($req)`	Fire an EventBridge rule manually

`$fc->scheduler()`

Method	Description
`getSchedules()`	List EventBridge Scheduler schedules
`fireSchedule($group, $name, ?$accountId, ?$region)`	Fire a scheduled invocation immediately (default account/region: the server's)

`$fc->glue()`

Method	Description
`getJobs()`	List all Glue jobs
`getJobRuns($jobName = null)`	List Glue job runs (optionally per job)
`getCrawlers()`	List Glue crawlers with state and targets

`$fc->cloudwatch()`

Method	Description
`getAlarms()`	List metric and composite alarms
`getMetrics()`	List unique metric series with latest value

`$fc->firehose()`

Method	Description
`getDeliveryStreams()`	List delivery streams with type, status, encryption, dest count

`$fc->s3()`

Method	Description
`getNotifications()`	List S3 notification events
`tickLifecycle()`	Tick the lifecycle processor
`getAccessPoints()`	List S3 access points
`getObjectLambdaResponses()`	List recorded S3 Object Lambda WriteGetObjectResponse calls

`$fc->dynamodb()`

Method	Description
`tickTtl()`	Tick the TTL processor
`saveSnapshot(?dataPath)`	Save a DynamoDB snapshot on demand (`null` -> configured store)

`$fc->secretsmanager()`

Method	Description
`tickRotation()`	Tick the rotation scheduler

`$fc->cognito()`

Method	Description
`getUserCodes($poolId, $username)`	Get confirmation codes for a user
`getConfirmationCodes()`	List all confirmation codes
`confirmUser($req)`	Confirm a user (bypass verification)
`getTokens()`	List all active tokens
`expireTokens($req)`	Expire tokens (optionally filtered)
`getAuthEvents()`	List auth events
`getPreTokenGenInvocations()`	List PreTokenGeneration Lambda trigger invocations
`mintAuthorizationCode($req)`	Mint a single-use OAuth2 authorization code (alternative to /oauth2/authorize)
`setCompromisedPasswords($req)`	Mark passwords as compromised for the advanced-security simulator
`getWebAuthnCredentials()`	List enrolled WebAuthn credentials

`$fc->apigatewayv2()`

Method	Description
`getRequests()`	List all HTTP API requests received
`getConnections()`	List active WebSocket API connections
`mtlsInfo($domainName)`	Get mTLS truststore info for a custom domain
`wsUrl($apiId, $stage = null)`	Compute the WebSocket URL for an API/stage

`$fc->stepfunctions()`

Method	Description
`getExecutions()`	List all state machine execution history
`getSyncExecutions()`	List `StartSyncExecution` results
`getExecutionTree($arn)`	Get the full parent/child execution tree for an execution
`enqueueActivityTask($req)`	Enqueue an activity task for `GetActivityTask` consumers

`$fc->bedrock()`

Method	Description
`getInvocations()`	List recorded Bedrock runtime invocations
`setModelResponse($modelId, $text)`	Configure a single canned response for a model
`setResponseRules($modelId, $rules)`	Replace prompt-conditional response rules for a model
`clearResponseRules($modelId)`	Clear all prompt-conditional response rules for a model
`queueFault($rule)`	Queue a fault rule for the next N calls
`getFaults()`	List currently queued fault rules
`clearFaults()`	Clear all queued fault rules

`$fc->bedrockAgent()`

Method	Description
`getAgents()`	List Bedrock Agent definitions

`$fc->bedrockAgentRuntime()`

Method	Description
`getInvocations()`	List Bedrock Agent runtime invocations

`$fc->ecs()`

Method	Description
`getClusters()`	List ECS clusters
`getTasks($cluster = null, $status = null)`	List ECS tasks (optionally filtered by cluster and status)
`getTask($taskId)`	Get a single ECS task
`getTaskLogs($taskId)`	Get captured stdout/stderr logs for a task
`forceStopTask($taskId)`	Force-stop a running task
`markTaskFailed($taskId, $req)`	Mark a task as failed with the supplied reason
`getEvents()`	List ECS service/task lifecycle events
`getTaskMetadata($taskArn)`	Get ECS task metadata (control-plane shape)
`getTaskCredentials($taskId)`	Get the IAM credentials served via the task metadata endpoint
`getTaskMetadataV3($taskId)`	Get the task metadata v3 payload
`getTaskMetadataV4($taskId)`	Get the task metadata v4 payload

`$fc->elbv2()`

Method	Description
`getLoadBalancers()`	List ELBv2 load balancers
`getTargetGroups()`	List ELBv2 target groups
`getListeners()`	List ELBv2 listeners
`getRules()`	List ELBv2 listener rules
`flushAccessLogs()`	Flush buffered ELBv2 access logs to their S3 bucket
`getWafCounts()`	Get WAF allow/block counts seen by ELBv2 listeners

`$fc->route53()`

Method	Description
`setHealthCheckStatus($id, $status, $reason)`	Flip a health check between `Success` / `Failure` / `Timeout` / `DnsError` / `InsufficientDataPoints` / `Unknown` to drive failover routing
`getDnssecMaterial($zoneId)`	Get the simulated DNSSEC key material for a hosted zone
`signDnssec($zoneId, $req)`	Sign a payload with the zone's DNSSEC key

`$fc->acm()`

Method	Description
`setCertificateStatus($arnOrId, $status, $reason)`	Force an ACM certificate into a specific status
`approveCertificate($arnOrId)`	Approve a pending ACM certificate request
`getCertificateChainInfo($arnOrId)`	Get parsed chain info for an ACM certificate

`$fc->organizations()`

Method	Description
`getAccounts()`	List Organizations member accounts
`getResponsibilityTransfers()`	List billing responsibility transfers (direction, status, handshake)

`$fc->ssm()`

Method	Description
`setCommandStatus($commandId, $status, $accountId = null)`	Force an SSM Run Command into a specific terminal status
`failCommand($commandId, $accountId = null, $errorCode = null, ...)`	Fail an SSM Run Command with structured error metadata
`getParameterPolicyEvents($accountId = null)`	List Parameter Store policy expiration/notification events
`injectSession($req)`	Inject a Session Manager session for inspection in tests

`$fc->kms()`

Method	Description
`getUsage()`	Get KMS key usage counters (encrypt/decrypt/sign)

`$fc->wafv2()`

Method	Description
`evaluate($body)`	Evaluate a request against a WAFv2 WebACL and return the decision

`$fc->cloudfront()`

Method	Description
`getDistributions()`	List CloudFront distributions (id, domain, served)
`setDistributionStatus($distributionId, $status)`	Force a CloudFront distribution into a status

`$fc->serviceQuotas()`

Method	Description
`getQuotas(?$accountId, ?$region, ?$serviceCode)`	List quotas with applied value, usage and enforcement state (default account/region: the server's); without a service code: the enforceable, measured or changed quotas (applied value, override, open request); with one: the whole service
`putQuota($serviceCode, $quotaCode, $req)`	Set a quota's applied value (may be below the AWS default) and/or enforcement override
`deleteQuota($serviceCode, $quotaCode, ?$accountId, ?$region)`	Reset a quota to its AWS default and drop its override (the account's when `$accountId` is given)
`getEnforcement()`	Read the global `enforceAll` switch and every per-quota / per-account override
`putEnforcement($req)`	Change the global switch and/or a batch of overrides (all validated before any is applied)
`getRequestApproval()`	Read how increase requests are decided (`auto` or `manual`)
`setRequestApproval($mode)`	Switch between `auto` and `manual` approval
`getRequests(?$accountId, ?$status)`	List quota increase requests, newest first
`approveRequest($requestId)`	Approve a pending request, raising the applied value
`denyRequest($requestId, ?$status)`	Close a pending request (`DENIED` by default, or `NOT_APPROVED` / `CASE_CLOSED` / `INVALID_REQUEST`)

Enforcement is tri-state via the QuotaEnforcement enum: Enforce sends true, Ignore sends false, and Default sends null to clear the override. In PutServiceQuotaRequest, leaving enforcement null omits the key entirely and leaves enforcement unchanged.

use FakeCloud\PutServiceQuotaEnforcementRequest;
use FakeCloud\PutServiceQuotaRequest;
use FakeCloud\QuotaEnforcement;
use FakeCloud\ServiceQuotaEnforcementChange;

// Lower "Inbound or outbound rules per security group" to 2 and enforce
// it, so the third AuthorizeSecurityGroupIngress rule fails without
// creating sixty rules first.
$fc->serviceQuotas()->putQuota('vpc', 'L-0EA8095F', new PutServiceQuotaRequest(
    value: 2,
    enforcement: QuotaEnforcement::Enforce,
));

// Clear that override again, leaving the applied value alone.
$fc->serviceQuotas()->putEnforcement(new PutServiceQuotaEnforcementRequest(
    overrides: [new ServiceQuotaEnforcementChange('vpc', 'L-0EA8095F', QuotaEnforcement::Default)],
));

// Hold increase requests for a manual decision.
$fc->serviceQuotas()->setRequestApproval('manual');
foreach ($fc->serviceQuotas()->getRequests(status: 'PENDING')->requests as $r) {
    $fc->serviceQuotas()->approveRequest($r->requestId);
}

Full test loop — asserting on Bedrock calls

use FakeCloud\FakeCloud;
use FakeCloud\BedrockFaultRule;
use FakeCloud\BedrockResponseRule;

$fc = new FakeCloud();
$modelId = 'anthropic.claude-3-haiku-20240307-v1:0';

// beforeEach
$fc->reset();

// Prime prompt-conditional responses
$fc->bedrock()->setResponseRules($modelId, [
    new BedrockResponseRule('buy now', '{"label":"spam"}'),
    new BedrockResponseRule(null, '{"label":"ham"}'), // catch-all
]);

classify('hello friend');           // user code calls Bedrock
classify('buy now cheap pills');

$invocations = $fc->bedrock()->getInvocations()->invocations;
assert(count($invocations) === 2);
assert(str_contains($invocations[0]->output, 'ham'));
assert(str_contains($invocations[1]->output, 'spam'));

Error handling

All methods throw FakeCloudError (a RuntimeException) on non-2xx responses:

use FakeCloud\FakeCloudError;
use FakeCloud\ConfirmUserRequest;

try {
    $fc->cognito()->confirmUser(new ConfirmUserRequest('pool-1', 'nobody'));
} catch (FakeCloudError $err) {
    echo $err->status; // 404
    echo $err->body;   // "user not found"
}

Local development

# Build fakecloud (from repo root)
cargo build --release

# Install PHP dependencies
cd sdks/php
composer install

# Run unit tests
vendor/bin/phpunit tests/ClientTest.php

# Run E2E tests against the freshly-built binary
vendor/bin/phpunit tests/E2ETest.php

Name		Name	Last commit message	Last commit date
src		src
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
composer.json		composer.json
phpunit.xml		phpunit.xml

Latest commit

History

Folders and files

Repository files navigation

fakecloud

Installation

Quick start

API reference

FakeCloud

$fc->lambda()

$fc->rds()

$fc->elasticache()

$fc->ec2()

$fc->ecr()

$fc->logs()

$fc->ses()

$fc->sns()

$fc->sqs()

$fc->applicationAutoscaling()

$fc->athena()

$fc->events()

$fc->scheduler()

$fc->glue()

$fc->cloudwatch()

$fc->firehose()

$fc->s3()

$fc->dynamodb()

$fc->secretsmanager()

$fc->cognito()

$fc->apigatewayv2()

$fc->stepfunctions()

$fc->bedrock()

$fc->bedrockAgent()

$fc->bedrockAgentRuntime()

$fc->ecs()

$fc->elbv2()

$fc->route53()

$fc->acm()

$fc->organizations()

$fc->ssm()

$fc->kms()

$fc->wafv2()

$fc->cloudfront()

$fc->serviceQuotas()