Laravel Lumen

https://github.com/laravel/lumen
Admin
Laravel Lumen is a fast, lightweight PHP micro-framework designed for building microservices and...
Tokens:47,871
Snippets:570
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Creating an Example Controller

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/routing-and-controllers.md

A basic controller implementation with a constructor and a request handler.

```php
namespace App	eteControllers;

class ExampleController extends Controller
{
    /**
     * Create a new controller instance.
     */
    public function __construct()
    {
        // Called once when controller is instantiated
    }

    /**
     * Handle the request.
     */
    public function show($id)
    {
        return response()->json(['id' => $id]);
    }
}
```

--------------------------------

### Standard Code Example Format

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/README.md

The required template for all code examples, including method signatures and usage patterns.

```php
// Method signature with types
public function store(Request $request): Response

// Usage pattern
$user = User::create($request->all());
return response()->json($user, 201);
```

--------------------------------

### Define Example Event

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/events-and-listeners.md

An example of an event class that accepts a User model in its constructor.

```php
namespace App\Events;

use App\Models\User;

class ExampleEvent extends Event
{
    /**
     * The user associated with the event.
     *
     * @var \App\Models\User
     */
    public $user;

    /**
     * Create a new event instance.
     *
     * @param  \App\Models\User  $user
     * @return void
     */
    public function __construct(User $user)
    {
        $this->user = $user;
    }
}
```

--------------------------------

### Dispatching Jobs from Events

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/jobs-and-queues.md

Example of dispatching a job from an event listener.

```php
namespace App\Listeners;

use App\Events\OrderCreated;
use App\Jobs\ProcessOrder;

class DispatchProcessOrder
{
    public function handle(OrderCreated $event)
    {
        dispatch(new ProcessOrder($event->order));
    }
}
```

--------------------------------

### Register services in AppServiceProvider

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/service-providers.md

Example of binding singletons and classes into the IoC container.

```php
public function register()
{
    $this->app->singleton('email-sender', function ($app) {
        return new EmailSender($app['config']['mail']);
    });

    $this->app->bind('pdf-generator', PdfGenerator::class);
}
```

--------------------------------

### Create Example Job Class

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/jobs-and-queues.md

A basic job implementation extending the base Job class with a constructor for data injection and a handle method for execution.

```php
namespace App\Jobs;

class ExampleJob extends Job
{
    protected $data;

    /**
     * Create a new job instance.
     *
     * @return void
     */
    public function __construct($data)
    {
        $this->data = $data;
    }

    /**
     * Execute the job.
     *
     * @return void
     */
    public function handle()
    {
        // Process the job
    }
}
```

--------------------------------

### Dependency Injection in Controllers

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/routing-and-controllers.md

Examples of injecting dependencies via the constructor or method arguments.

```php
namespace App	eteControllers;

use Illuminate	tp	equest;
use Illuminate	ontracts	uth	actory as Auth;

class UserController extends Controller
{
    protected $auth;
    protected $request;

    public function __construct(Auth $auth, Request $request)
    {
        $this->auth = $auth;
        $this->request = $request;
    }

    public function store()
    {
        $user = $this->auth->user();
        $input = $this->request->input();
    }
}
```

```php
public function update(Request $request, $id)
{
    $data = $request->json();
    // Update logic
}
```

--------------------------------

### Debug Mode JSON Response Example

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/exception-handling.md

Example of the JSON structure returned when APP_DEBUG is set to true.

```json
{
    "message": "Undefined variable",
    "exception": "ErrorException",
    "file": "/app/Controllers/UserController.php",
    "line": 42,
    "trace": [...]
}
```

--------------------------------

### Dispatching Jobs from Controllers

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/jobs-and-queues.md

Example of dispatching a job within a controller's store method after creating a model instance.

```php
namespace App\Http\Controllers;

use App\Jobs\ProcessOrder;
use App\Models\Order;

class OrderController extends Controller
{
    public function store()
    {
        $order = Order::create(request()->all());

        dispatch(new ProcessOrder($order));

        return response()->json(['order' => $order], 201);
    }
}
```

--------------------------------

### Applying Middleware to Routes

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/authentication-and-authorization.md

Examples of applying the auth middleware to individual routes, route groups, and specifying custom guards.

```php
// Single route
$router->get('/profile', 'ProfileController@show')
    ->middleware('auth');

// Route group
$router->group(['middleware' => 'auth'], function ($router) {
    $router->get('/dashboard', 'DashboardController@show');
    $router->put('/profile', 'ProfileController@update');
});

// Specify guard
$router->get('/admin', 'AdminController@index')
    ->middleware('auth:admin');
```

--------------------------------

### Router::get

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/routing-and-controllers.md

Registers a route that responds to GET requests.

```APIDOC
## Router::get(string $uri, callable|string $callback)

### Description
Registers a route that responds to HTTP GET requests.

### Parameters
- **$uri** (string) - Required - The URI pattern for the route.
- **$callback** (callable|string) - Required - The controller action or closure to execute.
```

--------------------------------

### Returning HTTP Responses

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/routing-and-controllers.md

Examples of returning various data types and response objects from routes or controllers.

```php
// String response
return 'Hello World';

// JSON response
return response()->json(['name' => 'John', 'age' => 30]);
return response()->json($data, 200, $headers);

// Eloquent Model (auto-converted to JSON)
return App\\Models\\User::find(1);

// Eloquent Collection
return App\\Models\\User::all();

// HTTP Response
return response('Hello', 200)
    ->header('Content-Type', 'text/plain');

// File download
return response()->download('/path/to/file.pdf');

// Redirects
return redirect('/dashboard');
return redirect()->route('users.show', ['id' => 1]);
return redirect()->back();

// Errors
return response('Unauthorized', 401);
return response('Not Found', 404);

// Redirect with data
return redirect('/login')->with('message', 'Please log in');
```

