From 4.x to 5.0

CKEditor

The editor has been updated to version 5. This brings some new features (like mentions and images in content) but also impacts existing plugins. Most notable are The Wire (which now also has mention support) and the removal of the Embed plugin.

The related ‘longtext’ menu is no longer available.

Composer

PHP Requirements

The minimal PHP version is now 8.0.

Faker

The faker library is no longer maintained by fzaninotto so we switched to a fork which is maintained by FakerPHP.

Events and Hooks

These two similar concepts have been merged and from now on we will only refer to events. The public service hooks no longer exists. All hooks can now be registered in the events section of your plugin. If you use hook callbacks that expect a type hinted ElggHook argument you will need to update this to ElggEvent.

Create event

The create, <object|group|user|site> events can no longer be used to prevent the creation of the entity. Use create:before if you wish to prevent the creation.

Private Settings

The concept of private settings has been removed from the system. All private settings have been copied to metadata. All related functions have been removed.

Upgrades

Async or system upgrades are no longer classes that implement interfaces but extend abstract classes. Update your upgrades to extend the correct classes. The reason for this change is to be able to access the ElggUpgrade entity from the Batch that runs a part of the upgrade. You can access the upgrade by calling $this->getUpgrade().

Session

If you use the session service directly (or via elgg_get_session()) you might need to update your code. Various functions of this class have been moved to the elgg()->session_manager service.

Gatekeepers

The PageOwnerCanEditGatekeeper middleware now requires a pageowner to be set. This gatekeeper now also requires a logged in user at all times.

Files plugin

Files uploaded using the file plugin are no longer stored with the owner but with the file entity. File icons have also been changed. Icon images are only available for image file types. Icon sizes have been changed to use the default icon sizes.

Embed plugin

The embed plugin has been removed.

Javascript

Hooks system

The javascript hook functions have been moved to an AMD module. If you used javascript hooks than you need to update your code to use the elgg/hook module. The concept of ‘instant hooks’ is no longer present in the system.

The 'init', 'system' event is no longer triggered in javascript.

Removed functions

  • elgg.is_in_object_array

  • elgg.is_instant_hook

  • elgg.is_triggered_hook

  • elgg.push_to_object_array

  • elgg.register_hook_handler use the register function provide by the elgg\hooks module

  • elgg.register_instant_hook

  • elgg.set_triggered_hook

  • elgg.trigger_hook use the trigger function provided by the elgg\hooks module

Exceptions

The uses of exceptions in Elgg has been revisited. The \Elgg\Exceptions\InvalidParameterException has been removed and replaced with the correct exception. Also the use of the \Elgg\Exceptions\InvalidArgumentException has been checked. In some cases the exception was replaced by a more appropriate exception.

ElggRiverItem

It’s no longer allowed to set arbitrary data during runtime on an ElggRiverItem. Since the data was only available during runtime and not saved to the database this distinction has been removed. When setting an unsupported attribute an \Elgg\Exceptions\RuntimeException is thrown.

// this is allowed
$item = new \ElggRiverItem();
$item->subject_guid = elgg_get_logged_in_user_guid();

// this is no longer allowed (causes an \Elgg\Exceptions\RuntimeException)
$item = new \ElggRiverItem();
$item->foo = 'bar';

Metadata options in getter functions

Previously there was a magic that would turn the metadata_value string into an array if it contained an ,.

This magic has been removed. You now need to provide the array yourself. Because of this magic it was impossible to query for a metadata value that contained an ,.

// previously
$options = [
        'metadata_name_value_pairs' => [
                'some_name' => 'some_value1, some_value2',
        ],
];

// would result into, thus giving it an OR value
$options = [
        'metadata_name_value_pairs' => [
                'name' => 'some_name',
                'value' => [
                        'some_value1',
                        'some_value2',
                ],
                'operand' => '=',
        ],
];

Changes in functions

The following functions now have their arguments and/or return types type-hinted, this can cause TypeError errors. Also some class functions have their return value type hinted and you should update your function definition. Some function might have their arguments changed or the return type has been changed.

