|
| 1 | +<div class="position-relative p-4 text-body bg-body border rounded-4 d-flex align-items-center"> |
| 2 | + <div class="me-3"> |
| 3 | + <i class="bi bi-book h2"></i> |
| 4 | + </div> |
| 5 | + <p class="me-3 my-0"> |
| 6 | + Written by those who've walked the path. Want to improve our guides? Contribute and help build something awesome! |
| 7 | + </p> |
| 8 | + <a href="https://github.com/BlueprintFramework/web/tree/main/docs/pages/developing-extensions"> |
| 9 | + <button class="btn btn-primary px-4 rounded-pill placeholder-wave" type="button"> |
| 10 | + Contribute |
| 11 | + </button> |
| 12 | + </a> |
| 13 | +</div><br> |
| 14 | + |
| 15 | +# Creating custom web routes |
| 16 | +<h4 class="fw-light">Add your own web routes accessible from everywhere within Blueprint.</h4><br/> |
| 17 | + |
| 18 | +This guide provides a step-by-step overview on how to define custom web routes using a dedicated controller within a Blueprint extension.<br/><br/> |
| 19 | + |
| 20 | +### **Define the controller directory and routing file** |
| 21 | + |
| 22 | +Begin by creating a new directory within your extension to store your controller classes. In this example, we will use a directory named `controllers`. |
| 23 | + |
| 24 | +Next, open your `conf.yml` file and define the location of your controller directory and route file under the `requests` section. This allows Blueprint to recognize and load your custom logic. |
| 25 | + |
| 26 | +```yml |
| 27 | +requests: |
| 28 | + views: "" |
| 29 | + app: "controllers" |
| 30 | + routers: |
| 31 | + application: "" |
| 32 | + client: "" |
| 33 | + web: "routes.php" |
| 34 | +``` |
| 35 | +
|
| 36 | +- `app`: Points to the folder containing your controller classes. |
| 37 | +- `routers:web`: Defines the file responsible for registering your web routes. |
| 38 | + |
| 39 | +<div class="alert mt-2 rounded-4 border" role="alert"> |
| 40 | + <i class="bi bi-journal-text mb-1 float-start fs-4"></i> |
| 41 | + <div class="ps-3 ms-3">For more details on configuration, refer to the <a href="?page=documentation/confyml">conf.yml documentation</a>.</div> |
| 42 | +</div> |
| 43 | + |
| 44 | +Depending on your use case, you may also define routes using `routers:application` or `routers:client`. Unlike `web` routes, which are publicly accessible, even to unauthenticated users, these route types are protected: |
| 45 | + |
| 46 | +- `client`: Can only be accessed by logged in user and via API key. |
| 47 | +- `application`: Can only be accessed via API key. Exact permissions can be defined. |
| 48 | + |
| 49 | +Each route also has a different url prefix: |
| 50 | + |
| 51 | +- `application`: `/api/application/extensions/{identifier}` |
| 52 | +- `client`: `/api/client/extensions/{identifier}` |
| 53 | +- `web`: `/extensions/{identifier}` |
| 54 | + |
| 55 | + |
| 56 | +### **Creating a controller** |
| 57 | + |
| 58 | +Inside the `controllers` directory, create a PHP file named after your controller class. The file and class name **must match exactly**. |
| 59 | + |
| 60 | +In this example, we will create a controller that handles routes for the dashboard and name the file `ExtensionDashboardController.php`. |
| 61 | + |
| 62 | +```php |
| 63 | +<?php |
| 64 | +
|
| 65 | +namespace Pterodactyl\BlueprintFramework\Extensions\{identifier}; |
| 66 | +
|
| 67 | +use Pterodactyl\Http\Controllers\Controller; |
| 68 | +use Pterodactyl\BlueprintFramework\Libraries\ExtensionLibrary\Admin\BlueprintAdminLibrary as BlueprintExtensionLibrary; |
| 69 | +
|
| 70 | +class ExtensionDashboardController extends Controller |
| 71 | +{ |
| 72 | + public function __construct( |
| 73 | + private BlueprintExtensionLibrary $blueprint, |
| 74 | + ) {} |
| 75 | +
|
| 76 | + public function getData() |
| 77 | + { |
| 78 | + return response()->json([ |
| 79 | + 'status' => 'success', |
| 80 | + ]); |
| 81 | + } |
| 82 | +} |
| 83 | +``` |
| 84 | +- This controller defines a `getData()` method that returns a JSON response. |
| 85 | + |
| 86 | +<div class="alert mt-2 rounded-4 border" role="alert"> |
| 87 | + <div> |
| 88 | + <i class="bi bi-globe mb-1 float-start fs-4"></i> |
| 89 | + <div class="ps-3 ms-3">For advanced controller techniques, see the <a href="https://laravel.com/docs/10.x/controllers">Laravel controller documentation</a>.</div> |
| 90 | + </div> |
| 91 | + <div> |
| 92 | + <div class="ps-3 ms-3">For different response types (redirects, files, etc.), refer to <a href="https://laravel.com/docs/10.x/responses">Laravel HTTP responses documentation</a>.</div> |
| 93 | + </div> |
| 94 | +</div><br/> |
| 95 | + |
| 96 | +### **Registering routes** |
| 97 | + |
| 98 | +Create a PHP file named `routes.php` (or another name, as long as it matches your `conf.yml`) to define your routes. |
| 99 | + |
| 100 | +```php |
| 101 | +<?php |
| 102 | +
|
| 103 | +use Illuminate\Support\Facades\Route; |
| 104 | +use Pterodactyl\BlueprintFramework\Extensions\{identifier}\ExtensionDashboardController; |
| 105 | +
|
| 106 | +Route::get('/data', [ExtensionDashboardController::class, 'getData']); |
| 107 | +``` |
| 108 | + |
| 109 | +- All routes registered in this file are automatically prefixed with `/extensions/{identifier}`. |
| 110 | +- This example registers a new GET route accessible at `/extensions/{identifier}/data` and connects it to the `getData` function from `ExtensionDashboardController`. |
| 111 | + |
| 112 | +<div class="alert mt-2 rounded-4 border" role="alert"> |
| 113 | + <i class="bi bi-exclamation-diamond text-warning mb-1 float-start fs-4"></i> |
| 114 | + <div class="ps-3 ms-3">Be sure to update the second <code>use</code> statement to match the correct namespace and class name of your controller.</div> |
| 115 | +</div> |
| 116 | + |
| 117 | +<div class="alert mt-2 rounded-4 border" role="alert"> |
| 118 | + <i class="bi bi-globe mb-1 float-start fs-4"></i> |
| 119 | + <div class="ps-3 ms-3">For detailed route configuration, visit the <a href="https://laravel.com/docs/10.x/routing">Laravel routing documentation</a>.</div> |
| 120 | +</div><br/> |
| 121 | + |
| 122 | +<div class="btn-group docs-navigator" role="group" aria-label="Navigation" style="float: right"> |
| 123 | + <a href="?page=developing-extensions/React-components" class="btn btn-dark bg-light-subtle border-0 rounded-start-pill">Previous</a> |
| 124 | + <a href="?page=developing-extensions/Packaging-extensions" class="btn btn-dark bg-light-subtle border-0 rounded-end-pill">Next</a> |
| 125 | +</div> |
0 commit comments