--------------------------------

### Implementing Authenticatable in a User Model

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/authentication-and-authorization.md

Required setup for models to be used with Lumen's authentication system. Ensure the model implements the Authenticatable contract and uses the Authenticatable trait.

```php
namespace App\Models;

use Illuminate\Auth\Authenticatable;
use Illuminate\Contracts\Auth\Authenticatable as AuthenticatableContract;
use Illuminate\Database\Eloquent\Model;

class User extends Model implements AuthenticatableContract
{
    use Authenticatable;

    /**
     * The attributes that should be hidden for arrays.
     */
    protected $hidden = ['password'];
}
```

--------------------------------

### Configure Application Bootstrap

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/application-structure.md

Initializes the application instance, registers core service providers, and loads route definitions.

```php
$app = new Laravel\
Lumen\\Application(
    dirname(__DIR__)
);

// Register exception handler
$app->singleton(
    Illuminate\\Contracts\\Debug\\ExceptionHandler::class,
    App\\Exceptions\\Handler::class
);

// Register console kernel
$app->singleton(
    Illuminate\\Contracts\\Console\\Kernel::class,
    App\\Console\\Kernel::class
);

// Register service providers
$app->register(App\\Providers\\AppServiceProvider::class);

// Load routes
$app->router->group([
    'namespace' => 'App\\Http\\Controllers',
], function ($router) {
    require __DIR__.'/../routes/web.php';
});

return $app;
```

--------------------------------

### Implement a Configuration Provider

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/service-providers.md

Uses the boot method to set application configuration values during the boot phase.

```php
class ConfigProvider extends ServiceProvider
{
    public function boot()
    {
        config([
            'app.name' => env('APP_NAME', 'Lumen'),
            'app.debug' => env('APP_DEBUG', false),
            'app.timezone' => env('APP_TIMEZONE', 'UTC'),
        ]);
    }
}
```

--------------------------------

### Define and Register Middleware with Parameters

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/middleware.md

Demonstrates creating middleware that accepts parameters and registering it in the application bootstrap.

```php
// Define middleware with parameters
class CheckRole
{
    public function handle($request, Closure $next, $role)
    {
        if ($request->user()->role !== $role) {
            return response('Forbidden', 403);
        }
        
        return $next($request);
    }
}

// Register in bootstrap/app.php
$app->routeMiddleware([
    'role' => App\\Http\\Middleware\\CheckRole::class,
]);

// Use with parameter
$router->get('/admin', 'AdminController@index')
    ->middleware('role:admin');

// Multiple parameters
$router->get('/moderator', 'ModeratorController@index')
    ->middleware('role:moderator,editor');
```

--------------------------------

### Creating a Custom Service Provider

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/service-providers.md

Define service bindings in the register method and perform post-registration logic in the boot method.

```php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Services\PaymentService;

class PaymentServiceProvider extends ServiceProvider
{
    /**
     * Register services.
     */
    public function register()
    {
        // Singleton - same instance every time
        $this->app->singleton('payment', function ($app) {
            return new PaymentService($app['config']['payment']);
        });

        // Bind - new instance every time
        $this->app->bind('payment-factory', PaymentFactory::class);
    }

    /**
     * Bootstrap services after registration.
     */
    public function boot()
    {
        // Configuration is available here
        $config = $this->app['config'];
    }
}
```

--------------------------------

### Load and Access Configuration Files

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/application-structure.md

Enable configuration files by calling configure in the bootstrap process, then access values using the config helper.

```php
$app->configure('database');
```

```php
$driver = config('database.default');
$host = config('database.connections.mysql.host');
```

--------------------------------

### Implementing a Provider with Configuration Publishing

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/service-providers.md

Use mergeConfigFrom to load configuration and publishes to allow users to export configuration files.

```php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;

class ConfigServiceProvider extends ServiceProvider
{
    public function register()
    {
        // Register configuration
        $this->mergeConfigFrom(
            __DIR__ . '/../../config/custom.php',
            'custom'
        );
    }

    public function boot()
    {
        // Publish configuration files
        $this->publishes([
            __DIR__ . '/../../config/custom.php' => config_path('custom.php'),
        ], 'config');
    }
}
```

--------------------------------

### Customizing exception rendering

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/exception-handling.md

Example of returning a custom JSON response for specific exception types.

```php
public function render($request, Throwable $exception)
{
    // Handle custom exceptions
    if ($exception instanceof InvalidApiKeyException) {
        return response()->json(['error' => 'Invalid API key'], 401);
    }
    
    // Use parent for default handling
    return parent::render($request, $exception);
}
```

--------------------------------

### Registering and Using a Custom Service

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/service-providers.md

Register the provider in the bootstrap file and resolve the service from the container in a controller.

```php
$app->register(App\Providers\PaymentServiceProvider::class);
```

```php
class OrderController extends Controller
{
    public function store(Request $request)
    {
        $paymentService = app('payment');
        $result = $paymentService->charge($request->input('amount'));
    }
}
```

--------------------------------

### Configure Logging in .env

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/exception-handling.md

Set the logging channel and optional Slack webhook URL in the environment configuration file.

```text
LOG_CHANNEL=stack
LOG_SLACK_WEBHOOK_URL=
```

