Nik has uploaded a new change for review. https://gerrit.wikimedia.org/r/124331
Change subject: Added documentation to main PubSubHubbub class. ...................................................................... Added documentation to main PubSubHubbub class. Change-Id: I53582bcb41fd82485f803422ccf3c1774c0af7a9 --- M PubSubHubbub.body.php 1 file changed, 103 insertions(+), 9 deletions(-) git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/PubSubHubbub refs/changes/31/124331/1 diff --git a/PubSubHubbub.body.php b/PubSubHubbub.body.php index f744b11..dbd3677 100644 --- a/PubSubHubbub.body.php +++ b/PubSubHubbub.body.php @@ -24,10 +24,49 @@ namespace PubSubHubbub; +use Article; +use Content; +use JobQueueGroup; +use OutputPage; +use Page; +use RawPage; +use Revision; +use Status; +use Title; +use User; +use Wikibase\NamespaceUtils; +use WikiPage; + +/** + * The main implementation of the PubSubHubbub extension. + * + * @licence GNU GPL v2+ + * @author Sebastian Brückner < [email protected] > + * @author Alexander Lehmann < [email protected] > + */ class PubSubHubbub { - public static function onPageContentSaveComplete( $article, $user, $content, $summary, - $isMinor, $section, $flags, $revision, $status, $baseRevId ) { + /** + * Hook executed after an article has been updated. + * Creates a {@link PublishChangesJob} that publishes that change to the defined hub and adds it to the job queue. + * + * @see https://www.mediawiki.org/wiki/Manual:Hooks/PageContentSaveComplete + * + * @param WikiPage $article WikiPage modified. + * @param User $user User performing the modification. + * @param Content $content New content. + * @param string $summary Edit summary/comment. + * @param boolean $isMinor Whether or not the edit was marked as minor. + * @param boolean $isWatch (No longer used.) + * @param integer $section (No longer used.) + * @param integer $flags Flags passed to <code>WikiPage::doEditContent()</code>. + * @param Revision|null $revision New Revision of the article (can be null for edits that change nothing). + * @param Status $status Status object about to be returned by <code>doEditContent()</code>. + * @param integer $baseRevId The rev ID (or false) this edit was based on. + * @return bool whether to continue hook processing. This implementation always returns <code>true</code>. + */ + public static function onPageContentSaveComplete( WikiPage $article, User $user, $content, $summary, $isMinor, + $isWatch, $section, $flags, Revision $revision, Status $status, $baseRevId ) { if ( !self::isConfigurationSetUp() ) { return true; } @@ -35,7 +74,7 @@ $jobParams = array(); $title = $article->getTitle(); $job = new PublishChangesJob( $title, $jobParams ); - $jobQueueGroup = \JobQueueGroup::singleton()->push( $job ); + $jobQueueGroup = JobQueueGroup::singleton()->push( $job ); if ( !$jobQueueGroup ) { wfLogWarning( "Failed to acquire a JobQueueGroup for $job" ); } @@ -43,11 +82,17 @@ return true; } - public static function getPageURL( $title ) { + /** + * Create the resource URL for a given {@link Title}. + * + * @param Title $title The {@link Title} to generate a resource URL for. + * @return string the generated resource URL. + */ + public static function getPageURL( Title $title ) { if ( defined( 'WB_VERSION' ) ) { // Wikibase extension is installed - if ( \Wikibase\NamespaceUtils::isEntityNamespace( $title->getNamespace() ) ) { - $specialTitle = \Title::makeTitle( -1, 'EntityData' ); + if ( NamespaceUtils::isEntityNamespace( $title->getNamespace() ) ) { + $specialTitle = Title::makeTitle( -1, 'EntityData' ); return $specialTitle->getCanonicalURL() . "/" . $title->getBaseText() . '.json'; } } @@ -57,6 +102,11 @@ ) ); } + /** + * Insert an HTTP Link header to the current response. + * + * @param Article|WikiPage|RawPage $page The resource. + */ public static function insertLinkHeader( $page ) { global $wgRequest, $wgPubSubHubbubHubURL; if ( !self::isConfigurationSetUp() ) { @@ -65,6 +115,11 @@ $wgRequest->response()->header( self::createLinkHeader( $wgPubSubHubbubHubURL, $page ), false ); } + /** + * Check whether the extension is properly configured. + * + * @return bool whether there's a PubSubHubbub hub URL set up in the LocalSettings. + */ public static function isConfigurationSetUp() { global $wgPubSubHubbubHubURL; if( !isset( $wgPubSubHubbubHubURL ) ) { @@ -74,23 +129,62 @@ return true; } + /** + * Create an HTTP Link header for the given hub and resource. + * + * @param string $hubURL The URL of the hub to point to. + * @param Article|WikiPage|RawPage $page The resource. + * @return string the HTTP Link header. + */ public static function createLinkHeader( $hubURL, $page ) { return "Link: <" . $hubURL . ">; rel=\"hub\", <" - . self::getPageURL( $page->getTitle() ) . ">; rel=\"self\""; + . self::getPageURL( $page->getTitle() ) . ">; rel=\"self\""; } - public static function onRawPageViewBeforeOutput( $rawPage, $text ) { + /** + * Called before displaying a page with <code>action=raw</code>. + * Add HTTP Link headers. + * + * @see https://www.mediawiki.org/wiki/Manual:Hooks/RawPageViewBeforeOutput + * + * @param RawPage $rawPage The {@link RawPage} object. + * @param string $text The text that's going to be the output. + * @return bool whether display is allowed. This implementation always returns <code>true</code>. + */ + public static function onRawPageViewBeforeOutput( RawPage $rawPage, $text ) { self::insertLinkHeader( $rawPage ); + return true; } - public static function onOutputPageBeforeHTML( \OutputPage &$out, &$text ) { + /** + * A page has been processed by the parser and the resulting HTML is about to be displayed. + * Add HTTP Link headers. + * + * @see https://www.mediawiki.org/wiki/Manual:Hooks/OutputPageBeforeHTML + * + * @param OutputPage $out + * @param string $text The text that will be displayed, in HTML. + * @return OutputPage <code>$out</code> + */ + public static function onOutputPageBeforeHTML( OutputPage &$out, &$text ) { if ( $out->canUseWikiPage() ) { self::insertLinkHeader( $out->getWikiPage() ); } + return $out; } + /** + * Called when building a list of files with PHPUnit tests. + * Add our tests to the list of PHPUnit test files. + * + * @see https://www.mediawiki.org/wiki/Manual:Hooks/UnitTestsList + * + * @param string[] $files The list of test files. + * @return bool + */ public static function onUnitTestsList( &$files ) { $files = array_merge( $files, glob( __DIR__ . '/tests/phpunit/*Test.php' ) ); return true; } + } -- To view, visit https://gerrit.wikimedia.org/r/124331 To unsubscribe, visit https://gerrit.wikimedia.org/r/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I53582bcb41fd82485f803422ccf3c1774c0af7a9 Gerrit-PatchSet: 1 Gerrit-Project: mediawiki/extensions/PubSubHubbub Gerrit-Branch: master Gerrit-Owner: Nik <[email protected]> _______________________________________________ MediaWiki-commits mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
