Sage Directives

Before installing Sage Directives, ensure your environment meets the following requirements:

• Sage: version 10.0 or higher
• PHP: version 8.1 or higher
• Composer: installed and available in your path

Use @query to initialize a standard WP_Query object as $query. You can pass an array of WP_Query parameters to it.

Use @posts to begin a post loop. By default, @posts uses the $query variable initialized by @query. It is wrapped in a have_posts() conditional and will return null if no posts are found. You must close the loop with @endposts, which also handles wp_reset_postdata().

Alternatively, you can pass a specific WP_Query instance, a single post ID, a WP_Post object, or an array of these to @posts to control the loop content.

@query([
  'post_type' => 'post'
])

@posts
  <h2 class="entry-title">@title</h2>
  <div class="entry-content">
    @content
  </div>
@endposts

The @extract directive takes an associative array and extracts its keys into local variables. This is particularly useful in component views to provide default values for parameters passed via @include.

// entry-meta.blade.php
@extract([
  'author' => $author ?? true,
  'date'   => $date   ?? true
])

@if ($author)
  [...] 
@endif

To use Sage Directives in your project, install it using Composer. This package provides Blade directives for Sage 10, including helpers for WordPress and ACF.

$ composer require log1x/sage-directives

To iterate over ACF Repeater or Flexible Content fields, use the @fields directive. This directive handles both the if (have_rows(...)) check and the while (have_rows(...)) loop, automatically calling the_row() for each iteration.

• @fields <field_name>: Starts a loop for a repeater field.
• @fields <field_name>, <post_id>: Starts a loop for a repeater field on a specific post.
• @endfields: Closes the loop and the conditional block.
• @hasfields <field_name>: Only performs the if (have_rows(...)) check without starting a loop.
• @endhasfields: Closes the conditional block.

@fields('my_repeater_field')
  <div>{{ @sub('sub_field_name') }}</div>
@endfields

Use @query, @posts, and @endposts to handle WordPress queries and loops within Blade templates.

• @query: Initializes a new WP_Query with the provided expression.
• @posts: A powerful directive that can take a WP_Query expression, a single WP_Post object, a post ID, or an array of post IDs/objects. It automatically sets up a loop and handles the WP_Query instantiation.
• @endposts: Closes the loop and calls wp_reset_postdata() to ensure the global $post object is restored.

{{-- Using @posts with an array of IDs --}}
@posts [1, 2, 3]
    <h2>{{ @title }}</h2>
    <div>{{ @content }}</div>
@endposts

{{-- Using @query with a custom WP_Query expression --}}
@query ['post_type' => 'page', 'posts_per_page' => 5]
    @posts
        {{ @title }}
    @endposts
@endposts

Use these directives to conditionally render content based on whether a query or specific posts exist.

• @hasposts: Checks if a query (or a specific post/array of posts) has results. If an expression is provided, it builds a temporary query to check existence.
• @noposts: The inverse of @hasposts; renders content only if no posts are found.
• @endhasposts / @endnoposts: Closes the conditional block and calls wp_reset_postdata().

@hasposts ['post_type' => 'product']
    <p>We have products!</p>
@endhasposts

@noposts
    <p>No products found.</p>
@endnoposts

The SageDirectivesServiceProvider is the main entry point for the package. It automatically bootstraps and registers the available directive providers: Acf, Helpers, and WordPress. In a standard Sage or Laravel installation, this provider is typically registered via your application's service provider list or automatically discovered if using Composer's package discovery.

<?php

namespace Log1x
SageDirectives;

// The package is bootstrapped via the SageDirectivesServiceProvider,
// which registers the following directive classes:
// - Log1x\SageDirectives\Directives\Acf
// - Log1x\SageDirectives\Directives\Helpers
// - Log1x\SageDirectives\Directives\WordPress

Use these directives to manipulate the variable scope and state within your views:

• @global($variable): Makes the specified variable global.
• @set($variable, 'value'): Sets the specified variable to a specific value.
• @unset($variable): Unsets the specified variable.

@global($post)
@set($hello, 'world')
@unset($hello)

The @repeat(n) directive repeats its contents a specified number of times. It provides a $loop object inside the block, similar to Laravel's native looping, to track iteration state.

@repeat(5)
  Iteration {{ $loop->iteration }} of {{ $loop->count }}.
  Index: {{ $loop->index }}
  Is first: {{ $loop->first ? 'yes' : 'no' }}
  Is last: {{ $loop->last ? 'yes' : 'no' }}
  Remaining: {{ $loop->remaining }}
@endrepeat