While trying to add some more information to https://www.mediawiki.org/wiki/Manual:Code, I came across a slightly peculiar issue regarding the entry points for MediaWiki:
Right now, among all the entry points that I know of (those are listed in Manual:Code), only mw-config/index.php doesn't sit in the root folder. Furthermore, it's related to the installer at includes/installer/, but that is not clear at all from the code organization, specifically the directory names (and the lack of documentation both in the file and on mediawiki.org).
I have two questions, then: 1) should all access points be on the root directory of the wiki, for consistency? 2) should the name "mw-config" be changed to something that more clearly indicates its relationship with the installer?
Note that these aren't merely nitpicking: a consistent structure and intuitive names for files and directories play an important role in the self-documenting nature of the code, and make the learning curve smoother for new developers (e.g. yours truly :-)).
Also, I used Tim Starling's suggestion on IRC to make sure the list of entry point scripts listed in Manual:Code was complete: git grep -l /includes/WebStart.php I am not sure that exhausts the list, however, since thumb_handler.php doesn't show up on its results. Any pointers regarding potential entry points currently omitted from that list are most welcome.
--Waldir
ps - while investigating this subject I came accross some inconsistencies in the way the access points include the WebStart.php file, including an incorrect use (according to Tim) of require_once() instead of require(). I submitted a change to Gerrit harmonizing them; if this interests you, please review the commit: https://gerrit.wikimedia.org/r/#/c/49208/
On 15/02/13 09:16, Waldir Pimenta wrote:
While trying to add some more information to https://www.mediawiki.org/wiki/Manual:Code, I came across a slightly peculiar issue regarding the entry points for MediaWiki:
Right now, among all the entry points that I know of (those are listed in Manual:Code), only mw-config/index.php doesn't sit in the root folder. Furthermore, it's related to the installer at includes/installer/, but that is not clear at all from the code organization, specifically the directory names (and the lack of documentation both in the file and on mediawiki.org).
I have two questions, then:
- should all access points be on the root directory of the wiki, for
consistency?
No. The installer is on its on folder on purpose, so that you can delete that folder once you have installed the wiki.
- should the name "mw-config" be changed to something that more clearly
indicates its relationship with the installer?
Note that these aren't merely nitpicking: a consistent structure and intuitive names for files and directories play an important role in the self-documenting nature of the code, and make the learning curve smoother for new developers (e.g. yours truly :-)).
It was originally named "config". It came from the link that sent you there: "You need to configure your wiki first". Then someone had problems with other program that was installed sitewide on his host appropiating the /config/ folder, so it was renamed to mw-config.
Also, I used Tim Starling's suggestion on IRC to make sure the list of entry point scripts listed in Manual:Code was complete: git grep -l /includes/WebStart.php I am not sure that exhausts the list, however, since thumb_handler.php doesn't show up on its results. Any pointers regarding potential entry points currently omitted from that list are most welcome.
That's probably because it doesn't include WebStart (it included thumb.php, which is the one including WebStart).
Take a look at tools/code-utils/find-entries.php I have updated it to add a few new rules in https://gerrit.wikimedia.org/r/49230
It will give you about 100 files to check, most of them cli scripts. Although there are a few web-enabled ones, such as tests/qunit/data/styleTest.css.php
Use -d to see why that file was considered an entry point. As you'll see, it is very strict -with reason- in what it considers safe.
On Fri, Feb 15, 2013 at 11:58 AM, Platonides Platonides@gmail.com wrote:
On 15/02/13 09:16, Waldir Pimenta wrote:
- should all access points be on the root directory of the wiki, for
consistency?
No. The installer is on its on folder on purpose, so that you can delete that folder once you have installed the wiki.
Sorry if I wasn't clear. I meant that mw-config/index.php should be in te root, not that the installer files should. Unless I'm misunderstanding you, and by "the installer" you mean the contents of mw-config/ rather than /includes/installer (which would prove my point about unclear nomenclature).
Also, I used Tim Starling's suggestion on IRC to make sure the list of
entry point scripts listed in Manual:Code was complete: git grep -l /includes/WebStart.php I am not sure that exhausts the list, however, since thumb_handler.php doesn't show up on its results. Any pointers regarding potential entry points currently omitted from that list are most welcome.
That's probably because it doesn't include WebStart (it included thumb.php, which is the one including WebStart).
Take a look at tools/code-utils/find-entries.php I have updated it to add a few new rules in https://gerrit.wikimedia.org/r/49230
It will give you about 100 files to check, most of them cli scripts. Although there are a few web-enabled ones, such as tests/qunit/data/styleTest.css.php
Use -d to see why that file was considered an entry point. As you'll see, it is very strict -with reason- in what it considers safe.
Thanks, that sounds quite useful, but I don't seem to be able to run it properly (I get a few php warnings, and "0/0" as output). I placed it in the root dir of my local wiki. Am I missing anyting?
On 15/02/13 17:28, Waldir Pimenta wrote:
On Fri, Feb 15, 2013 at 11:58 AM, Platonides Platonides@gmail.com wrote:
On 15/02/13 09:16, Waldir Pimenta wrote:
- should all access points be on the root directory of the wiki, for
consistency?
No. The installer is on its on folder on purpose, so that you can delete that folder once you have installed the wiki.
Sorry if I wasn't clear. I meant that mw-config/index.php should be in te root, not that the installer files should. Unless I'm misunderstanding you, and by "the installer" you mean the contents of mw-config/ rather than /includes/installer (which would prove my point about unclear nomenclature).
Well, every bit of the installer used to be in the config folder, until the rewrite, which moved the classes to includes/installer Now you mention it, you're probably right in that it could be moved to eg. /installer.php
Thanks, that sounds quite useful, but I don't seem to be able to run it properly (I get a few php warnings, and "0/0" as output). I placed it in the root dir of my local wiki. Am I missing anyting?
Yes, you need to pass it a list of files as parameters.
If you want to run the script on the whole folder you could for instance run: find -name "*.php" -exec php find-entries.php {} +
On 15/02/13 09:16, Waldir Pimenta wrote:
should all access points be on the root directory of the wiki, for consistency? currently mw-config/index.php is the only one not in the root.
On Mon, Feb 18, 2013 at 3:56 PM, Platonides Platonides@gmail.com wrote:
Well, every bit of the installer used to be in the config folder, until the rewrite, which moved the classes to includes/installer Now you mention it, you're probably right in that it could be moved to eg. /installer.php
OK, so I'll ask here on the list: is there any reason we shouldn't move [root]/mw-config/index.php to [root]/installer.php?
On Feb 18, 2013, at 5:54 PM, Waldir Pimenta waldir@email.com wrote:
On 15/02/13 09:16, Waldir Pimenta wrote:
should all access points be on the root directory of the wiki, for consistency? currently mw-config/index.php is the only one not in the root.
On Mon, Feb 18, 2013 at 3:56 PM, Platonides Platonides@gmail.com wrote:
Well, every bit of the installer used to be in the config folder, until the rewrite, which moved the classes to includes/installer Now you mention it, you're probably right in that it could be moved to eg. /installer.php
OK, so I'll ask here on the list: is there any reason we shouldn't move [root]/mw-config/index.php to [root]/installer.php?
Well, Platonides already gave a reason:
On Feb 15, 2013, at 12:58 PM, Platonides platonides@gmail.com wrote:
On 15/02/13 09:16, Waldir Pimenta wrote:
should all access points be on the root directory of the wiki, for consistency?
No. The installer is on its on folder on purpose, so that you can delete that folder once you have installed the wiki.
It is also arguably easier to understand for non-tech users to navigate to the "mw-config" directory compared to the "installer.php" file (though that's a minor difference, if any).
There's also an overrides.php file and an mw-config/index.php5 file.
If it were just "installer.php" it'd be equally easy to removed as the directory, but since there three files, (one of which depends on another, so if you'd just remove installer.php then you're left in an unclean state where hitting installer.php5 will cause an internal server error clogging the php error log).
… which brings up for how much longer we should keep that *.php5 stuff around…
But before more bike shedding (have we had enough these last 2 months yet?), is there a problem with having a directory?
-- Krinkle
On Mon, Feb 18, 2013 at 5:17 PM, Krinkle krinklemail@gmail.com wrote:
But before more bike shedding (have we had enough these last 2 months yet?), is there a problem with having a directory?
It somewhat breaks the pattern, considering that all the other access points (and their corresponding php5 files) are located in the root. So that leaves only overrides.php, which I'm not sure why it was kept in mw-config, considering that (quoting Platonides) "the installer used to be in the config folder, until the rewrite, which *moved the classes* to includes/installer" (emphasis mine). If the classes were moved to includes/installer, why did those of overrides.php's remain? So they can be easily deleted? I don't think they're the only files that are kept around that people won't use, so the convenience of an easy deletion doesn't seem that much of a big advantage, especially at the expense of a logical organization of the code.
By the way, there's also an INSTALL file in the root, so even if overrides.php was moved there, it wouldn't be the only installation-related non-access-point to be kept there.
On Mon, Feb 18, 2013 at 1:53 PM, Waldir Pimenta waldir@email.com wrote:
On Mon, Feb 18, 2013 at 5:17 PM, Krinkle krinklemail@gmail.com wrote:
But before more bike shedding (have we had enough these last 2 months yet?), is there a problem with having a directory?
It somewhat breaks the pattern, considering that all the other access points (and their corresponding php5 files) are located in the root. So that leaves only overrides.php, which I'm not sure why it was kept in mw-config, considering that (quoting Platonides) "the installer used to be in the config folder, until the rewrite, which *moved the classes* to includes/installer" (emphasis mine). If the classes were moved to includes/installer, why did those of overrides.php's remain? So they can be easily deleted? I don't think they're the only files that are kept around that people won't use, so the convenience of an easy deletion doesn't seem that much of a big advantage, especially at the expense of a logical organization of the code.
By the way, there's also an INSTALL file in the root, so even if overrides.php was moved there, it wouldn't be the only installation-related non-access-point to be kept there. _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Moving around files causes confusion as all docs have to be updated, and some docs will be missed. Sometimes that sort of confusion can't be avoided, but if there's no problem with where the installer is, I would be opposed to moving.
Some very paranoid people may still want to delete the installer entry point after install, as one can still use it to do maintenance stuff (db upgrades) if folks have the right password. Putting it in /mw-config also provides a nice separation from mediawiki proper imo.
--bawolff
On 18/02/13 18:53, Waldir Pimenta wrote:
It somewhat breaks the pattern, considering that all the other access points (and their corresponding php5 files) are located in the root. So that leaves only overrides.php, which I'm not sure why it was kept in mw-config, considering that (quoting Platonides) "the installer used to be in the config folder, until the rewrite, which *moved the classes* to includes/installer" (emphasis mine). If the classes were moved to includes/installer, why did those of overrides.php's remain?
Read the beginning of overrides.php:
<?php /**
- MediaWiki installer overrides.
- Modify this file if you are a packager who needs to modify the behavior of the MediaWiki installer.
- Altering it is preferred over changing anything in /includes.
On Mon, 18 Feb 2013 09:53:54 -0800, Waldir Pimenta waldir@email.com wrote:
On Mon, Feb 18, 2013 at 5:17 PM, Krinkle krinklemail@gmail.com wrote:
But before more bike shedding (have we had enough these last 2 months yet?), is there a problem with having a directory?
It somewhat breaks the pattern, considering that all the other access points (and their corresponding php5 files) are located in the root.
index.php, api.php, etc... provide entrypoints into the configured wiki.
mw-config/ installs and upgrades the wiki. With much of itself disconnected from core code that requires a configured wiki. And after installation it can even be eliminated completely without issue.
I don't consider the stuff inside mw-config to be an entrypoint. Nor something that belongs in the root.
I wouldn't even include mw-config in entrypoint modifications that would be applied to other entrypoint code. https://www.mediawiki.org/wiki/Requests_for_comment/Entrypoint_Routing_and_4...
On Wed, Feb 27, 2013 at 9:13 PM, Daniel Friesen daniel@nadir-seen-fire.comwrote:
index.php, api.php, etc... provide entrypoints into the configured wiki.
mw-config/ installs and upgrades the wiki. With much of itself disconnected from core code that requires a configured wiki. And after installation it can even be eliminated completely without issue.
I think this clarifies the issue for me. Correct me if I'm wrong, but basically the entry points are for continued, repeated use, for indeed *accessing* wiki resources (hence I suggest the normalization of the name of these scripts to "access points" everywhere in the docs, because "entry" is a little more generic), while mw-config/index.php is a one-off script that has no use once the wiki installation is done. I'll update the docs in mw.org accordingly, to make this clear.
I wouldn't even include mw-config in entrypoint modifications that would be applied to other entrypoint code.
You mean like this one https://gerrit.wikimedia.org/r/#/c/49208/? I can understand, in the sense that it gives people the wrong idea regarding its relationship with the other access points, but if the documentation is clear, I see no reason not to have mw-config/index.php benefit from changes when the touched code is the part common to all *entry* points (in the strict meaning of files that can be used to enter the wiki from a web browser).
That said, and considering what Platonides mentioned:
It was originally named "config". It came from the link that sent you
there: "You need to configure your wiki first". Then someone had problems with other program that was installed sitewide on his host appropiating the /config/ folder, so it was renamed to mw-config.
...I would suggest the mw-config directory to be renamed to something that more clearly identifies its purpose. I'm thinking "first-run" or something to that effect. I'll submit a patchset proposing this.
--Waldir
On 3/8/13, Waldir Pimenta waldir@email.com wrote:
On Wed, Feb 27, 2013 at 9:13 PM, Daniel Friesen daniel@nadir-seen-fire.comwrote:
index.php, api.php, etc... provide entrypoints into the configured wiki.
mw-config/ installs and upgrades the wiki. With much of itself disconnected from core code that requires a configured wiki. And after installation it can even be eliminated completely without issue.
I think this clarifies the issue for me. Correct me if I'm wrong, but basically the entry points are for continued, repeated use, for indeed *accessing* wiki resources (hence I suggest the normalization of the name of these scripts to "access points" everywhere in the docs, because "entry" is a little more generic), while mw-config/index.php is a one-off script that has no use once the wiki installation is done. I'll update the docs in mw.org accordingly, to make this clear.
I wouldn't even include mw-config in entrypoint modifications that would be applied to other entrypoint code.
You mean like this one https://gerrit.wikimedia.org/r/#/c/49208/? I can understand, in the sense that it gives people the wrong idea regarding its relationship with the other access points, but if the documentation is clear, I see no reason not to have mw-config/index.php benefit from changes when the touched code is the part common to all *entry* points (in the strict meaning of files that can be used to enter the wiki from a web browser).
That said, and considering what Platonides mentioned:
It was originally named "config". It came from the link that sent you
there: "You need to configure your wiki first". Then someone had problems with other program that was installed sitewide on his host appropiating the /config/ folder, so it was renamed to mw-config.
...I would suggest the mw-config directory to be renamed to something that more clearly identifies its purpose. I'm thinking "first-run" or something to that effect. I'll submit a patchset proposing this.
--Waldir _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
The installer is also used to do database updates when upgrading mediawiki, so its not just a run-once-and-only-once thing.
--bawolff
On Sat, Mar 9, 2013 at 11:48 AM, Brian Wolff bawolff@gmail.com wrote:
On 3/8/13, Waldir Pimenta waldir@email.com wrote:
...I would suggest the mw-config directory to be renamed to something
that
more clearly identifies its purpose. I'm thinking "first-run" or
something
to that effect. I'll submit a patchset proposing this.https://lists.wikimedia.org/mailman/listinfo/wikitech-l
The installer is also used to do database updates when upgrading mediawiki, so its not just a run-once-and-only-once thing.
So mw-config can't be deleted after all? Or you mean the installer at includes/installer? Is you mean the former, then how about "run-installer" instead of my previous proposal of "first-run"? Any of these would be clearer than "mw-config", imo.
--Waldir
On 09/03/13 15:47, Waldir Pimenta wrote:
So mw-config can't be deleted after all? Or you mean the installer at includes/installer? Is you mean the former, then how about "run-installer" instead of my previous proposal of "first-run"? Any of these would be clearer than "mw-config", imo.
--Waldir
You can delete it, but then you can't use it to upgrade the wiki (or rather, you would need to copy it again from the new tree).
On Sat, 09 Mar 2013 08:15:05 -0800, Platonides Platonides@gmail.com wrote:
On 09/03/13 15:47, Waldir Pimenta wrote:
So mw-config can't be deleted after all? Or you mean the installer at includes/installer? Is you mean the former, then how about "run-installer" instead of my previous proposal of "first-run"? Any of these would be clearer than "mw-config", imo.
--Waldir
You can delete it, but then you can't use it to upgrade the wiki (or rather, you would need to copy it again from the new tree).
mw-config only updates the databse to the currently installed version of MW. So it's fine to delete mw-config because you won't need that mw-config anymore. When you upgrade you'll need the mw-config that comes with the code for the new version of MediaWiki you're installing.
On 2013-03-12 6:31 AM, "Daniel Friesen" daniel@nadir-seen-fire.com wrote:
On Sat, 09 Mar 2013 08:15:05 -0800, Platonides Platonides@gmail.com
wrote:
On 09/03/13 15:47, Waldir Pimenta wrote:
So mw-config can't be deleted after all? Or you mean the installer at includes/installer? Is you mean the former, then how about "run-installer" instead of my previous proposal of "first-run"? Any of these would be clearer than "mw-config", imo.
--Waldir
You can delete it, but then you can't use it to upgrade the wiki (or rather, you would need to copy it again from the new tree).
mw-config only updates the databse to the currently installed version of
MW. So it's fine to delete mw-config because you won't need that mw-config anymore. When you upgrade you'll need the mw-config that comes with the code for the new version of MediaWiki you're installing.
-- ~Daniel Friesen (Dantman, Nadir-Seen-Fire) [http://danielfriesen.name/]
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
There are cases where you still want mw-config even without upgrading. For example changing wgCategoryCollation or installing an extension with schema changes.
-bawolff
On Fri, 08 Mar 2013 18:18:52 -0800, Waldir Pimenta waldir@email.com wrote:
On Wed, Feb 27, 2013 at 9:13 PM, Daniel Friesen daniel@nadir-seen-fire.comwrote:
I wouldn't even include mw-config in entrypoint modifications that would be applied to other entrypoint code.
You mean like this one https://gerrit.wikimedia.org/r/#/c/49208/? I can understand, in the sense that it gives people the wrong idea regarding its relationship with the other access points, but if the documentation is clear, I see no reason not to have mw-config/index.php benefit from changes when the touched code is the part common to all *entry* points (in the strict meaning of files that can be used to enter the wiki from a web browser).
No different changes. I was talking about this RFC: https://www.mediawiki.org/wiki/Requests_for_comment/Entrypoint_Routing_and_4...
Part of the plan was to move all the entrypoint handling into the common code. All the entrypoint files like api.php would become non-mandatory. They would basically be tiny files that all just include the MediaWiki code in the exact same way. While the common code does the work deciding what code to run for which entrypoint. After that most of the paths could be blindly directed right to index.php and the codebase would handle delegating paths like api.php to the Api, handling 404s, etc...
mw-config/index.php would never get that tweak.
--Waldir
wikitech-l@lists.wikimedia.org