--------------------------------

### Create Email Dispatch Job

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/jobs-and-queues.md

Example of a job that sends an email and includes a delayed dispatch call.

```php
namespace App\Jobs;

use App\Mail\OrderConfirmation;
use Illuminate\Mail\Mailable;

class SendOrderConfirmation extends Job
{
    protected $order;

    public function __construct($order)
    {
        $this->order = $order;
    }

    public function handle()
    {
        Mail::send(new OrderConfirmation($this->order));
    }
}

// Dispatch
dispatch(new SendOrderConfirmation($order))->delay(now()->addMinutes(5));
```

--------------------------------

### Firing Events in Controllers

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/events-and-listeners.md

Example of triggering an event within a controller's store method after model creation.

```php
namespace App\Http\Controllers;

use App\Events\UserRegistered;
use App\Models\User;
use Illuminate\Http\Request;

class UserController extends Controller
{
    public function store(Request $request)
    {
        $user = User::create($request->all());
        
        event(new UserRegistered($user));
        
        return response()->json(['user' => $user], 201);
    }
}
```

--------------------------------

### Implement a Database Connection Provider

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/service-providers.md

Registers a database connection as a singleton in the application container.

```php
class DatabaseProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->singleton('db', function ($app) {
            return new DatabaseConnection(
                $app['config']['database']
            );
        });
    }
}
```

--------------------------------

### Customizing exception reporting

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/exception-handling.md

Example of adding custom logging logic within the report method before calling the parent handler.

```php
public function report(Throwable $exception)
{
    // Log specific exception type
    if ($exception instanceof \PDOException) {
        \Log::error('Database error: ' . $exception->getMessage());
    }
    
    // Call parent to use default reporting
    parent::report($exception);
}
```

--------------------------------

### Implement a Controller with Dependency Injection

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/INDEX.md

Demonstrates constructor injection of a repository class to handle data retrieval within a controller method.

```php
class UserController extends Controller {
    public function __construct(private UserRepository $users) {}
    
    public function show($id) {
        return response()->json($this->users->find($id));
    }
}
```

--------------------------------

### Retrieve Application Paths and Instances

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/helpers-and-utilities.md

Access the application container and resolve various directory paths relative to the project root.

```php
// Get application instance
app();
app('key');                  // Get service from container

// Get path
app_path();                  // Path to app/ directory
app_path('Models/User.php'); // Specific path
base_path();                 // Project root
base_path('config');         // Relative to root
config_path();               // config/ directory
database_path();             // database/ directory
storage_path();              // storage/ directory
storage_path('logs');        // Specific storage path
public_path();               // public/ directory
resource_path();             // resources/ directory
resource_path('views');      // Views directory

// Get version
app()->version();            // Lumen version
```

--------------------------------

### Configure Queue Connection

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/jobs-and-queues.md

Set the default queue connection in the .env file.

```text
QUEUE_CONNECTION=sync
```

--------------------------------

### Manage Configuration Values

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/helpers-and-utilities.md

Retrieve or set configuration values at runtime using the config helper.

```php
// Get config value
config('app.name');          // From config/app.php
config('database.default');  // Default database
config('queue.connection');  // Queue connection
config('cache.default');     // Cache driver
config('app.debug', false);  // With default

// Set config value (runtime only)
config(['app.name' => 'MyApp']);
```

--------------------------------

### Configuring Queue Connection

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/events-and-listeners.md

Environment configuration settings for defining the queue driver.

```text
QUEUE_CONNECTION=sync    # Use sync for testing
QUEUE_CONNECTION=redis   # Use redis for production
QUEUE_CONNECTION=database # Use database for production
```

--------------------------------

### Register Event Mappings and Provider

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/events-and-listeners.md

Map events to multiple listeners in the $listen array and register the provider in the application bootstrap.

```php
protected $listen = [
    \App\Events\UserRegistered::class => [
        \App\Listeners\SendWelcomeEmail::class,
        \App\Listeners\LogRegistration::class,
    ],
    \App\Events\OrderPlaced::class => [
        \App\Listeners\SendOrderConfirmation::class,
        \App\Listeners\DeductInventory::class,
        \App\Listeners\NotifyWarehouse::class,
    ],
    \App\Events\PostCreated::class => [
        \App\Listeners\GenerateThumbnails::class,
    ],
];
```

```php
$app->register(App\Providers\EventServiceProvider::class);
```

--------------------------------

### Implementing Deferred Service Providers

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/service-providers.md

Optimize performance by setting the $defer property to true and defining the provides method to load the provider only when the service is requested.

```php
class CustomProvider extends ServiceProvider
{
    protected $defer = true;

    public function provides()
    {
        return ['custom-service'];
    }

    public function register()
    {
        $this->app->singleton('custom-service', function () {
            return new CustomService();
        });
    }
}
```

--------------------------------

### Execute Seeders via CLI

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/database-migrations.md

Run seeders individually, all at once, or integrate them into migration workflows.

```bash
# Run all seeders
php artisan db:seed

# Run specific seeder
php artisan db:seed --class=UserSeeder

# Run during migration
php artisan migrate --seed

# Refresh and seed
php artisan migrate:refresh --seed
```

--------------------------------

### Register and Apply Middleware

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/middleware.md

Register middleware in the application bootstrap and apply it to individual routes or route groups.

