HivePress

https://docs.hivepress.io/developer-docs
Admin
HivePress is an open-source WordPress plugin and extensible framework for building directory and...
Tokens:30,587
Snippets:342
Trust Score:9.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Query documentation via HTTP GET

Source: https://docs.hivepress.io/developer-docs/llms.txt

Perform a GET request to the documentation index using the ask and goal parameters to receive a direct answer.

```http
GET https://docs.hivepress.io/developer-docs/framework/fields/text.md?ask=<question>&goal=<end_goal>
```

--------------------------------

### Set and get WordPress-level arguments

Source: https://docs.hivepress.io/developer-docs/framework/models/making-queries.md

Integrate with native WordPress query arguments when necessary.

```php
$query->set_args(
	[
		'meta_key'   => 'custom_field',
		'meta_value' => 123,
	]
);
```

```php
$args = $query->get_args();
```

--------------------------------

### Cache Listing Count Example

Source: https://docs.hivepress.io/developer-docs/framework/components/cache.md

Demonstrates caching a calculated value and retrieving it to avoid redundant database queries.

```php
function get_listing_count( $user_id ) {

	// Get the cached value.
	$listing_count = hivepress()->cache->get_user_cache( $user_id, 'listing_count', 'models/listing' );

	if ( is_null( $listing_count ) ) {

		// Count listings.
		$listing_count = HivePress\Models\Listing::query()->filter(
			[
				'user'       => $user_id,
				'status__in' => [ 'draft', 'pending', 'publish' ],
			]
		)->get_count();

		// Cache the calculated value.
		hivepress()->cache->set_user_cache( $user_id, 'listing_count', 'models/listing', $listing_count );
	}

	return $listing_count;
}
```

--------------------------------

### Retrieve query results

Source: https://docs.hivepress.io/developer-docs/framework/models/making-queries.md

Use the get method to fetch entries from the database.

```php
$listings = $query->get();
```

--------------------------------

### Render a Repeater field with text and number inputs

Source: https://docs.hivepress.io/developer-docs/framework/fields/repeater.md

This example demonstrates how to initialize and render a Repeater field containing a text field with a minimum length requirement and a number field with a minimum value constraint.

```php
echo ( new HivePress\Fields\Repeater(
	[
		'name'   => 'custom_field',

		'fields' => [
			'custom_text'   => [
				'placeholder' => 'Custom text',
				'type'        => 'text',
				'min_length'  => 10,
				'_order'      => 123,
			],

			'custom_number' => [
				'placeholder' => 'Custom number',
				'type'        => 'number',
				'min_value'   => 100,
				'_order'      => 321,
			],
		],
	]
) )->render();
```

--------------------------------

### GET /developer-docs/framework/fields/text.md

Source: https://docs.hivepress.io/developer-docs/llms.txt

Queries the documentation index for a specific question, optionally providing a broader goal to tailor the response.

```APIDOC
## GET /developer-docs/framework/fields/text.md

### Description
Perform an HTTP GET request on the documentation index to retrieve a direct answer to a specific question, along with relevant excerpts and sources.

### Method
GET

### Endpoint
https://docs.hivepress.io/developer-docs/framework/fields/text.md

### Parameters
#### Query Parameters
- **ask** (string) - Required - The specific, self-contained question written in natural language.
- **goal** (string) - Optional - Describes the broader end goal to help tailor the answer.
```

--------------------------------

### Define a Custom HivePress Model

Source: https://docs.hivepress.io/developer-docs/framework/models/creating-models.md

Example of a custom model class extending the Post base class with defined fields and custom methods.

```php
<?php
namespace HivePress\Models;

use HivePress\Helpers as hp;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

class Foo_Bar extends Post {
	public function __construct( $args = [] ) {
		$args = hp\merge_arrays(
			[
				// Define the model fields.
				'fields' => [
					'description' => [
						'type'       => 'textarea',
						'max_length' => 1234,
						'required'   => true,
						'_alias'     => 'post_content',
					],
				],
			],
			$args
		);

		parent::__construct( $args );
	}

	// Implement custom methods.
	public function get_short_description() {
		return substr( $this->get_description(), 0, 123 );
	}
}
```

--------------------------------

### Define a HivePress Model

Source: https://docs.hivepress.io/developer-docs/tutorials/create-a-custom-hivepress-extension.md

Create a model class to represent database entities. This example extends the Comment class to store follower and vendor IDs.

```php
<?php
namespace HivePress\Models;

use HivePress\Helpers as hp;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

/**
 * Model class.
 */
class Follow extends Comment {

	/**
	 * Class constructor.
	 *
	 * @param array $args Model arguments.
	 */
	public function __construct( $args = [] ) {
		$args = hp\merge_arrays(
			[
				'fields' => [
					'user'   => [
						'type'     => 'id',
						'required' => true,
						'_alias'   => 'user_id',
						'_model'   => 'user',
					],

					'vendor' => [
						'type'     => 'id',
						'required' => true,
						'_alias'   => 'comment_post_ID',
						'_model'   => 'vendor',
					],
				],
			],
			$args
		);

		parent::__construct( $args );
	}
}
```

--------------------------------

### Get Page Number

Source: https://docs.hivepress.io/developer-docs/framework/components/request.md

Retrieves the current page number for paginated queries.

```php
$page = hivepress()->request->get_page_number();
```

--------------------------------

### Get Request Context

Source: https://docs.hivepress.io/developer-docs/framework/components/request.md

Retrieves a previously stored value from the request context.

```php
$value = hivepress()->request->get_context( 'custom_key' );
```

