Download the PHP package redberry/laravel-cloud-sdk without Composer

Laravel Cloud SDK

A fluent, expressive PHP SDK for the Laravel Cloud API. Manage your applications, environments, databases, caches, object storage, and more - directly from your Laravel application.

This is a community-maintained SDK. It is not officially affiliated with, endorsed by, or supported by Laravel. "Laravel" and "Laravel Cloud" are trademarks of their respective owners.

Requirements

Installation

You may install the Laravel Cloud SDK via Composer:

The package will automatically register its service provider.

Configuration

Publish the configuration file:

This will create a config/laravel-cloud-sdk.php configuration file. You should add your Laravel Cloud API token to your .env file:

You may generate an API token from your Laravel Cloud account settings.

Usage

Creating a Client

The most common way to interact with the SDK is through the LaravelCloud facade, which automatically uses the API token from your configuration:

If you need to provide a token at runtime - for example, when managing multiple Cloud organizations - you may use the forToken method:

You may also instantiate the client directly:

Enums

The SDK ships with enums for all known API values - regions, PHP versions, database types, statuses, and more. Enums provide type safety and IDE autocompletion, but they are never required. Every method that accepts an enum also accepts a plain string:

Response objects return enum instances for known values and fall back to raw strings for values the SDK doesn't yet recognize. This means the SDK never breaks when Laravel Cloud adds new options:

Pagination

Methods that return lists of resources use automatic pagination behind the scenes. The SDK returns LazyCollection instances that fetch pages on demand as you iterate, so you never need to manage pagination manually:

Because results are lazy, only the pages you actually consume are fetched from the API. If you only need the first result, only one API call is made.

Response Data Objects

Every API response is automatically converted into a strongly-typed data object. You never work with raw arrays or JSON - every property is typed, every enum is resolved, and your IDE can autocomplete every field:

Methods that return lists yield LazyCollection instances where each item is the same typed data object:

Each resource section below includes a Response toggle documenting all available data object properties.

Relationships

When you retrieve resources - whether a single resource or a list - the SDK automatically loads their related resources. Related data is available as typed properties directly on the response object, with no extra API calls needed:

Singular relationships return the related data object or null if not set. Array relationships return an array of data objects (empty array if none exist).

Each resource section below documents available relationship properties in its Response toggle.

Creating & Updating Resources

Create and update methods use named parameters for a clean, readable API:

For updates, only pass the fields you want to change - all other fields remain unchanged.

Every create and update method also has a corresponding *With variant that accepts a data object directly. This is useful when you want to build the payload programmatically or reuse it across calls:

Each resource section below documents all available parameters for its create and update methods.

Deleting Resources

Delete methods accept a resource ID:

About Redberry

This package is built and maintained by Redberry, one of the few Official Premier Laravel Partner agencies worldwide. With 250+ Laravel projects shipped across 20+ countries, a 200-person team, and over a decade in the Laravel ecosystem, Redberry has helped startups, SMEs, and publicly traded enterprises in regulated industries build SaaS platforms, custom web applications, APIs, and more. Learn about our Laravel development services.

Table of Contents

• Applications
• Environments
• Deployments
• Instances
• Background Processes
• Commands
• Domains
• Database Clusters
• Database Snapshots
• Databases
• Caches
• Object Storage Buckets
• Bucket Keys
• Websocket Clusters
• Websocket Applications
• Dedicated Clusters
• Organization
• Regions
• IP Addresses
• Error Handling
• Testing

Applications

Applications are the top-level organizational unit in Laravel Cloud. Each application represents a single Laravel project connected to a source control repository and deployed to a specific region. An application contains one or more environments and serves as the parent for all deployment infrastructure.

Listing Applications

Retrieving an Application

Creating an Application

Updating an Application

Deleting an Application

Warning: Deleting an application removes all of its environments. Shared resources like databases, caches, and buckets are not deleted.

Application Avatar

You may upload or remove an application's avatar image:

Environments

Environments represent isolated deployment configurations within an application. Each environment has its own compute instances, resource attachments, environment variables, domains, and deployment settings.

A typical setup might include a production environment with larger, non-hibernating instances and a dedicated database cluster, alongside dev, staging, and UAT environments with smaller instances sharing a single database cluster. You can also spin up short-lived environments for feature testing or pull request previews.

When an environment is attached to resources (databases, caches, object storage), Laravel Cloud automatically injects the necessary environment variables - DB_HOST, REDIS_HOST, FILESYSTEM_DISK, and so on.

