Http Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require nette/http
   

   Requires PHP 8.3+ (check your runtime).

2. Basic Request/Response Usage

   use Nette\Http\Request;
   use Nette\Http\Response;
   
   $request = Request::createFromGlobals();
   $response = new Response();
   
   // Get a GET parameter
   $name = $request->getQuery('name');
   
   // Set a cookie
   $response->setCookie('user', 'JohnDoe', [
       'expire' => '2025-01-01',
       'sameSite' => SameSite::LAX,
   ]);
   

3. First Use Case: Secure File Upload

   if ($request->getMethod() === 'POST' && $request->hasFile('avatar')) {
       $upload = $request->getFile('avatar');
       $sanitizedName = $upload->getSanitizedName(); // Safe filename
       $upload->moveTo(__DIR__ . "/uploads/{$sanitizedName}");
   }
   

Where to Look First

• Request: Nette\Http\Request – Handles HTTP requests, form data, files, and headers.
• Response: Nette\Http\Response – Manages cookies, redirects, and headers.
• URL Handling: Nette\Http\Url – Immutable URL manipulation with validation.
• SSRF Protection: Nette\Http\UrlValidator – Validate URLs before making external requests.

Implementation Patterns

1. Request Handling Workflow

// Middleware-like request processing
$request = Request::createFromGlobals();
$response = new Response();

// Validate SSRF (e.g., for external API calls)
$validator = new UrlValidator();
$validator->setAllowedSchemes(['https']);
$validator->setAllowedHosts(['api.example.com']);
$url = new Url('https://api.example.com/data');
if (!$validator->validate($url)) {
    throw new \RuntimeException('Invalid URL');
}

// Process form data
if ($request->isMethod('POST')) {
    $data = $request->getPost();
    // Sanitize/validate $data...
}

// Handle file uploads
if ($request->hasFile('document')) {
    $file = $request->getFile('document');
    $file->moveTo(__DIR__ . "/uploads/{$file->getSanitizedName()}");
}

2. Session Management

use Nette\Http\SessionSection;

// Start session (auto-start disabled by default in v3.x)
$session = new Session();
$session->start();

// Use sections for organized data
$userData = $session->getSection('user');
$userData->name = 'Alice';
$userData->preferences = ['theme' => 'dark'];

// Read data
$name = $userData->name;

// Destroy session (e.g., on logout)
$session->destroy();

3. URL Generation and Validation

// Immutable URL creation
$url = new Url('https://example.com/path?query=value');

// Validate before external requests (SSRF protection)
$validator = new UrlValidator();
$validator->setAllowedSchemes(['https']);
$validator->setAllowedHosts(['api.trusted.com']);
$validator->setBlockedPorts([80, 443]); // Block HTTP/HTTPS ports

if (!$validator->validate($url)) {
    throw new \RuntimeException('URL blocked by security rules');
}

// Generate relative URLs
$baseUrl = new Url('/app');
$relativeUrl = $baseUrl->setPath('/dashboard')->getAbsoluteUrl();

4. Cookie Handling with Modern Standards

$response = new Response();
$response->setCookie('auth_token', 'abc123', [
    'expire' => '2025-01-01', // Absolute expiry (recommended over seconds)
    'sameSite' => SameSite::STRICT, // Type-safe enum
    'secure' => true, // Auto-set if SameSite=None
    'partitioned' => true, // CHIPS support for third-party cookies
]);

5. Integration with Laravel

Leverage nette/http alongside Laravel’s built-in request/response objects:

use Illuminate\Http\Request as LaravelRequest;
use Nette\Http\Request as NetteRequest;

// Convert Laravel request to Nette request (for advanced features)
$netteRequest = NetteRequest::createFromGlobals(
    $_GET,
    $_POST,
    [],
    $_COOKIE,
    $_FILES,
    $_SERVER
);

// Use Nette's SSRF validator for external API calls
$validator = new UrlValidator();
$validator->setAllowedHosts(['api.laravel.com']);
$url = new Url('https://api.laravel.com/data');
if (!$validator->validate($url)) {
    abort(403, 'Forbidden');
}

Gotchas and Tips

Pitfalls

1. Deprecated Methods

   • Request::getRemoteHost() returns null (use getRemoteAddress() + manual DNS resolution if needed).
   • Request::isSameSite() is deprecated; use isFrom() for same-site detection.
   • UserStorage is removed; use Laravel’s session or Nette\Http\Session.

2. Cookie Quirks

   • SameSite enum is required (no more magic strings). Typos will cause runtime errors.
   • expire in setCookie() now uses DateTimeInterface or strings (e.g., '2025-01-01'). Avoid 0 (use null for session cookies).
   • Secure flag is auto-set if SameSite=None (no manual configuration needed).

3. URL Handling

   • Url::getUser()/getPassword() are deprecated. Use getBasicCredentials() instead.
   • Url::canonicalize() no longer encodes ". Use UrlImmutable for immutable operations.

4. Session Gotchas

   • autoStart defaults to false (v3.x). Explicitly call $session->start().
   • SessionSection no longer supports ArrayAccess or magic methods (use set()/get()).

5. SSRF Misconfigurations

   • Always pair UrlValidator with IPAddress for IP-range checks:

     $validator = new UrlValidator();
     $validator->setIpValidator(new IPAddress('192.168.1.0/24')); // Allow only private IPs
     

Debugging Tips

1. Request Inspection

   dump($request->getHeaders()); // All headers
   dump($request->getQueryParams()); // GET params
   dump($request->getPostParams()); // POST data
   

2. Cookie Debugging

   • Use Response::getCookieParams('cookie_name') to inspect existing cookies.
   • Check SameSite and Secure flags in browser dev tools (Network tab).

3. URL Validation

   • Test UrlValidator with edge cases:

     $validator = new UrlValidator();
     $validator->setAllowedSchemes(['https']);
     $validator->setBlockedPorts([80, 443]);
     $validator->validate(new Url('http://example.com')); // Fails (scheme)
     $validator->validate(new Url('https://example.com:80')); // Fails (port)
     

4. Session Issues

   • Enable autoStart temporarily for debugging:

     $session = new Session(['autoStart' => true]);
     

   • Check session_status() if sessions behave unexpectedly.

Extension Points

1. Custom URL Validators Extend UrlValidator for domain-specific rules:

   class ApiUrlValidator extends UrlValidator {
       public function __construct() {
           $this->setAllowedHosts(['api.yourdomain.com']);
           $this->setAllowedPaths(['/v1/*']);
       }
   }
   

2. Session Handlers Replace the default session handler with a custom one (e.g., Redis):

   $session = new Session([
       'handler' => new RedisSessionHandler($redisClient),
   ]);
   

3. Request Factories Override RequestFactory to modify request creation (e.g., for proxies):

   $factory = new RequestFactory();
   $factory->setForceHttps(true); // Force HTTPS behind load balancers
   $request = $factory->createFromGlobals();
   

4. File Upload Sanitization Extend FileUpload for custom filename rules:

   class CustomFileUpload extends FileUpload {
       public function getSanitizedName(): string {
           $name = parent::getSanitizedName();
           return preg_replace('/[^a-z