The new PSR-3 debug logging system brought namespaced external code (Psr\Log\LoggerInterface) into use in MediaWiki core. The classes I built out to work with this system are using faux namespaces by virtue of class names like "MWLoggerFactory", "MWLoggerLegacyLogger" and "MWLoggerMonologSyslogHandler". Before 1.25 starts rolling out as a tarball release I'd like to change these classes to use actual PHP namespaces rather than this clunky collision avoidance mechanism. [0] There is also a task to backport minimal PSR-3 support to the 1.23 LTS system to simplify backports of code and extensions that adopt direct use of PSR-3 and I'd like to only do that once if possible.
The color I have picked for this namespace bikeshed is MediaWiki\Core\Logger. The MediaWiki root namespace is a pretty obvious choice. "Core" is inserted to distinguish this fundamental MediaWiki functionality from any existing or future extensions that might use namespaces. I'm hoping "Logger" is sufficiently distinct from other uses of the term "log" in MediaWiki which generally mean "audit trail" rather than "debugging information". I'd be fine with throwing Debug in between Core and Logger too if consensus found for that instead.
I'd also like to start organizing these files in a directory structure that would be compatible with the PSR-4 auto loader standard. PSR-1 required all namespace elements to be in the file path as directories, but PSR-4 allows a common prefix for all classes to be dropped. I was thinking an includes/Core/ directory could be used as the common base for these and future namespaced classes in MediaWiki core.
We had some discussion last summer [2] about namespace use in extensions that seemed to end with "cool do it when you want" and "we don't really need any standard conventions". Since I'm suggesting namespace usage in core I figured this was worth another (hopefully short) round of discussion with the larger community than is likely to see my patches when they land in Gerrit.
[0]: https://phabricator.wikimedia.org/T93406 [1]: https://phabricator.wikimedia.org/T91653 [2]: http://www.gossamer-threads.com/lists/wiki/wikitech/476296
Bryan
On Fri, Mar 20, 2015 at 12:51 PM Bryan Davis bd808@wikimedia.org wrote:
The new PSR-3 debug logging system brought namespaced external code (Psr\Log\LoggerInterface) into use in MediaWiki core. The classes I built out to work with this system are using faux namespaces by virtue of class names like "MWLoggerFactory", "MWLoggerLegacyLogger" and "MWLoggerMonologSyslogHandler". Before 1.25 starts rolling out as a tarball release I'd like to change these classes to use actual PHP namespaces rather than this clunky collision avoidance mechanism. [0] There is also a task to backport minimal PSR-3 support to the 1.23 LTS system to simplify backports of code and extensions that adopt direct use of PSR-3 and I'd like to only do that once if possible.
Yay go for it imho :)
The color I have picked for this namespace bikeshed is MediaWiki\Core\Logger. The MediaWiki root namespace is a pretty obvious choice. "Core" is inserted to distinguish this fundamental MediaWiki functionality from any existing or future extensions that might use namespaces. I'm hoping "Logger" is sufficiently distinct from other uses of the term "log" in MediaWiki which generally mean "audit trail" rather than "debugging information". I'd be fine with throwing Debug in between Core and Logger too if consensus found for that instead.
MediaWiki\Core is a terrible name. Core is stupid and redundant and it's a terrible pattern I hate having encouraged.
-Chad
On Fri, Mar 20, 2015 at 3:09 PM, Chad innocentkiller@gmail.com wrote:
On Fri, Mar 20, 2015 at 12:51 PM Bryan Davis bd808@wikimedia.org wrote:
The color I have picked for this namespace bikeshed is MediaWiki\Core\Logger. The MediaWiki root namespace is a pretty obvious choice. "Core" is inserted to distinguish this fundamental MediaWiki functionality from any existing or future extensions that might use namespaces. I'm hoping "Logger" is sufficiently distinct from other uses of the term "log" in MediaWiki which generally mean "audit trail" rather than "debugging information". I'd be fine with throwing Debug in between Core and Logger too if consensus found for that instead.
MediaWiki\Core is a terrible name. Core is stupid and redundant and it's a terrible pattern I hate having encouraged.
Ok. Just MediaWiki\Logger then? In the last discussion there were many examples of reasons that an extension might use any random namespace root other than MediaWiki\Extension\Foo but we didn't try to set a standard for namespaces *not* to use. I think I've seen some extensions that used MediaWiki\Foo as their namespace.
Bryan
On Fri, Mar 20, 2015 at 12:51 PM, Bryan Davis bd808@wikimedia.org wrote:
The color I have picked for this namespace bikeshed is MediaWiki\Core\Logger
That means you need to map MediaWiki\Core to includes or includes/Core. Given that we have a mediawiki/core repo containing a bunch of classes which are not going to be in that directory (maintenance scripts, i18n), that's a bit confusing. Also, what non-core subnamespaces do you expect? I imagine all extensions would go under MediaWiki\Extension, which would make the top-level namespace a bit underused.
The MediaWiki root namespace is a pretty obvious choice.
Just to play devil's advocate, we could also use a vendor schema (Wikimedia\MediaWiki...). That looks uglier but is better at preventing conflicts as each vendor has its own subspace. PSR-0 actually required this, but PSR-3 backed out of it.
I'd be fine with throwing Debug in between Core and Logger too
if consensus found for that instead.
Logger is fine IMO, it's the other log class that should eventually get a more descriptive name.
I was thinking an includes/Core/ directory could be used as the common
base for these and future namespaced classes in MediaWiki core.
If we intend to put all MediaWiki core classes under the Core namespace, then the two-level directory structure seems a bit silly; MediaWiki\Core should just map to a top-level directory. That can't be includes, because not all OS-es have case-sensitive directory names and we don't want to tiptoe around old directory names when choosing namespaces. Also we probably want to enforce stronger code conventions for the new classes (such as PSR-3 conformance) and automating that is easier when everything in the same directory needs the same rules. So how about /src/Logger? That's a fairly standard structure while "includes" has that nineties flavor where you had your controllers in the apache docroot and the rest of your classes were manually included from somewhere else...
On Fri, Mar 20, 2015 at 1:51 PM, Bryan Davis bd808@wikimedia.org wrote:
The new PSR-3 debug logging system brought namespaced external code (Psr\Log\LoggerInterface) into use in MediaWiki core. The classes I built out to work with this system are using faux namespaces by virtue of class names like "MWLoggerFactory", "MWLoggerLegacyLogger" and "MWLoggerMonologSyslogHandler". Before 1.25 starts rolling out as a tarball release I'd like to change these classes to use actual PHP namespaces rather than this clunky collision avoidance mechanism. [0] There is also a task to backport minimal PSR-3 support to the 1.23 LTS system to simplify backports of code and extensions that adopt direct use of PSR-3 and I'd like to only do that once if possible.
The color I have picked for this namespace bikeshed is MediaWiki\Core\Logger. The MediaWiki root namespace is a pretty obvious choice. "Core" is inserted to distinguish this fundamental MediaWiki functionality from any existing or future extensions that might use namespaces. I'm hoping "Logger" is sufficiently distinct from other uses of the term "log" in MediaWiki which generally mean "audit trail" rather than "debugging information". I'd be fine with throwing Debug in between Core and Logger too if consensus found for that instead.
I'd also like to start organizing these files in a directory structure that would be compatible with the PSR-4 auto loader standard. PSR-1 required all namespace elements to be in the file path as directories, but PSR-4 allows a common prefix for all classes to be dropped. I was thinking an includes/Core/ directory could be used as the common base for these and future namespaced classes in MediaWiki core.
We had some discussion last summer [2] about namespace use in extensions that seemed to end with "cool do it when you want" and "we don't really need any standard conventions". Since I'm suggesting namespace usage in core I figured this was worth another (hopefully short) round of discussion with the larger community than is likely to see my patches when they land in Gerrit.
My changes have been merged into HEAD and will be included in the upcoming 1.26wmf1 and REL_1_25 branches.
The base namespace that was used in the merged patch is MediaWiki\Logger. There is also a MediaWiki\Logger\Monolog namespace for Monolog specific classes. I left the PHP files in $IP/includes/debug/logger. The files there follow PSR-4 autoloader naming conventions but the idea of making a new PSR-4 compatible directory in $IP seemed like a tarpit that would have held up approval of the patch.
The MediaWiki\Logger\LoggerFactory::getInstance() static method is what most application level code should be interacting with to get a PSR-3 logger instance. This replaces the previous MWLoggerFactory::getInstance() and the deprecated MWLogger::getInstance() methods. Both of these are still available as shim classes until we get rid of all references to the old classes in extensions and WMF configuration files.
I will also be working on 1.23 LTS and 1.24 backport patches that will provide MediaWiki\Logger\LoggerFactory::getInstance() and Psr\Log\LoggerInterface with an implementation that proxies all of the Psr\Log\LoggerInterface methods to wfDebugLog(). This should make backporting things easier as MediaWiki core and extensions move to more direct use of PSR-3 logging.
Bryan
wikitech-l@lists.wikimedia.org