Listing Environments

Retrieving an Environment

Creating an Environment

Updating an Environment

Only pass the fields you want to change. All other fields remain unchanged:

Starting & Stopping an Environment

Deleting an Environment

Environment Variables

You may set environment variables using the EnvironmentVariableMethod::Append strategy (add or update specific keys) or the EnvironmentVariableMethod::Set strategy (replace all variables entirely). Each variable is an array with key and value entries:

Environment Metrics

Retrieve CPU, memory, and HTTP metrics for an environment:

Available periods: 6h, 24h, 3d, 7d, 30d.

Environment Logs

Query application logs with time range filters:

Log results are automatically paginated using cursor-based pagination and returned as a LazyCollection. You may filter by type: All, Application, or Access.

Deployments

Deployments represent individual releases of your application. Each deployment captures a snapshot of your code at a specific commit, builds it, and rolls it out to the environment's instances.

Listing Deployments

Retrieving a Deployment

Creating a Deployment

Deployment Logs

Retrieve the build and deploy logs for a specific deployment:

Instances

Instances are the compute infrastructure that runs your application code. Every environment has at least one App instance that serves HTTP traffic, and may optionally have Worker instances for background processing.

Instances come in two performance classes: Flex (lightweight, cost-efficient, supports hibernation) and Pro (larger sizes for sustained production workloads). Scaling can be disabled, set to custom min/max replicas, or left unlimited for automatic horizontal scaling.

Listing Instances

Retrieving an Instance

Creating an Instance

Updating an Instance

Deleting an Instance

Listing Available Instance Sizes

Background Processes

Background processes are long-running daemons attached to an instance - typically queue workers or custom commands. Each process defines a daemon type, the number of concurrent processes, and optionally a custom command or queue configuration.

Listing Background Processes

Retrieving a Background Process

Creating a Background Process

Updating a Background Process

Deleting a Background Process

Commands

Commands let you execute one-off Artisan or shell commands against a running environment - useful for migrations, cache clearing, or debugging.

Listing Commands

Retrieving a Command

Running a Command

Domains

Every environment receives a free laravel.cloud subdomain after its first deployment. For production, you can attach custom domains with automatic SSL provisioning and renewal.

Custom domains support root domains, www variants, and wildcards. Domain verification can happen in real-time (point DNS first) or via pre-verification (verify ownership before switching traffic).

Listing Domains

Retrieving a Domain

Creating a Domain

Updating a Domain

Verifying a Domain

Deleting a Domain

Database Clusters

A database cluster is the managed infrastructure that hosts one or more logical databases. You create a cluster once, then create individual databases within it for each environment.

This is one of the most important cost-optimization concepts in Laravel Cloud: non-production environments can share a single database cluster by each having their own database within it, while production typically would get a dedicated cluster.

Laravel Cloud supports Laravel MySQL (managed MySQL 8.0/8.4) and Neon Serverless Postgres (serverless PostgreSQL 16/17/18). AWS RDS (MySQL 8 or PostgreSQL 18) is also available for Laravel Private Cloud customers.

Listing Database Clusters

Retrieving a Database Cluster

Creating a Database Cluster

Updating a Database Cluster

Deleting a Database Cluster

Database Cluster Metrics

Metrics accept the same MetricPeriod options as environment metrics:

Listing Available Database Types

Database Snapshots

Snapshots provide point-in-time backups of your database cluster. You can create manual snapshots, list existing ones, and restore a cluster from a snapshot or a specific point in time.

Creating a Snapshot

Listing Snapshots

Retrieving a Snapshot

Restoring From a Snapshot

Restoring creates a new database cluster from the snapshot data:

Deleting a Snapshot

Databases

Databases are the logical schemas within a database cluster. When you attach a database to an environment, Laravel Cloud automatically injects the connection credentials. This separation allows you to share one cluster across dev, staging, and UAT environments - each with their own isolated database.

Listing Databases

Retrieving a Database

Creating a Database

Deleting a Database

Caches

Caches are managed Redis-compatible stores that serve as your application's cache, queue backend, or session store. Caches can be shared across environments - each receives a unique prefix to prevent collisions.

Two types are available: Laravel Valkey (managed, Redis-compatible) and Upstash Redis (serverless). When attached to an environment, Laravel Cloud injects CACHE_STORE, REDIS_HOST, and REDIS_PASSWORD automatically.

