Migrating configurations from INI files

Introduction

Infinity versions 1.2 and higher have a new configuration syntax which does not use INI files. You may need to migrate custom configurations to the new syntax.

Should I be worried about this?

If you are a theme developer that is migrating an Infinity theme fork, or an Infinity child theme to be compatible with version 1.2 or higher, then yes.

How do I know if I need to take action on this?

If you edited the bundled INI configuration files, or added your own overriding INI files, you will need to convert only the specific options you changed or overrode to the new syntax. Don't worry, it's super easy.

What happened to using INI files, anyways?

Originally, INI files were chosen to make it easy for developers to add additional configurations and modify existing ones. Two things occurred that made INI files no longer a good choice for this:

1. Quite a few people complained that it wasn't possible to translate the strings in the INI files. We didn't think this would ever be an issue... but when developers started putting default string values for options which would appear on the front end, it became a real problem.

2. The WordPress theme-check plugin added the PHP functions which load and parse INI files to their black list of disallowed functions due to the fact that they open files directly from disk. This prevents any Infinity based themes from being accepted into the WordPress.org free theme directory.

Old vs New Syntax

The following is an overview which compares the old syntax to the new syntax. Each would give identical results.

INI configuration syntax

This is example INI syntax for a Splash Image Position option:

; The My Homepage feature is configured only once.
[infinity-myhomepage-images]
type = "default";
title = "My Homepage Images";
description = "My custom homepage images.";
options.section = "homepage";

; An image position option.
[infinity-myhomepage-images.splash-image-pos]
section = "homepage";
title = "Splash Image Position";
description = "Choose on which side you want to display the splash image.";
type = "radio";
default_value = "left";
field_options[] = "left=Left";
field_options[] = "right=Right";

The value of this options was previously retrieved with this API function call:

<?php

// Notice how the entire feature name had to be included (yuck)
$pos = infinity_option_get( 'infinity-myhomepage-images.splash-image-pos' );

?>

ICE API configuration syntax

This is the PHP code which uses the ICE (Infinity Component Engine) for the Splash Image Position option:

<?php

// My Homepage group (configured only once)
// This creates the group (also a namespace) named "myhomepage" which allows features and options to share stored values easily.
ice_register_group( 'myhomepage' );

// My Homepage feature (configured only once)
// This creates the feature named "images" in the "myhomepage" group, which can then have options assigned to it.
ice_register_feature(
	array(
		'group' => 'myhomepage',
		'name' => 'images',
		'type' => 'default',
		'title' => 'My Homepage Images',
		'description' => 'My custom homepage options.'
	)
);

// The Splash Image Position option
ice_register_option(
	array(
		'group' => 'myhomepage',
		'required_feature' => 'images',
		'name' => 'splash-image-pos',
		'section' => 'homepage',
		'title' => 'Splash Image Position',
		'description' => 'Choose on which side you want to display the splash image.',
		'type' => 'radio',
		'default_value' => 'left',
		'field_options' => array(
			'left' => 'Left',
			'right' => 'Right'
		)
	)
);

?>

The feature must be enabled using add_theme_support() as shown here:

<?php

// Notice the group name and the feature name.
// You can enable multiple features for the same group by adding additional arguments.
add_theme_support( 'infinity:myhomepage', 'images' );

?>

The value of the option can now be retrieved with this API function call:

<?php

// Notice how only the group and option name are used.
// It is no longer necessary or valid to include the feature name.
$pos = infinity_option_get( 'myhomepage.splash-image-pos' );

?>

Overriding existing option configurations

If you are working with an Infinity fork or child theme, you may have the need to override options which have been configured by Infinity core, or the parent theme. This is extremely easy to do!

In this example we are overriding the default favicon and header logo image by hooking into the infinity_config_loaded action which is called immediately after Infinity has loaded all of the configuration files, but before it actually spins up the components that were defined.

<?php

/**
 * Tweak some option settings after core config has been loaded.
 */
function my_customize_options()
{
	// Calling ice_register_option() with only the parameters you want to
	// override is all you need to do in order to modify the configuration.
	//
	// Important:
	// The 'group' and 'name' arguments are required and must *exactly* match
	// the original config that you are trying to modify.

	// use a custom favicon
	ice_register_option(
		array(
			'group' => 'core',
			'name' => 'custom-favicon',
			'default_value' => 'assets/images/my-favicon.png'
		)
	);

	// use a custom header logo
	ice_register_option(
		array(
			'group' => 'header-logo',
			'name' => 'image',
			'default_value' => 'assets/images/my-logo.png'
		)
	);
}
add_action( 'infinity_config_loaded', 'my_customize_options' );

?>