HTTP Requests

ZephyrPHP provides a powerful, user-friendly Request class for handling all incoming HTTP request data including input, files, headers, and more.

Accessing the Request

Access the current request instance in multiple ways:

use ZephyrPHP\Core\Http\Request;

// In a controller (via $this->request)
public function store()
{
    $name = $this->request->input('name');
}

// Get singleton instance
$request = Request::getInstance();

// Capture current request
$request = Request::capture();

// Using helper function
$name = request('name');

Retrieving Input

Basic Input

// Get all input (query + post + json merged)
$all = $request->all();

// Get specific input with default
$name = $request->input('name');
$email = $request->input('email', 'default@example.com');

// Using dot notation for nested values
$street = $request->get('address.street');

// Get query string parameters only
$page = $request->query('page', 1);
$allQuery = $request->query();

// Get POST data only
$data = $request->post('data');
$allPost = $request->post();

Input Filtering

// Get only specific keys
$credentials = $request->only(['email', 'password']);

// Get all except specific keys
$data = $request->except(['_token', '_method']);

// Collect inputs into array
$userData = $request->collect(['name', 'email', 'phone']);

Checking Input Existence

// Check if input exists (may be empty)
if ($request->has('name')) { }

// Check if multiple keys exist
if ($request->has(['email', 'password'])) { }

// Check if any key exists
if ($request->hasAny(['email', 'phone'])) { }

// Check if input exists and is not empty
if ($request->filled('name')) { }

// Check if input is missing
if ($request->missing('optional_field')) { }

// Conditional callbacks
$request->whenFilled('email', function ($email) {
    // Do something with email
}, function () {
    // Email was empty
});

$request->whenHas('callback_url', function ($url) {
    // Process callback URL
});

Input Casting

Cast input values to specific types automatically:

// String
$name = $request->string('name');
$name = $request->string('name', 'Anonymous');

// Integer
$page = $request->integer('page');
$page = $request->integer('page', 1);

// Float
$price = $request->float('price');
$price = $request->float('price', 0.00);

// Boolean (handles 'true', '1', 'yes', 'on', etc.)
$remember = $request->boolean('remember');
$active = $request->boolean('active', false);

// Array (handles JSON strings and comma-separated values)
$tags = $request->array('tags');
$ids = $request->array('ids', []);

// Date
$date = $request->date('published_at');
$date = $request->date('event_date', 'Y-m-d');
$date = $request->date('meeting_time', 'H:i', 'America/New_York');

// Enum (PHP 8.1+)
$status = $request->enum('status', OrderStatus::class);
$priority = $request->enum('priority', Priority::class, Priority::Normal);

Sanitized Input

// Get sanitized input by type
$email = $request->sanitized('email', 'email');
$id = $request->sanitized('id', 'integer');
$url = $request->sanitized('website', 'url');
$slug = $request->sanitized('slug', 'slug');
$name = $request->sanitized('name', 'string');
$price = $request->sanitized('price', 'float');

File Uploads

Handle file uploads with the UploadedFile class:

// Check if file was uploaded
if ($request->hasFile('avatar')) {
    $file = $request->file('avatar');
}

// Get single file
$file = $request->file('document');

// Get all uploaded files
$files = $request->allFiles();

UploadedFile Methods

$file = $request->file('avatar');

// File information
$file->getClientOriginalName();     // 'photo.jpg'
$file->getClientOriginalExtension(); // 'jpg'
$file->getMimeType();               // 'image/jpeg'
$file->guessExtension();            // 'jpg' (from MIME)
$file->getSize();                   // 1024 (bytes)
$file->path();                      // temporary path
$file->getContent();                // file contents

// Validation
$file->isValid();                   // true if uploaded successfully
$file->isImage();                   // true if image file
$file->getError();                  // upload error code
$file->getErrorMessage();           // human-readable error

// Image dimensions (if image)
$dimensions = $file->dimensions();
// ['width' => 800, 'height' => 600]

// Moving files
$path = $file->move('/uploads/avatars');
$path = $file->move('/uploads/avatars', 'custom-name.jpg');

// Store with generated hash name
$path = $file->store('/uploads/documents');

// Store with specific name
$path = $file->storeAs('/uploads/documents', 'report.pdf');

// Generate hash name
$hashName = $file->hashName(); // 'a3f2c1b5...'

Headers & Cookies

Headers

// Get all headers
$headers = $request->headers();

// Get specific header
$contentType = $request->header('Content-Type');
$accept = $request->header('Accept', 'text/html');

// Check header exists
if ($request->hasHeader('Authorization')) { }

// Get bearer token from Authorization header
$token = $request->bearerToken();

// Get basic auth credentials
$user = $request->getUser();
$pass = $request->getPassword();

Cookies

// Get cookie
$theme = $request->cookie('theme');
$language = $request->cookie('language', 'en');

// Check cookie exists
if ($request->hasCookie('session_id')) { }

// Get all cookies
$cookies = $request->cookies();

HTTP Method

// Get HTTP method
$method = $request->method();
$method = $request->getMethod();

// Get real method (before spoofing)
$realMethod = $request->getRealMethod();

// Check method
if ($request->isMethod('POST')) { }
if ($request->isGet()) { }
if ($request->isPost()) { }
if ($request->isPut()) { }
if ($request->isPatch()) { }
if ($request->isDelete()) { }
if ($request->isOptions()) { }
if ($request->isHead()) { }