Lib functions return types

  • elgg_add_admin_notice() now returns null on failure instead of a bool

  • elgg_create_river_item() now returns null on failure or an ElggRiverItem

  • elgg_delete_metadata() no longer returns null

  • elgg_delete_river() no longer returns null

  • elgg_deprecated_notice() no longer returns bool

  • elgg_generate_entity_url() now returns null on failure instead of a bool

  • elgg_generate_url() now returns null on failure instead of a bool

  • elgg_get_annotation_from_id() now returns null if no annotation is found instead of a bool

  • elgg_get_download_url() now returns null if there is an error

  • elgg_get_entity_as_row() now returns null if no entity is found instead of a bool

  • elgg_get_entity_dates() no longer returns a bool

  • elgg_get_form_footer() no longer returns a bool

  • elgg_get_inline_url() now returns null if there is an error

  • elgg_get_metadata_from_id() now returns null if no metadata could be found

  • elgg_get_page_owner_entity() now returns null if page owner could not be found

  • elgg_get_river_item_from_id() now returns null if no river item could be found

  • elgg_get_system_cache() now returns an instance of \Elgg\Cache\BaseCache instead of an \ElggCache

  • elgg_get_uploaded_file() now returns null if no file could be found or the file was invalid

  • elgg_normalize_site_url() now returns null when the url is not a site url

  • elgg_register_action() no longer returns a bool

  • elgg_register_menu_item() no longer has a return value

  • elgg_register_widget_type() no longer has a return value

  • elgg_set_form_footer() no longer has a return value

  • elgg_trigger_after_event() no longer has a return value

  • elgg_unregister_action() no longer has a return value

  • elgg_unregister_event_handler() no longer has a return value

  • elgg_unregister_notification_event() no longer has a return value

  • elgg_unregister_notification_method() no longer has a return value

  • elgg_unregister_widget_type() no longer has a return value

  • elgg_view_annotation() no longer returns a bool

  • elgg_view_comments() no longer returns a bool

  • elgg_view_list_item() no longer returns a bool

  • elgg_view_relationship() no longer returns a bool

  • get_entity() now returns null if no entity is found instead of a bool

  • get_user() now returns null if no user is found instead of a bool

  • elgg_ws_expose_function() no longer returns a bool