--------------------------------

### Define a new configuration file

Source: https://docs.hivepress.io/developer-docs/framework/configurations.md

Create a new PHP file in the includes/configs directory and return an array of parameters.

```php
return [
	'one'   => 'One',
	'two'   => 'Two',
	'three' => 'Three',
];
```

--------------------------------

### Get Query Variable

Source: https://docs.hivepress.io/developer-docs/framework/components/request.md

Retrieves a HivePress-specific query variable by name.

```php
$value = hivepress()->request->get_param( 'custom_name' );
```

--------------------------------

### Create and save model objects

Source: https://docs.hivepress.io/developer-docs/framework/models.md

Instantiate a model, fill it with data, and persist it to the database. Use _get_errors() to retrieve validation issues if saving fails.

```php
// Create listing.
$listing = ( new HivePress\Models\Listing() )->fill(
	[
		'title'    => 'Custom title',
		'featured' => true,
	]
);

// Save listing.
$listing->save();
```

```php
if ( ! $listing->save() ) {
	$errors = $listing->_get_errors();
}
```

```php
$id = $listing->get_id();
```

--------------------------------

### Retrieve result count

Source: https://docs.hivepress.io/developer-docs/framework/models/making-queries.md

Get the total number of results matching the query.

```php
$listing_count = $query->get_count();
```

--------------------------------

### Initialize a query object

Source: https://docs.hivepress.io/developer-docs/framework/models/making-queries.md

Create a new query instance for a specific model.

```php
$query = HivePress\Models\Listing::query();
```

--------------------------------

### Get Current User

Source: https://docs.hivepress.io/developer-docs/framework/components/request.md

Retrieves the current user object if the user is logged in.

```php
$user = hivepress()->request->get_user();
```

--------------------------------

### Implement route redirect and action functions

Source: https://docs.hivepress.io/developer-docs/tutorials/create-a-custom-hivepress-extension.md

Define the redirect logic to handle authentication and context checks, followed by the action function to query data and render the template.

```php
/**
 * Redirects listing feed page.
 *
 * @return mixed
 */
public function redirect_feed_page() {

	// Check authentication.
	if ( ! is_user_logged_in() ) {
		return hivepress()->router->get_return_url( 'user_login_page' );
	}

	// Check followed vendors.
	if ( ! hivepress()->request->get_context( 'vendor_follow_ids' ) ) {
		return hivepress()->router->get_url( 'user_account_page' );
	}

	return false;
}

/**
 * Renders listing feed page.
 *
 * @return string
 */
public function render_feed_page() {

	// Create listing query.
	$query = Models\Listing::query()->filter(
		[
			'status'     => 'publish',
			'vendor__in' => hivepress()->request->get_context( 'vendor_follow_ids' ),
		]
	)->order( [ 'created_date' => 'desc' ] )
	->limit( get_option( 'hp_listings_per_page' ) )
	->paginate( hivepress()->request->get_page_number() );

	// Set request context.
	hivepress()->request->set_context(
		'post_query',
		$query->get_args()
	);

	// Render page template.
	return ( new Blocks\Template(
		[
			'template' => 'listings_feed_page',

			'context'  => [
				'listings' => [],
			],
		]
	) )->render();
}
```

--------------------------------

### Get current route name

Source: https://docs.hivepress.io/developer-docs/framework/components/router.md

Retrieves the name of the route currently being accessed.

```php
$route = hivepress()->router->get_current_route_name();
```

--------------------------------

### Define the main plugin file

Source: https://docs.hivepress.io/developer-docs/tutorials/create-a-custom-hivepress-extension.md

The main entry point for the extension, containing plugin metadata and the registration hook for HivePress.

```php
<?php
/**
 * Plugin Name: Followers for HivePress
 * Description: Allow users to follow vendors.
 * Version: 1.0.0
 * Author: Foo
 * Author URI: https://example.com/
 * Text Domain: foo-followers
 * Domain Path: /languages/
 */

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

// Register extension directory.
add_filter(
	'hivepress/v1/extensions',
	function( $extensions ) {
		$extensions[] = __DIR__;

		return $extensions;
	}
);
```

--------------------------------

### Implement REST API action

Source: https://docs.hivepress.io/developer-docs/framework/controllers.md

Handle incoming requests and return JSON responses using the provided helper functions.

```php
public function custom_action( $request ) {
	// Perform some actions based on the request.

	if ( ! $request->get_param( 'custom_parameter' ) ) {

		// Return the error code and message.
		return hp\rest_error( 400, 'Custom error message' );
	}

	// Return the response code and data.
	return hp\rest_response(
		200,
		[
			'custom_result' => 123,
		]
	);
}
```

--------------------------------

### Define a template route

Source: https://docs.hivepress.io/developer-docs/framework/controllers.md

Register a new URL route by adding an array of parameters including title, path, redirect, and action callbacks.

```php
'custom_route' => [
	'title'    => 'Custom Title',
	'path'     => '/custom-route',
	'redirect' => [ $this, 'custom_redirect' ],
	'action'   => [ $this, 'custom_action' ],
],
```

--------------------------------

### Define a custom HivePress menu class

Source: https://docs.hivepress.io/developer-docs/framework/menus.md

Create a new menu by extending the Menu class and defining items within the constructor. Ensure the class name matches the file naming convention.

