PHP/Web

Fork 0

Sky Johnson 568bd621f9 explicit input methods

2025-09-11 08:48:10 -05:00

18 KiB

Raw Blame History

Web Framework Examples

This file contains practical examples demonstrating how to use the Web framework.

Quick Start

<?php
require_once 'Web.php';

$app = new Web(debug: true);

$app->get('/', function(Context $context) {
    return 'Hello World!';
});

$app->get('/users/:id', function(Context $context, $id) {
    return ['user_id' => $id, 'name' => 'John Doe'];
});

$app->run();
?>

Web Application Examples

Basic Setup

// Create application with debug mode
$app = new Web(debug: true);

// Add global middleware
$app->use(function(Context $context, callable $next) {
    // Pre-processing
    $next();
    // Post-processing
});

// Define routes
$app->get('/path', $handler);
$app->post('/path', $handler);
$app->put('/path', $handler);
$app->patch('/path', $handler);
$app->delete('/path', $handler);
$app->head('/path', $handler);

// Route groups
$app->group('/api', function(Web $app) {
    $app->get('/users', $usersHandler);
    $app->post('/users', $createUserHandler);
});

// Custom error handlers
$app->setErrorHandler(404, function(Context $context) {
    $context->json(['error' => 'Custom 404'], 404);
});

$app->setDefaultErrorHandler(function(Context $context, int $status, string $message, ?Exception $e) {
    $context->json(['error' => $message, 'status' => $status], $status);
});

// Start the application
$app->run();

Router Examples

$router = new Router();

// Add routes with dynamic parameters
$router->get('/posts/:id', $handler);
$router->post('/users/:userId/posts/:postId', $handler);

// Perform lookup
$result = $router->lookup('GET', '/posts/123');
// Returns: ['code' => 200, 'handler' => $handler, 'params' => ['123']]

// Route patterns
'/users/:id'           // matches /users/123, /users/abc
'/posts/:slug/edit'    // matches /posts/my-post/edit
'/'                    // matches root path

Context Examples

Request Helpers

// Get input from specific sources - explicit and predictable
$name = $context->input('name', 'default');        // POST data only
$search = $context->query('search', '');           // Query params only
$data = $context->jsonValue('data', []);           // JSON body only
$id = $context->param('id', 0);                    // Route params only

// Examples with conflicting parameter names
// URL: /users/123?name=query_name
// POST: name=post_name
// JSON: {"name": "json_name"}

$routeId = $context->param('id');           // "123" from route
$queryName = $context->query('name');       // "query_name" from URL
$postName = $context->input('name');        // "post_name" from form
$jsonName = $context->jsonValue('name');    // "json_name" from JSON

// Get all input data merged from all sources (route params override all)
$all = $context->all(); 
$data = $context->only(['name', 'email']); // specific keys only
$data = $context->except(['password']); // all except specified keys

// Check if input exists (checks all sources)
if ($context->has('email')) {
    // handle email
}

// Request headers and cookies
$auth = $context->header('authorization');
$token = $context->cookie('session_token');

// Request information
$ip = $context->ip();
$userAgent = $context->userAgent();
$referer = $context->referer();
$contentType = $context->contentType();

// Request checks
if ($context->expectsJson()) {
    // return JSON response
}

if ($context->isAjax()) {
    // handle AJAX request
}

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

// URL helpers
$url = $context->url(); // full URL
$fullUrl = $context->fullUrl(); // URL with query string

// Path matching
if ($context->is('api/*')) {
    // matches API routes
}

Response Helpers

// Set status and headers
$context->status(201);
$context->setHeader('X-Custom', 'value');
$context->setCookie('name', 'value', ['expires' => time() + 3600]);

// Response content
$context->json(['message' => 'Success']); // JSON response
$context->text('Hello World'); // Plain text
$context->html('<h1>Hello</h1>'); // HTML
$context->redirect('/login'); // Redirect
$context->error(404, 'Not Found'); // Error response

// Manual response building
$context->write('Some content');
$context->write(' more content');
$context->send(); // Send response

// Or end with content
$context->end('Final content');

State Management

// Store and retrieve context state
$context->set('user', $user);
$user = $context->get('user');

Validation

// Validate request data
$validator = $context->validateRequest([
    'email' => 'required|email',
    'name' => 'required|string|min:2'
]);

// Validate any data
$validator = $context->validate($data, [
    'field' => 'required|string'
], ['field.required' => 'Custom error message']);

