Package Developers: Upgrading Your Packages for Version 8

This tutorial is over a year old and may not apply to your version of Concrete CMS.
May 20, 2016

Concrete CMS version 8 adds a lot of user-facing improvements, but also refactors a number of classes under the hood. Your package could be affected. In general, we're really trying to make this version fully backward compatible, but it's not always possible. With that in mind, here are some fixes to common issues that may strike your add-ons and themes as you install them on concrete v8.

Important Note: This is a work in progress. If you have employed a particular method to make a package compatible with version 8 while retaining backward compatibility, please edit this tutorial with your ideas.

Avoid Type-Hinting Package in your Methods

The Concrete\Core\Package\Package class was a massive beast. In version 8 it is being split into many other files. Consequently, you should no longer type-hint your installation methods against Concrete\Core\Package\Package because you might be working with an alternate object. Consider this code, which works in version 7:

public function installStore()
{
    $pkg = Package::getByHandle('community_store');
    Installer::installSinglePages($pkg);
}

And in the Installer class

public static function installSinglePages(\Concrete\Core\Package\Package $pkg)

Unfortunately, Package::getByHandle() now returns an entity object (Concrete\Core\Entity\Package) instead of the service object found at Concrete\Core\Package\Package.). So the type hint will fail.

Solution

Simply remove the type hint. Obviously, stricter code could type-hint with the entity object instead, but then that renders your code unusable in 5.7.x. The easiest and most compatible code simply removes the type hint, resulting in this:

public static function installSinglePages($pkg)

Creating thumbnails types programmatically

In 5.7, you would use the Concrete\Core\File\Image\Thumbnail\Type\Type class to create thumbnails. In 5.8, this has been replaced by the Concrete\Core\Entity\File\Image\Thumbnail\Type\Type class.

These are some of the errors you may get: Undefined method Concrete\Core\File\Image\Thumbnail\Type\Type::setName() Undefined method Concrete\Core\File\Image\Thumbnail\Type\Type::setHandle() Undefined method Concrete\Core\File\Image\Thumbnail\Type\Type::setWidth()

Solution

Simply replace the old class with the new one in your code. Have a look at the "Keeping backward compatibility in your code" section on this page if you need your code to work in both version.

Keeping backward compatibility in your code

Concrete 5.8 is a backward compatible. However, in some cases you'll need make some updates in your code. In those cases, to ensure backware compatibility, you can add the following function to your package:

if (!function_exists('compat_is_version_8')) {
    function compat_is_version_8() {
        return interface_exists('\Concrete\Core\Export\ExportableInterface');
    }
}

Then you can use that function in your if statements:

if ( compat_is_version_8() ) {
    //code for version 8
}
else {
    //code for version 7
}

More Coming Soon

This tutorial is unfinished. I am posting it now, but I'd love to have community additions to it as more backward compatibility tweaks are made to your code bases.

Recent Tutorials
WebOps Tutorial on Running and Upgrading a Concrete CMS Website
May 2, 2024
By myq.

Describes how to deploy, manage, and upgrade a Concrete CMS website

Using the Concrete Migration Tool Addon
Apr 27, 2024

How to use the Concrete CMS Migration Tool

Create custom Site Health tasks
Apr 19, 2024
By myq.

This tutorial will guide you through the creation of a new Site Health task

Reusing the same Express entity in multiple associations
Apr 11, 2024
By myq.

How to create and manage multiple associations in Express

Express Form Styling
Apr 11, 2024
By myq.

Different ways to style Express forms

Setting addon/theme version compatibility in the marketplace
Jan 9, 2024

For developers worn out with setting the latest addon or theme version manually across too many core versions, here is a JavaScript bookmarklet to do it for you.

Improvements?

Let us know by posting here.