Version refs/tags/4.4.0

4.4.0

Version refs/tags/4.3.0

4.3.0

Version 4.1.2

4.1.2

Version 4

Major Version Update With Breaking Changes

Upgrade process:

1. Update to latest version 3.
2. Enable WP_DEBUG.
3. Resolve any deprecated notices and warnings.
4. Update to version 4.0.0.

Full notes for upgrading are here.

Maintainers

• @lipemat

New Contributors

• @migueliriano made their first contribution in #4

Full Changelog: 3.15.0...4.0.0

Version 3.1.0

Introduce add_looping_action on Actions class

WordPress supports short circuiting various methods using filters to allow handling the process in an external way. Sometimes you need to call the original API to run your external process.

Complications arise when the short circuit is part of original API as you end up in an endless loop. A common case for this would be special handling of metadata. This is where the add_looping_action and its partner method add_looping_filter come in. These methods automatically handle the register, unregister, and re-register process to prevent infinite loops.

Remove $accepted_args Requirement From Actions Class

The filters system supports a 4th argument to specify how many arguments will be passed to the callback's parameters. Omitting this argument will only pass the first argument to the callback.

Failure to specify a large enough number of accepted arguments will prevent your callbacks parameters from populating, but specifying too large a number has virtually no side effects. For this reason, all methods in the Actions class no longer have an acccepted_args parameter and will automatically pass the first 10 arguments to callbacks.

Fix Versions Sorting

PHP8 changed the way version_compare functions when an operator is used for sorting. version_compare will return bool instead of int when using an operator. It's best to sort using the returned int instead of using an operator in PHP8. For this reason we have updated the Versions class to no longer use an operator and therefore fix a bug with PHP8.

Simplify Cache Posts Group Handling

Instead of using our own cache constant for specifying we want a group's cache to be flushed when a post is updated then translating it back to posts, we removed the middleman. Now the constant's value is posts and will continue to function the same way without the extra logic.

Introduce Initial_Data::is_retrieving method

Sometimes you need to adjust the REST responses specifically when doing the initial render of the data to wp_localize_script. Instead of cluttering up the template by adding a filter directly to it, you now have a method to use directly in the filter's callback. The method will return true if currently rendering initial data.

Support Setting Object Properties Within Mutator_Trait

Previously you were able to retrieve any property from the retrieved object using the magic __get method. Now there is a partner __set magic method for setting any of the objects properties as well.

Both the __get and __set methods now support retrieving and setting properties on the objects data property as well.

Introduce Styles::crossorigin_javascript Method

Like the previously existing defer_javascript and async_javascript this method adds a simple way to add a "crossorigin" attribute to script tags. If no value is passed it will add a crossorigin flag to the tag, otherwise the crossorigin will be set to the provided value.

Misc

• Prevent sanitization_cb from doubling within the meta repo.
• Properly store encryption 'iterations' for maintainability.
• Fixed Comment_Trait @Property types.
• Improved PHPStan validations.

Version 3

Version 3 of WordPress Libs is now stable and ready for general use. This is a major version update with breaking changes so be sure to read on before you update existing projects.

You may have noticed that we have not written a release article in a while although a few minor versions have been released. The last few versions were all slowing integrating the new WordPress systems and preparing for version 3.

Purpose

It has been almost exactly 2 years since version 2 was release. Since that time we have maintained backward compatibility with every change. Over time we accumulated a lot of deprecated methods, actions, and classes. Version 3 does not initially add any new features, but instead cleared out all the previously deprecated code and gives us a fresh starting point to start adding new code.

Requirements

We updated the requirements for PHP and WordPress core to more recent versions so we can start tapping into modern abilities.

The majority of WordPress sites are now on PHP version 7.4 so there will be very little impact from the new PHP version requirement.

It is unlikely that sites using legacy version of WordPress core are actively updating their development dependencies so we expect very little impact from the new WordPress version requirement.

1. The minimum WordPress core version is now 5.5.0.
2. The minimum PHP version is now 7.3.0.

If you plan to stay on version 2 due to PHP version or WP version limitations, you'll likely want to lock your project to ^2.24.2.