```php
<?php
namespace HivePress\Menus;

use HivePress\Helpers as hp;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

class Foo_Bar extends Menu {
	public function __construct( $args = [] ) {
		$args = hp\merge_arrays(
			[
				// Define the menu items.
				'items' => [
					'first_item'  => [
						'label'  => 'First Item',
						'route'  => 'listings_view_page',
						'_order' => 123,
					],

					'second_item' => [
						'label'  => 'Second Item',
						'url'    => 'https://example.com',
						'_order' => 321,
					],
				],
			],
			$args
		);

		parent::__construct( $args );
	}
}
```

--------------------------------

### Defining a custom component class

Source: https://docs.hivepress.io/developer-docs/framework/components.md

Create a class extending Component to register hooks and define helper methods. Ensure the file is placed in the includes/components directory of your extension.

```php
<?php
namespace HivePress\Components;

use HivePress\Helpers as hp;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

final class Foo_Bar extends Component {
	public function __construct( $args = [] ) {

		// Attach functions to hooks here (e.g. add_action, add_filter).
		add_action( 'template_redirect', [ $this, 'redirect_page' ] );

		parent::__construct( $args );
	}

	public function redirect_page() {
		// Implement the attached function here.
	}

	public function do_something() {
		// Implement the helper function here.
	}
}
```

--------------------------------

### Perform CRUD operations on a model

Source: https://docs.hivepress.io/developer-docs/framework/models.md

Demonstrates creating, updating, and deleting a listing model instance.

```php
// Create listing.
$listing = ( new HivePress\Models\Listing() )->fill(
	[
		'title'       => 'Custom title',
		'description' => 'Custom text',
	]
);

if ( $listing->save( [ 'title', 'description' ] ) ) {

	// Mark as featured.
	$listing->set_featured( true )->save_featured();

	// Delete listing.
	$listing->delete();
}
```

--------------------------------

### Render a URL field in PHP

Source: https://docs.hivepress.io/developer-docs/framework/fields/url.md

Renders a URL field with a specific name, label, placeholder, and required validation.

```php
echo ( new HivePress\Fields\URL(
	[
		'name'        => 'custom_field',
		'label'       => 'Custom field',
		'placeholder' => 'Custom text',
		'required'    => true,
	]
) )->render();
```

--------------------------------

### Implement template route callbacks

Source: https://docs.hivepress.io/developer-docs/framework/controllers.md

Define the redirect logic and template rendering action methods within the controller class.

```php
public function custom_redirect() {

	// Perform checks and return the redirect URL.
	if ( is_user_logged_in() ) {
		return hivepress()->router->get_url( 'user_account_page' );
	}

	// Return false to prevent the redirect.
	return false;
}

public function custom_action() {

	// Return the rendered page template.
	return ( new HivePress\Blocks\Template(
		[
			'template' => 'user_login_page',
		]
	) )->render();
}
```

--------------------------------

### Render WordPress site title using Callback block

Source: https://docs.hivepress.io/developer-docs/framework/blocks/callback.md

Uses the Callback block to execute get_bloginfo with the 'name' parameter, returning the result for rendering.

```php
echo ( new HivePress\Blocks\Callback(
	[
		'callback' => 'get_bloginfo',
		'params'   => [ 'name' ],
		'return'   => true,
	]
) )->render();
```

--------------------------------

### Define a custom controller class

Source: https://docs.hivepress.io/developer-docs/tutorials/create-a-custom-hivepress-extension.md

Create a controller class to manage URL routes and implement corresponding actions.

```php
<?php
namespace HivePress\Controllers;

use HivePress\Helpers as hp;
use HivePress\Models;
use HivePress\Blocks;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

/**
 * Controller class.
 */
final class Followers extends Controller {

	/**
	 * Class constructor.
	 *
	 * @param array $args Controller arguments.
	 */
	public function __construct( $args = [] ) {
		$args = hp\merge_arrays(
			[
				'routes' => [
					// Define custom URL routes here.
				],
			],
			$args
		);

		parent::__construct( $args );
	}
	
	// Implement the route actions here.
}
```

--------------------------------

### Render a File Picker Field

Source: https://docs.hivepress.io/developer-docs/framework/fields/file.md

Renders a required file picker that accepts multiple image formats including JPG, PNG, and GIF.

```php
echo ( new HivePress\Fields\File(
	[
		'name'     => 'custom_field',
		'label'    => 'Custom field',
		'formats'  => [ 'jpg', 'png', 'gif' ],
		'multiple' => true,
		'required' => true,
	]
) )->render();
```

--------------------------------

### Define a custom block class

Source: https://docs.hivepress.io/developer-docs/tutorials/create-a-custom-hivepress-extension.md

Create a new block type by extending the Toggle class, defining its states, and setting the request URL in the boot method.

```php
<?php
namespace HivePress\Blocks;

use HivePress\Helpers as hp;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

/**
 * Block class.
 */
class Follow_Toggle extends Toggle {

	/**
	 * Class constructor.
	 *
	 * @param array $args Block arguments.
	 */
	public function __construct( $args = [] ) {
		$args = hp\merge_arrays(
			[
				'states' => [
					[
						'icon'    => 'user-plus',
						'caption' => esc_html__( 'Follow', 'foo-followers' ),
					],
					[
						'icon'    => 'user-minus',
						'caption' => esc_html__( 'Unfollow', 'foo-followers' ),
					],
				],
			],
			$args
		);

		parent::__construct( $args );
	}

	/**
	 * Bootstraps block properties.
	 */
	protected function boot() {

		// Get vendor from the block context.
		$vendor = $this->get_context( 'vendor' );

		if ( $vendor ) {

			// Set URL for sending requests on click.
			$this->url = hivepress()->router->get_url(
				'vendor_follow_action',
				[
					'vendor_id' => $vendor->get_id(),
				]
			);

			// Set active state if vendor is followed.
			if ( in_array(
				$vendor->get_id(),
				hivepress()->request->get_context( 'vendor_follow_ids', [] )
			) ) {
				$this->active = true;
			}
		}

		parent::boot();
	}
}
```

