Prisma PHP Reactivity

Prisma PHP Reactivity allows you to write dynamic templates using {{ expression }} syntax. These expressions are evaluated to render state or computed values without side effects.

Expression Rules

Inside {{ ... }}, only pure expressions are allowed. These include reading state, performing computations, and string formatting. Any mutation or imperative code is forbidden.

Allowed vs. Not Allowed

⚠️ Reserved Variable Names

When using reactivity with {{ jsVariable }} syntax, avoid naming your variables with commonly used HTML attributes or global DOM properties. These may cause unexpected behavior due to browser-native conflicts or overwritten properties during binding.

⛔ Do Not Use These Reserved Names

If you use any of these by accident, Prisma PHP will attempt to handle them safely using proxies and fallback defaults. However, for clarity and stability, it’s best to rename your variables when possible. Use prefixes like userClass, formName, or textValue.

Using Mustache Variables

When you declare a variable using {{ jsVariable }}, it becomes globally accessible and is available in pphp.props.jsVariable. This mechanism allows Prisma PHP to enable shorthand usage of variable names within your script tags. Behind the scenes, the PPHP class manages reactivity and ensures seamless template rendering.

Examples

{{ user.name }}
<h1>Welcome, {{ user.name }}!</h1>
<p>Length: {{ textCount.length }}!</p>
<p>Balance: {{ Number(account.balance) + Number(bonus) }}</p>
<p>Status: {{ isActive ? 'Active' : 'Inactive' }}</p>
<p class="bg-red-500 {{ textColor }}"></p>

🧪 Example: Using Backticks with Expressions

You can use JavaScript template literals inside expressions as long as they remain on a single line. This is especially helpful when combining strings and variables.

{{ `Username: ${user.name}` }}
{{ `Balance: ${Number(balance).toFixed(2)}` }}

Avoid using line breaks inside the backticks. If you need multiline output, use multiple elements instead of a multiline template string.

When you use , the variable becomes globally accessible via window.jsVariable and pphp.props.jsVariable. Inside a function, you can retrieve its value using pphp.props.jsVariable. To update the variable and trigger a re-render of the template, simply assign a new value to pphp.props.jsVariable, like pphp.props.jsVariable = 'new value'.

Initialize Variable

{{ user.name }}
<h1>Welcome, {{ user.name }}!</h1>
<p>Length: {{ textCount.length }}!</p>
<p>Balance: {{ Number(account.balance) + Number(bonus) }}</p>
<p>Status: {{ isActive ? 'Active' : 'Inactive' }}</p>
<p class="bg-red-500 {{ textColor }}"></p>
<script>
    // Initialize variables using pphp.state
    const [user, setUser] = pphp.state({ name: 'John Doe' });
    const [textColor, setTextColor] = pphp.state('bg-red-500');
    const [textCount] = pphp.state('Hello World');
    const account = pphp.state({ balance: 100, bonus: 20 });
    pphp.state('isActive', true); // Note: Direct effect methods (like pphp.effect) do not support this pattern
    
    // Initialize variables using pphp.share
    const [user, setUser] = pphp.share({ name: 'John Doe' });
    const [textColor, setTextColor] = pphp.share('bg-red-500');
    const [textCount] = pphp.share('Hello World');
    const account = pphp.share({ balance: 100, bonus: 20 });
    pphp.share('isActive', true); // Note: Direct effect methods (like pphp.effect) do not support this pattern
</script>

📥 Example: Getting Input Value

<input type="text" onchange="inputValue = this.value" value="{{ inputValue }}" class="input input-bordered" />
<p>You entered: {{ inputValue }}</p>
<button onclick="getInputValue">Click Me!</button>
<script>
    const [inputValue, setInputValue] = pphp.state(''); // Initialize input value state
    const [user, setUser] = pphp.state({ name: 'John Doe' }); // Initialize user state

    export function getInputValue() {
        // This function can be called on button click
        console.log(inputValue); // Access the current input value
        setUser({ name: inputValue.value }); // Update user state with input value
    }