Migration

To assist in migration we properly deprecated everything within version 2.24 which was removed in version 3. Using the built in WordPress deprecation handlers, we enabled notices anytime a deprecated item is used.

To being migration, lock your project to version ^2.24.2 and set your WP_DEBUG constant to true. Using your site like normal and/or running your unit tests will automatically start displaying notices for anything which no longer exists on version 3

If you still need something that was deprecated, you must copy it into your own code before updating.

Once you have resolved all deprecations, you are ready to update to version 3.

Note: It is recommended not to enable WP_DEBUG on production environments as the deprecated notices will be shown to your users.

Flashlight for final V2 version

This will be the final V2 dot release

All items which will be removed in V3 have now been wrapped in _deprecated functions to log uses when WP_DEBUG is true. Use this version to get your codebase ready for V3.

https://github.com/lipemat/wordpress-libs/wiki/Version-3-Migration

If you plan to stay on V2 due to PHP version or WP version limitations, you'll likely want to lock your project to 2.23.1.

CMB2 2.7.0, Array enhancements, Bugfixes and compatibility.

Version 2.17.0 of WordPress Libs is now available for public use. This release focused on getting everything ready for CMB2 version 2.7.0. It also includes many bug fixes and compatibility improvements.

CMB2 2.7.0

CMB2 released version 2.7.0 back in January. Since it took a year for that release to be ready, we wanted to wait a while to make sure there were not going to be any quick follow-up bug fixes before we implemented it. Now that we are confident it is ready for prime time, we’ve added support for the new features.

display_class field parameter

The Field class now contains the display_class property to assign an entirely custom class to use for rendering within admin columns and likewise. As a custom display class should extend the CMB2_Field_Display class, we’ve typed this property appropriately.

register_rest_field_cb box paramter

The Box class now contains the register_rest_field_cb property to replace the registering of the rest fields for the particular box. Used when an entirely custom response is desired.

char_counter field parameters

A new char_counter method has been added to the Field class which takes care of the heavy lifting when adding a character counter to a field. Character counters are now supported on textarea, text, or wysiwyg type fields.

	/**
	 * Enable a character/word counter for a 'textarea', 'wysiwyg', or 'text' type field.
	 *
	 * @param bool $count_words – Count words instead of characters.
	 * @param null|int  $max – Show remaining character/words based on provided limit.
	 * @param bool  $enforce – Enforce max length using `maxlength` attribute when
	 *                       characters are counted.
	 * @param array $labels  – Override the default text strings associated with these
	 *                       parameters {
	 *                          'words_left_text' – Default: "Words left"
	 *                          'words_text' – Default: "Words"
	 *                          'characters_left_text' – Default: "Characters left"
	 *                          'characters_text' – Default: "Characters"
	 *                          'characters_truncated_text' – Default: "Your text may be truncated."
	 *                       }
	 *
	 * @notice Does not work with wysiwyg which are repeatable.
	 *
	 * @since CMB2 2.7.0
	 *
	 * @return Field
	 */
	public function char_counter( $count_words = false, $max = null, $enforce = false, $labels = [] ) : Field {
		$this->char_counter = $count_words ? 'words' : true;

		if ( $max ) {
			$this->char_max = $max;
			if ( $enforce ) {
				if ( 'words' === $this->char_counter ) {
					\_doing_it_wrong( 'char_counter', __( 'You cannot enforce max length when counting words', 'lipe' ), '2.17.0' );
				}
				$this->char_max_enforce = true;
			}
		}

		if ( ! empty( $labels ) ) {
			$this->text = array_merge( (array) $this->text, \array_intersect_key( $labels, array_flip( [
				'words_left_text',
				'words_text',
				'characters_left_text',
				'characters_text',
				'characters_truncated_text',
			] ) ) );
		}

		return $this;
	}

The method accepts the following arguments:

1. bool $count_words – By default the field will count characters; if you would like it to count words, pass true.
2. int $max – If set, this will count down the characters/words until maximum is reached.
3. bool $enforce – If we are counting characters, you may force the field to only allow the specified $max.
4. array $labels – Override the labels used for various states throughout the counting process.