--------------------------------

### Request Context and Query Methods

Source: https://docs.hivepress.io/developer-docs/framework/components/request.md

Methods for setting and retrieving request context values, user information, page numbers, and query parameters.

```APIDOC
## hivepress()->request->set_context(string $key, mixed $value)

### Description
Sets a value in the request context.

### Parameters
- **key** (string) - Required - The context key.
- **value** (mixed) - Required - The value to store.

## hivepress()->request->get_context(string $key)

### Description
Retrieves a value from the request context.

### Parameters
- **key** (string) - Required - The context key to retrieve.

## hivepress()->request->get_user()

### Description
Returns the current user object if the user is logged in.

## hivepress()->request->get_page_number()

### Description
Returns the current page number for paginated queries.

## hivepress()->request->get_param(string $name)

### Description
Retrieves a specific HivePress query variable (prefixed with hp_).

### Parameters
- **name** (string) - Required - The variable name.

## hivepress()->request->get_params()

### Description
Returns an array of all HivePress query variables.
```

--------------------------------

### Implement email notification logic

Source: https://docs.hivepress.io/developer-docs/tutorials/create-a-custom-hivepress-extension.md

Define the function to query followers and send emails when a listing is published.

```php
/**
 * Sends emails about a new listing.
 *
 * @param int    $listing_id Listing ID.
 * @param string $new_status New status.
 * @param string $old_status Old status.
 * @param object $listing Listing object.
 */
public function send_feed_emails( $listing_id, $new_status, $old_status, $listing ) {

	// Check listing status.
	if ( 'publish' !== $new_status || ! in_array( $old_status, [ 'auto-draft', 'pending' ] ) ) {
		return;
	}

	// Get follows.
	$follows = Models\Follow::query()->filter(
		[
			'vendor' => $listing->get_vendor__id(),
		]
	)->get();

	foreach ( $follows as $follow ) {

		// Get user.
		$user = $follow->get_user();

		// Send email.
		( new Emails\Listing_Feed(
			[
				'recipient' => $user->get_email(),

				'tokens'    => [
					'user_name'     => $user->get_display_name(),
					'listing_title' => $listing->get_title(),
					'listing_url'   => hivepress()->router->get_url( 'listing_view_page', [ 'listing_id' => $listing->get_id() ] ),
				],
			]
		) )->send();
	}
}
```

--------------------------------

### Retrieve the first result

Source: https://docs.hivepress.io/developer-docs/framework/models/making-queries.md

Fetch only the first entry from the query results.

```php
$listing = $query->get_first();
```

--------------------------------

### Render a template part using the Part block

Source: https://docs.hivepress.io/developer-docs/framework/blocks/part.md

Use this snippet to render a specific template file by providing its path relative to the templates directory.

```php
echo ( new HivePress\Blocks\Part(
	[
		'path' => 'page/no-results-message',
	]
) )->render();
```

--------------------------------

### Create Template Part

Source: https://docs.hivepress.io/developer-docs/tutorials/create-a-custom-hivepress-extension.md

Define the HTML template part that triggers the modal window.

```php
<?php
// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;
?>
<a href="#vendors_unfollow_modal" class="button"><?php esc_html_e( 'Unfollow Vendors', 'foo-followers' ); ?></a>
```

--------------------------------

### Define a custom HivePress controller class

Source: https://docs.hivepress.io/developer-docs/framework/controllers.md

Create a new controller by extending the base Controller class and defining routes within the constructor. Ensure the class name matches the file naming convention to enable automatic loading.

```php
<?php
namespace HivePress\Controllers;

use HivePress\Helpers as hp;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

final class Foo_Bar extends Controller {
	public function __construct( $args = [] ) {
		$args = hp\merge_arrays(
			[
				'routes' => [
					// Define custom URL routes here.
				],
			],
			$args
		);

		parent::__construct( $args );
	}
	
	// Implement the route actions here.
}
```

--------------------------------

### Chain query methods

Source: https://docs.hivepress.io/developer-docs/framework/models/making-queries.md

Combine retrieval and serialization for improved readability.

```php
$listings = $query->get()->serialize();
```

--------------------------------

### Render a Section block with PHP

Source: https://docs.hivepress.io/developer-docs/framework/blocks/section.md

Instantiates and renders a Section block containing a nested content block.

```php
echo ( new HivePress\Blocks\Section(
	[
		'title'  => 'My Custom Text',

		'blocks' => [
			'my_custom_block' => [
				'type'    => 'content',
				'content' => 'Hello World!',
				'_order'  => 123,
			],
		],
	]
) )->render();
```

--------------------------------

### Define a custom block type class

Source: https://docs.hivepress.io/developer-docs/framework/blocks.md

Create a new block type by extending the base Block class, defining properties, and implementing the render method.