```php
// Register in bootstrap/app.php
$app->routeMiddleware([
    'auth' => App\Http\Middleware\Authenticate::class,
]);

// Apply to route
$router->get('/dashboard', 'DashboardController@show')
    ->middleware('auth');

// Apply to group
$router->group(['middleware' => 'auth'], function ($router) {
    $router->get('/profile', 'ProfileController@show');
});

// Specify guard
$router->get('/admin', 'AdminController@index')
    ->middleware('auth:admin');
```

--------------------------------

### Create Migration Files

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/database-migrations.md

Use Artisan commands to generate new migration files in the database/migrations directory.

```bash
php artisan make:migration create_users_table
php artisan make:migration add_age_to_users_table
php artisan make:migration create_posts_table --create=posts
php artisan make:migration add_columns_to_posts_table --table=posts
```

--------------------------------

### Implement a Queue Provider

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/service-providers.md

Configures queue services by matching the connection type to the corresponding queue implementation.

```php
class QueueProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->singleton('queue', function ($app) {
            $connection = config('queue.connection', 'sync');

            return match($connection) {
                'redis' => new RedisQueue($app['redis']),
                'database' => new DatabaseQueue($app['db']),
                'sqs' => new SqsQueue($app['aws.sqs']),
                default => new SyncQueue(),
            };
        });
    }
}
```

--------------------------------

### Access Services in Middleware

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/middleware.md

Demonstrates dependency injection via the constructor or using the global app container helper.

```php
class ExampleMiddleware
{
    protected $cache;
    
    public function __construct(Cache\\Repository $cache)
    {
        $this->cache = $cache;
    }
    
    public function handle($request, Closure $next)
    {
        // Use injected cache
        if ($this->cache->has('key')) {
            // ...
        }
        
        return $next($request);
    }
}
```

```php
public function handle($request, Closure $next)
{
    $cache = app('cache');
    $logger = app('log');
    
    return $next($request);
}
```

--------------------------------

### Bootstrap HTTP Entry Point

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/application-structure.md

The primary entry point for all incoming HTTP requests.

```php
$app = require __DIR__.'/../bootstrap/app.php';
$app->run();
```

--------------------------------

### Access Middleware Parameters

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/middleware.md

Shows how to define the handle method to accept multiple parameters passed from the route.

```php
public function handle($request, Closure $next, $role, $secondParam = null)
{
    // Use $role parameter
}
```

--------------------------------

### Configuring AuthServiceProvider

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/authentication-and-authorization.md

Register gates and policies within the boot method of the AuthServiceProvider.

```php
namespace App\\Providers;

use Illuminate\\Support\\ServiceProvider;

class AuthServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     */
    public function register()
    {
        //
    }

    /**
     * Boot the authentication services for the application.
     */
    public function boot()
    {
        // Define gates
        $this->registerGates();

        // Register model policies
        $this->registerPolicies();
    }

    protected function registerGates()
    {
        // Gate::define('edit-post', function ($user, $post) {
        //     return $user->id === $post->user_id;
        // });
    }

    protected function registerPolicies()
    {
        // Gate::policy(Post::class, PostPolicy::class);
    }
}
```

--------------------------------

### Response and Redirect Helpers

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/helpers-and-utilities.md

Methods for returning HTTP responses, managing redirects, and triggering abort exceptions.

```php
// Return responses
return response('content', 200);
return response()->json(['data' => $data]);
return response()->download('/path/to/file');
return response()->stream(function () { echo 'data'; });

// Return redirects
return redirect('/path');
return redirect()->back();
return redirect()->route('users.show', ['id' => 1]);
return redirect('/login')->with('message', 'Login required');
return back()->withInput();
return back()->withErrors(['email' => 'Invalid']);

// Abort
abort(404);
abort(403, 'Unauthorized');
abort_if(!$user->isAdmin(), 403);
abort_unless($user->can('edit'), 403);
```

--------------------------------

### Implement a Cache Provider

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/service-providers.md

Uses a match expression to resolve the appropriate cache driver based on configuration.

```php
class CacheProvider extends ServiceProvider
{
    public function register()
    {
        $driver = config('cache.driver', 'file');

        $this->app->singleton('cache', function ($app) use ($driver) {
            return match($driver) {
                'redis' => new RedisCache($app['config']['redis']),
                'memcached' => new MemcachedCache($app['config']['memcached']),
                default => new FileCache(),
            };
        });
    }
}
```

--------------------------------

### Define Console Commands with Dependencies

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/console-and-scheduling.md

Implement custom commands by extending the Command class and injecting services via the constructor.

```php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use App\Services\OrderService;

class ProcessOrders extends Command
{
    protected $signature = 'orders:process';
    protected $description = 'Process pending orders';

    protected $orderService;

    public function __construct(OrderService $orderService)
    {
        parent::__construct();
        $this->orderService = $orderService;
    }

    public function handle()
    {
        $this->orderService->process();
        $this->info('Orders processed');
    }
}
```

--------------------------------

### Execute Migration Commands

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/database-migrations.md

Run, refresh, or rollback database migrations using various Artisan command options.

```bash
# Run all pending migrations
php artisan migrate

# Run migrations for specific batch
php artisan migrate --step

# Refresh database (drop all tables and re-run migrations)
php artisan migrate:refresh

# Refresh and seed
php artisan migrate:refresh --seed

# Reset all migrations
php artisan migrate:reset

# Rollback last batch
php artisan migrate:rollback

# Rollback specific steps
php artisan migrate:rollback --steps=2

# Rollback all
php artisan migrate:reset

# Status of migrations
php artisan migrate:status
```

--------------------------------

### Creating and Saving Model Instances

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/models-and-eloquent.md