Request Examples

$request = new Request();

// Basic properties
$request->method;      // GET, POST, etc.
$request->uri;         // /path?query=value
$request->path;        // /path
$request->query;       // query=value
$request->body;        // raw request body

// Parsed data
$request->queryParams; // parsed query parameters
$request->postData;    // parsed POST data
$request->params;      // route parameters (set by router)

// Input methods
$value = $request->input('key', 'default');        // POST data only
$value = $request->query('key', 'default');        // Query params only
$value = $request->jsonValue('key', 'default');    // JSON body only
$value = $request->param('key', 'default');        // Route params only
$all = $request->all();                             // all input merged
$subset = $request->only(['key1', 'key2']);
$subset = $request->except(['password']);
$exists = $request->has('key');

// Headers and cookies
$auth = $request->header('authorization');
$type = $request->contentType();
$cookie = $request->cookie('session');

// JSON handling
$data = $request->json(); // decode JSON body

// Request info
$ip = $request->ip();
$agent = $request->userAgent();
$referer = $request->referer();
$secure = $request->isSecure();
$ajax = $request->isAjax();
$expectsJson = $request->expectsJson();

// URL info
$url = $request->url();
$fullUrl = $request->fullUrl();
$matches = $request->is('admin/*'); // path matching

Response Examples

$response = new Response();

// Set status and headers
$response->status(201)
         ->header('Content-Type', 'application/json')
         ->header('X-Custom', 'value');

// Content methods
$response->json($data, 201);           // JSON with status
$response->text('Hello', 200);         // Plain text
$response->html('<h1>Hi</h1>', 200);   // HTML
$response->redirect('/login', 302);     // Redirect

// Cookies
$response->cookie('name', 'value', [
    'expires' => time() + 3600,
    'path' => '/',
    'secure' => true,
    'httponly' => true,
    'samesite' => 'Strict'
]);

// Manual building
$response->write('Part 1');
$response->write('Part 2');
$response->send(); // Send to client

// Or end immediately
$response->end('Final content');

Session Examples

$session = new Session();
$session->start();

// Basic session data
$session->set('key', 'value');
$value = $session->get('key', 'default');
$exists = $session->has('key');
$session->remove('key');

// Flash messages (available only for next request)
$session->flash('success', 'Data saved!');
$message = $session->getFlash('success');
$hasMessage = $session->hasFlash('error');

// CSRF protection
$token = $session->csrfToken();
$valid = $session->validateCsrf($userToken);

// Session management
$session->regenerate();  // Regenerate session ID
$session->destroy();     // Destroy session completely
$session->clear();       // Clear data but keep session active
$all = $session->all();  // Get all session data

Validation Examples

$validator = new Validator();

// Validate data
$isValid = $validator->validate($data, [
    'email' => 'required|email',
    'password' => 'required|min:8',
    'age' => 'integer|between:18,120',
    'tags' => 'array',
    'website' => 'url',
    'role' => 'in:admin,user,moderator'
], [
    'email.required' => 'Email is mandatory',
    'password.min' => 'Password must be at least 8 characters'
]);

// Check results
if ($validator->failed()) {
    $errors = $validator->errors();
    $firstError = $validator->firstError();
    $fieldError = $validator->firstError('email');
}

// Custom validation rules
Validator::extend('custom', function($value, $parameters, $data) {
    return $value === 'custom_value';
});

Authentication Examples

$auth = new Auth($session, [
    'cookie_name' => 'remember_token',
    'cookie_lifetime' => 2592000, // 30 days
    'cookie_secure' => true
]);

// Authentication
$auth->login($userData, $remember = false);
$auth->loginUser($userObject, $remember = false);
$auth->logout();

// User checks
$isAuthenticated = $auth->check();
$isGuest = $auth->guest();
$user = $auth->user();
$userId = $auth->id();

// Password handling
$hash = $auth->hashPassword('password');
$valid = $auth->verifyPassword('password', $hash);

// Manual user data management
$auth->setUserData($userData);
$auth->clear(); // Clear all auth data

User Model Examples

$user = new User([
    'id' => 1,
    'username' => 'john',
    'email' => 'john@example.com',
    'role' => 'admin'
]);

// Properties
$user->id;
$user->username;
$user->email;
$user->role;

// Methods
$identifier = $user->getIdentifier(); // email or username
$id = $user->getId();
$array = $user->toArray();           // with all data
$safe = $user->toSafeArray();        // without sensitive data

