HTTP Routes and Controllers

This document describes the HTTP routing and controller examples provided in the workbench environment. The workbench includes sample route definitions in workbench/routes/api.php and workbench/routes/web.php, along with the ExampleController class that demonstrates basic controller patterns. These examples serve as both testing fixtures for the testbench itself and reference implementations for package developers.

For information about defining routes in test classes using defineRoutes() and defineWebRoutes(), see HandlesRoutes Trait. For workbench structure and service provider discovery, see Workbench Structure and Discovery.

---

Workbench Route Files

The workbench environment provides route definition files that follow standard Hypervel conventions. These files are discovered automatically by the WorkbenchServiceProvider and loaded into the application during test execution.

Route File Structure

File	Purpose	Middleware Group
workbench/routes/api.php	API endpoints returning JSON responses	None (explicit prefix)
workbench/routes/web.php	Web routes with session/CSRF support	web
workbench/routes/console.php	Console command routes	N/A

The route files use the Hypervel\Support\Facades\Route facade to define HTTP endpoints. Routes defined in these files are automatically registered during application bootstrapping.

Sources: workbench/routes/api.php1-23

---

API Routes

The api.php file demonstrates basic API route patterns including successful responses and exception handling.

Defined Routes

Route: GET /api/hello

Defined at workbench/routes/api.php18-20 this route returns a simple JSON response. The closure handler returns an associative array that is automatically serialized to JSON by the framework.

['message' => 'Hello, world!']

Route: GET /api/failed

Defined at workbench/routes/api.php22 this route intentionally throws a RuntimeException to demonstrate error handling and exception response patterns in tests. This is useful for testing exception handlers and error middleware.

Sources: workbench/routes/api.php18-22

---

ExampleController

The ExampleController class provides a simple controller implementation for workbench demonstrations and testing.

Controller Structure

Namespace: Workbench\App\Http\Controllers

Location: workbench/app/Http/Controllers/ExampleController.php1-14

index Method

The index() method at workbench/app/Http/Controllers/ExampleController.php9-12 returns a simple string identifier:

'ExampleController@index'

This method can be used in tests to verify:

• Controller instantiation
• Route-to-controller mapping
• Response content assertions
• Dependency injection in controllers

Method Signature:

public function index(): string

The method takes no parameters and returns a string, making it suitable for basic routing tests without complex setup requirements.

Sources: workbench/app/Http/Controllers/ExampleController.php1-14

---

Route-Controller Integration

The workbench demonstrates how routes connect to controllers and return responses. While api.php uses closure-based routes, the ExampleController shows the controller-based pattern.

HTTP Request Flow

Testing Route Responses

Tests can verify these routes using the HTTP testing utilities provided by the testbench:

Testing Success Route:

$response = $this->get('/api/hello');
$response->assertStatus(200);
$response->assertJson(['message' => 'Hello, world!']);

Testing Exception Route:

$this->expectException(RuntimeException::class);
$this->expectExceptionMessage('Bad route!');
$this->get('/api/failed');

Sources: workbench/routes/api.php18-22 workbench/app/Http/Controllers/ExampleController.php9-12

---

Integration with TestCase

The workbench routes are loaded during the application bootstrap process initiated by TestCase. The route files are discovered by the WorkbenchServiceProvider which is automatically registered when the workbench is active.

Route Loading Process

Custom Route Definition

Tests can supplement or override workbench routes using the defineRoutes() and defineWebRoutes() methods from the HandlesRoutes trait:

Example:

protected function defineRoutes($router)
{
 $router->get('custom/endpoint', function () {
 return 'Custom response';
 });
}

This allows tests to define additional routes specific to the test case without modifying the workbench files. See HandlesRoutes Trait for complete documentation.

Sources: workbench/routes/api.php1-23 workbench/app/Http/Controllers/ExampleController.php1-14

---

Route Definition Patterns

The workbench demonstrates two common route definition patterns used in Hypervel applications:

Closure-Based Routes

Used in workbench/routes/api.php18-22 closure-based routes define the handler inline:

Advantages:

• Simple, concise syntax for basic routes
• No need for separate controller files
• Ideal for API endpoints with minimal logic

Pattern:

Route::get('path', function () {
 return ['data' => 'value'];
});

Controller-Based Routes

The ExampleController demonstrates the controller pattern:

Advantages:

• Separation of routing and business logic
• Easier to test controller methods in isolation
• Better organization for complex applications

Pattern:

Route::get('path', [ExampleController::class, 'index']);

Route Attributes Summary

Route	Method	Handler Type	Response Type	Purpose
/api/hello	GET	Closure	JSON array	Success case testing
/api/failed	GET	Closure	Exception	Error handling testing
N/A	N/A	Controller method	String	Controller pattern example

Sources: workbench/routes/api.php18-22 workbench/app/Http/Controllers/ExampleController.php9-12

---

Usage in Tests

The workbench routes and controllers serve as testing fixtures. Package developers can reference these patterns when creating their own test routes or use the existing routes for integration testing.

Example Test Usage

Testing Workbench Routes:

public function test_api_hello_returns_json()
{
 $response = $this->get('/api/hello');
 $response->assertOk();
 $response->assertJson(['message' => 'Hello, world!']);
}

Testing Exception Handling:

public function test_api_failed_throws_exception()
{
 $this->withoutExceptionHandling();
 $this->expectException(RuntimeException::class);
 $this->get('/api/failed');
}

Testing Controller Instantiation:

public function test_example_controller_can_be_instantiated()
{
 $controller = $this->app->make(ExampleController::class);
 $this->assertInstanceOf(ExampleController::class, $controller);
 $this->assertEquals('ExampleController@index', $controller->index());
}

Extending Routes for Package Tests

Package developers can add their own routes alongside the workbench routes:

In Test Class:

protected function defineWebRoutes($router)
{
 $router->get('my-package/endpoint', function () {
 return 'Package-specific route';
 });
}

This approach allows testing package-specific routing logic without modifying the shared workbench files.

Sources: workbench/routes/api.php18-22 workbench/app/Http/Controllers/ExampleController.php9-12

---

Summary

The workbench HTTP routes and controllers provide:

1. Example route definitions in api.php showing both success and error cases
2. Controller pattern demonstrated by ExampleController with a simple index() method
3. Testing fixtures for verifying HTTP functionality in the testbench
4. Reference implementations for package developers to follow

These components integrate seamlessly with the TestCase lifecycle through the WorkbenchServiceProvider and can be supplemented with custom routes using the HandlesRoutes trait methods.

Sources: workbench/routes/api.php1-23 workbench/app/Http/Controllers/ExampleController.php1-14