```php
<?php
namespace HivePress\Blocks;

use HivePress\Helpers as hp;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

class Foo_Bar extends Block {

	// Declare the block properties.
	protected $say_hello;

	public function __construct( $args = [] ) {

		// Set the property defaults.
		$args = hp\merge_arrays(
			[
				'say_hello' => false,
			],
			$args
		);

		parent::__construct( $args );
	}

	public static function init( $meta = [] ) {

		// Add label and settings for Gutenberg.
		$meta = hp\merge_arrays(
			[
				'label'    => 'Hello World',

				'settings' => [
					'say_hello' => [
						'label'  => 'Say Hello',
						'type'   => 'checkbox',
						'_order' => 123,
					],
				],
			],
			$meta
		);

		parent::init( $meta );
	}

	protected function boot() {
		// Do something after the block is loaded.

		parent::boot();
	}

	public function render() {

		// Render the block HTML content.
		$output = '<h1>';

		if ( $this->say_hello ) {
			$output .= 'Hello World!';
		} else {
			$output .= 'Silence...';
		}

		$output .= '</h1>';

		return $output;
	}
}
```

--------------------------------

### Define a custom form class

Source: https://docs.hivepress.io/developer-docs/framework/forms.md

Create a new form by extending the Form class and defining parameters like action, method, and fields.

```php
<?php
namespace HivePress\Forms;

use HivePress\Helpers as hp;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

class Foo_Bar extends Form {
	public function __construct( $args = [] ) {
		$args = hp\merge_arrays(
			[

				// Set the form parameters.
				'action'  => hivepress()->router->get_url( 'custom_action' ),
				'method'  => 'POST',
				'message' => 'Custom text',
				'reset'   => true,

				// Set the field parameters.
				'fields'  => [
					'custom_field' => [
						'label'    => 'Custom field',
						'type'     => 'text',
						'required' => true,
						'_order'   => 123,
					],
				],

				// Set the button parameters.
				'button'  => [
					'label' => 'Custom button',
				],
			],
			$args
		);

		parent::__construct( $args );
		}
}
```

--------------------------------

### Render a Textarea field in PHP

Source: https://docs.hivepress.io/developer-docs/framework/fields/textarea.md

Renders a required multi-line text field with a custom label, placeholder, and character limit.

```php
echo ( new HivePress\Fields\Textarea(
	[
		'name'        => 'custom_field',
		'label'       => 'Custom field',
		'placeholder' => 'Custom text',
		'max_length'  => 100,
		'required'    => true,
	]
) )->render();
```

--------------------------------

### Call a helper function using the Helper component

Source: https://docs.hivepress.io/developer-docs/framework/components/helper.md

Use this syntax to invoke helper functions like sanitize_html from anywhere in the codebase.

```php
hivepress()->helper->sanitize_html( 'custom HTML content' );
```

--------------------------------

### HivePress\Blocks\Menu

Source: https://docs.hivepress.io/developer-docs/framework/blocks/menu.md

The Menu block renders a specified menu with optional HTML attributes. It is instantiated with an array of configuration parameters and rendered using the render() method.

```APIDOC
## HivePress\Blocks\Menu

### Description
Renders a menu block based on the provided configuration.

### Parameters
- **menu** (string) - Required - The name of the menu to render.
- **attributes** (array) - Optional - HTML attributes to apply to the menu.

### Example
```php
echo ( new HivePress\Blocks\Menu(
	[
		'menu'       => 'user_account',

		'attributes' => [
			'class' => [ 'my-custom-class' ],
		],
	]
) )->render();
```
```

--------------------------------

### Send a custom email

Source: https://docs.hivepress.io/developer-docs/framework/emails.md

Instantiate an email class with recipient and token data, then invoke the send method.

```php
( new HivePress\Emails\Foo_Bar(
	[
		'recipient' => 'user@example.com',

		'tokens'    => [
			'custom_token' => 123,
		],
	]
) )->send();
```

--------------------------------

### Render a Phone Field in PHP

Source: https://docs.hivepress.io/developer-docs/framework/fields/phone.md

Renders a required phone field with specific country restrictions and a default country selection.

```php
echo ( new HivePress\Fields\Phone(
	[
		'name'        => 'custom_field',
		'label'       => 'Custom field',
		'placeholder' => 'Custom text',
		'countries'   => [ 'USA', 'GB' ],
		'country'     => 'USA',
		'required'    => true,
	]
) )->render();
```

--------------------------------

### Implement REST API Action Functions

Source: https://docs.hivepress.io/developer-docs/tutorials/create-a-custom-hivepress-extension.md

Implement controller methods to handle follow/unfollow logic, including authentication checks and database operations.

```php
/**
 * Follows or unfollows vendor.
 *
 * @param WP_REST_Request $request API request.
 * @return WP_Rest_Response
 */
public function follow_vendor( $request ) {

	// Check authentication.
	if ( ! is_user_logged_in() ) {
		return hp\rest_error( 401 );
	}

	// Get vendor.
	$vendor = Models\Vendor::query()->get_by_id( $request->get_param( 'vendor_id' ) );

	if ( ! $vendor || $vendor->get_status() !== 'publish' ) {
		return hp\rest_error( 404 );
	}

	// Get follows.
	$follows = Models\Follow::query()->filter(
		[
			'user'   => get_current_user_id(),
			'vendor' => $vendor->get_id(),
		]
	)->get();

	if ( $follows->count() ) {

		// Delete follows.
		$follows->delete();
	} else {

		// Add new follow.
		$follow = ( new Models\Follow() )->fill(
			[
				'user'   => get_current_user_id(),
				'vendor' => $vendor->get_id(),
			]
		);

		if ( ! $follow->save() ) {
			return hp\rest_error( 400, $follow->_get_errors() );
		}
	}

	return hp\rest_response(
		200,
		[
			'data' => [],
		]
	);
}

/**
 * Unfollows all vendors.
 *
 * @param WP_REST_Request $request API request.
 * @return WP_Rest_Response
 */
public function unfollow_vendors( $request ) {

	// Check authentication.
	if ( ! is_user_logged_in() ) {
		return hp\rest_error( 401 );
	}

	// Delete follows.
	$follows = Models\Follow::query()->filter(
		[
			'user' => get_current_user_id(),
		]
	)->delete();

	return hp\rest_response(
		200,
		[
			'data' => [],
		]
	);
}
```

