Using the PHP API

Overview

In Ultimate Fields you can create a container and add fields to it both through the administration interface (the "Ultimate Fields" section in the back-end) and through the PHP API.

The PHP API allows you to create and setup your containers and fields by using PHP functions and classes, but without having to use the administration interface at all. If you choose to use it, you can experience various performance and portability benefits.

Important

This article explains how to use the API to create fields. Using field values is about using field values in the front-end.

Workflow

No matter which method of creating fields you choose (code vs UI), the steps which you need to perform are very similar:

1. Create a container
2. Setup the container
3. Add a location/locations to the container, while setting them up
4. Add fields to the container, while also setting them up.

Generic structure

The standard declaration of a container with PHP looks like the code below.

<?php
use Ultimate_Fields\Container;
use Ultimate_Fields\Field;

add_action( 'uf.init', 'theme_register_fields' );
function theme_register_fields() {
    Container::create( 'container_id' )
        ->add_location( 'post_type', 'post' )
        ->add_fields(array(
            Field::create( 'text', 'field_name' )
        ));
}

Namespaces

The first thing to keep in mind when using Ultimate Fields is that the plugin uses PHP namespacing. This means that you should declare the classes that you are about to use before you actually use them.

Even though Ulltimate Fields includes a lot of classes, you will have direct interaction mainly with just of them. Those classes are Container and Field, which you should use with the UF namespace in the beginning of your file:

use Ultimate_Fields\Container;
use Ultimate_Fields\Field;

Afterwards you can refer to the classes as simply Container and Field, without having to prefix them.

Info

If you are not familiar with namespaces, we recommend that you read the Namespaces article from the PHP documentation.

The uf.init action

When you create containers with Ultimate Fields, you should always use the uf.init action. This ensures that even if Ultimate Fields is not active, your theme/plugin will not generate errors by trying to use functionality, which is not yet available.

add_action( 'uf.init', 'theme_register_fields' );
function theme_register_fields() {
	// Add your containers here
}

In the example we are creating a new function called theme_register_fields. The name of this function is not important for Ultimate Fields, as it's only needed for the WordPress plugin API.

Method chaining

Most classes in Ultimate Fields utilize the method chaining mechanism. In object-oriented programming this means that a method of a class returns the current instance of that class after performing its actions.

Please take a look at the following example, ignoring the actual class and method names (we will do this in a bit).

$container = new Container( 'my_container' );
$container->set_title( __( 'My container' ) );
$container->set_style( 'seamless' );
$container->add_location( 'post_type', 'post' );

In this case, we are instantiating a class and calling three methods of the object. In Ultimate Fields, most methods which do not start with get_*, like set_* or add_* return the object, which means that the example can be transformed this way:

Container::create( 'my_container' )
    ->set_title( __( 'My container' ) )
    ->set_style( 'seamless' )
    ->add_location( 'post_type', 'post' );

What happened here:

1. We are using Container::create instead of new Container. The reason for this is that PHP does not allow automatic method calls after using the new keyword. The static create method accepts the same arguments, but returns the new instance and allows you to directly call the methods of the container.
2. Instead of using the $container variable for every method, we are directly using the returned value of the previous method and invoking the new method.

If you have already used jQuery, you will find this technique very familiar.

Creating the container

Creating a container is done through the the static create method of the Container class. The container class is the hub, which connects locations and fields together. The create method simply returns a newly instantiated container, so that you can use method chaining.

The first argument for the container is an identifier. Unique identifiers must be used for every container, in order to avoid conflicts. By default, the ID of the container will be used in order to automatically generate a title for the container. For example, using the container ID my_container will result in My Container being used as the title for it.

For all settings and methods, available for containers, please read the Container Settings article.

Once the container is created, you can call various methods in order to set it up, for example set_title if you want to use a title, different from the auto-generated one:

Container::create( 'my_container' )
    ->set_title( __( 'My container ) )

Adding locations

Locations can be added to containers through the add_location method, like this:

$container->add_location( 'post_type', 'post' [, $args = array() ]);

What add_location does is to locate the needed location class, used in the first parameter, and initialize it with the rest of the parameters, given to the method. If you instantiate a location by yourself, you can directly pass it to the method.

A more detailed explanation of the way to use and manipulate locations, check out the Locations article.

Adding fields

Fields can be added to containers through the add_field and add_fields methods.

The Fields chapter describes all possible types of fields and their methods.

Fields can be created through the create method of the Field class. It receives the field type as a first parameter (ex. text) and its name as the second parameter.

$field = Field::create( 'text', 'field_name' );
$container->add_field( $field );

or

$container->add_fields(array(
	Field::create( 'text', 'field_name' )
));

But why?

Choosing to use the PHP API instead of the administration interface can benefit you in multiple ways:

Better code portability

Since containers and fields are stored in PHP, no database migrations or synchronizations are needed - the code is just there.

Slightly improved perfomance

The administration interface requires additional code and database calls, which are not required anymore.

Flexibility

As good as the administration interface is, it requires you to go the admin, open the "Ultimate Fields" section, locate the container and so on. When you use code, navigating to the file, which contains the fields and containers is a keyboard shortcut away in most editors.

With that in mind, if you are just starting to use Ultimate Fields, we recommend that you use the administration interface. This way you can get to familiarize yourself with the plugin and its functionality before having to learn and new functions, classes and methods.