From 4.x to 5.0

Contents

CKEditor
Composer
Events and Hooks
Private Settings
Breadcrumbs integrated into menu system
Upgrades
Session
Gatekeepers
Files plugin
Embed plugin
Javascript
Exceptions
ElggRiverItem
Metadata options in getter functions
Changes in functions

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.

Breadcrumbs integrated into menu system 

Helper functions for the breadcrumb menu have been changed to use elgg_register_menu_item() for adding items to the breadcrumb menu. Breadcrumb related events have been removed in favor of the regular menu events.

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