--------------------------------

### Perform CRUD operations on listings

Source: https://docs.hivepress.io/developer-docs/framework/models/making-queries.md

Demonstrates querying, updating, and deleting listings using the HivePress model API.

```php
// Query listings.
$listings = HivePress\Models\Listing::query()->filter(
	[
		'featured'       => true,
		'categories__in' => [ 123 ],
	]
)->order( [ 'created_date' => 'desc' ] )
->limit( 3 )
->get();

// Update listings.
foreach ( $listings as $listing ) {
	$listing->set_title( 'Custom text' )->save_title();
}

// Delete listings.
$listings->delete();
```

--------------------------------

### Render an email field in PHP

Source: https://docs.hivepress.io/developer-docs/framework/fields/email.md

Renders a required email field with a specific name, label, and placeholder.

```php
echo ( new HivePress\Fields\Email(
	[
		'name'        => 'custom_field',
		'label'       => 'Custom field',
		'placeholder' => 'Custom text',
		'required'    => true,
	]
) )->render();
```

--------------------------------

### Render a Container block with PHP

Source: https://docs.hivepress.io/developer-docs/framework/blocks/container.md

Renders a section element with a custom class containing a content block, conditional on the content being non-empty.

```php
echo ( new HivePress\Blocks\Container(
	[
		'tag'        => 'section',
		'optional'   => true,

		'attributes' => [
			'class' => [ 'my-custom-class' ],
		],

		'blocks'     => [
			'my_custom_block' => [
				'type'    => 'content',
				'content' => 'Hello World!',
				'_order'  => 123,
			],
		],
	]
) )->render();
```

--------------------------------

### Define a custom template class

Source: https://docs.hivepress.io/developer-docs/tutorials/create-a-custom-hivepress-extension.md

Create a template class by extending an existing page class and defining blocks within the constructor.

```php
<?php
namespace HivePress\Templates;

use HivePress\Helpers as hp;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

/**
 * Template class.
 */
class Listings_Feed_Page extends User_Account_Page {

	/**
	 * Class constructor.
	 *
	 * @param array $args Template arguments.
	 */
	public function __construct( $args = [] ) {
		$args = hp\merge_trees(
			[
				'blocks' => [
					'page_content' => [
						'blocks' => [
							'listings'               => [
								'type'    => 'listings',
								'columns' => 2,
								'_order'  => 10,
							],

							'listing_pagination'     => [
								'type'   => 'part',
								'path'   => 'page/pagination',
								'_order' => 20,
							],
						],
					],
				],
			],
			$args
		);

		parent::__construct( $args );
	}
}
```

--------------------------------

### Implementing add_menu_item

Source: https://docs.hivepress.io/developer-docs/tutorials/create-a-custom-hivepress-extension.md

Adds a custom menu item to the user account menu if the user follows any vendors.

```php
/**
 * Adds menu item to user account.
 *
 * @param array $menu Menu arguments.
 * @return array
 */
public function add_menu_item( $menu ) {
	if ( hivepress()->request->get_context( 'vendor_follow_ids' ) ) {
		$menu['items']['listings_feed'] = [
			'route'  => 'listings_feed_page',
			'_order' => 20,
		];
	}

	return $menu;
}
```

--------------------------------

### Render a Toggle Link in PHP

Source: https://docs.hivepress.io/developer-docs/framework/blocks/toggle.md

Renders a toggle link that switches between two states (Follow/Unfollow) and sends an AJAX request to the specified URL.

```php
echo ( new HivePress\Blocks\Toggle(
	[
		'url'    => 'https://example.com',

		'states' => [
			[
				'icon'    => 'user-plus',
				'caption' => 'Follow',
			],
			[
				'icon'    => 'user-minus',
				'caption' => 'Unfollow',
			],
		],
	]
) )->render();
```

--------------------------------

### Implementing set_request_context

Source: https://docs.hivepress.io/developer-docs/tutorials/create-a-custom-hivepress-extension.md

Retrieves or caches followed vendor IDs and injects them into the request context.

```php
/**
 * Sets request context for pages.
 *
 * @param array $context Context values.
 * @return array
 */
public function set_request_context( $context ) {

	// Get user ID.
	$user_id = get_current_user_id();

	// Get cached vendor IDs.
	$vendor_ids = hivepress()->cache->get_user_cache( $user_id, 'vendor_follow_ids', 'models/follow' );

	if ( is_null( $vendor_ids ) ) {

		// Get follows.
		$follows = Models\Follow::query()->filter(
			[
				'user' => $user_id,
			]
		)->get();

		// Get vendor IDs.
		$vendor_ids = [];

		foreach ( $follows as $follow ) {
			$vendor_ids[] = $follow->get_vendor__id();
		}

		// Cache vendor IDs.
		hivepress()->cache->set_user_cache( $user_id, 'vendor_follow_ids', 'models/follow', $vendor_ids );
	}

	// Set request context.
	$context['vendor_follow_ids'] = $vendor_ids;

	return $context;
}
```

--------------------------------

### hivepress()->translator->get_string()

Source: https://docs.hivepress.io/developer-docs/framework/components/translator.md

Retrieves a translated string from the configuration based on the provided key.

