From 9adfb4f0a9e57cab9ca9f71fab887f9ca540e14f Mon Sep 17 00:00:00 2001 From: Antoine Musso Date: Tue, 19 Oct 2010 20:45:02 +0000 Subject: [PATCH] documentation, a couple notes about code and some whitespaces adjustements to make code easier to read. --- includes/resourceloader/ResourceLoader.php | 42 ++++++++++++++----- .../resourceloader/ResourceLoaderContext.php | 17 ++++---- 2 files changed, 42 insertions(+), 17 deletions(-) diff --git a/includes/resourceloader/ResourceLoader.php b/includes/resourceloader/ResourceLoader.php index cda10d29bd..37ef160b56 100644 --- a/includes/resourceloader/ResourceLoader.php +++ b/includes/resourceloader/ResourceLoader.php @@ -23,7 +23,10 @@ defined( 'MEDIAWIKI' ) || die( 1 ); /** - * Dynamic JavaScript and CSS resource loading system + * Dynamic JavaScript and CSS resource loading system. + * + * Most of the documention is on the MediaWiki documentation wiki starting at + * http://www.mediawiki.org/wiki/ResourceLoader */ class ResourceLoader { @@ -39,9 +42,12 @@ class ResourceLoader { * * This is not inside the module code because it's so much more performant to request all of the information at once * than it is to have each module requests it's own information. - * - * @param $modules array list of module names to preload information for - * @param $context ResourceLoaderContext context to load the information within + * + * This method grab modules dependencies from the database and initialize modules object. + * A first pass compute dependencies, a second one the blob mtime. + * + * @param $modules Array List of module names to preload information for + * @param $context ResourceLoaderContext Context to load the information within */ protected function preloadModuleInfo( array $modules, ResourceLoaderContext $context ) { if ( !count( $modules ) ) { @@ -57,7 +63,8 @@ class ResourceLoader { 'md_skin' => $context->getSkin() ), __METHOD__ ); - + + // Set modules dependecies $modulesWithDeps = array(); foreach ( $res as $row ) { $this->modules[$row->md_module]->setFileDependencies( $skin, @@ -65,7 +72,7 @@ class ResourceLoader { ); $modulesWithDeps[] = $row->md_module; } - // Register the absence of a dependencies row too + // Register the absence of a dependency row too foreach ( array_diff( $modules, $modulesWithDeps ) as $name ) { $this->modules[$name]->setFileDependencies( $skin, array() ); } @@ -96,7 +103,13 @@ class ResourceLoader { } /** - * Runs text through a filter, caching the filtered result for future calls + * Runs text (js,CSS) through a filter, caching the filtered result for future calls. + * + * Availables filters are: + * - minify-js \see JSMin::minify + * - minify-css \see CSSMin::minify + * - flip-css \see CSSJanus::transform + * When the filter names does not exist, text is returned as is. * * @param $filter String: name of filter to run * @param $data String: text to filter, such as JavaScript or CSS text @@ -108,6 +121,8 @@ class ResourceLoader { wfProfileIn( __METHOD__ ); // For empty or whitespace-only things, don't do any processing + # FIXME: we should return the data unfiltered if $filter is not supported. + # that would save up a md5 computation and one memcached get. if ( trim( $data ) === '' ) { wfProfileOut( __METHOD__ ); return $data; @@ -125,6 +140,7 @@ class ResourceLoader { // Run the filter try { switch ( $filter ) { + # note: if adding a new filter. Please update method documentation above. case 'minify-js': $result = JSMin::minify( $data ); break; @@ -143,7 +159,7 @@ class ResourceLoader { throw new MWException( 'Filter threw an exception: ' . $exception->getMessage() ); } - // Save to memcached + // Save filtered text to memcached $wgMemc->set( $key, $result ); wfProfileOut( __METHOD__ ); @@ -259,13 +275,13 @@ class ResourceLoader { // If a version wasn't specified we need a shorter expiry time for updates to // propagate to clients quickly if ( is_null( $context->getVersion() ) ) { - $maxage = $wgResourceLoaderMaxage['unversioned']['client']; + $maxage = $wgResourceLoaderMaxage['unversioned']['client']; $smaxage = $wgResourceLoaderMaxage['unversioned']['server']; } // If a version was specified we can use a longer expiry time since changing // version numbers causes cache misses else { - $maxage = $wgResourceLoaderMaxage['versioned']['client']; + $maxage = $wgResourceLoaderMaxage['versioned']['client']; $smaxage = $wgResourceLoaderMaxage['versioned']['server']; } @@ -311,6 +327,12 @@ class ResourceLoader { wfProfileOut( __METHOD__ ); } + /** + * + * @param $context ResourceLoaderContext + * @param $modules Array array( modulename => ResourceLoaderModule ) + * @param $missing Unavailables modules (Default null) + */ public function makeModuleResponse( ResourceLoaderContext $context, array $modules, $missing = null ) { // Pre-fetch blobs $blobs = $context->shouldIncludeMessages() ? diff --git a/includes/resourceloader/ResourceLoaderContext.php b/includes/resourceloader/ResourceLoaderContext.php index 11a86ad47d..a053ff52b1 100644 --- a/includes/resourceloader/ResourceLoaderContext.php +++ b/includes/resourceloader/ResourceLoaderContext.php @@ -49,16 +49,19 @@ class ResourceLoaderContext { $this->resourceLoader = $resourceLoader; $this->request = $request; + // Interpret request + # list of modules $modules = $request->getVal( 'modules' ); - $this->modules = $modules ? explode( '|', $modules ) : array(); - $this->language = $request->getVal( 'lang' ); + $this->modules = $modules ? explode( '|', $modules ) : array(); + # various parameters + $this->language = $request->getVal( 'lang' ); $this->direction = $request->getVal( 'dir' ); - $this->skin = $request->getVal( 'skin' ); - $this->user = $request->getVal( 'user' ); - $this->debug = $request->getFuzzyBool( 'debug', $wgResourceLoaderDebug ); - $this->only = $request->getVal( 'only' ); - $this->version = $request->getVal( 'version' ); + $this->skin = $request->getVal( 'skin' ); + $this->user = $request->getVal( 'user' ); + $this->debug = $request->getFuzzyBool( 'debug', $wgResourceLoaderDebug ); + $this->only = $request->getVal( 'only' ); + $this->version = $request->getVal( 'version' ); // Fallback on system defaults if ( !$this->language ) { -- 2.20.1