README

Seamless Local-to-Lambda Tinker Bridge with State Persistence

sls-tinker revolutionizes debugging and development for serverless Laravel applications by creating a transparent bridge between your local Tinker session and remote Lambda execution. Experience the familiar comfort of your local php artisan tinker while executing commands directly against your production Lambda environment with full state preservation across commands.

Unlike traditional approaches that require web interfaces or SSH access, this package maintains the native Tinker experience you know and love, while seamlessly forwarding each command to your remote Lambda function and preserving the execution state for subsequent commands.

Support us

You can support this project via GitHub Sponsors.

Installation

You can install the package via composer:

composer require datpmwork/sls-tinker

🚀 How It Works

# Start local tinker that connects to your Lambda
bash-4.2# php artisan sls-tinker lambda-function-name
> Psy Shell v0.11.22 (PHP 8.2.29 — cli) by Justin Hileman
> You're running Tinker in AWS Lambda
> Target Lambda: lambda-function-name

> $a = 1 # Assign variable
= 1 # Result from remote execution

> $a + 3 # Use variable in next command
= 4 # Result from remote execution

> $u = User::first() # Use Eloquent model
[!] Aliasing 'User' to 'App\Models\User' for this Tinker session.⏎
= App\Models\User {#6616  # Eloquent model fetched from remote
    id: 1,
    name: "Pham Minh Dat",
    email: "datpm@example.com",
    email_verified_at: null,
    created_at: "2025-02-06 14:57:18",
    updated_at: "2025-02-06 14:57:16",
    avatar: null,
  }

> $u->update(['name' => 'datpmwork']) # Update model attribute
= true # Result from remote execution

> $u
= App\Models\User {#6638  # Updated model fetched from remote
    id: 1,
    name: "datpmwork",
    email: "datpm@example.com",
    email_verified_at: null,
    created_at: "2025-02-06 14:57:18",
    updated_at: "2025-08-23 15:36:57",
    avatar: null,
  }

✨ Key Features

🖥️ Native Local Experience - Use your familiar local Tinker interface and shortcuts
⚡ Lambda Execution - Every command runs on your actual Lambda environment
💾 Stateful Sessions - Variables and state persist across commands seamlessly
🔄 Automatic State Sync - Previous command context automatically sent with each request
🌐 Multi-Environment - Switch between different Lambda deployments (staging, production)
🔍 Full Laravel Integration - Access models, services, facades - everything works as expected
📝 Command History - Full history support with up/down arrow navigation
🏃‍♂️ Performance Optimized - Efficient state serialization and minimal overhead

Why This Approach?

Traditional serverless debugging problems:

No SSH access to Lambda functions
Can't run interactive commands in production
Web-based tools feel foreign and limited
State doesn't persist between commands
Complex setup and authentication

sls-tinker Solution:

Keep using your local terminal and favorite tools
Execute commands in the actual production environment
Seamless state management across command invocations
Zero learning curve - it's just Tinker
Simple configuration and authentication

You can publish the config file with:

php artisan vendor:publish --tag="sls-tinker-config"

Configuration

AWS Region & Credentials

By default, requests are sent to us-east-1. If your Lambda functions live in another region, export the region into your shell before running the command:

export AWS_DEFAULT_REGION=eu-central-1

For authentication you can either export static credentials:

export AWS_ACCESS_KEY_ID=your-key
export AWS_SECRET_ACCESS_KEY=your-secret

…or use a named AWS profile instead:

export AWS_PROFILE=your-profile

The region and profile are read from real environment variables (via getenv()), so make sure to export them. Setting them only in your Laravel .env is not reliable, because Laravel does not populate getenv() by default. Also ensure the credentials have permission to invoke the target Lambda function.

Targeting the Right Function

When your serverless setup deploys multiple functions (e.g. web, artisan, jobWorker with bref), you must target the artisan (console) function. The local shell forwards each command as a CLI invocation, which only the console function can execute — the web (HTTP) and jobWorker (queue) functions expect different event payloads and will not work:

php artisan sls-tinker your-app-production-artisan

Testing

./vendor/bin/pest

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

License

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

datpmwork / sls-tinker

Maintainers

Package info

Fund package maintenance!

Statistics

Security