```APIDOC
## get_string(string $key)

### Description
Retrieves a string from the strings configuration.

### Parameters
- **key** (string) - Required - The key of the string to retrieve.

### Example
```php
hivepress()->translator->get_string( 'listings' );
```
```

--------------------------------

### Declare HivePress support in functions.php

Source: https://docs.hivepress.io/developer-docs/tutorials/integrate-your-theme-with-hivepress.md

Use this to hide incompatibility notices and explicitly declare theme support for HivePress.

```php
add_action(
	'after_setup_theme',
	function() {
		add_theme_support( 'hivepress' );
	}
);
```

--------------------------------

### Retrieve configuration values

Source: https://docs.hivepress.io/developer-docs/framework/configurations.md

Use the hivepress()->get_config() method to access configuration data by name.

```php
$config = hivepress()->get_config( 'foo_bar' );
```

```php
$post_types = hivepress()->get_config( 'post_types' );
```

--------------------------------

### Retrieve a translated string

Source: https://docs.hivepress.io/developer-docs/framework/components/translator.md

Use the get_string method to fetch specific strings defined in the configuration.

```php
hivepress()->translator->get_string( 'listings' );
```

--------------------------------

### Define a HivePress Component

Source: https://docs.hivepress.io/developer-docs/tutorials/create-a-custom-hivepress-extension.md

Create a component class to group actions, filters, and helper functions. The class must extend the Component base class.

```php
<?php
namespace HivePress\Components;

use HivePress\Helpers as hp;
use HivePress\Models;
use HivePress\Emails;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

/**
 * Component class.
 */
final class Followers extends Component {

	/**
	 * Class constructor.
	 *
	 * @param array $args Component arguments.
	 */
	public function __construct( $args = [] ) {
		// Attach functions to hooks here (e.g. add_action, add_filter).

		parent::__construct( $args );
	}

	// Implement the attached functions here.
}
```

--------------------------------

### HivePress\Blocks\Part

Source: https://docs.hivepress.io/developer-docs/framework/blocks/part.md

Renders a template part by the provided path relative to the templates directory.

```APIDOC
## HivePress\Blocks\Part

### Description
This block type renders a template part by the provided path.

### Parameters
- **path** (string) - Required - The PHP file path, without the extension and relative to the `templates` subdirectory of HivePress or its extensions.

### Example
```php
echo ( new HivePress\Blocks\Part(
	[
		'path' => 'page/no-results-message',
	]
) )->render();
```
```

--------------------------------

### Render a Date Range Picker

Source: https://docs.hivepress.io/developer-docs/framework/fields/date-range.md

Renders a required date range picker with custom formatting and length constraints.

```php
echo ( new HivePress\Fields\Date_Range(
	[
		'name'           => 'custom_field',
		'label'          => 'Custom field',
		'format'         => 'Y-m-d',
		'display_format' => 'F j, Y',
		'min_length'     => 7,
		'max_length'     => 30,
		'required'       => true,
	]
) )->render();
```

--------------------------------

### Render header menu in header.php

Source: https://docs.hivepress.io/developer-docs/tutorials/integrate-your-theme-with-hivepress.md

Displays essential HivePress links and buttons like login and Add Listing in the site header.

```php
if ( function_exists( 'hivepress' ) ) {
	echo hivepress()->template->render_menu();
}
```

--------------------------------

### Render a menu with custom attributes

Source: https://docs.hivepress.io/developer-docs/framework/blocks/menu.md

Use this snippet to render a specific menu, such as the user account menu, while injecting custom CSS classes.

```php
echo ( new HivePress\Blocks\Menu(
	[
		'menu'       => 'user_account',

		'attributes' => [
			'class' => [ 'my-custom-class' ],
		],
	]
) )->render();
```

--------------------------------

### Hooking into user account menu

Source: https://docs.hivepress.io/developer-docs/tutorials/create-a-custom-hivepress-extension.md

Register the filter in the component constructor to modify the user account menu.

```php
add_filter( 'hivepress/v1/menus/user_account', [ $this, 'add_menu_item' ] );
```

--------------------------------

### Render a Password Field in PHP

Source: https://docs.hivepress.io/developer-docs/framework/fields/password.md

Renders a required password field with a custom label, placeholder, and a minimum length constraint.

```php
echo ( new HivePress\Fields\Password(
	[
		'name'        => 'custom_field',
		'label'       => 'Custom field',
		'placeholder' => 'Custom text',
		'min_length'  => 10,
		'required'    => true,
	]
) )->render();
```

--------------------------------

### HivePress\Fields\Textarea

Source: https://docs.hivepress.io/developer-docs/framework/fields/textarea.md

Instantiates and renders a multi-line text field.

```APIDOC
## HivePress\Fields\Textarea

### Description
Creates a multi-line text input field. Inherits all parameters from the Text field type.

### Parameters
- **name** (string) - Required - The field name.
- **label** (string) - Optional - The field label.
- **placeholder** (string) - Optional - The placeholder text.
- **max_length** (int) - Optional - Maximum character limit.
- **required** (bool) - Optional - Whether the field is required.
- **editor** (bool|array) - Optional - Set to true to enable rich text editor or provide an array of TinyMCE buttons.

### Example
```php
echo ( new HivePress\Fields\Textarea(
	[
		'name'        => 'custom_field',
		'label'       => 'Custom field',
		'placeholder' => 'Custom text',
		'max_length'  => 100,
		'required'    => true,
	]
) )->render();
```
```

--------------------------------

### Define a custom email class

Source: https://docs.hivepress.io/developer-docs/framework/emails.md

Create a new email class by extending the Email base class and defining default subject, body, and label metadata.