Methods for instantiating and persisting new records to the database.

```php
// Create instance (not saved)
$post = new Post();
$post->title = 'My Post';
$post->content = 'Post content';
$post->save(); // Save to database

// Create and save in one step
$post = Post::create([
    'title' => 'My Post',
    'content' => 'Post content',
]);

// Create without saving
$post = Post::make([
    'title' => 'My Post',
    'content' => 'Post content',
]);
$post->save();

// Update or create
$post = Post::updateOrCreate(
    ['slug' => 'my-post'], // Find by these attributes
    ['title' => 'My Post', 'content' => 'Content'] // Update/create with these
);

// Create many records
Post::insert([
    ['title' => 'Post 1', 'content' => 'Content 1'],
    ['title' => 'Post 2', 'content' => 'Content 2'],
]);
```

--------------------------------

### Dispatching Jobs

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/jobs-and-queues.md

Use the global dispatch helper or the Bus facade to send jobs to the queue.

```php
use App\Jobs\ProcessOrder;

// Dispatch a job
dispatch(new ProcessOrder($order));

// Or using the facade
Bus::dispatch(new ProcessOrder($order));
```

--------------------------------

### Response Macros

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/request-and-response.md

Define custom response methods in a service provider's boot method to standardize API output.

```php
// In service provider boot
Response::macro('success', function ($data, $message = null) {
    return response()->json([
        'success' => true,
        'message' => $message,
        'data' => $data,
    ]);
});

Response::macro('error', function ($message, $code = 400) {
    return response()->json([
        'success' => false,
        'message' => $message,
    ], $code);
});

// Usage
return response()->success(['user' => $user], 'User created');
return response()->error('Invalid email', 422);
```

--------------------------------

### Execute Artisan CLI Commands

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/application-structure.md

Standard syntax for interacting with the application via the command line.

```bash
php artisan {command} {arguments}
```

--------------------------------

### Manage Files and Storage

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/helpers-and-utilities.md

Interact with the file system using Storage and File facades, or handle file uploads via request objects.

```php
// Storage access
Storage::disk('local')->get('file.txt');
Storage::disk('public')->put('avatar.jpg', $contents);
Storage::exists('file.txt');
Storage::delete('file.txt');
Storage::url('file.txt');                // Generate URL
storage_path('logs');                    // Storage path

// File operations
File::get('/path/to/file');
File::put('/path/to/file', $contents);
File::exists('/path/to/file');
File::delete('/path/to/file');
File::isDirectory('/path');

// Upload file
$file = request()->file('upload');
$path = $file->store('uploads');         // Store in storage/app/uploads
$path = $file->storeAs('uploads', 'name.jpg');
```

--------------------------------

### Access Configuration via Environment Variables

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/application-structure.md

Retrieve configuration values defined in the environment using the env helper function.

```php
$timezone = env('APP_TIMEZONE', 'UTC');
$debug = env('APP_DEBUG', false);
$key = env('DB_PASSWORD');
```

--------------------------------

### Dispatch Jobs with Queue Options

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/jobs-and-queues.md

Use the dispatch helper to send jobs to specific connections or queues, with optional delays.

```php
// Run job synchronously (for testing)
dispatch(new ProcessOrder($order))->onConnection('sync');

// Use specific queue
dispatch(new ProcessOrder($order))->onQueue('orders');

// Combine
dispatch(new ProcessOrder($order))
    ->onConnection('redis')
    ->onQueue('orders')
    ->delay(30);
```

--------------------------------

### Define and Fire Domain Events

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/events-and-listeners.md

Create an event class with properties and trigger it using the event helper function.

```php
namespace App\Events;

class UserRegistered extends Event
{
    public $user;
    public $registrationSource;

    public function __construct(User $user, $source = 'web')
    {
        $this->user = $user;
        $this->registrationSource = $source;
    }
}

// Fire with context
event(new UserRegistered($user, 'mobile-app'));
```

--------------------------------

### Manage Task Callbacks and Output

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/console-and-scheduling.md

Configure hooks for task lifecycle events or redirect command output to files, emails, or external URLs.

```php
// Run before scheduled task
$schedule->command('orders:process')
    ->before(function () {
        \Log::info('Processing started');
    });

// Run after scheduled task
$schedule->command('orders:process')
    ->after(function () {
        \Log::info('Processing completed');
    });

// Send output to file
$schedule->command('backup:database')
    ->sendOutputTo('/storage/logs/backup.log');

// Append to file
$schedule->command('cleanup:cache')
    ->appendOutputTo('/storage/logs/cleanup.log');

// Email output on failure
$schedule->command('orders:process')
    ->emailOnFailure('admin@example.com');

// Ping URL when task completes
$schedule->command('reports:generate')
    ->onSuccess(function () {
        return Http::get('https://example.com/success');
    });
```

--------------------------------

### Register service providers in bootstrap/app.php

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/service-providers.md

Syntax for registering providers within the application bootstrap file.

```php
// Register in bootstrap/app.php
// $app->register(App\Providers\AppServiceProvider::class);

// Or with delayed registration
// $app->register(\App\Providers\AppServiceProvider::class);
```

--------------------------------

### Attempt Authentication with Credentials

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/authentication-and-authorization.md

Authenticate users via credentials, optional remember-me functionality, or specific guards.

```php
// Attempt login with credentials
if (auth()->attempt(['email' => $email, 'password' => $password])) {
    // Login successful
    $user = auth()->user();
} else {
    // Login failed
}

// Attempt with remember me
auth()->attempt(['email' => $email, 'password' => $password], $remember = true);

// Attempt on specific guard
auth('admin')->attempt(['email' => $email, 'password' => $password]);
```