</script>

Special Attributes: pp-bind and pp-bind-*

Prisma PHP Reactivity introduces special attributes for dynamic DOM bindings: pp-bind and pp-bind-*. These enable you to bind JavaScript variables to specific DOM properties and attributes in a declarative way, by default this will replace the content of the element with the value of the variable.

NOTE: When using pp-bind-class, the existing class attribute will be replaced entirely by the value of the JavaScript variable. If you want to preserve existing classes and append the variable's value, consider using a template like <p class="bg-amber-200 {{ jsVariable }}"></p> instead.

💬 pp-bind="jsVariable"

This binds the content of the element directly to the specified JavaScript variable. It sets the textContent of the element.

<span pp-bind="username"></span> 
// sets: span.textContent = username

🔧 pp-bind-* (Dynamic Attribute Bindings)

The wildcard asterisk (*) in pp-bind-* allows you to bind any specific attribute or property of a DOM element.

• pp-bind-value="age" → sets element.value = age
• pp-bind-checked="isChecked" → sets element.checked = isChecked
• pp-bind-class="dynamicClass" → updates element.className
• pp-bind-disabled="isDisabled" → sets element.disabled = isDisabled

📌 Key Differences

🧪 Live Example

<input type="text" pp-bind-value="userInput" />
<p pp-bind="userInput"></p>
<input type="checkbox" pp-bind-checked="acceptTerms" />
<div pp-bind-class="cardClass">Card</div>

These bindings ensure your DOM elements always stay in sync with your reactive state.

Setting Variables Using Events

In Prisma PHP Reactivity, you can directly update your reactive variables using standard DOM events such as onclick, onchange, oninput, and more. Once a variable is updated, any element that uses it via {{ }} or pp-bind will automatically reflect the change.

📥 Input Binding

Use an onchange or oninput event to assign the value to your variable.

<input type="text" onchange="name = this.value" class="input input-bordered" />
<p>Your name is: {{ name }}</p>

☑️ Checkbox Binding

Combine pp-bind-checked with an event to toggle booleans.

<input type="checkbox" pp-bind-checked="active" onchange="active = this.checked" />
<p>Account is: {{ active ? 'Active' : 'Inactive' }}</p>

🖱️ Toggle on Button Click

A button click can toggle values or modify them in any way using pure expressions.

<button onclick="active = !active" class="btn btn-primary">
    Toggle Active
</button>
<p>Status: {{ active ? 'Enabled' : 'Disabled' }}</p>

🧪 More Examples

<!-- Updating a number -->
<input type="number" onchange="age = this.value" class="input input-bordered" />
<p>Age: {{ age }}</p>

<!-- Dropdown selector -->
<select onchange="role = this.value" class="select select-bordered">
    <option value="admin">Admin</option>
    <option value="editor">Editor</option>
    <option value="viewer">Viewer</option>
</select>
<p>Selected Role: {{ role }}</p>

<!-- Toggle visibility using a boolean -->
<button onclick="showInfo = !showInfo" class="btn btn-info">
    Toggle Info
</button>
<div class="mt-2 {{ showInfo ? 'block' : 'hidden' }}">
    Extra info is now visible!
</div>

Any JavaScript expression that updates a variable will automatically re-render all related reactive bindings. Keep expressions pure and declarative for best results.

NOTE: If you need to apply multiple behaviors, it is recommended to use a JavaScript function. For example, you can set attributes like pp-bind="setText" and pp-bind-class="replaceClass". Within the function triggered by an event (e.g., onclick), you can update the variable values and class names.

Conclusion

By restricting {{ ... }} to pure expressions only, Prisma PHP Reactivity ensures your templates stay safe, fast, and easy to reason about. Avoid side effects, and your UI will stay in sync with the state like magic ✨.