Listing Caches

Retrieving a Cache

Creating a Cache

Updating a Cache

Deleting a Cache

Cache Metrics

Metrics accept the same MetricPeriod options as environment metrics:

Listing Available Cache Types

Object Storage Buckets

Buckets provide S3-compatible file storage powered by Cloudflare R2, integrated directly with Laravel's Storage facade. When a bucket is attached to an environment, Laravel Cloud injects the necessary AWS S3-compatible credentials and FILESYSTEM_DISK configuration automatically.

Buckets can be private (files are inaccessible to the public, though you can generate temporary URLs via Storage::temporaryUrl) or public (files are accessible via internet-facing URLs). You may also choose a jurisdiction (default or eu) for data residency compliance.

A common pattern is to create one private bucket for user uploads and sensitive files, and one public bucket for assets that need to be served directly. Non-production environments can share a single bucket with different keys for access isolation - each key provides scoped credentials, so staging and QA can use the same bucket without interfering with each other.

Listing Buckets

Retrieving a Bucket

Creating a Bucket

Updating a Bucket

Deleting a Bucket

Bucket Keys

Bucket keys are scoped credentials that control access to a specific bucket. Each key has a permission level - read-write or read-only. You can create multiple keys with different permissions to control access granularity - for example, giving your application full read-write access while providing a reporting service with read-only credentials.

Listing Bucket Keys

Retrieving a Bucket Key

Creating a Bucket Key

Updating a Bucket Key

Deleting a Bucket Key

Websocket Clusters

Websocket clusters provide fully managed WebSocket infrastructure powered by Laravel Reverb. Each cluster is created in a specific region with a maximum concurrent connection capacity that is shared across its websocket applications. When a websocket application is attached to an environment, Laravel Cloud automatically injects the necessary Reverb connection credentials.

Listing Websocket Clusters

Retrieving a Websocket Cluster

Creating a Websocket Cluster

Updating a Websocket Cluster

Deleting a Websocket Cluster

Websocket Cluster Metrics

Metrics accept the same MetricPeriod options as environment metrics:

Websocket Applications

Websocket applications are logical partitions within a websocket cluster. Each cluster creates a default main application on provisioning. Additional applications distribute the cluster's connection capacity across different projects.

Listing Websocket Applications

Retrieving a Websocket Application

Creating a Websocket Application

Updating a Websocket Application

Deleting a Websocket Application

Websocket Application Metrics

Metrics accept the same MetricPeriod options as environment metrics:

Dedicated Clusters

Dedicated clusters provide isolated compute infrastructure for your resources. You may filter by region, resource type, or status:

Available cluster types: Applications, MysqlDatabases, RdsDatabases, RedisCaches, ReverbWebsocketServers.

Organization

Retrieve the organization associated with the current API token:

Regions

Regions determine where your infrastructure is physically located. For optimal performance, your application and all its resources should be in the same region.

IP Addresses

Retrieve the IP addresses used by Laravel Cloud, optionally filtered by region. This is useful for configuring firewall allowlists on external services:

Error Handling

The SDK throws specific exceptions for common API errors:

All other HTTP errors (401, 404, 500, etc.) throw Saloon's default RequestException, which you may catch for general error handling:

The SDK also detects unexpected HTML responses from the API (which can occur during maintenance or when an endpoint URL is incorrect) and throws an HtmlResponseException with a descriptive message instead of failing silently or returning unparseable data.

Testing

The SDK is built on Saloon, which provides a built-in mechanism for faking HTTP requests during tests. You should use Saloon's MockResponse to prevent real API calls and assert that the correct requests are being sent.

Faking Responses

The Laravel Cloud API follows the JSON:API specification. Each resource is returned with an id, type, and attributes object inside data. Related resources are sideloaded in a top-level included array and linked via the relationships object.

The SDK handles all of this automatically - you just need to structure your mock responses to match. Here's a basic example without relationships:

Faking Responses with Relationships

To test relationship hydration, add a relationships object to each resource in data and provide the related resources in the included array. The SDK will automatically match them by type and id:

Preventing Stray Requests

To ensure no real API calls leak through during your test suite, you may call preventStrayRequests. Any unfaked request will throw an exception:

Faking Error Responses

For more details on request faking, assertions, and recording, refer to the Saloon testing documentation.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Gaga Darsalia
• All Contributors

License

The MIT License (MIT). Please see License File for more information.