```php
<?php
namespace HivePress\Emails;

use HivePress\Helpers as hp;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

class Foo_Bar extends Email {
	public function __construct( $args = [] ) {

		// Set the default subject and message.
		$args = hp\merge_arrays(
			[
				'subject' => 'Custom subject',
				'body'    => 'Custom message with a %custom_token%.',
			],
			$args
		);

		parent::__construct( $args );
	}

	public static function init( $meta = [] ) {

		// Add details for the email editor.
		$meta = hp\merge_arrays(
			[
				'label' => 'My Custom Email',
			],
			$meta
		);

		parent::init( $meta );
	}
}
```

--------------------------------

### Render a Modal Window in PHP

Source: https://docs.hivepress.io/developer-docs/framework/blocks/modal.md

Creates a modal window with a specific title and inner content block. The 'name' parameter defines the anchor ID used to trigger the modal.

```php
echo ( new HivePress\Blocks\Modal(
	[
		'title'  => 'My Custom Text',
		'name'   => 'my_custom_modal',

		'blocks' => [
			'my_custom_block' => [
				'type'    => 'content',
				'content' => 'Hello World!',
				'_order'  => 123,
			],
		],
	]
) )->render();
```

--------------------------------

### Retrieve a custom setting value

Source: https://docs.hivepress.io/developer-docs/framework/configurations/settings.md

Fetches the value of a registered setting using the WordPress get_option function with the hp_ prefix.

```php
$value = get_option( 'hp_custom_option' );
```

--------------------------------

### Render a template block in PHP

Source: https://docs.hivepress.io/developer-docs/framework/blocks/template.md

Renders a specific template by name using the HivePress\Blocks\Template class.

```php
echo ( new HivePress\Blocks\Template(
	[
		'template' => 'listings_view_page',
	]
) )->render();
```

--------------------------------

### Limit and paginate results

Source: https://docs.hivepress.io/developer-docs/framework/models/making-queries.md

Control the number of returned results and handle pagination.

```php
$query->limit( 123 );
```

```php
$query->offset( 123 );
```

```php
$query->paginate( 123 );
```

--------------------------------

### Create a model-based form

Source: https://docs.hivepress.io/developer-docs/framework/forms.md

Use the Model_Form class to automatically inherit fields from a specific HivePress model.

```php
<?php
namespace HivePress\Forms;

use HivePress\Helpers as hp;

// Exit if accessed directly.
defined( 'ABSPATH' ) || exit;

class Foo_Bar extends Model_Form {
	public static function init( $meta = [] ) {
		$meta = hp\merge_arrays(
			[
				// Set the model name.
				'model' => 'listing',
			],
			$meta
		);

		parent::init( $meta );
	}

	public function __construct( $args = [] ) {
		$args = hp\merge_arrays(
			[
				// Set the fields to inherit.
				'fields' => [
					'title'       => [
						'_order' => 123,
					],

					'description' => [
						'_order' => 321,
					],
				],
			],
			$args
		);

		parent::__construct( $args );
	}
}
```

--------------------------------

### Render a Select field in PHP

Source: https://docs.hivepress.io/developer-docs/framework/fields/select.md

Renders a drop-down list with a specific name, label, and set of options, enforcing a requirement for selection.

```php
echo ( new HivePress\Fields\Select(
	[
		'name'     => 'custom_field',
		'label'    => 'Custom field',
		'required' => true,

		'options'  => [
			'one'   => 'One',
			'two'   => 'Two',
			'three' => 'Three',
		],
	]
) )->render();
```

--------------------------------

### Retrieve URLs

Source: https://docs.hivepress.io/developer-docs/framework/components/router.md

Methods for generating or retrieving current URLs, including support for route parameters and redirect logic.

```php
$url = hivepress()->router->get_current_url();
```

```php
$url = hivepress()->router->get_url( 'my_custom_route' );
```

```php
$url = hivepress()->router->get_url( 'listing_view_page', [ 'listing_id' => 123 ] );
```

```php
$url = hivepress()->router->get_return_url( 'my_custom_route' );
```

```php
$url = hivepress()->router->get_redirect_url();
```

--------------------------------

### User/Post/Comment/Term Specific Cache Methods

Source: https://docs.hivepress.io/developer-docs/framework/components/cache.md

Methods for managing cache scoped to specific entities like users, posts, comments, or terms.

```APIDOC
## Cache Methods for Entities

### Description
Methods such as `set_user_cache`, `get_user_cache`, `delete_user_cache` (and corresponding methods for `post`, `comment`, and `term`) allow scoping cache to specific entity IDs.

### Parameters
- **$id** (int) - Required - The ID of the user, post, comment, or term.
- **$key** (string) - Required - The cache key.
- **$group** (string) - Required - The group name (often the model name).
```

--------------------------------

### Accessing a component helper method

Source: https://docs.hivepress.io/developer-docs/framework/components.md

Call public methods of a component globally using the hivepress() function.

```php
$url = hivepress()->router->get_url( 'my_custom_route' );
```

--------------------------------

### Render a user registration form with custom attributes

Source: https://docs.hivepress.io/developer-docs/framework/blocks/form.md

Use this snippet to render a registration form with a custom CSS class, pre-filled email, and page refresh on success.

```php
echo ( new HivePress\Blocks\Form(
	[
		'form'       => 'user_register',
		'redirect'   => true,

		'values'     => [
			'email' => 'user@example.com',
		],

		'attributes' => [
			'class' => [ 'my-custom-class' ],
		],
	]
) )->render();
```
Tokens:
Raw