Skip to content

Version 5 Migration

Jump to bottom
Mat Lipe edited this page Jul 23, 2024 · 24 revisions

Version 5 is a major release with many breaking changes. This guide to show you how to migrate your project from version 4 to version 5.

Honestly, version 5 is a huge change. It may be easier to leave existing projects on version 4.9 unless you've got time on your hands.

Getting Started

The majority of changes have called out using _deprecated functions and phpdocs in version 4.10.0 of the library. It is recommended to follow this procedure before updating to version 5.

  1. Update to version 4.10.*
  2. Enable WP_DEBUG.
  3. Return true on the deprecated_class_trigger_error filter (if applicable).
  4. Run through your normal unit/regression testing and follow any prompts from the _deprecated system.

It may be wise to leave the project running version 4.10.* for a little while to make sure no deprecations where missed.

It is strongly recommended to use PHPStan to detect type inconsistencies as version 5 introduces a large number of strict types.

Table of Contents

New Requirements

  • WP Core version 6.3+ is now required.
  • PHP version 8.1+ is now required. Version 4.10.0 introduced this requirement so if you followed Getting Started you are already on PHP 8.1.

Classes Removed With No Alternative

Some classes have been removed entirely with no alternative available. To continue to use these classes, you'll want to copy them into your project.

  1. \Lipe\Lib\Util\Image_Resize

Classes Removed With Alternative

Some classes have been refactored into composition instead of inheritance. Using the new version will require some refactoring but the majority of the original functionality has been maintained.

  1. \Lipe\Lib\Schema\Db -> Use \Lipe\Lib\Db\Custom_Table See
  2. \Lipe\Lib\Schema\Meta_Box -> Use \Lipe\Lib\Meta\Meta_Box
  3. \Lipe\Lib\Schema\Post_List_Column -> Use \Lipe\Lib\Post_Type\Post_List_Column
  4. \Lipe\Lib\Schema\Settings -> Use \Lipe\Lib\Settings\Settings_Page
  5. \Lipe\Lib\Cron\Cron_Abstract -> Use \Lipe\Lib\Cron\Runner
  6. \Lipe\Lib\Query\Args_Abstract => Use \Lipe\Lib\Args\Args
  7. \Lipe\Lib\Query\Clause\Clause_Abstract -> Use \Lipe\Lib\Args\Clause
  8. \Lipe\Lib\Meta\Translate_Abstract -> Use \Lipe\Lib\Meta\Translate_Abstract
  9. \Lipe\Lib\Query\Update_Post -> Use \Lipe\Lib\Post_Type\Wp_Insert_Post
  10. \Lipe\Lib\Query\Args -> Use \Lipe\Lib\Query\Query_Args

Classes With Changed Signature

Some classes remain but have slightly to massively changed signatures. Existing code may be affected by the changes. This only applies to classes which are accessed directly. You may see some PHP fatal errors related to these classes which should be easy to locate and mitigate. The best approach to migrating is to use PHPStan to detect missing properties or methods and look for similar elements on the same class.

  1. \Lipe\Lib\Taxonomy\Taxonomy
  2. \Lipe\Lib\Post_Type\Custom_Post_Type
  3. \Lipe\Lib\CMB2\Group
  4. \Lipe\Lib\Api\Route
  5. \Lipe\Lib\Api\Zip
  6. \Lipe\Lib\Query\Args_Interface
  7. \Lipe\Lib\CMB2\Field
  8. \Lipe\Lib\CMB2\Group

Methods Removed With Alternative

Some methods have been removed with an alternative avaiable.

  1. \Lipe\Lib\Theme\Resources::defer_javascript -> Use wp_script_add_data( $handle, 'strategy', 'defer' );
  2. \Lipe\Lib\Theme\Resources::async_javascript -> Use wp_script_add_data( $handle, 'strategy', 'async' );

Schema Namespace Is No More

The \Lipe\Lib\Schema namespace contained classes which were a throwback to a time before PHP provided the necessary tools to implement strict composition and type validation. Even the name "Schema" is confusing because since it was created JSON schema has become the standard when using the "Schema" terminology.

Each class in this namespace as been removed with a similar class using the a composition pattern has taken its place. If you are heavily using a class from "Schema" it may be easier to move the class from version 4.9.0 into your project. Otherwise the @deprecated or _deprecated_class will point you to the new class.

\Lipe\Lib\Schema\Db Class Has Been Refactored To \Lipe\Lib\Db\Custom_Table

The Db class has been converted from abstract to composition. The general looseness of the class has been converted to strict, static analyzable values. For projects verbosely using this class is may be easier to copy the class from version 4.9.* into your project as a refactor will be intensive.

For most accurate refactoring, pass the available generics and let PHPStan be your guide. The new Custom_Table class supports full static analysis, so phpstan reports will help tremendously.

  • Tables now require the \Lipe\Lib\Db\Table interface.
  • Class constants are no longer honored.
  • 3 new generics have been introduced on the Table interface.
    1. FORMATS used for both the interface and Custom_Table class.
    2. COLUMNS mimic what the COLUMNS class constant used to be.
    3. PARTIALS can by \Partial<COLUMNS>. Required due to limitations with phpstan and utility types.
  • The $columns parameter is no longer available in any methods except get_select_query.
  • get_* methods now return a single type of result instead of changing via $count and $columns.
  • The $where parameter now only accepts an array.
  • The result of get_* methods is not an associative array instead of an object or array of objects.
  • create_table is no longer called automatically and must be managed within your project.
  • Returned values from get_* are now formatted to match the result of the get_column_formats formats instead of string for everything.

To return a single column from the database

The Custom_Table class uses composition so you may create a method in your own class to return a custom column. Here is an example method which returns a single column from results and remains static analyzable.

/**
 * @phpstan-type COLUMNS array{
 *     ID: int,
 *     ip: string,
 *     count: int,
 *     date: string
 * }
 * @phpstan-type FORMATS array{
 *     ID: "%d",
 *     ip: "%s",
 *     count: "%d",
 *     date: "%s"
 * }
 *
 * @implements Table<FORMATS, COLUMNS, \Partial<COLUMNS>>
 */
class Db implements Table {
	/**
	 * @phpstan-param \Partial<COLUMNS> $wheres
	 * @return string[]
	 */
	public function get_branch( array $wheres, ?int $count = null ): array {
		global $wpdb;
		$query = $this->db()->get_select_query( [ 'branch' ], $wheres, $count );
		return $wpdb->get_col( $query, 'ARRAY_A' );
	}


	/**
	 * @phpstan-return Custom_Table<Db>
	 */
	private function db(): Custom_Table {
		return Custom_Table::factory( $this );
	}
}
Clone this wiki locally