output()
public function output(bool $return = false): ?string
Description
Outputs the currently loaded image directly to the browser or returns the image data as a string. This method provides two modes of operation: streaming the image directly to the browser for immediate display, or capturing the image data as a binary string for further processing or storage.
When to Use output() vs. Standard <img> Tags
Use standard <img> tags in view files for:
- Displaying images that are already saved as files on disk
- Standard image galleries, product photos, user avatars
- Any scenario where you have a static image file to display
Use output() in controller methods for:
- Serving images that require on-the-fly processing (resize, crop, watermark)
- Protecting images behind authentication/authorisation checks
- Dynamic image serving based on URL parameters
- Capturing image data for APIs, PDFs, or database storage
The output() method is designed for use in controller methods only, not in view files. Your view files still use standard <img> tags that point to either static image files or controller URLs that use output().
Alternative: Interceptors for Blanket Protection: Trongate v2's Interceptors feature can protect entire directories or URL patterns before routing occurs. However, controller-based serving with output() provides more granular control, allowing per-image authorisation decisions and custom processing logic.
Set Headers First: When outputting directly to the browser (default behaviour), always set the Content-Type header using get_header() before calling output(). Without the proper header, browsers may fail to display the image correctly.
Parameters
| Parameter | Type | Description | Default | Required |
|---|---|---|---|---|
| $return | bool | If true, returns image data as a string. If false, outputs directly to browser. | false | No |
Return Value
| Type | Description |
|---|---|
| string|null | Returns binary image data as a string when $return is true. Returns null when $return is false (outputs directly to browser). |
Example #1
The code sample below demonstrates outputting an image directly to the browser.
Direct Output Pattern: When calling output() without parameters (or with false), the image is streamed directly to the browser. This is the most common use case for serving images dynamically. Always set the Content-Type header first, and avoid any other output before or after the output() call.
How This Works with View Files: In your view files, you still use standard HTML <img> tags. The src attribute points to a controller method that uses output() to serve the image:
In your view file:
<img src="<?= BASE_URL ?>gallery/serve_photo/<?= $photo_id ?>" alt="Photo">
In your controller:
public function serve_photo() { /* load image, set headers, output() */ }
The browser makes a request to your controller URL, which processes and outputs the image. This pattern is only needed when you require on-the-fly processing or access control. For static images already on disk, point src directly to the file path.
Example #2
The example above shows how to serve a dynamically resized image to the browser.
Dynamic Image Serving: This pattern is ideal for on-the-fly image processing. Instead of pre-generating multiple sizes, you can create a controller method that accepts dimensions as URL parameters and serves appropriately sized images. Add cache headers to improve performance for repeated requests.
Example #3
The example above demonstrates using the return parameter to capture image data as a string.
Capturing Image Data: When output(true) is called, the method returns the binary image data as a string instead of outputting to the browser. This is useful for embedding images in PDFs, storing in databases as BLOBs, or sending via APIs. The returned data is the complete binary image file.
Example #4
The example above shows how to create an API endpoint that returns image data in a JSON response.
API Image Delivery: When building APIs that need to include image data, use output(true) to capture the binary data, then encode it as base64 for JSON transport. The data_uri format shown above can be used directly in HTML <img> tags on the frontend.
No Additional Output: When using output() without the return parameter, ensure no other content is sent to the browser before or after the call. Any extra output (whitespace, error messages, HTML) will corrupt the image data. This includes making sure there's no output buffering elsewhere in your application that might interfere.