Auth Middleware Examples

$authMiddleware = new AuthMiddleware($auth);

// Require authentication
$app->use($authMiddleware->requireAuth());

// Require guest (not authenticated)
$app->use($authMiddleware->requireGuest());

// Optional authentication
$app->use($authMiddleware->optional());

// Role-based access
$app->use($authMiddleware->requireRole('admin'));
$app->use($authMiddleware->requireRole(['admin', 'moderator']));

// Rate limiting
$app->use($authMiddleware->rateLimit(maxAttempts: 60, decayMinutes: 1));

// CSRF protection
$app->use($authMiddleware->verifyCsrf());

// Remember token handling
$app->use($authMiddleware->remember());

Error Handling Examples

$errorHandler = new ErrorHandler(debug: true);

// Register custom error handlers
$errorHandler->register(404, function(Context $context, int $status, string $message) {
    $context->json(['error' => 'Custom not found'], 404);
});

$errorHandler->setDefaultHandler(function(Context $context, int $status, string $message, ?Exception $e) {
    $context->json(['error' => $message, 'code' => $status], $status);
});

// Handle errors manually
$errorHandler->handle($context, 500, 'Server Error', $exception);
$errorHandler->handleException($context, $exception);

// Custom exceptions
throw new HttpException(422, 'Unprocessable Entity');
throw new ValidationException($validator->errors(), 'Validation failed');

Middleware Examples

// Basic middleware
$app->use(function(Context $context, callable $next) {
    // Pre-processing
    $start = microtime(true);
    
    $next(); // Call next middleware/handler
    
    // Post-processing
    $duration = microtime(true) - $start;
    $context->setHeader('X-Response-Time', $duration . 'ms');
});

// Conditional middleware
$app->use(function(Context $context, callable $next) {
    if ($context->is('api/*')) {
        $context->setHeader('Content-Type', 'application/json');
    }
    $next();
});

// Logging middleware
$app->use(function(Context $context, callable $next) {
    $method = $context->request->method;
    $path = $context->request->path;
    $ip = $context->ip();
    
    error_log("[$method] $path from $ip");
    $next();
});

// CORS middleware
$app->use(function(Context $context, callable $next) {
    $context->setHeader('Access-Control-Allow-Origin', '*');
    $context->setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
    $context->setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
    
    if ($context->request->method === 'OPTIONS') {
        $context->status(200)->send();
        return;
    }
    
    $next();
});

Route Handler Examples

// Simple handler
$app->get('/hello', function(Context $context) {
    return 'Hello World!';
});

// Handler with parameters
$app->get('/users/:id/posts/:slug', function(Context $context, $userId, $slug) {
    return [
        'user_id' => $userId,
        'post_slug' => $slug,
        'data' => $context->all()
    ];
});

// Handler return types
$app->get('/json', fn($context) => ['key' => 'value']);     // Auto JSON
$app->get('/text', fn($context) => 'Plain text');          // Auto text
$app->get('/response', fn($context) => $context->json([])); // Manual response

// Complex handler with validation
$app->post('/users', function(Context $context) {
    $context->validateRequest([
        'name' => 'required|string|min:2',
        'email' => 'required|email',
        'age' => 'integer|min:18'
    ]);
    
    $userData = $context->only(['name', 'email', 'age']);
    
    // Save user logic here
    $userId = saveUser($userData);
    
    return [
        'message' => 'User created successfully',
        'user_id' => $userId
    ];
});

// File upload handler
$app->post('/upload', function(Context $context) {
    if (!isset($_FILES['file'])) {
        $context->error(400, 'No file uploaded');
        return;
    }
    
    $file = $_FILES['file'];
    
    if ($file['error'] !== UPLOAD_ERR_OK) {
        $context->error(400, 'Upload failed');
        return;
    }
    
    // Handle file upload logic
    $filename = handleFileUpload($file);
    
    return ['filename' => $filename];
});

Complete Application Example

<?php
require_once 'Web.php';
require_once 'auth/Auth.php';
require_once 'auth/AuthMiddleware.php';

$app = new Web(debug: true);

// Setup auth
$auth = new Auth($app->context->session);
$authMiddleware = new AuthMiddleware($auth);

// Global middleware
$app->use(function(Context $context, callable $next) {
    $context->setHeader('X-Framework', 'Web');
    $next();
});

