From f03a8c2f6b6f3bec56c50772efca2e998c25bd2c Mon Sep 17 00:00:00 2001 From: Guy Sartorelli Date: Thu, 15 Aug 2024 16:54:19 +1200 Subject: [PATCH] DOC Document standardisation of extension hooks --- .../00_Model/07_Permissions.md | 2 +- .../00_Model/09_Validation.md | 2 +- .../00_Model/10_Versioning.md | 2 +- .../01_Templates/02_Common_Variables.md | 2 +- .../How_Tos/03_Track_member_logins.md | 2 +- .../How_Tos/Customise_CMS_Menu.md | 2 +- .../Extending_An_Existing_ModelAdmin.md | 2 +- .../03_Managing_Sessions.md | 4 +-- en/08_Changelogs/6.0.0.md | 28 ++++++++++++++++++- 9 files changed, 36 insertions(+), 10 deletions(-) diff --git a/en/02_Developer_Guides/00_Model/07_Permissions.md b/en/02_Developer_Guides/00_Model/07_Permissions.md index 728333a19..6ebdc8075 100644 --- a/en/02_Developer_Guides/00_Model/07_Permissions.md +++ b/en/02_Developer_Guides/00_Model/07_Permissions.md @@ -118,7 +118,7 @@ use SilverStripe\Security\Permission; class PermissionsExtension extends Extension { - public function canView() + protected function canView() { if (!Permission::check('CMS_ACCESS_CMSMain', 'any', $member)) { return false; diff --git a/en/02_Developer_Guides/00_Model/09_Validation.md b/en/02_Developer_Guides/00_Model/09_Validation.md index e531dd0e6..4e821eab8 100644 --- a/en/02_Developer_Guides/00_Model/09_Validation.md +++ b/en/02_Developer_Guides/00_Model/09_Validation.md @@ -42,7 +42,7 @@ Most validation constraints are actually data constraints which belong on the mo called any time the `write()` method is called, before the `onBeforeWrite()` extension hook. By default, there is no validation - objects are always valid! However, you can override this method in your `DataObject` -sub-classes to specify custom validation, or use the `validate()` extension hook through an [Extension](api:SilverStripe\Core\Extension). +sub-classes to specify custom validation, or use the `updateValidate()` extension hook through an [Extension](api:SilverStripe\Core\Extension). Invalid objects won't be able to be written - a [`ValidationException`](api:SilverStripe\ORM\ValidationException) will be thrown and no write will occur. diff --git a/en/02_Developer_Guides/00_Model/10_Versioning.md b/en/02_Developer_Guides/00_Model/10_Versioning.md index c41ff493a..d9834f4b7 100644 --- a/en/02_Developer_Guides/00_Model/10_Versioning.md +++ b/en/02_Developer_Guides/00_Model/10_Versioning.md @@ -331,7 +331,7 @@ use SilverStripe\Security\Permission; class MyObjectExtension extends DataExtension { - public function canViewNonLive($member = null) + protected function canViewNonLive($member = null) { if (!Permission::check($member, 'DRAFT_STATUS')) { return false; diff --git a/en/02_Developer_Guides/01_Templates/02_Common_Variables.md b/en/02_Developer_Guides/01_Templates/02_Common_Variables.md index 7a59143d7..63bd0704c 100644 --- a/en/02_Developer_Guides/01_Templates/02_Common_Variables.md +++ b/en/02_Developer_Guides/01_Templates/02_Common_Variables.md @@ -159,7 +159,7 @@ SilverStripe\CMS\Model\SiteTree: ### Modifying meta tags -You can override the `MetaComponents()` method on your `SiteTree` sub-classes or make use of the `MetaComponents` extension point to manipulate the underlying data that is rendered by `$MetaTags`. Example (for `Page` class): +You can override the `MetaComponents()` method on your `SiteTree` sub-classes or make use of the `updateMetaComponents` extension point to manipulate the underlying data that is rendered by `$MetaTags`. Example (for `Page` class): ```php namespace App\PageType; diff --git a/en/02_Developer_Guides/05_Extending/How_Tos/03_Track_member_logins.md b/en/02_Developer_Guides/05_Extending/How_Tos/03_Track_member_logins.md index b36e5c9f5..4b6c802d7 100644 --- a/en/02_Developer_Guides/05_Extending/How_Tos/03_Track_member_logins.md +++ b/en/02_Developer_Guides/05_Extending/How_Tos/03_Track_member_logins.md @@ -35,7 +35,7 @@ class MyMemberExtension extends DataExtension /** * This extension hook is called every time a member is logged in */ - public function afterMemberLoggedIn() + protected function onAfterMemberLoggedIn() { $this->logVisit(); } diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Menu.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Menu.md index a9d9a7242..679ab59a4 100644 --- a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Menu.md +++ b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Customise_CMS_Menu.md @@ -86,7 +86,7 @@ class CustomLeftAndMain extends LeftAndMainExtension { // ... - public function init() + protected function onInit() { // unique identifier for this item. Will have an ID of Menu-$ID $id = 'LinkToExample'; diff --git a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Extending_An_Existing_ModelAdmin.md b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Extending_An_Existing_ModelAdmin.md index 615b833fd..8b000e4cf 100644 --- a/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Extending_An_Existing_ModelAdmin.md +++ b/en/02_Developer_Guides/15_Customising_the_Admin_Interface/How_Tos/Extending_An_Existing_ModelAdmin.md @@ -15,7 +15,7 @@ use SilverStripe\Core\Extension; class MyAdminExtension extends Extension { - public function updateEditForm($form) + protected function updateEditForm($form) { $form->Fields()->push(/* ... */) } diff --git a/en/02_Developer_Guides/18_Cookies_And_Sessions/03_Managing_Sessions.md b/en/02_Developer_Guides/18_Cookies_And_Sessions/03_Managing_Sessions.md index a4e3bc5c2..1f88913fe 100644 --- a/en/02_Developer_Guides/18_Cookies_And_Sessions/03_Managing_Sessions.md +++ b/en/02_Developer_Guides/18_Cookies_And_Sessions/03_Managing_Sessions.md @@ -91,7 +91,7 @@ class LoginSessionExtension extends DataExtension /** * @param Member $member */ - public function canView($member) + protected function canView($member) { if ($this->getOwner()->Member()->canView($member)) { // If you can view a Member, you can also view their sessions. @@ -103,7 +103,7 @@ class LoginSessionExtension extends DataExtension /** * @param Member $member */ - public function canDelete($member) + protected function canDelete($member) { if ($this->getOwner()->Member()->canEdit($member)) { // If you can edit a Member, you can also log them out of a session. diff --git a/en/08_Changelogs/6.0.0.md b/en/08_Changelogs/6.0.0.md index 188e2526c..b5520a70c 100644 --- a/en/08_Changelogs/6.0.0.md +++ b/en/08_Changelogs/6.0.0.md @@ -259,7 +259,33 @@ This release includes a number of bug fixes to improve a broad range of areas. C ### Most extension hook methods are now protected {#hooks-protected} -Core implementations of most extension hooks such as `updateCMSFields()` now have protected visibility. Formally they had public visibility which meant they could be called directly which was not how they were intended to be used. Extension hook implementations are still able to be declared public in project code, though it is recommended that all extension hook methods are declared protected in project code to follow best practice. +Core implementations of most extension hooks such as `updateCMSFields()` now have protected visibility. Formerly they had public visibility which meant they could be called directly which was not how they were intended to be used. Extension hook implementations are still able to be declared public in project code, though it is recommended that all extension hook methods are declared protected in project code to follow best practice. + +### Changes to some extension hook names {#hooks-renamed} + +In order to better align the codebase in Silverstripe CMS with best practices, the following extension hook methods have changed name: + +|class that defined the hook|old name|new name| +|---|---|---| +|[`Member`](api:SilverStripe\Security\Member)|`afterMemberLoggedIn`|`onAfterMemberLoggedIn`| +|[`Member`](api:SilverStripe\Security\Member)|`afterMemberLoggedOut`|`onAfterMemberLoggedOut`| +|[`Member`](api:SilverStripe\Security\Member)|`authenticationFailed`|`onAuthenticationFailed`| +|[`Member`](api:SilverStripe\Security\Member)|`authenticationFailedUnknownUser`|`onAuthenticationFailedUnknownUser`| +|[`Member`](api:SilverStripe\Security\Member)|`authenticationSucceeded`|`onAuthenticationSucceeded`| +|[`Member`](api:SilverStripe\Security\Member)|`beforeMemberLoggedIn`|`onBeforeMemberLoggedIn`| +|[`Member`](api:SilverStripe\Security\Member)|`beforeMemberLoggedOut`|`onBeforeMemberLoggedOut`| +|[`LeftAndMain`](api:SilverStripe\Admin\LeftAndMain)|`init`|`onInit`| +|[`DataObject`](api:SilverStripe\ORM\DataObject)|`flushCache`|`onFlushCache`| +|[`LostPasswordHandler`](api:SilverStripe\Security\MemberAuthenticator\LostPasswordHandler)|`forgotPassword`|`onForgotPassword`| +|[`ErrorPage`](api:SilverStripe\ErrorPage\ErrorPage)|`getDefaultRecords`|`updateDefaultRecords`| +|[`SiteTree`](api:SilverStripe\CMS\Model\SiteTree)|`MetaComponents`|`updateMetaComponents`| +|[`SiteTree`](api:SilverStripe\CMS\Model\SiteTree)|`MetaTags`|`updateMetaTags`| +|[`DataObject`](api:SilverStripe\ORM\DataObject)|`populateDefaults`|`onAfterPopulateDefaults`| +|[`Member`](api:SilverStripe\Security\Member)|`registerFailedLogin`|`onRegisterFailedLogin`| +|[`DataObject`](api:SilverStripe\ORM\DataObject)|`requireDefaultRecords`|`onRequireDefaultRecords`| +|[`DataObject`](api:SilverStripe\ORM\DataObject)|`validate`|`updateValidate`| + +If you have implemented any of those methods in an [`Extension`](api:SilverStripe\Core\Extension) subclass, you will need to rename it for it to continue working. ### Strict typing for `Factory` implementations {#factory-strict-typing}