Lib functions function parameters

  • blog_prepare_form_vars() now requires a ElggBlog for $blog and a ElggAnnotation for $revision

  • bookmarks_prepare_form_vars() now requires a ElggBookmark for $bookmark

  • discussion_prepare_form_vars() now requires a ElggDiscussion for $topic

  • elgg_add_action_tokens_to_url() now requires a string for $url and a bool for $html_encode

  • elgg_can_edit_widget_layout() now requires a string for $context and int for $user_guid

  • elgg_clear_event_handlers() now requires a string for $event and $type

  • elgg_clear_sticky_form() now requires a string for $context

  • elgg_create_widget() now requires an int for $owner_guid and $access_id and a string for $handler and $context

  • elgg_define_js() now requires a string for $name and an array for $config

  • elgg_delete_system_cache() now requires a string for $type

  • elgg_echo() now requires a string for $message_key and a string for $language

  • elgg_enqueue_notification_event() no longer requires a $type

  • elgg_entity_exists() now requires a int for $guid

  • elgg_entity_gatekeeper() now requires a int for $guid and a string for $type and a string for $subtype and a bool for $validate_can_edit

  • elgg_error_response() now requires a string or array for $message and a string for $forward_url

  • elgg_extend_view() now requires a string for $view and $view_extension

  • elgg_extract() now requires a bool for $strict

  • elgg_format_bytes() now requires an int for $size and $precision

  • elgg_format_element() now requires a string for $tag_name and a string for $text

  • elgg_format_html() now requires a string for $html

  • elgg_generate_action_url() now requires a string for $action and a boolean for $add_csrf_tokens

  • elgg_generate_entity_url() now requires a string for $resource and $subresource

  • elgg_generate_url() now requires a string for $name

  • elgg_get_config() now requires a string for $name

  • elgg_get_download_url() now requires a bool for $use_cookie and a string for $expires

  • elgg_get_embed_url() now requires a string for $size

  • elgg_get_entity_class() now requires a string for $type and a string for $subtype

  • elgg_get_excerpt() now requires a string for $text and an int for $num_chars

  • elgg_get_friendly_upload_error() now requires an int for $error_code

  • elgg_get_friendly_time() now requires an int for $time and $current_time

  • elgg_get_friendly_title() now requires a string for $title

  • elgg_get_icon_sizes() now requires a string for $entity_type and $entity_subtype

  • elgg_get_ini_setting_in_bytes() now requires a string for $setting

  • elgg_get_inline_url() now requires a bool for $use_cookie and a string for $expires

  • elgg_get_login_url() now requires a string for $fragment

  • elgg_get_metadata_from_id() now requires an int for $id

  • elgg_get_registration_url() now requires a string for $fragment

  • elgg_get_request_data() now requires a bool for $filter_result

  • elgg_get_simplecache_url() now requires a string for $view and $sub_view

  • elgg_get_sticky_value() now requires a string for $form_name and a string for $variable and a bool for $filter_result

  • elgg_get_sticky_values() now requires a string for $form_name and a bool for $filter_result

  • elgg_get_title_input() now requires a string for $variable and a string for $default

  • elgg_get_uploaded_file() now requires a string for $input_name and a bool for $check_for_validity

  • elgg_get_uploaded_files() now requires a string for $input_name

  • elgg_get_view_extensions() now requires a string for $view

  • elgg_get_widget_types() now requires a string or array for $context

  • elgg_get_widgets() now requires a int for $owner_guid and string for $context

  • elgg_group_tool_gatekeeper() now requires a string for $tool_name and an int for $group_guid

  • elgg_html_decode() now requires a string for $string

  • elgg_http_add_url_query_elements() now requires a string for $url

  • elgg_http_build_url() now requires a bool for $html_encode

  • elgg_http_get_signed_url() now requires a string for $url and $expires

  • elgg_http_remove_url_query_element() now requires a string for $url and a string for $element

  • elgg_http_url_is_identical() now requires a string for $url1 and $url2 and an array for $ignore_params

  • elgg_http_validate_signed_url() now requires a string for $url

  • elgg_in_context() now requires a string for $context

  • elgg_is_sticky_form() now requires a string for $form_name

  • elgg_is_widget_type() now requires a string for $handler and $context

  • elgg_language_key_exists() now requires a string for $key and a string for $language

  • elgg_list_entities() now requires a callable for $getter and a callable for $viewer

  • elgg_list_entities_from_relationship_count() now requires an array for $options

  • elgg_list_relationships() now requires an array for $options

  • elgg_load_system_cache() now requires a string for $type

  • elgg_make_sticky_form() now requires a string for $form_name

  • elgg_normalize_site_url() now requires a string for $unsafe_url

  • elgg_normalize_url() now requires a string for $url

  • elgg_ok_response() now requires a string or array for $message and a string for $forward_url

  • elgg_parse_emails() now requires a string for $text

  • elgg_push_context() now requires a string for $context

  • elgg_redirect_response() now requires a string for $forward_url

  • elgg_register_action() now requires a string for $filename

  • elgg_register_ajax_view() now requires a string for $view

  • elgg_register_error_message() now requires a string|array for $message

  • elgg_register_event_handler() now requires a string for $event and $type and an int for $priority and a callable|string for $callable

  • elgg_register_menu_item() now requires a string for $menu_name and a array|\ElggMenuItem for $menu_item

  • elgg_register_notification_event() now requires a string for $object_type and $object_subtype

  • elgg_register_notification_method() now requires a string for $name

  • elgg_register_route() now requires a string for $name

  • elgg_register_simplecache_view() now requires a string for $view_name

  • elgg_register_success_message() now requires a string|array for $message

  • elgg_register_title_button() has the first argument ($handler) removed and requires a string for $name, $entity_type and $entity_subtype

  • elgg_register_viewtype_fallback() now requires a string for $viewtype

  • elgg_register_widget_type() now only supports an array suitable for \Elgg\WidgetDefinition::factory() for $options

  • elgg_remove_config() now requires a string for $name

  • elgg_require_js() now requires a string for $name

  • elgg_save_config() now requires a string for $name

  • elgg_save_resized_image() now requires a string for $source and a string for $destination

  • elgg_save_system_cache() now requires a string for $type

  • elgg_set_config() now requires a string for $name

  • elgg_set_context() now requires a string for $context

  • elgg_set_entity_class() now requires a string for $type and a string for $subtype and a string for $class

  • elgg_set_form_footer() now requires a string for $footer

  • elgg_set_http_header() now requires a string for $header and a bool for $replace

  • elgg_set_page_owner_guid() now requires a int for $guid

  • elgg_set_view_location() now requires a string for $view, $location and $viewtype

  • elgg_set_viewtype() now requires a string for $viewtype

  • elgg_strip_tags() now requires a string for $string and $allowable_tags

  • elgg_trigger_after_event() now requires a string for $event and $type

  • elgg_trigger_before_event() now requires a string for $event and $type

  • elgg_trigger_deprecated_event() now requires a string for $event, $type, $message and $version

  • elgg_trigger_event() now requires a string for $event and $type

  • elgg_unregister_ajax_view() now requires a string for $view

  • elgg_register_event_handler() now requires a string for $event and $type and a callable|string for $callable

  • elgg_unregister_menu_item() now requires a string for $menu_name and $item_name

  • elgg_unregister_notification_event() now requires a string for $object_type and $object_subtype

  • elgg_unregister_notification_method() now requires a string for $name

  • elgg_unregister_route() now requires a string for $name

  • elgg_unregister_widget_type() now requires a string for $handler

  • elgg_unrequire_js() now requires a string for $name

  • elgg_validate_invite_code() now requires a string for $username and $code

  • elgg_validate_registration_data() now requires a string for $username, $name and $email, a bool for $multiple and a string|array for $password

  • elgg_view() now requires a string for $view and $viewtype and a bool for $recurse

  • elgg_view_annotation_list() now requires an array for $annotations

  • elgg_view_deprecated() now requires a string for $view, $message and $version

  • elgg_view_comments() now requires an ElggEntity for $entity and a bool for $add_comment

  • elgg_view_entity_icon() now requires a string for $size and an array for $vars

  • elgg_view_entity_list() now requires an array for $entities

  • elgg_view_exists() now requires a string for $view and $viewtype and an array for $vars

  • elgg_view_form() now requires a string for $action and an array for $form_vars and $body_vars

  • elgg_view_icon() now requires a string for $name and an array for $vars

  • elgg_view_image_block() now requires a string for $type, $title and $body

  • elgg_view_layout() now requires a string for $layout_name and an array for $vars

  • elgg_view_message() now requires a string for $type and $body

  • elgg_view_page() now requires a string for $title and $page_shell, an array for $vars and a string|array for $body

  • elgg_view_relationship_list() now requires an array for $relationships

  • elgg_view_river_item() now requires an ElggRiverItem for $item

  • elgg_view_resource() now requires a string for $name

  • elgg_view_title() now requires a string for $title

  • embed_get_list_options() now requires an array for $options

  • embed_list_items() now requires an array for $entities and $vars

  • file_prepare_form_vars() now requires an ElggFile for $file

  • get_entity() now requires a int for $guid

  • get_input() now requires a string for $variable and a bool for $filter_result

  • get_user() now requires a int for $guid

  • groups_get_group_join_menu_item() now requires an ElggUser for $user

  • groups_get_group_leave_menu_item() now requires an ElggUser for $user

  • groups_get_invited_groups() now requires an int for $user_guid, a bool for $return_guids and an array for $options

  • notify_user() now requires an int|array for $to and a int for $from and a string for $subject and $message

  • pages_get_navigation_tree() now requires a ElggEntity for $container

  • pages_prepare_form_vars() now requires a ElggPage for $page, an int for $parent_guid and a ElggAnnotation for $revision

  • pages_prepare_parent_breadcrumbs() now requires a ElggPage for $page

  • set_input() now requires a string for $variable

  • thewire_filter() now requires a string for $text

  • thewire_get_hashtags() now requires a string for $text

  • thewire_save_post() now requires a string for $text and $method and an int for $userid and $access_id and $parent_guid

  • uservalidationbyemail_request_validation() now requires an int for $user_guid

  • elgg_ws_expose_function() now requires a string for $method and $description and $call_method, an array for $parameters and a bool for $require_api_auth and $require_user_auth and $assoc

  • elgg_ws_register_service_handler() now requires a string for $handler

  • elgg_ws_unexpose_function() now requires a string for $method and a string for $http_request_method

  • elgg_ws_unregister_service_handler() now requires a string for $handler