--------------------------------

### Cache and Session Helper Usage

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/helpers-and-utilities.md

Use these helpers for managing application cache, session data, and authentication tokens.

```php
// Cache
Cache::get('key');
Cache::put('key', 'value', 60);
Cache::remember('key', 60, fn() => expensive_operation());
Cache::forget('key');

// Session
session('key');
session(['key' => 'value']);
session()->flash('message', 'Success');
old('field');

// Remember token (for "remember me")
auth()->user()->getRememberToken();
auth()->user()->setRememberToken('token');
```

--------------------------------

### Registering Policies

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/authentication-and-authorization.md

Policies must be registered in the boot method of the AuthServiceProvider.

```php
public function boot()
{
    Gate::policy(Post::class, PostPolicy::class);
    Gate::policy(Comment::class, CommentPolicy::class);
}
```

--------------------------------

### Implement Authenticate Middleware

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/middleware.md

Verify user authentication status and return a 401 response if unauthorized.

```php
namespace App\Http\Middleware;

use Closure;
use Illuminate\Contracts\Auth\Factory as Auth;

class Authenticate
{
    /**
     * The authentication guard factory instance.
     *
     * @var \Illuminate\Contracts\Auth\Factory
     */
    protected $auth;

    /**
     * Create a new middleware instance.
     *
     * @param  \Illuminate\Contracts\Auth\Factory  $auth
     * @return void
     */
    public function __construct(Auth $auth)
    {
        $this->auth = $auth;
    }

    /**
     * Handle an incoming request.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Closure  $next
     * @param  string|null  $guard
     * @return mixed
     */
    public function handle($request, Closure $next, $guard = null)
    {
        if ($this->auth->guard($guard)->guest()) {
            return response('Unauthorized.', 401);
        }

        return $next($request);
    }
}
```

--------------------------------

### Configure Server Cron and Scheduler Commands

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/console-and-scheduling.md

Add the scheduler to the system crontab or execute manual commands for testing and listing tasks.

```bash
* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1
```

```bash
php artisan schedule:run
php artisan schedule:test
php artisan schedule:list
```

--------------------------------

### Configure Cache Driver in Code

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/caching-and-sessions.md

Update the cache configuration dynamically at runtime.

```php
config(['cache.default' => 'redis']);
```

--------------------------------

### Configure Session Middleware

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/caching-and-sessions.md

Enabling session support by uncommenting the required middleware in bootstrap/app.php.

```php
// $app->middleware([
//     \Illuminate\Session\Middleware\StartSession::class,
//     \Illuminate\View\Middleware\ShareErrorsFromSession::class,
// ]);
```

--------------------------------

### Create HTTP Responses with Helpers

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/request-and-response.md

Use the global response() helper to generate various response types including plain text, JSON, files, and streams.

```php
// Create response
response('Hello World');
response('Hello World', 200);
response('Hello World', 200, ['X-Custom-Header' => 'value']);

// Create JSON response
response()->json(['name' => 'John', 'age' => 30]);
response()->json($data, 200, $headers);

// Create with content type
response('<?xml version="1.0"?><data></data>', 200, [
    'Content-Type' => 'application/xml',
]);

// Redirect response
response()->redirect('/destination');
response()->redirectTo('/destination');
response()->back();

// File download
response()->download('/path/to/file.pdf');
response()->download('/path/to/file.pdf', 'custom-name.pdf');

// Stream response
response()->stream(function () {
    echo "data: event1\n\n";
    echo "data: event2\n\n";
    flush();
});

// Empty response
response('', 204); // No content
response('', 304); // Not modified
```

--------------------------------

### Register Regular Bindings

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/service-providers.md

Registers a service that creates a new instance every time it is resolved.

```php
$app->bind('service', function ($app) {
    return new MyService();
});

// Usage
$service1 = app('service');
$service2 = app('service');
// $service1 !== $service2 (different instances)
```

--------------------------------

### Implement File Processing Job

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/jobs-and-queues.md

Demonstrates handling file storage, processing, and failure logging with retry limits.

```php
class ProcessUploadedFile extends Job
{
    protected $filePath;
    protected $userId;

    public function __construct($filePath, $userId)
    {
        $this->filePath = $filePath;
        $this->userId = $userId;
    }

    public $tries = 3;
    public $timeout = 3600;

    public function handle()
    {
        $file = Storage::get($this->filePath);
        
        // Process file
        $result = $this->process($file);

        // Store result
        Storage::put("processed/{$this->userId}.json", json_encode($result));

        // Notify user
        event(new FileProcessed($this->userId, $result));
    }

    public function failed(Throwable $exception)
    {
        Log::error("File processing failed for user {$this->userId}: " . $exception->getMessage());
    }
}
```

--------------------------------

### Implementing RESTful Controller Methods

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/routing-and-controllers.md

Standard method signatures for handling RESTful resource operations.

```php
class ResourceController extends Controller
{
    // GET /resources - List all
    public function index() {}

    // GET /resources/create - Show creation form
    public function create() {}

    // POST /resources - Store new resource
    public function store(Request $request) {}

    // GET /resources/{id} - Show single resource
    public function show($id) {}

    // GET /resources/{id}/edit - Show edit form
    public function edit($id) {}

    // PUT/PATCH /resources/{id} - Update resource
    public function update(Request $request, $id) {}

    // DELETE /resources/{id} - Delete resource
    public function destroy($id) {}
}
```

