PHP Templates

Using PHP files in the templates directory

PHP files can be placed in the templates/ directory and are processed through the Elements template engine before being deployed. This allows you to combine Elements template directives with PHP code for server-side functionality.

Overview

PHP template files provide:

• Server-side processing - Execute PHP code on the server

• Property insertion - Use component properties in PHP code

• Template directives - Combine Elements Language with PHP

• Backend deployment - PHP files are deployed to the published site

For most server-side functionality, you should use the Backend directory which is specifically designed for PHP files that need to be deployed to the server's backend directory.

File Location

com.yourcompany.component/
├── templates/
│   ├── index.html
│   ├── handler.php        # PHP template (rare at root level)
│   └── backend/           # More common location for PHP
│       └── process.php

When to Use PHP Templates

Root-Level PHP (Uncommon)

Root-level PHP templates are processed and included in the page output. This is rarely needed, as most PHP functionality belongs in the backend directory.

Use root-level PHP when:

• You need to generate HTML with server-side logic during page rendering

• The PHP output should be part of the page's normal HTML flow

Backend PHP (Recommended)

Most PHP files should be in the templates/backend/ directory:

templates/
└── backend/
    ├── submit.php        # Form submission handler
    ├── api.php           # API endpoint
    └── process.php       # Data processing

Use backend PHP for:

• Form processing

• API endpoints

• Database operations

• Server-side data manipulation

• AJAX request handlers

See the Backend directory documentation for detailed information about backend PHP files.

Basic Usage

PHP template files can use both Elements template directives and PHP code:

<?php
// PHP variables from component properties
$componentId = '{{id}}';
$formAction = '{{formAction}}';
$maxFileSize = {{maxFileSize}};

@if(enableLogging)
// Conditional PHP
error_log("Component $componentId initialized");
@endif
?>

<form action="<?php echo $formAction; ?>" method="POST">
    <input type="hidden" name="component_id" value="{{id}}">
    <input type="hidden" name="max_size" value="{{maxFileSize}}">
    <!-- Form fields -->
</form>

Property Insertion in PHP

Insert component properties into PHP code:

<?php
// String properties
$title = '{{title}}';
$description = '{{description}}';

// Numeric properties
$maxItems = {{maxItems}};
$timeout = {{timeout}};

// Boolean properties
$isEnabled = {{enabled}};  // true or false

@if(debugMode)
// Debug information
var_dump([
    'component_id' => '{{id}}',
    'title' => $title,
    'max_items' => $maxItems
]);
@endif
?>

Processing Behavior

Template Processing First

Elements template directives are processed before PHP execution:

1. Elements processes {{property}}, @if, @each, etc.

2. Resulting PHP code is deployed to the server

3. PHP executes when the page is requested

This means you can use template directives to generate PHP code dynamically.

Backend Directory (Recommended Pattern)

The most common use case for PHP in components is form handling in the backend directory:

<!-- templates/backend/submit.php -->
<?php
if ($_SERVER["REQUEST_METHOD"] == "POST") {
    // Get component ID from template
    $componentId = '{{id}}';

    // Sanitize input
    $name = htmlspecialchars(strip_tags(trim($_POST["name"])));
    $email = filter_var(trim($_POST["email"]), FILTER_SANITIZE_EMAIL);

    @if(enableValidation)
    // Conditional validation
    if (empty($name) || empty($email)) {
        http_response_code(400);
        echo json_encode(['error' => 'Missing required fields']);
        exit;
    }
    @endif

    // Process form
    $result = processFormData($name, $email);

    @if(sendEmail)
    // Send notification email
    mail('{{notificationEmail}}', 'Form Submission', $result);
    @endif

    echo json_encode(['success' => true, 'message' => 'Form submitted']);
}
?>

Then reference it from your HTML template:

<!-- templates/index.html -->
<form id="contact-form-{{id}}">
    <input type="text" name="name" required>
    <input type="email" name="email" required>
    <button type="submit">Submit</button>
</form>

<script>
document.getElementById('contact-form-{{id}}').addEventListener('submit', async (e) => {
    e.preventDefault();
    const formData = new FormData(e.target);

    const response = await fetch('{{node.backendPath}}/submit.php', {
        method: 'POST',
        body: formData
    });

    const result = await response.json();
    console.log(result);
});
</script>

See the Backend documentation for complete examples and best practices.

Limitations

Template Processing Only

PHP files in templates are processed by Elements template engine during publish, but they're not executed during the build process. They're deployed to the server and execute when requested.