URL & Path

// Current URL
$url = $request->url();           // '/users?page=1'
$path = $request->path();          // '/users'
$decoded = $request->decodedPath(); // URL decoded path

// Full URL
$full = $request->fullUrl();       // 'https://example.com/users?page=1'

// Modify URL with query parameters
$url = $request->fullUrlWithQuery(['sort' => 'name']);
$url = $request->fullUrlWithoutQuery(['page']);

// URL parts
$root = $request->root();          // 'https://example.com'
$scheme = $request->getScheme();   // 'https'
$host = $request->getHost();       // 'example.com'
$port = $request->getPort();       // 443

// Check HTTPS
if ($request->isSecure()) { }

// Path segments
$segments = $request->segments();  // ['users', '123', 'edit']
$first = $request->segment(1);     // 'users'
$second = $request->segment(2);    // '123'

// Check path pattern
if ($request->is('admin/*')) {
    // On admin page
}

if ($request->is('/users', '/users/*')) {
    // On users page
}

// Check route name
if ($request->routeIs('users.*')) {
    // On a users route
}

// Get previous URL (referer)
$previous = $request->previousUrl();

JSON Requests

// Check if JSON request
if ($request->isJson()) {
    // Content-Type is JSON
}

// Get JSON payload
$data = $request->json();
$name = $request->json('user.name');
$email = $request->json('user.email', 'default@example.com');

// Check if expects JSON response
if ($request->expectsJson()) {
    return Response::json($data);
}

if ($request->wantsJson()) {
    return Response::json($data);
}

Content Negotiation

// Get acceptable content types
$types = $request->getAcceptableContentTypes();

// Check if accepts content type
if ($request->accepts('application/json')) {
    return Response::json($data);
}

if ($request->accepts(['text/html', 'application/json'])) {
    // Accepts either
}

// Check preferred format
if ($request->prefersJson()) {
    return Response::json($data);
}

if ($request->prefersHtml()) {
    return view('page');
}

// Get preferred format
$format = $request->format('html'); // 'html', 'json', 'xml', 'txt'

AJAX & Special Requests

// Check AJAX request
if ($request->isAjax()) { }
if ($request->ajax()) { }

// Check PJAX request
if ($request->isPjax()) { }

// Check prefetch request
if ($request->isPrefetch()) { }

Client Information

// Get client IP (handles proxies, Cloudflare, etc.)
$ip = $request->ip();

// Get all IPs in forward chain
$ips = $request->ips();

// Get user agent
$userAgent = $request->userAgent();

// Generate request fingerprint (unique hash)
$fingerprint = $request->fingerprint();

Route Parameters

// Get all route parameters
$params = $request->route();

// Get specific route parameter
$id = $request->route('id');
$slug = $request->route('slug', 'default');

Old Input (Flash)

Flash input to session for form repopulation:

// Flash all input
$request->flash();

// Flash only specific keys
$request->flashOnly(['email', 'name']);

// Flash all except specific keys (don't flash passwords!)
$request->flashExcept(['password', 'credit_card']);

// Get old input (in next request)
$email = $request->old('email');
$name = $request->old('name', 'Guest');

// Clear old input
$request->flushOld();

In Twig templates:

<input type="text" name="email" value="{{ old('email') }}">

CSRF Validation

// Validate CSRF token
if (!$request->validateCSRFToken()) {
    abort(419, 'CSRF token mismatch');
}

Input Transformation

// Merge data into request
$request->merge(['processed' => true]);

// Merge only if missing
$request->mergeIfMissing(['status' => 'pending']);

// Replace all input
$request->replace($newData);

Debugging

// Dump request info
$info = $request->dump();
/*
Returns: [
    'method' => 'POST',
    'url' => 'https://example.com/users',
    'path' => '/users',
    'query' => [...],
    'post' => [...],
    'json' => [...],
    'headers' => [...],
    'cookies' => [...],
    'files' => [...],
    'ip' => '192.168.1.1',
    'userAgent' => 'Mozilla/5.0...'
]
*/

// Convert to array
$array = $request->toArray();

Complete Example

<?php

namespace App\Controllers;

use ZephyrPHP\Core\Controllers\Controller;
use ZephyrPHP\Core\Http\Response;

class UserController extends Controller
{
    public function store()
    {
        // Validate CSRF
        if (!$this->request->validateCSRFToken()) {
            return Response::forbidden('Invalid CSRF token');
        }

        // Check required fields
        if (!$this->request->filled(['name', 'email', 'password'])) {
            $this->request->flash();
            return $this->backWithErrors(['error' => 'All fields are required']);
        }

        // Get typed input
        $name = $this->request->string('name');
        $email = $this->request->sanitized('email', 'email');
        $age = $this->request->integer('age', 0);
        $subscribe = $this->request->boolean('newsletter');

        // Handle file upload
        if ($this->request->hasFile('avatar')) {
            $file = $this->request->file('avatar');

            if ($file->isValid() && $file->isImage()) {
                $path = $file->store('/uploads/avatars');
            }
        }

        // Create user...

        // Return appropriate response
        if ($this->request->expectsJson()) {
            return Response::created(['user' => $user]);
        }

        $this->flash('success', 'User created!');
        return $this->redirect('/users');
    }
}

Method Reference