Support taxonomy_select_hierarchical field type

The Field_Type class now contains mappings for the new taxonomy_select_hierarchical field. It functions the same as the previously existing taxonomy_select field except the hierarchy is indented on display.

/**
	 * A select field pre-populated with taxonomy terms and displayed hierarchical.
	 *
	 * @param string $taxonomy       – slug
	 * @param string $no_terms_text
	 * @param bool   $remove_default – remove default WP terms metabox
	 *
	 * @todo Add links once docs become available.
	 *
	 * @since CMB2 2.7.0
	 *
	 * @return Field
	 */
	public function taxonomy_select_hierarchical( $taxonomy, $no_terms_text = null, $remove_default = null ) : Field {
		$_args = $this->field_type_taxonomy( $this->taxonomy_select_hierarchical, $taxonomy, $no_terms_text, $remove_default );

		return $this->set( $_args, Repo::TAXONOMY_SINGULAR );
	}

Add disable_sorting parameter to column method

CMB2 now supports sorting the post list by column by default. This may be disabled per field by passing a disable_sortable to the column arguments. You may now set $disable_sorting to true using the method to disable sorting.

New array_map_assoc method

The Arrays class now contains an array_map_assoc method which automatically passes the array key as the second argument to the specified callback and preserves the original keys.

	/**
	 * Works the same as `array_map` except the array key is passed as the
	 * second argument to the callback and original keys are preserved.
	 *
	 *
	 * @param callable $callback
	 * @param array    $array
	 *
	 * @since 2.17.0
	 *
	 * @return array
	 */
	public function array_map_assoc( callable $callback, array $array ) : array {
		return array_combine( array_keys( $array ), array_map( $callback, $array, array_keys( $array ) ) );
	}

Settings Trait now supports a callback during update_option

Building off of the support already available with the Mutator_Trait you may now pass a callback as the $value argument of update_option. This callback will receive the previous value as an argument and should return the new value.

Persistent Memoize Method

Introducing Memoize::persistant

Simple persistent value caching using the object cache is now available via the Memoize trait using the persistent method.

Same functionality as the Memoize::memoize with the different of being persistent across runs. The data is automatically added to the object cache for the specified length of time and will pull from the cache if the arguments are the same for the life of the cache.

Replaces the boilerplate "check cache" if empty "retrieve data" then "add to cache".

   public function get_something_this_is_normally_the_same( $version, $option ) : array {
   	return $this->persistent( function ( $version, $option ) {
   		return [
   			'version' => $version,
   			'option' => $option,
   		];
   	}, __METHOD__ , 0, $version, $option );
  }

CMB2 and Meta Enhancements

Open last used tab after saving CMB2 options page with tabs.

Now saving option pages with tabs will bring you back where you left off after saving instead of reloading with the first tab active.

Support selectively enabling CMB2 fields in rest API.

Leaving show_in_rest set to false on a box and setting it to
a truthy value on a field now automatically sets the box to true
and false for any non specified field.

Introduce new show_in_rest method to the Field class.

Meta repo enhancements

Fallback to default meta handling for non registered meta fields.

Previously to access the meta data from classes using the Mutator trait, you were required to register the field with CMB2 using the helper classes. Now, registering the fields is optional.

You may access any meta data field registered or not using the same methods or array access and repo will fall back to the default WordPress get_metadata automatically.

Add support for accessing an object properties directly.

The various object type traits which extend the mutator trait have now been enhanced to allow for accessing their object properties directly. For instance when using the Post_Object_Trait you may access any of the $post properties directly.

The only requirement for this functionality to work, is the class using the mutator trait must have a get_object() method which returns the object who's properties you want to access. To honor this pattern the previous methods such as get_post(), get_user(), get_term(), etc. have been deprecated in favor of using get_object() on each.

Call defined escape_cb or sanitize_cb arguments when accessing meta values.

When registering CMB2 fields we may specify escape_cb for retrieval and sanitize_cb for saving. Typically these callbacks are only called during meta box saving or retrieval.

The meta repo now honors both these callbacks during get or update. If a callback is not specified the meta repo continues without sanitization or escaping like before.