Download the PHP package metalogico/laravel-mocka without Composer

Laravel Mocka ☕

Laravel Mocka provides fake API responses to designated users while serving real data to everyone else. A drop-in replacement for Laravel's Http facade, perfect for app store submissions, demos, and testing without disrupting production traffic.

Why Mocka?

When your Laravel app calls external APIs (like DMS, MES, or any third-party service), you often need to provide mock responses for:

• 🍎 App Store Reviews - Apple and Google reviewers need working apps without real API access
• 🧪 Testing Environments - Stable, predictable responses for your test suite
• 👥 Demo Users - Showcase your app without depending on external services
• 🚀 Development - Work offline or with unstable external APIs

Features

• 🎯 User-specific mocking - Mock responses only for designated users
• 🔄 Drop-in replacement - Use MockaHttp instead of Laravel's Http facade
• 📁 File-based mocks - Organize mock responses in PHP files
• 🎨 Response templating - Dynamic mock responses with Faker integration
• 📊 Request logging - Track which requests are mocked vs real
• ❌ Error simulation - Test failure scenarios easily
• 🛣️ Header activator - Enable/disable mocking via X-Mocka header
• 📝 Force activation - Enable/disable mocking via withOptions(['mocka' => true])
• 🐌 Rate limiting simulation - Simulate slow APIs delays for testing
• 🔍 Advanced URL matching - Regex, wildcards, and parameter matching (coming soon ™)
• ⌘ Command Line tools - List mappings
• ⚡ Zero performance impact - Only active for designated users

Installation

You can install the package via composer:

Publish the config file:

Quick Start

1. Configure Mock Users

In your .env file:

2. Create Mock Files

Create mock files in resources/mocka/:

resources/mocka/api.mock.php

3. Configure URL Mappings

In config/mocka.php:

4. Use MockaHttp in Your Services

Replace Laravel's Http facade with MockaHttp:

Advanced Features

Response Types: Static, Dynamic, or Hybrid

Mocka supports three approaches for mock responses:

Static Responses

Perfect for app store reviews and basic demos:

Dynamic Responses

For complex testing with varying data:

Hybrid Responses

You can even mix static and dynamic data as needed:

Advanced URL Matching

Configure sophisticated URL matching patterns:

Error Simulation

Simulate API errors by defining error configurations in your mappings:

Define error responses in your mock files:

Rate Limiting Simulation

Add delays to simulate slow APIs:

Jobs and Artisan (Force Activation)

When running inside queued Jobs or Artisan commands (where there is no web request/user), you can explicitly enable Mocka per request using options:

Notes:

• Mocka must still be enabled and allowed in the current environment/host by config.
• If the current user is in MOCKA_USERS, forcing is not required (it's always active).
• You can also use the X-Mocka header in regular request contexts to activate per-call.

Artisan Commands

List Mock Mappings

List all configured mappings and whether they correctly resolve to a mock file/key. The output uses a compact, two-line layout per mapping:

Per mapping you will see two rows:

• Main row — shows mapping details and overall Status for file/key resolution.
• Sub-row — shows the errors key (or - if none) in the key column, and its validation result in status.

Configuration

The configuration file config/mocka.php supports these options:

• __allowed_hosts__: restricts Mocka activation to specific upstream hosts; leave empty to allow all.
• environments: restricts activation to these Laravel environments (default ['local']).

How It Works

1. Activation Check: If enabled and allowed by environment/host, Mocka checks activation triggers in order: user allowlist, withOptions(['mocka' => true]), or X-Mocka header
2. URL Matching: If the user should be mocked, it matches the request URL against the configured mappings
3. Mock Loading: Loads the appropriate mock file and extracts the response using dot notation
4. Template Processing: Processes any template variables (faker, time functions, etc.)
5. Response Simulation: Returns the mock response with optional delays or errors
6. Logging: Logs whether the request was mocked or passed through

Testing

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

License

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

Made with ☕ in Italy