use php

"use php" unlocks PHP snippets inside a React component. When the compiler sees the directive, it forwards tagged template literals (`php“…```) to the embedded PHP runtime instead of treating them as plain strings.

Reference
Usage
Troubleshooting

Reference

`"use php"`

Add "use php" to the top of a function to opt that scope into PHP interop mode.

function LegacyInvoice({ items }) {
  "use php";

  return (
    <section>
      {php`
        <?php foreach ($items as $item) { ?>
          <li><?= strtoupper($item["name"]) ?></li>
        <?php } ?>
      `}
    </section>
  );
}

With the directive enabled, the compiler:

Keeps all php``…`` template literals as runtime calls to the PHP bridge.
Skips React Hook checks inside the literal, deferring execution to PHP.
Emits hydration boundaries so the server-rendered PHP markup can slot back into the React tree.

Caveats

The directive must be the first statement in the function body (comments above it are fine).
You must provide a php tagged template helper that proxies to your PHP engine.
The function cannot contain "use memo"—the compiler treats use php as mutually exclusive with other opt-in directives.
Only synchronous PHP execution is supported; asynchronous bridges should wrap results in await phpAsync\“ calls outside the template literal.

How `"use php"` bridges runtimes

"use php" tells the React Compiler to…

Mark the component as requiring the PHP bridge.
Hoist each php``…`` literal into a server call site.
Serialize props referenced inside the literal using JSON, making them available to the PHP runtime as $props.
Reinsert the rendered HTML back into the React output before hydration.

Because the compiler controls serialization, it enforces deterministic input (no functions or Symbols). Violations trigger build-time errors with instructions to precompute data on the JavaScript side.

When to use `"use php"`

"use php" shines in hybrid applications migrating from PHP templates:

Gradual rewrites

Keep critical pages rendering through legacy PHP while incrementally moving logic to React.

function AccountSettings({ user }) {
  "use php";

  return (
    <div>
      <ReactSummary user={user} />
      {php`
        <?php include 'settings-form.php'; // TODO: migrate ?>
      `}
    </div>
  );
}

Server-side utilities

Call into established PHP libraries (PDF generation, currency formatting) without abandoning React.

function DownloadReceipt({ order }) {
  "use php";

  const receiptPath = php`
    <?php return generate_receipt_pdf($props["order"]); ?>
  `;

  return <a href={receiptPath}>Download receipt</a>;
}

Usage

You can enable PHP interop at the file level or per function:

"use php"; // Module-level opt-in for every function below.

function Bootstrapper(props) {
  return php`
    <?php bootstrap_app($props); ?>
  `;
}

function ExplicitComponent() {
  "use php"; // Reinforces the directive on a single component.

  return php`
    <div><?= render_navigation(); ?></div>
  `;
}

Every tagged template literal receives a $props array containing the JavaScript props serialized by the compiler. Nested functions inherit the directive, so helper functions declared inside the component can also emit PHP.

Troubleshooting

`ReferenceError: php is not defined`

Ensure you provide a php tagged template helper:

import { php } from "@company/react-php-bridge";

Without this import the compiler leaves a direct call to php([...]), which will fail at runtime.

Props missing inside PHP

Only serializable values are forwarded. Convert non-serializable props before entering the literal:

const safeProps = {
  ...props,
  onSubmit: undefined, // Functions can't cross the runtime boundary.
};

return php`<?php render_form($props["safeProps"]); ?>`;

Hydration mismatch warnings

The PHP output must remain stable between server and client. Avoid calling time-based helpers (time(), rand()) directly; precompute values in JavaScript and pass them through $props.