See this search for a list; this was briefly discussed on r539529.
Basically, &$this won't pass a reference to $this, hence there are two options:
- If you only want callees to modify properties of $this, the ampersand is redundant as of PHP4.
- If you expect the callee to replace the parameter with something else, you should assign $this to a temporary variable and pass that variable by reference. This is what the PHPCS sniff suggests, and the code in the search above is doing.
For PHPCS, we're probably going to suggest both (1.) and (2.) whenever we find &$this. Existing code should instead be checked manually, determine what its intent is, and act as appropriate.
Per T234118#5531469, Hooks::run calls should be audited manually, then we should write a script to update hook handlers. Handlers should be fixed first, then the Hooks::run calls.
Progress
(all hooks using a temp var to pass $this by reference must be fixed, as apparently there's no situation where we expect the param to change)
- EditPage: reference can be removed from all hooks: EditPage::showEditForm:initial, EditPage::showEditForm:fields, EditPageBeforeConflictDiff, EditPageBeforeEditButtons, and EditPageNoSuchSection. Some handlers already updated, ref T234118#5531469.
- OutputPage: reference can be removed from all hooks: OutputPageMakeCategoryLinks, OutputPageParserOutput, OutputPageBeforeHTML, and BeforePageDisplay.
- Title: reference can be removed from all hooks: GetFullURL, GetLocalURL::Article, GetLocalURL::Internal, GetLocalURL, GetInternalURL, and GetCanonicalURL
- RawAction: can be removed from RawPageViewBeforeOutput
- HistoryPager: can be removed from PageHistoryPager::getQueryInfo
- ApiBase: can be removed from APIGetAllowedParams
- ApiPageSet: can be removed from APIQueryGeneratorAfterExecute
- DatabaseBlock: can be removed from AbortAutoblock
- ChangesList: can be removed from ChangesListInsertArticleLink
- OldChangesList: can be removed from OldChangesListRecentChangesLine
- RecentChange: can be removed from RecentChange_save
- LinksUpdate: can be removed from LinksUpdateConstructed, LinksUpdate, and LinksUpdateComplete
- DifferenceEngine: can be removed from AbortDiffCache
- XmlDumpWriter: can be removed from XmlDumpWriterWriteRevision
- LocalFile: can be removed from LocalFile::getHistory
- Article: can be removed from ArticleAfterFetchContentObject, ArticleViewHeader, ArticleViewRedirect, DisplayOldSubtitle, and IsFileCacheable
- CategoryPage: can be removed from CategoryPageView
- ImagePage: can be removed from ImageOpenShowImageInlineBefore
- WikiPage: can be removed from ArticlePageDataBefore, ArticlePageDataAfter, ArticleDelete, ArticlePurge, ArticleProtect, and ArticleProtectComplete
- Parser: can be removed from: ParserFirstCallInit, ParserClearState, ParserBeforeStrip, ParserAfterStrip, ParserAfterParse, ParserBeforeInternalParse, InternalParseBeforeSanitize, InternalParseBeforeLinks, ParserAfterUnstrip, ParserBeforeTidy, ParserAfterTidy, ParserGetVariableValueVarCache, ParserGetVariableValueTs, ParserGetVariableValueSwitch, and BeforeParserrenderImageGallery. And also from setFunctionHook docs, mFunctionTagHooks, and mFunctionHooks
- ResourceLoader: can be removed from ResourceLoaderTestModules
- BaseTemplate: can be removed from BaseTemplateToolbox and SkinTemplateToolboxEnd
- SkinTemplate: can be removed from SkinTemplateOutputPageBeforeExec, SkinTemplateTabAction, SkinTemplatePreventOtherActiveTabs, SkinTemplateNavigation, SkinTemplateNavigation::SpecialPage, SkinTemplateNavigation::Universal, and SkinTemplateBuildNavUrlsNav_urlsAfterPermalink
- SpecialMovepage: can be removed from SpecialMovepageAfterMove
- SpecialUpload: can be removed from SpecialUploadComplete, UploadForm:initial, and UploadForm:BeforeProcessing
- SpecialWantedpages: can be removed from WantedPages::getQueryInfo
- ContribsPager: can be removed from ContribsPager::getQueryInfo
- NewPagesPager: can be removed from SpecialNewpagesConditions
- UploadBase: can be removed from UploadComplete
- User: can be removed from GetBlockedStatus, PingLimiter, UserIsBlockedGlobally, UserRetrieveNewTalks, UserEffectiveGroups, UserClearNewTalkNotification, UserLogout, UserCanSendEmail, and EmailConfirmed