// Auth routes
$app->post('/login', function(Context $context) use ($auth) {
    $context->validateRequest([
        'email' => 'required|email',
        'password' => 'required|min:6'
    ]);
    
    $email = $context->input('email');
    $password = $context->input('password');
    
    // Verify credentials externally, then login
    if (verifyCredentials($email, $password)) {
        $userData = getUserData($email);
        $auth->login($userData, $context->input('remember'));
        return ['message' => 'Logged in successfully'];
    }
    
    $context->error(401, 'Invalid credentials');
});

$app->post('/logout', function(Context $context) use ($auth) {
    $auth->logout();
    return ['message' => 'Logged out'];
});

// Protected routes
$app->group('/api', function(Web $app) use ($authMiddleware) {
    $app->use($authMiddleware->requireAuth());
    $app->use($authMiddleware->rateLimit(100, 1));
    
    $app->get('/profile', function(Context $context) {
        return $context->get('user')->toSafeArray();
    });
    
    $app->put('/profile', function(Context $context) {
        $context->validateRequest([
            'name' => 'required|string|min:2',
            'email' => 'required|email'
        ]);
        
        // Update profile logic here
        return ['message' => 'Profile updated'];
    });
    
    $app->get('/posts', function(Context $context) {
        $page = $context->input('page', 1);
        $limit = $context->input('limit', 10);
        
        // Get posts with pagination
        $posts = getPosts($page, $limit);
        
        return [
            'posts' => $posts,
            'pagination' => [
                'page' => $page,
                'limit' => $limit
            ]
        ];
    });
    
    $app->post('/posts', function(Context $context) {
        $context->validateRequest([
            'title' => 'required|string|min:5',
            'content' => 'required|string|min:10',
            'tags' => 'array'
        ]);
        
        $postData = $context->only(['title', 'content', 'tags']);
        $postData['user_id'] = $context->get('user')->id;
        
        $postId = createPost($postData);
        
        return [
            'message' => 'Post created successfully',
            'post_id' => $postId
        ];
    });
});

// Admin routes
$app->group('/admin', function(Web $app) use ($authMiddleware) {
    $app->use($authMiddleware->requireRole('admin'));
    
    $app->get('/users', function(Context $context) {
        return ['users' => getAllUsers()];
    });
    
    $app->delete('/users/:id', function(Context $context, $userId) {
        deleteUser($userId);
        return ['message' => 'User deleted successfully'];
    });
    
    $app->get('/stats', function(Context $context) {
        return [
            'total_users' => getUserCount(),
            'total_posts' => getPostCount(),
            'active_sessions' => getActiveSessionCount()
        ];
    });
});

// Public API routes
$app->group('/public', function(Web $app) {
    $app->get('/posts', function(Context $context) {
        $posts = getPublicPosts();
        return ['posts' => $posts];
    });
    
    $app->get('/posts/:id', function(Context $context, $postId) {
        $post = getPublicPost($postId);
        if (!$post) {
            $context->error(404, 'Post not found');
            return;
        }
        return ['post' => $post];
    });
});

// Error handlers
$app->setErrorHandler(404, function(Context $context) {
    if ($context->expectsJson()) {
        $context->json(['error' => 'Endpoint not found'], 404);
    } else {
        $context->html('<h1>Page Not Found</h1>', 404);
    }
});

$app->setErrorHandler(429, function(Context $context) {
    $context->json([
        'error' => 'Rate limit exceeded',
        'message' => 'Please slow down your requests'
    ], 429);
});

$app->run();
?>

Testing Examples

// Simple test setup
function testRoute($method, $path, $data = []) {
    $_SERVER['REQUEST_METHOD'] = $method;
    $_SERVER['REQUEST_URI'] = $path;
    
    if ($method === 'POST' && $data) {
        $_POST = $data;
    }
    
    $app = new Web();
    // Setup your routes...
    
    ob_start();
    $app->run();
    $output = ob_get_clean();
    
    return $output;
}

// Test examples
$response = testRoute('GET', '/api/users');
$response = testRoute('POST', '/api/users', ['name' => 'John', 'email' => 'john@example.com']);

18 KiB Raw Blame History

Web Framework Examples

Quick Start

Web Application Examples

Basic Setup

Router Examples

Context Examples

Request Helpers

Response Helpers

State Management

Validation

Request Examples

Response Examples

Session Examples

Validation Examples

Authentication Examples

User Model Examples

Auth Middleware Examples

Error Handling Examples

Middleware Examples

Route Handler Examples

Complete Application Example

Testing Examples

18 KiB

Raw Blame History