Security Considerations

Always sanitize and validate user input in PHP:

<?php
// Sanitize input
$userInput = htmlspecialchars(strip_tags(trim($_POST['input'])));

// Validate
if (!filter_var($userInput, FILTER_VALIDATE_EMAIL)) {
    http_response_code(400);
    exit('Invalid input');
}

// Use prepared statements for database queries
$stmt = $pdo->prepare('SELECT * FROM users WHERE email = ?');
$stmt->execute([$userInput]);
?>

Common Patterns

Form Processing

Process form submissions with component properties:

<?php
if ($_SERVER["REQUEST_METHOD"] == "POST") {
    $componentId = '{{id}}';
    $maxFileSize = {{maxFileSize}};
    $allowedTypes = ['{{allowedTypes}}'];

    // Process uploaded file
    if (isset($_FILES['file'])) {
        if ($_FILES['file']['size'] > $maxFileSize) {
            http_response_code(400);
            echo json_encode(['error' => 'File too large']);
            exit;
        }

        // Handle file upload
        // ...
    }

    echo json_encode(['success' => true]);
}
?>

API Endpoints

Create simple API endpoints:

<?php
header('Content-Type: application/json');

$componentId = '{{id}}';
$apiKey = '{{apiKey}}';

// Verify API key
if (!isset($_SERVER['HTTP_X_API_KEY']) || $_SERVER['HTTP_X_API_KEY'] !== $apiKey) {
    http_response_code(401);
    echo json_encode(['error' => 'Unauthorized']);
    exit;
}

// Handle request
$data = [
    'component' => $componentId,
    'items' => getItems(),
    'timestamp' => time()
];

echo json_encode($data);
?>

Configuration Files

Generate PHP configuration from component properties:

<?php
return [
    'component_id' => '{{id}}',
    'settings' => [
        'enabled' => {{enabled}},
        'max_items' => {{maxItems}},
        'cache_duration' => {{cacheDuration}},
        'api_endpoint' => '{{apiEndpoint}}'
    ],
    @if(features)
    'features' => [
        'feature1' => {{feature1Enabled}},
        'feature2' => {{feature2Enabled}}
    ],
    @endif
];
?>

Best Practices

Use Backend Directory

Place PHP files in templates/backend/ rather than at the root level:

✓ templates/backend/handler.php
✗ templates/handler.php

Pass Configuration from Properties

Use component properties to configure PHP behavior:

// hooks.js
const transformHook = (rw) => {
    rw.setProps({
        node: rw.node,
        apiEndpoint: '/api/data',
        timeout: 30,
        enableCaching: true
    });
};

<!-- templates/backend/api.php -->
<?php
$endpoint = '{{apiEndpoint}}';
$timeout = {{timeout}};
$caching = {{enableCaching}};

// Use configuration
?>

Separate Logic from Configuration

Keep complex PHP logic in shared assets, use templates for configuration:

<!-- templates/backend/process.php -->
<?php
// Include shared library
require_once('{{siteAssetPath}}/lib/processor.php');

// Configure from properties
$processor = new Processor([
    'option1' => '{{option1}}',
    'option2' => {{option2}},
    'option3' => {{option3}}
]);

// Execute
$result = $processor->run($_POST);
echo json_encode($result);
?>

Handle Errors Gracefully

Provide proper error handling:

<?php
try {
    @if(debugMode)
    error_reporting(E_ALL);
    ini_set('display_errors', 1);
    @else
    error_reporting(0);
    @endif

    // Process request
    $result = processRequest($_POST);

    echo json_encode([
        'success' => true,
        'data' => $result
    ]);

} catch (Exception $e) {
    http_response_code(500);

    @if(debugMode)
    $message = $e->getMessage();
    @else
    $message = 'An error occurred';
    @endif

    echo json_encode([
        'success' => false,
        'error' => $message
    ]);
}
?>

Templates vs Assets

Choose the right location for PHP files:

Use templates/backend/ When:

• PHP needs component property values

• PHP is component-specific functionality

• PHP handles form submissions or AJAX requests

• Configuration varies per component

Use Shared Assets When:

• PHP is a reusable library

• PHP doesn't need component properties

• Code is shared across multiple components

• You want to minimize deployed files

Related Documentation

• Backend Directory - Detailed backend PHP documentation

• Shared Assets - Shared PHP libraries

• Elements Language - Template syntax in PHP

• Hooks.js - Passing data to PHP templates

• Properties - Defining configuration properties