Class function return types

  • \ElggEntity::deleteMetadata() no longer returns null

  • \ElggEntity::getOwnedAccessCollection() no longer returns false but null when no access collection is found

  • \ElggEntity::setContainerGUID() no longer returns int

  • \ElggFile::getDownloadURL() now returns null if there is an error

  • \ElggFile::getInlineURL() now returns null if there is an error

  • \ElggMenuItem::factory() no longer returns null if there is an error

  • \Elgg\Page::getParentEntity() no longer returns false but null if there is no parent entity found

Class function parameters

  • \ElggAccessCollection::getObjectFromID() now requires a int for $id

  • \ElggAnnotation::getObjectFromID() now requires a int for $id

  • \ElggEntity::addRelationship() now requires an int for $guid_two and a string for $relationship

  • \ElggEntity::cache() now requires a bool for $persist

  • \ElggEntity::canAnnotate() now requires an int for $user_guid and a string for $annotation_name

  • \ElggEntity::canComment() now requires an int for $user_guid

  • \ElggEntity::canDelete() now requires an int for $user_guid

  • \ElggEntity::canEdit() now requires an int for $user_guid

  • \ElggEntity::canWriteToContainer() now requires an int for $user_guid and a string for $type and $subtype

  • \ElggEntity::countAnnotations() now requires a string for $name

  • \ElggEntity::countEntitiesFromRelationship() now requires a string for $relationship and a bool for $inverse_relationship

  • \ElggEntity::delete() now requires a bool for $recursive

  • \ElggEntity::deleteAnnotations() now requires a string for $name

  • \ElggEntity::deleteIcon() now requires a string for $type

  • \ElggEntity::deleteMetadata() now requires a string for $name

  • \ElggEntity::deleteOwnedAnnotations() now requires a string for $name

  • \ElggEntity::disable() now requires a string for $reason and a bool for $recursive

  • \ElggEntity::disableAnnotations() now requires a string for $name

  • \ElggEntity::enable() now requires a bool for $recursive

  • \ElggEntity::enableAnnotations() now requires a string for $name

  • \ElggEntity::getAnnotationsAvg() now requires a string for $name

  • \ElggEntity::getAnnotationsMax() now requires a string for $name

  • \ElggEntity::getAnnotationsSum() now requires a string for $name

  • \ElggEntity::getIcon() now requires a string for $size and $type

  • \ElggEntity::getIconLastChange() now requires a string for $size and $type

  • \ElggEntity::getIconURL() now requires a string or array for $params

  • \ElggEntity::getObjectFromID() now requires an int for $id

  • \ElggEntity::getOwnedAccessCollections() now requires an array for $options

  • \ElggEntity::getOwnedAccessCollection() now requires a string for $subtype

  • \ElggEntity::getMetadata() now requires a string for $name

  • \ElggEntity::getVolatileData() now requires a string for $name

  • \ElggEntity::hasIcon() now requires a string for $size and $type

  • \ElggEntity::removeAllRelationships() no longer allows null to be passed to $relationship

  • \ElggEntity::removeRelationship() now requires an int for $guid_two and a string for $relationship

  • \ElggEntity::saveIconFromElggFile() now requires a string for $type

  • \ElggEntity::saveIconFromLocalFile() now requires a string for $input_name and $type

  • \ElggEntity::saveIconFromUploadedFile() now requires a string for $input_name and $type

  • \ElggEntity::setContainerGUID() now requires an int for $container_guid

  • \ElggEntity::setDisplayName() now requires a string for $display_name

  • \ElggEntity::setMetadata() now requires a string for $name and $value_type and a bool for $multiple

  • \ElggEntity::setTempMetadata() now requires a string for $name and a bool for $multiple

  • \ElggEntity::setVolatileData() now requires a string for $name

  • \ElggEntity::updateLastAction() now requires an int for $posted

  • \ElggMetadata::getObjectFromID() now requires a int for $id

  • \ElggRelationship::getObjectFromID() now requires a int for $id

  • \ElggFile::getDownloadURL() now requires a bool for $use_cookie and a string for $expires

  • \ElggFile::getInlineURL() now requires a bool for $use_cookie and a string for $expires

  • \ElggGroup::isToolEnabled() now requires a string for $name

  • \ElggMenuItem::factory() now requires an array for $options

  • \ElggTempFile::getDownloadURL() now requires a bool for $use_cookie and a string for $expires

  • \ElggTempFile::getInlineURL() now requires a bool for $use_cookie and a string for $expires

  • \Elgg\WebServices\Di\ApiRegistrationService::registerApiMethod() now requires a \Elgg\WebServices\ApiMethod as the only parameter

