[B][COLOR=#0b6d90]Automating WordPress customizations - the install.php way[/COLOR][/B]
Posted by [B][COLOR=#0b6d90]Leonid Mamchenkov[/COLOR][/B] on August 10, 2007
In “[B][COLOR=#0b6d90]Automating WordPress customizations - the plugin way[/COLOR][/B]” we looked at how to change a whole bunch of thing in one go by having our own plugin. The plugin approach can save a lot of time, but it does not actually give any control over the installation process.
Often we want to interfere with the way things are. For example, upon successful WordPress installation you find a web site with one post (”Hello World!”), one page (”About”), and a test comment to the first post. Also, there is a category “Uncategorized”, and “admin” user, and a few other things in the database, which are not so obvious (for example, user roles, such as Administrator, Editor, and Subscriber).
There are also a few things, which are happening during the installation process itself. For example, a random password for the administrator is generation, and email is sent to the administrator’s address with credentials and new site details. As handy as it is for a friend’s new blog, there are many situations when we don’t want this done, or want it done differently.
WordPress has a way to control installation flow via a custom [I]install.php[/I] file, which saves you from all the problems of core files editing. In this post, we’ll see how to use this feature and what can actually be done with it.
Let’s start with some source diving. Before we do any modifications of our own, it’s good to get an idea of how things work under the hood. The installation process starts with [URL="http://www.nulled.ws/r.php?url=http%3A%2F%2Fwordpress.taragana.net%2Fwp-admin%2Finstall.php.source.html"][B][COLOR=#0b6d90]wp-admin/install.php[/COLOR][/B][/URL] , so this where we’ll start too. This is what we see at the top of the file (chopped off on the right a bit, but it doesn’t matter for now):
[IMG]http://wpbits.files.wordpress.com/2007/08/top_of_install_php.png[/IMG]
A flag that signals that we are in the installation process is set, and a check is done for the presence of the [I]wp-config.php[/I] file, which should have database credentials, table prefix, and things like that. So far so good.
Then the content of [I]wp-config.php[/I] is imported. OK, makes sense.
Then the content of [URL="http://www.nulled.ws/r.php?url=http%3A%2F%2Fwordpress.taragana.net%2Fwp-admin%2Fupgrade-functions.php.source.html"][B][COLOR=#0b6d90]upgrade-functions.php[/COLOR][/B][/URL] is imported. Hold on. What’s that? Let’s see the content of that file before we go forward. Maybe there is something interesting in there. Here are the first few lines:
[IMG]http://wpbits.files.wordpress.com/2007/08/top_of_upgrade-functions_php.png[/IMG]
A check is done for the presence of [I]wp-content/install.php[/I] file. And if it exists, it’s included straight away. But what is in this wp-content/install.php file? I don’t have any in my brand new and shiny WordPress installation. Did I do something wrong?
No! This is exactly what we were looking for. This is the way WordPress gives you all the power over the installation process. Before it does anything itself, it checks if instructed it to do anything. If you don’t have your own [I]wp-content/install.php[/I] file, WordPress will do its own installation routine.
What can we do with it now? Anything. But anything is too broad of a thing. We need a test of our new superpowers. How about we cancel a WordPress installation altogether? That should prove how much power we have over WordPress. So, here is the content of [B]the first version[/B] of my [I]wp-content/install.php[/I] file:
[IMG]http://wpbits.files.wordpress.com/2007/08/custom_install_php_v1.png[/IMG]
Looks sufficient. Now let’s see what happens to the installation process… Oh, Noooo! It didn’t work! It worked, but it didn’t do everything I wanted it to. Here is how my WordPress installation screen looks now.
[IMG]http://wpbits.files.wordpress.com/2007/08/broken_wordpress_installation_v1.png[/IMG]
My evil signature appears at the top of the installation screen, but the installation didn’t stop. Why? Because, actually I never told it to. So, here is the second version of my custom install.php, which should fix the problem:
[IMG]http://wpbits.files.wordpress.com/2007/08/custom_install_php_v2.png[/IMG]
Now I tell WordPress to exit (as in finish, stop, end) from the installation process, like everything is done. And it works! Here is how my installation screen looks now:
[IMG]http://wpbits.files.wordpress.com/2007/08/broken_wordpress_installation_v2.png[/IMG]
So, now there is no way to install WordPress. I have full control over the matter. And that makes me feel all that powerful and important. Now that we established the authority (”Respect my authorita!” © South Park), how can we do good?
Although you can completely re-write and re-implement WordPress installation process, it’s not something you’d want to do very often. After all, it works, right? So, why break it? What we do want often though is some minor changes to the process.
How can we achieve this? Is there a simple way of modifying WordPress installation without creating it from scratch ourselves? The answer is - yes.
Let’s look further down into the [URL="http://www.nulled.ws/r.php?url=http%3A%2F%2Fwordpress.taragana.net%2Fwp-admin%2Fupgrade-functions.php.source.html"][B][COLOR=#0b6d90]wp-admin/upgrade-functions.php[/COLOR][/B][/URL] file. It has functions, alright. But there are a few places where it checks for the presence of the function, before defining it. See the example of [I]wp_install()[/I].
[IMG]http://wpbits.files.wordpress.com/2007/08/middle_of_upgrade-functions_php.png[/IMG]
Notice that [I]function_exists(’wp_install’)[/I] check? Why is it there? Doesn’t WordPress know which functions it has and which it doesn’t?
This is the nice way that WordPress gives us to control the installation process without much work on our side. If we look through the file, we’d notice that there are four functions which are defined in this way:
[LIST]
[*][I]wp_install()[/I]
[*][I]wp_install_defaults()[/I]
[*][I]wp_new_blog_notification()[/I]
[*][I]wp_upgrade()[/I]
[/LIST]So, these are the places where we can easily interfere.
Since we only want to change just a few things, we can start from the existing code. We can achieve that by simply copying the code from WordPress definitions of these functions into our custom [I]install.php[/I] and change a few lines there. If we have any of those functions defined in our [I]install.php[/I], WordPress will use those instead of its own ones.
[B]IMPORTANT:[/B] if we are to supply WordPress with our own functions, than we should accept the parameters and return values as WordPress expects them. Otherwise, things might break.
So, what do those special functions do?
[B]wp_install()[/B]
This function handles the installation routines. It calls other methods, which create database tables, populate options with default values, create user roles, etc. It also creates an admin user with a random password and assigns it an Administrator role. Once everything is done, it calls another function to send a notification about successful blog installation.
[B]wp_install_defaults()[/B]
This function creates all those default entries that you find in your new WordPress installation - first post, first comment, first page, default category, and a bunch of links in the blogroll.
[B]wp_new_blog_notification()[/B]
This function generates and sends that email with username and password which site administrator gets upon a successful installation.
[B]wp_upgrade()[/B]
This function handles the upgrade process. If you made a lot of changes to the installation process, chances are you’ll want to make sure those changse are handled properly during the upgrade of the system, and so this is the function to help you out in that.
Here are a couple of examples of what you might want to do.
[B]Modify user roles[/B]
If you want your web sites roles to be configured differently, you can, of course, use an excellent Role Manager plugin and set them just the way you want. But that would be a pain to do over and over again for new sites. So, it might be a better option to customize things automatically during the installation process.
Here is how to do that:[LIST=1]
[*]See how [I]populate_roles()[/I] function works (it is defined in [URL="http://www.nulled.ws/r.php?url=http%3A%2F%2Fwordpress.taragana.net%2Fwp-admin%2Fupgrade-schema.php.source.html"][B][COLOR=#0b6d90]wp-admin/upgrade-schema.php[/COLOR][/B][/URL] file)
[*]Define your own function (say [I]populate_my_roles()[/I]) in your custom [I]install.php[/I]
[*]Copy the definition of [I]wp_install()[/I] function from [URL="http://www.nulled.ws/r.php?url=http%3A%2F%2Fwordpress.taragana.net%2Fwp-admin%2Fupgrade-functions.php.source.html"][B][COLOR=#0b6d90]wp-admin/upgrade-functions.php[/COLOR][/B][/URL] into your custom [I]install.php[/I]
[*]Add a call to your role functions ([I]populate_my_roles()[/I]) after the call to [I]populate_roles()[/I] in the copied [I]wp_install()[/I] function.
[/LIST][B]Add, change or remove default category, post, page, links[/B]
I’ve heard many people who want to start with “General” category, not “Uncategorized”. And if you are making lots of WordPress-based web sites, than first post, page, and comment probably don’t make much sense - you remove them right after the installation. If you are WordPress installations for corporate clients, you often want to lose the default links (as much as you love WordPress developers, links to their blogs don’t make much sense from your clients’ web sites).
[I]wp_install_defaults()[/I] is the place to do all that. Copy it to your custom install.php . If you want to start with a clean WordPress installation - remove all lines in that function. Just delete them. So that you have only the function definition and nothing else. Otherwise, add and edit the lines accordingly. Most of the stuff you see in WordPress’ function definition are SQL statements anyway. So you can put your own ones here.
Now it is time to return to the [URL="http://www.nulled.ws/r.php?url=http%3A%2F%2Fwordpress.taragana.net%2Fwp-admin%2Finstall.php.source.html"][B][COLOR=#0b6d90]wp-admin/install.php[/COLOR][/B][/URL] file, which we got carried away from by all those upgrade functions. If you scroll through really slow, you’d notice that there is something about steps in there.
[IMG]http://wpbits.files.wordpress.com/2007/08/installation_steps.png[/IMG]
These steps are used to move the user from one installation screen to another. In the same file, there is a switch() statement, which selects the appropriate screen to show. There are a few links and forms in the file, that specify to which step the installation should switch further. Those a bit difficult to spot because of all the HTML markup in the file, but you can search for “step” and see where it is used.
The [I]install.php[/I] file from WordPress can be used as a real example for a custom installation routine. If you want to change the way your WordPress is installed, what the user is asked, or which functions are called at which points of the installation, [I]install.php[/I] is a valuable reference.
Did I miss anything?