--------------------------------

### Register Singleton Bindings

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/service-providers.md

Registers a service that returns the same instance across the application lifecycle.

```php
$app->singleton('service', function ($app) {
    return new MyService();
});

// Or using class name
$app->singleton(MyService::class);

// Usage
$service1 = app('service');
$service2 = app('service');
// $service1 === $service2 (same instance)
```

--------------------------------

### Configure Mass Assignment

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/models-and-eloquent.md

Shows how to use $fillable and $guarded properties to control mass assignment, along with creation and update methods.

```php
// Use $fillable to whitelist attributes
protected $fillable = ['title', 'content', 'author_id'];

// Create with mass assignment
$post = Post::create([
    'title' => 'Title',
    'content' => 'Content',
    'author_id' => 1,
]);

// Update with mass assignment
$post->update([
    'title' => 'New Title',
    'content' => 'New Content',
]);

// Use $guarded to blacklist attributes
protected $guarded = ['id', 'created_at', 'updated_at'];

// Fill method (doesn't save)
$post->fill(['title' => 'New Title']);
```

--------------------------------

### Configuring Job Properties

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/jobs-and-queues.md

Define queue, retry, timeout, and connection settings directly within the job class.

```php
class ProcessOrder extends Job
{
    // Specify which queue to use
    public $queue = 'orders';

    // Number of times to retry on failure
    public $tries = 3;

    // Job timeout in seconds
    public $timeout = 3600;

    // Connection to use
    public $connection = 'redis';

    // Delay before job runs
    protected $delay = 60;

    public function __construct(Order $order)
    {
        $this->order = $order;
    }

    public function handle()
    {
        // Process job
    }
}
```

--------------------------------

### Access Environment Variables and Application State

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/helpers-and-utilities.md

Use env() to retrieve environment variables and App::environment() to check the current application environment.

```php
// Get environment variable
env('APP_ENV');              // Returns 'local', 'production', etc.
env('APP_DEBUG', false);     // With default value
env('DB_HOST');              // Database host

// Check environment
App::environment('production');
App::environment('local', 'testing');
```

--------------------------------

### Implement Model Lifecycle Events

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/models-and-eloquent.md

Hooks into model events within the booting method to execute logic during creation, update, or deletion.

```php
class Post extends Model
{
    // Before/after creating
    protected static function booting()
    {
        static::creating(function ($post) {
            // Before insert
            $post->slug = Str::slug($post->title);
        });

        static::created(function ($post) {
            // After insert
            Log::info("Post {$post->id} created");
        });

        // Before/after updating
        static::updating(function ($post) {
            // Before update
        });

        static::updated(function ($post) {
            // After update
        });

        // Before/after saving (both create and update)
        static::saving(function ($post) {
            // Before save
        });

        static::saved(function ($post) {
            // After save
        });

        // Before/after deleting
        static::deleting(function ($post) {
            // Before delete
        });

        static::deleted(function ($post) {
            // After delete
        });
    }
}
```

--------------------------------

### Define Basic HTTP Routes

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/routing-and-controllers.md

Register routes for various HTTP methods using the $router instance.

```php
// GET request
$router->get('/path', 'ControllerName@methodName');
$router->get('/', function () {
    return 'Hello World';
});

// POST request
$router->post('/users', 'UserController@store');

// PUT request
$router->put('/users/{id}', 'UserController@update');

// PATCH request
$router->patch('/users/{id}', 'UserController@patch');

// DELETE request
$router->delete('/users/{id}', 'UserController@destroy');

// Multiple methods
$router->match(['get', 'post'], '/search', 'SearchController@handle');

// All methods
$router->any('/catch-all', function () {
    return 'Matches any HTTP method';
});
```

--------------------------------

### Implementing Job Lifecycle Methods

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/jobs-and-queues.md

Define custom logic for job failures, retry conditions, and backoff intervals.

```php
class ProcessOrder extends Job
{
    public function handle()
    {
        // Job logic
    }

    // Called if job fails all retries
    public function failed(Exception $exception)
    {
        // Handle failure
        Log::error('Job failed: ' . $exception->getMessage());
    }

    // Determine if job should be retried
    public function shouldRetry(Exception $exception)
    {
        return $exception instanceof RetryableException;
    }

    // Backoff delay in seconds for retries
    public function backoff()
    {
        return [10, 20, 30]; // Wait 10s, 20s, 30s between retries
    }
}
```

--------------------------------

### Configure Cache Driver in .env

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/caching-and-sessions.md

Set the default cache driver using the CACHE_DRIVER environment variable.

```text
CACHE_DRIVER=file
# Other options: redis, memcached, database, array
```

--------------------------------

### Register Instance Bindings

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/service-providers.md

Registers an existing object instance into the container.

```php
$instance = new MyService();
$app->instance('service', $instance);
```

--------------------------------

### Create Seed Data in Seeder

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/database-migrations.md

Implement the run method to insert records or use factories to generate test data.

```php
namespace Database\Seeders;

use App\Models\User;
use Illuminate\Database\Seeder;

class UserSeeder extends Seeder
{
    /**
     * Run the database seeds.
     */
    public function run()
    {
        // Create specific user
        User::create([
            'name' => 'Admin User',
            'email' => 'admin@example.com',
            'password' => bcrypt('password'),
        ]);

        // Create multiple users
        User::factory(10)->create();

        // Create with specific attributes
        User::factory(5)
            ->state(['role' => 'admin'])
            ->create();
    }
}
```

--------------------------------

