Content rendering

This guide provides practical examples of how to use the PHP SDK to fetch and render a Slot in your application.

Basic usage

Let’s say you have a slot called home-hero for the hero section of your homepage.

To fetch content, use the fetchContent method. This method receives the ID of the slot you want to fetch and returns a FetchResponse with the resolved content:

<?phpuse Croct\Plug\Croct;
$croct = Croct::fromDotenv();$content = $croct->fetchContent('home-hero')->getContent();

The actual structure of the content depends on the schema of the slot, but here is an example:

{"title": "The best personalization platform for developers","subtitle": "Best-in-class developer experience and enterprise-grade reliability.","image": {  "url": "https://cdn.croct.io/devs.png",  "alt": "A screenshot of an editor showing a code snippet."},"button": {  "label": "See docs",  "url": "https://docs.croct.com"}}

You can then use this content to render the hero section of your homepage with any templating engine:

<?phpuse Croct\Plug\Croct;
$croct = Croct::fromDotenv();$hero = $croct->fetchContent('home-hero')->getContent();?><section class="hero">  <h1><?= $hero['title'] ?></h1>  <p class="subtitle"><?= $hero['subtitle'] ?></p>  <img src="<?= $hero['image']['url'] ?>" alt="<?= $hero['image']['alt'] ?>">  <a href="<?= $hero['button']['url'] ?>"><?= $hero['button']['label'] ?></a></section>

The example echoes content directly for clarity. In production, escape output or use a templating engine such as Twig or Blade, which escapes it automatically.

Typing

The PHPStan and Psalm plugins shipped with the SDK infer the exact shape of every slot, so fetchContent is typed with no manual annotations:

<?phpuse Croct\Plug\Croct;
$croct = Croct::fromDotenv();$content = $croct->fetchContent('home-banner')->getContent();$title = $content['title']; // string

The CLI writes these definitions to a slots.stub file whenever you add or update slots, and the plugins load it automatically. You can also reference a generated type by ID or by name in your own annotations.

Fault tolerance

You should always provide a fallback content to make your application resilient to unexpected errors, downtime, and network failures.

Pass a fallback through the withFallback option, and the SDK returns it whenever the content cannot be fetched:

<?phpuse Croct\Plug\Croct;use Croct\Plug\FetchOptions;
$croct = Croct::fromDotenv();$options = FetchOptions::defaults()->withFallback([    'title' => 'Welcome to Croct!',    'subtitle' => 'The easiest way to personalize your application.',]);$content = $croct->fetchContent('home-hero', $options)->getContent();

Without a fallback, a failed request throws a CroctException, which you can catch to handle the error yourself.

Version control

You can lock a specific slot version to keep the content structure aligned with your application’s expectations. This gives your team the freedom to evolve the structure over time without the risk of breaking things.

Specify the version by passing a versioned ID in the form <id>@<version>. For example, passing home-hero@2 fetches the content for the home-hero slot in version 2. Not specifying a version is the same as passing home-hero@latest, which loads the latest content:

<?phpuse Croct\Plug\Croct;
$croct = Croct::fromDotenv();$content = $croct->fetchContent('home-hero@2')->getContent();

For more information, see Slot versioning.

Localization

To support multiple locales, use the withPreferredLocale option to specify the locale of the content you want to retrieve. This is usually the locale of the user’s browser or account:

<?phpuse Croct\Plug\Croct;use Croct\Plug\FetchOptions;
$croct = Croct::fromDotenv();$options = FetchOptions::defaults()->withPreferredLocale('en-ca');$content = $croct->fetchContent('home-hero', $options)->getContent();

By default, if you do not specify a locale, or if the content is not available in the preferred locale, the content is returned in the default locale of your workspace.

Context variables

Sometimes you need to provide additional information to personalize or segment your users.

For example, if you are working on a SaaS application, you may want to personalize the content based on the subscription plan, quota usage, features, or any other application-specific information. You can achieve this by passing any relevant information through the withAttribute option:

<?phpuse Croct\Plug\Croct;use Croct\Plug\FetchOptions;
$croct = Croct::fromDotenv();$options = FetchOptions::defaults()->withAttribute('plan', 'premium');$content = $croct->fetchContent('upgrade-banner', $options)->getContent();

These values are then accessible as custom attributes in the context variable:

context's plan is "premium"

Keep in mind that the context has some constraints on the number of attributes and levels of nesting. For more information, see the withAttribute documentation.