March
3rd, 2009
How to host the php.net manual on your laptop for offline use
In a previous article I wrote about how to develop web applications locally on your laptop. In addition to being faster to develop, it lets you work without needing to be connected to the Internet. But what about the tools you use while developing? If you’re a PHP developer then the manual at php.net is an invaluable tool. It only make sense to have it available for when you’re not online.
The general concept
The best way to get the full functionality of the php.net website is to create a mirror of it. This will give you the manual as well as additional functionality. The additional functionality isn’t as useful and you can remove any unwanted parts as you wish. We’ll be following the official mirroring documentation from the php.net website. This is for people that want to provide a mirror, but it turns out that it’s just as useful if you want to run a local copy of the site.
Setting up the rsync
The rsync command is fairly straightforward but we’ll be doing some slight modifications to it. We’ll create a shell script so that it’s easy to update the files as needed.
user# echo '#!/bin/sh
rsync -avzC --timeout=600 --delete --delete-after \
--include="manual/en/" --include="manual/en/**" --exclude="manual/**" --exclude="distributions/manual/**" \
--exclude="distributions/**" \
rsync.php.net::phpweb /path/to/document/root' > php-net-mirror.sh
user# chmod u+x php-net-mirror.sh
user# sudo su
root# echo 'php' >> /etc/hosts
root# exit
user# ./php-net-mirror.sh
You’ll notice that we added an exclusion list for distributions/**. This is so you won’t be sitting and waiting for 10+ distributions of PHP source to download to your laptop. You’ll also need to replace /path/to/document/root to any location that you have write permission to. We’ll later use this in our Apache vhost definition. I put it something inside of my home directory in a subdirectory named php.net. Don’t forget to set the permissions on the shell script so that you can execute it.
NOTE: If you’re using windows then you can use cwRsync available on sourceforge. Thanks to Ronnie and rui for the tips in the comments.
In order to access it from your browser you’ll need to decide what hostname to use. I chose php so that I can quickly browse to http://php/mysql_connect to view the documentation for that function. You can choose whatever you want, just substitute that when echo’ing into the hosts file.
The final step is to run the script. You’ll see the full list of files as they download. Updates should be much faster since you’ll only be pulling down files which have been modified.
Setting up Apache
Create a new Apache virtual host using the following definition.
<VirtualHost *>
<Directory "/path/to/document/root">
# Do not display directory listings if index is not present,
# and do not try to match filenames if extension is omitted
Options -Indexes -MultiViews
</Directory>
ServerName php
ServerAdmin yourname@example.com
# Webroot of PHP mirror site
DocumentRoot /path/to/document/root
# Log server activity
ErrorLog logs/error_log
TransferLog logs/access_log
# Set directory index
DirectoryIndex index.php index.html
# Handle errors with local error handler script
ErrorDocument 401 /error.php
ErrorDocument 403 /error.php
ErrorDocument 404 /error.php
# Add types not specified by Apache by default
AddType application/octet-stream .chm .bz2 .tgz .msi
AddType application/x-pilot .prc .pdb
# Set mirror's preferred language here
SetEnv MIRROR_LANGUAGE "en"
# Turn spelling support off (which would break URL shortcuts)
<IfModule mod_speling.c>
CheckSpelling Off
</IfModule>
</VirtualHost>
You’ll need to update the path to your document root on lines 2 and 12. This should match the path you specified in the shell script above. Line 8 also needs to be updated with the hostname you specified earlier to access the site with.
Fire up the site
That’s all! Execute the command you use to restart Apache. If you’re using OSX with MacPorts then you can execute the following commands.
user# sudo /opt/local/apache2/bin/apachectl restart user# open -a Safari "http://php/mysql_connect"
Viola!
An alternative for Mac users
Aziz noted in the comments that there’s a downloadable program PHPfi for Mac OSX users that looks very slick. You can download it from http://www.artissoftware.com/phpfi/index.html.
and living in Sunnyvale, CA.
March 5th, 2009 at 5:46 pm
Hi Jaisen… This tip is very useful… I`m syncing now php docs…
Can I publish your article in portuguese at my website?
March 5th, 2009 at 6:02 pm
@duodraco, of course. If you don’t mind linking back, that’d be great – but not required :).
March 5th, 2009 at 6:56 pm
Or you can grab the CHM from the php.net site if you’re running Windows.
http://us3.php.net/docs-echm.php
March 6th, 2009 at 5:16 am
Dan, last time that I grabbed CHM it was so old… I don’t know if it remains … but rsync method takes always updated information.
Jaisen: can you talk about .htaccess file for http://php/mysql_connect like searches? I did it, but i`m without my notebook today, so without file.
Sorry by mistakes in my english…
March 6th, 2009 at 3:56 pm
Jaisen,
Amazingly well-written tutorial. Much appreciated.
You can often tell the grasp someone has of their subject matter when they are able to write so effectively.
And congratulations on your new addition to the family!!!
March 8th, 2009 at 12:34 am
Also it’s not too difficult to build the manual then view said build in a similar way. See also:
http://wiki.php.net/doc/phd/view
And the build system (affectionally known as phd) also allows building plain old html, chm, and pdf too.
March 9th, 2009 at 1:45 pm
Thank you very much for the tutorial. After some hair pulling (very new to Apache, vhosts and overall programming beginner), I finally have a working mirror of the php.net documentation on my laptop.
Question, would you happen to have instructions for mirroring the Apache httpd documentation, too? I don’t really want to download the whole 28GB for the Apache website specially now that my ISP has implemented bandwidth caps, not to mention my laptop has barely any free space left. ^_^;
March 9th, 2009 at 2:20 pm
@rui, you can follow a similar sequence of steps by following the docs for setting up an apache mirror here: http://www.apache.org/info/how-to-mirror.html
March 10th, 2009 at 5:32 am
Thanks. I read that page but was hoping to avoid the large download:
“At least 40 GB of available disk space. The current distribution directory is around 28 GB, but we wish to leave room for considerable expansion.”
March 10th, 2009 at 6:50 am
@rui, that’s a bit big :). It’s entirely possible that you could exclude different languages and whatnot. However, I still expect it to be a big download.
March 10th, 2009 at 9:46 am
Yep, it’s really big. I think the problem with the instructions is it only gives you the rsync command-line to mirror the entire website. It doesn’t mention how you can download specific projects. For example, I’m only interested in getting a working mirror for the HTTP Server (httpd.apache.org), Perl (perl.apache.org) and XML (xml.apache.org) projects.
Guess I’ll try downloading on my desktop and trim it down before copying to the laptop. Just have to be really careful I don’t go over the 100GB download limit set by Charter. :(
March 12th, 2009 at 10:32 am
There is an Rsync for Windows called cwRsync at SourceForge. How well does that work? I would imagine the syntax for the shell script is the same, or at least easily adaptable.
March 12th, 2009 at 10:53 am
That’s a nice article – the limit with the CHMs they provide is that they go out of date quickly and you have to remember to update them. Having php.net rsync seems a pretty cool idea heh!
March 13th, 2009 at 10:41 am
@Ronnie:
That’s what I used for when following this tutorial. It worked pretty well and I now have a working mirror of the PHP manual on my laptop. Searchable, too. :)
March 13th, 2009 at 10:49 am
@rui, @Ronnie,
Thanks for the tip. I updated the post with a link to cwRsync. I have to say, after using it for a week I’m impressed at how well it works. Better than I suspected. Kudos to the PHP team!
March 13th, 2009 at 2:19 pm
Well I am going to have to follow in Rui’s footsteps and fire that puppy up. I am using Html-kit with keyword help that opens up the online Php manual, but sometimes the lag is unbearable (I want the answer now).
And jaisen, my name is not Lonnie. ;-)
March 13th, 2009 at 2:22 pm
@Ronnie, doh! Fixed. The L is nowhere close to the R on the keyboard.
May 1st, 2009 at 1:49 pm
awesome!
May 2nd, 2009 at 5:37 am
How to do it in windows?
May 2nd, 2009 at 5:41 am
oh, i got it. didn’t marked the line for windows :D
December 7th, 2009 at 5:48 pm
Are you using feedburner as your feed? I can’t seems to get it working on my feed reader.
December 18th, 2009 at 5:42 am
For the love of god someone please explain how to do this on windows..
Tried everythiung i can think of and now cwrsync is going through every registry entry on my pc.. wth is going on :(.
December 18th, 2009 at 5:55 am
Right. Figured, i hope..
My rsyncd.conf:
use chroot = false
strict modes = false
hosts allow = *
log file = rsyncd.log
# Module definitions
# Remember cygwin naming conventions : c:\work becomes /cygwin/c/work
#
[phpweb]
path = /cygdrive/c/phpman
comment = Rsync PHP Manual
read only = false
My Batch File:
rsync -avzC –timeout=600 –delete –delete-after –include=”manual/en/” –include=”manual/en/**” –exclude=”manual/**” –exclude=”distributions/manual/**” –exclude=”distributions/**” rsync.php.net::phpweb /cygdrive/c/phpman/’
(All of my batch file contents are on a single line).
Hopefully this will save the hour it took me to figure it out :P.
January 28th, 2010 at 1:57 am
can somebody give me a tip how to make it work under windows os ?
i have cwRsync
but what else ?
should i launch rsync.exe via cmd with parameters like given above ? cause im always getting errors :/
should i modify some files also ? *.cmd file ?
January 28th, 2010 at 2:01 am
Unfortunately, I can’t really help much on Windows. The best bet will probably be to use cygwin. Here’s an article I found via Google.
http://www.trueblade.com/knowledge/using-rsync-and-cygwin-to-sync-files-from-a-linux-server-to-a-windows-notebook-pc
January 28th, 2010 at 2:06 am
damn, but it is going aroung quite much :/ as i see above, people solved this on Win OS, but i have no idea how :)
im always getting some problems, cause im dont even know if im doing it correct …
nevertheless, im forced to see link you’ve provided, thanks
May 18th, 2010 at 4:36 am
nice article but i lack rsync access on my college network :(
@Dan Previte
Thanks for the chm link.. it is very latest :)
July 26th, 2010 at 4:41 am
I’m commenting a little bit late, but better late than never, right?
If you’re on a Mac, there is a little app called PHPfi, or PHP Function Index and it’s free for “Academic & Hobbyist Users”.
It’s basically a GUI frontend for the multiple xhtml files version of the php manual that you can find in the downloads section of php.net.
The cool thing is that it also indexes user comments and shows them in a drawer, AND it has a Textmate command that lets you search the current word in PHPfi from within the editor.
Here’s the link: http://www.artissoftware.com/phpfi/index.html
July 26th, 2010 at 7:35 am
@Aziz, This looks like a very cool program. I added it to the end of the blog post.