### Create Custom Artisan Command

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/console-and-scheduling.md

Extend the base Command class to define custom console commands with signatures, descriptions, and execution logic.

```php
namespace App\Console\Commands;

use Illuminate\Console\Command;

class ProcessOrders extends Command
{
    /**
     * The name and signature of the console command.
     *
     * @var string
     */
    protected $signature = 'orders:process {--retry=5}';

    /**
     * The description of the command.
     *
     * @var string
     */
    protected $description = 'Process pending orders';

    /**
     * Execute the console command.
     *
     * @return int
     */
    public function handle()
    {
        $retry = $this->option('retry');

        $this->info('Processing orders with retry limit: ' . $retry);

        // Process orders
        Order::where('status', 'pending')
            ->take(100)
            ->each(function ($order) {
                $this->processOrder($order);
            });

        $this->info('Orders processed successfully');

        return Command::SUCCESS;
    }

    private function processOrder($order)
    {
        // Process logic here
    }
}
```

--------------------------------

### Create Custom Middleware Class

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/middleware.md

Implement a handle method to intercept requests and perform logic.

```php
namespace App\Http\Middleware;

use Closure;

class CheckVersion
{
    public function handle($request, Closure $next)
    {
        // Check API version header
        $version = $request->header('X-API-Version');
        
        if (!$version) {
            return response()->json(['error' => 'Version header required'], 400);
        }
        
        return $next($request);
    }
}
```

--------------------------------

### Access Command Input

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/console-and-scheduling.md

Retrieve arguments and options passed to the command during execution.

```php
// Get argument value
$user = $this->argument('user');
$user = $this->argument('user', 'default'); // With default

// Get all arguments
$arguments = $this->arguments();

// Get option value
$queue = $this->option('queue');

// Get all options
$options = $this->options();

// Check if option is set
if ($this->option('retry')) {
    // Option was provided
}
```

--------------------------------

### Create Custom Event with Broadcasting

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/events-and-listeners.md

A custom event class demonstrating public properties and a broadcastOn method.

```php
namespace App\Events;

use App\Models\Order;

class OrderCreated extends Event
{
    public $order;
    public $notifyCustomer;

    public function __construct(Order $order, $notifyCustomer = true)
    {
        $this->order = $order;
        $this->notifyCustomer = $notifyCustomer;
    }

    public function broadcastOn()
    {
        return ['orders'];
    }
}
```

--------------------------------

### Register Route Middleware

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/middleware.md

Define route-specific middleware aliases in bootstrap/app.php.

```php
// In bootstrap/app.php
$app->routeMiddleware([
    'auth' => App\Http\Middleware\Authenticate::class,
    'throttle' => App\Http\Middleware\Throttle::class,
    'admin' => App\Http\Middleware\IsAdmin::class,
]);
```

--------------------------------

### Event Facade Methods

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/events-and-listeners.md

Use the Event facade to dispatch, listen, check, or remove event listeners programmatically.

```php
// Fire an event
Event::dispatch(new UserCreated($user));

// Fire and wait for completion
Event::dispatchSync(new UserCreated($user));

// Listen for all events
Event::listen('*', function ($event, $data) {
    // Handle all events
});

// Listen for specific event
Event::listen(UserCreated::class, function ($event) {
    // Handle specific event
});

// Check if event has listeners
Event::hasListeners(UserCreated::class);

// Forget event listeners
Event::forget(UserCreated::class);
Event::forgetPushed();
```

--------------------------------

### Create Model Instances with Factories

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/models-and-eloquent.md

Generates test model instances, including support for bulk creation, non-persisted objects, and related models.

```php
// Create single instance
$post = Post::factory()->create([
    'title' => 'Test Post',
]);

// Create multiple
$posts = Post::factory(5)->create();

// Create without saving
$post = Post::factory()->make();

// Create with relationships
$posts = Post::factory()
    ->for(User::factory())
    ->create();
```

--------------------------------

### Define Middleware Execution Order

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/middleware.md

Illustrates how middleware groups execute in a nested order, wrapping the controller action.

```php
$router->group(['middleware' => ['auth', 'throttle', 'admin']], function ($router) {
    // Executes in order: auth -> throttle -> admin -> controller -> admin -> throttle -> auth
});
```

--------------------------------

### Response Helpers

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/request-and-response.md

Methods for creating standard HTTP responses, including plain text, JSON, file downloads, and streams.

```APIDOC
## response()

### Description
Creates a new HTTP response instance.

### Usage
- response($content, $status = 200, array $headers = [])
- response()->json($data, $status = 200, array $headers = [])
- response()->download($path, $name = null)
- response()->stream($callback)

### Parameters
- **$content** (mixed) - The response content.
- **$status** (int) - HTTP status code.
- **$headers** (array) - Custom HTTP headers.
```

--------------------------------

### Dispatch Events and Jobs

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/helpers-and-utilities.md

Trigger application events, queue background jobs, and log system activity.

```php
// Dispatch event
event(new UserCreated($user));

// Dispatch job
dispatch(new ProcessOrder($order));
dispatch(new ProcessOrder($order))->delay(30);

// Log event
Log::info('Event fired', ['event' => get_class($event)]);
```

--------------------------------

### Reset and Seed Database

Source: https://github.com/laravel/lumen/blob/10.x/_autodocs/database-migrations.md

Commands to drop all tables and re-run migrations, optionally seeding the database.

```bash
php artisan migrate:fresh          # Drop all tables and run migrations
php artisan migrate:fresh --seed   # Drop and seed
```
Tokens:
Raw