From 2.2 to 2.3

PHP Version

PHP 5.5 has reached end of life in July 2016. To ensure that Elgg sites are secure, we now require PHP 5.6 for new installations.

Existing installations can continue using PHP 5.5 until Elgg 3.0.

In order to upgrade Elgg to 2.3 using composer while using PHP 5.5, you may need to use --ignore-platform-reqs flag.

Deprecated APIs

  • Registering for to:object hook by the extender name: Use to:object, annotation and to:object, metadata hooks instead.
  • ajax_forward_hook(): No longer used as handler for ‘forward’,’all’ hook. Ajax response is now wrapped by the ResponseFactory
  • ajax_action_hook(): No longer used as handler for ‘action’,’all’ hook. Output buffering now starts before the hook is triggered in ActionsService
  • elgg_error_page_handler(): No longer used as a handler for ‘forward’,<error_code> hooks
  • get_uploaded_file(): Use new file uploads API instead
  • get_user_notification_settings(): Use ElggUser::getNotificationSettings()
  • set_user_notification_setting(): Use ElggUser::setNotificationSetting()
  • pagesetup, system event: Use the menu or page shell hooks instead.
  • elgg.walled_garden JavaScript is deprecated: Use elgg/walled_garden AMD module instead.
  • elgg()->getDb()->getTableprefix(): Use elgg_get_config('dbprefix').
  • Private update_entity_last_action(): Refrain from manually updating last action timestamp.
  • Setting non-public access_id on metadata is deprecated. See below.
  • get_resized_image_from_existing_file(): Use elgg_save_resized_image().
  • get_resized_image_from_uploaded_file(): Use elgg_save_resized_image() in combination with upload API.
  • get_image_resize_parameters() will be removed.
  • elgg_view_input(): Use elgg_view_field(). Apologies for the API churn.

Deprecated Views

  • resources/file/world: Use the resources/file/all view instead.
  • resources/pages/world: Use the resources/pages/all view instead.
  • walled_garden.js: Use the elgg/walled_garden module instead.

New API for page and action handling

Page handlers and action script files should now return an instance of \Elgg\Http\ResponseBuilder. Plugins should use the following convenience functions to build responses:

  • elgg_ok_response() sends a 2xx response with HTML (page handler) or JSON data (actions)
  • elgg_error_response() sends a 4xx or 5xx response without content/data
  • elgg_redirect_response() silently redirects the request

New API for working with file uploads

  • elgg_get_uploaded_files() - returns an array of Symfony uploaded file objects
  • ElggFile::acceptUploadedFile() - moves an uploaded file to Elgg’s filestore

New API for manipulating images

New image manipulation service implements a more efficient approach to cropping and resizing images.

  • elgg_save_resized_image() - crops and resizes an image to preferred dimensions

New API for events

  • elgg_clear_event_handlers() - similar to elgg_clear_plugin_hook_handlers this functions removes all registered event handlers

New API for signing URLs

URLs can now be signed with a SHA-256 HMAC key and validated at any time before URL expiry. This feature can be used to tokenize action URLs in email notifications, as well as other uses outside of the Elgg installation.

  • elgg_http_get_signed_url() - signs the URL with HMAC key
  • elgg_http_validate_signed_url() - validates the signed URL
  • elgg_signed_request_gatekeeper() - gatekeeper that validates the signature of the current request

Extendable form views

Form footer rendering can now be deferred until the form view and its extensions have finished rendering. This allows plugins to collaborate on form views without breaking the markup logic.

  • elgg_set_form_footer() - sets form footer for deferred rendering
  • elgg_get_form_footer() - returns currently set form footer

Metadata access_id

It’s now deprecated to create metadata with an explicit access_id value other than ACCESS_PUBLIC.

In Elgg 3.0, metadata will not be access controlled, and will be available in all contexts. If your plugin relies on access control of metadata, it would be wise to migrate storage to annotations or entities instead.

New API for extracting class names from arrays

Similar to elgg_extract(), elgg_extract_class() extracts the “class” key (if present), merges into existing class names, and always returns an array.

Notifications

  • A high level 'prepare','notification' hook is now triggered for instant and subscription notifications and can be used to alter notification objects irrespective of their type.
  • 'format','notification:<method>' hook is now triggered for instant and subscription notifications and can be used to format the notification (e.g. strip HTML tags, wrap the notification body in a template etc).
  • Instant notifications are now handled by the notifications service, hence almost all hooks applicable to subscription notifications also apply to instant notifications.
  • elgg_get_notification_methods() can be used to obtain registered notification methods
  • Added ElggUser::getNotificationSettings() and ElggUser::setNotificationSetting()

Entity list functions can output tables

In functions like elgg_list_entities($options), table output is possible by setting $options['list_type'] = 'table' and providing an array of table columns as $options['columns']. Each column is an Elgg\Views\TableColumn object, usually created via methods on the service elgg()->table_columns.

Plugins can provide or alter these factory methods (see Elgg\Views\TableColumn\ColumnFactory). See the view admin/users/newest for a usage example.

Inline tabs components

Inline tabs component can now be rendered with page/components/tabs view. The components allows to switch between pre-populated and ajax-loaded. See page/components/tabs in core views and theme_sandbox/components/tabs in developers plugin for usage instructions and examples.

API to alter registration and login URL

  • elgg_get_registration_url() should be used to obtain site’s registration URL
  • elgg_get_login_url() should be used to obtain site’s login URL
  • registration_url, site hook can be used to alter the default registration URL
  • login_url, site hook can be used to alter the default login URL

Support for fieldsets in forms

  • elgg_view_field() replaces elgg_view_input(). It has a similar API, but accepts a single array.
  • elgg_view_field() supports #type, #label, #help and #class, allowing unprefixed versions to be sent to the input view $vars.
  • The new view input/fieldset can be used to render a set of fields, each rendered with elgg_view_field().