Moved classes

  • \ElggAutoP has been moved to \Elgg\Views\AutoParagraph

  • \ElggCache has been moved to \Elgg\Cache\BaseCache

  • \ElggDiskFilestore has been moved to \Elgg\Filesystem\Filestore\DiskFilestore

  • \ElggFilestore has been moved to \Elgg\Filesystem\Filestore

  • \ElggRewriteTester has been moved to \Elgg\Router\RewriteTester

  • \ElggTempDiskFilestore has been moved to \Elgg\Filesystem\Filestore\TempDiskFilestore

  • \Elgg\Database\SiteSecret has been moved to \Elgg\Security\SiteSecret

Deprecated APIs

  • elgg_clear_plugin_hook_handlers use elgg_clear_event_handlers

  • elgg_register_plugin_hook_handler use elgg_register_event_handler

  • elgg_trigger_plugin_hook use elgg_trigger_event_results

  • elgg_unregister_plugin_hook_handler use elgg_unregister_event_handler

  • get_user_by_email use elgg_get_user_by_email

  • get_user_by_username use elgg_get_user_by_username

Removed classes

  • Elgg\WebServices\ApiKeyForm

  • Loggable this interface has been merged into the ElggData class

Removed functions

  • blog_prepare_form_vars

  • bookmarks_prepare_form_vars

  • discussion_prepare_form_vars

  • elgg_get_breadcrumbs

  • elgg_pop_breadcrumb

  • elgg_set_email_transport use _elgg_services()->set('mailer', ...)

  • elgg_trigger_deprecated_plugin_hook

  • elgg_ws_expose_function use elgg-plugin.php or 'register', 'api_methods' event

  • file_prepare_form_vars

  • get_user_by_email use elgg_get_user_by_email

  • get_user_by_username use elgg_get_user_by_username

  • groups_prepare_form_vars

  • messages_prepare_form_vars

  • pages_prepare_form_vars

  • thewire_latest_guid

Removed class functions

  • \ElggWidget::saveSettings()

Removed events

  • access:collections:addcollection, collection use the create, access_collection sequence

  • access:collections:deletecollection, collection use the delete, access_collection sequence

  • prepare, breadcrumbs use register, menu:breadcrumbs

  • widget_settings, <widget_handler>

Removed exceptions

  • \Elgg\Exceptions\InvalidParameterException

Constants

  • The misspelled REFERER constant has been removed. Use REFERRER instead.

  • The REFERRER constant has been changed to a string with the value __elgg_referrer