Tuesday, January 5, 2010

Unix manual pages for PHP functions

Did you know that unix manual pages for PHP functions and methods existed?

For a while I had vim configured to run reflection when I hit "K", but after the PHP documentation team released unix manual pages for PHP I now get the manual page in all its glory; function description, parameter descriptions, return values, examples, notes, see also and everything you are used to see from the online manual.
Its awesome.

As many PHP functions use "standard names" the documentation team decided to not install the manual in the standard man directory.
When you install the unix manual package you get a little shell script (called "pman") which runs the normal "man" command for you, and sets the manual directory to wherever you installed the package.


To install the PHP manual as unix manual pages:

$ pear install doc.php.net/pman


If you are running very old pear version you need to "discover" the doc.php.net channel first:

$ pear channel-discover doc.php.net

And then run the command above.

The manual will install into whichever directory you have specified as the "doc_dir" in the pear configuration, and the "pman" script into "bin_dir".
By default I believe pear sets the "bin_dir" to something that is already in your $PATH so you should be able to execute "pman strpos" now.


In VIM you need to update the "keywordprg" config (or add it, if it doesn't exists already) to "pman":

set keywordprg=pman


Now open up a .php file, place your cursor over some PHP function and hit "K", you should get the manual page for that function \o/.


Unfortunately Symfony, Zend Framework, Doctrine, and other frameworks/libraries/.. do not distribute unix manual pages yet so I use the Taglist plugin to jump to the code.

Looking forward to when these frameworks start producing unix manual pages, so much easier to read :D

-Hannes

29 comments:

  1. Really nice. Thanks for the hint.

    ReplyDelete
  2. Cool -- I've added the keywordprg setting to my php.vim ftplugin, and now can have man page lookup that's specific to PHP. /me takes note to figure out how we might do this in ZF...

    ReplyDelete
  3. This is indeed a very nice feature which I will use from this day on...

    ReplyDelete
  4. That's a really nice manual format I didn't know about until now. Thanks for the post. I love the easy integration with Vim, which is my favorite php editor :)

    Cheers,
    Jakob

    ReplyDelete
  5. Really would appreciate if you could add a screenshot of vi with the man open.

    ReplyDelete
  6. Anon: There isn't much to see, other then a standard manual page.
    Rudy posted some screenshots couple of years ago...:

    ReplyDelete
  7. Thanks for reminding me of this. Newbies with ubuntu should remember to increase PHP memory before installing... :P

    ReplyDelete
  8. thank you for sharing this tip with us. Though it is available for some time I seem to have missed it while I wanted it.

    ReplyDelete
  9. sam@sam-desktop:/usr/share/php/PEAR/pman$ sudo pear install doc.php.net/pman
    downloading pman-1.0.1.tgz ...
    Starting to download pman-1.0.1.tgz (3,895,049 bytes)
    .....................done: 3,895,049 bytes
    sam@sam-desktop:/usr/share/php/PEAR/pman$ pman strpos
    The program 'pman' is currently not installed. You can install it by typing:
    sudo apt-get install pmtools
    pman: command not found
    sam@sam-desktop:/usr/share/php/PEAR/pman$

    ==================
    I have this problem when I use pear install under Ubuntu9.10

    ReplyDelete
  10. sam:
    Make sure the path you get from:
    $ pear config-get bin_dir

    is in your $PATH

    ReplyDelete
  11. Yes, it is:

    sam@sam-laptop:~$ pear config-get bin_dir
    /usr/bin
    sam@sam-laptop:~$ echo $PATH
    /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games

    ReplyDelete
  12. More Info:
    ==========
    sam@sam-laptop:~$ sudo find / -name 'pman';
    [sudo] password for sam:
    /usr/share/php/PEAR/pman
    sam@sam-laptop:~$

    ReplyDelete
  13. Thats.. odd.
    I assume you have thousands of files under /usr/share/php/PEAR/pman/man3 ?

    I just noticed, while reinstalling pman locally, you never get the "install ok: channel://doc.php.net/pman-1.0.1" message.

    Try turning on all possible PHP warnings, maybe pear is error out somehwere.

    You should have around 6200 files in the pman/man3 directory, plus one executable 'pman'.

    ReplyDelete
  14. This should be a download problem under Ubuntu, My error level setting:
    error_reporting = E_ALL
    display_errors = On
    But I didn't get any error info.
    ===========
    sam@sam-desktop:/usr/share/php/PEAR/pman$ ls -all ./man3/* | wc -l
    1900
    sam@sam-desktop:/usr/share/php/PEAR/pman
    ===========
    seems like a tar probelm:
    cp /build/buildd/php5-5.2.10.dfsg.1/pear-build-download/pman-1.0.1.tgz ~/
    cd ~
    sudo tar -zxcf pman-1.0.1.tgz
    cd pman-1.0.1/
    sam@sam-desktop:~/pman-1.0.1$ ls -all
    total 276
    drwxr-xr-x 3 root root 4096 2010-01-07 10:16 .
    drwxr-xr-x 38 sam sam 4096 2010-01-07 10:16 ..
    drwxr-xr-x 2 root root 270336 2010-01-07 10:16 man3
    -rw-r--r-- 1 sam sam 53 2009-01-08 02:35 pman.sh
    sam@sam-desktop:~/pman-1.0.1$ ls -all man3/* | wc -l
    6204

    ReplyDelete
  15. I copy all the file to man3 and make a softlike for pman.sh to /usr/bin/, but still can't use 'K' in VIM:
    ========
    try pman
    sam@sam-desktop:/usr/share/php/PEAR/pman$ pman
    What manual page do you want?

    try VIM:
    No manual entry for in_array
    shell returned 16
    Press ENTER or type command to continue

    ReplyDelete
  16. Does this work?
    $ man -M /usr/share/php/PEAR/pman/ strpos

    Did you remember to update your vim binding?

    ReplyDelete
  17. sam@sam-desktop:/usr/share/php/PEAR/pman$ man -M /usr/share/php/PEAR/pman/ strpos
    No manual entry for strpos

    sam@sam-desktop:/usr/share/php/PEAR/pman/man3$ ls -al *strpos*
    -rw-r--r-- 1 root root 841 2010-01-07 10:13 grapheme_strpos.3.gz
    -rw-r--r-- 1 root root 820 2010-01-07 10:13 iconv_strpos.3.gz

    ReplyDelete
  18. sam: your download seems broken.
    Try
    $ wget http://doc.php.net/get/pman-1.0.1.tgz
    $ pear install pman-1.0.1.tgz

    If that doesn't work, send me an email; hannes.magnusson@gmail.com and I'll look better into this.

    ReplyDelete
  19. with the help of
    $ wget http://doc.php.net/get/pman-1.0.1.tgz
    $ pear install pman-1.0.1.tgz

    I finally find the problem:
    Fatal error: Allowed memory size of 33554432 bytes exhausted (tried to allocate 8192 bytes) in /usr/share/php/PEAR/Installer.php on line 572

    So I modify /etc/php5/cli/php.ini and pman can be installed now.

    ReplyDelete
  20. Awesome, thanks for the tip.

    ReplyDelete
  21. I've got all 6204 files in man3 as noted in the earliest test of using the tarball, but a lot of functions that seem to have man pages in that directory are returning "No manual entry for X" from vim. dirname works, for example, but str_replace, get_include_path, set_include_path, in_array, and spl_autoload_register don't. Seems to be any function with an underscore in the name has this problem?

    ReplyDelete
  22. Elazar:
    Function names with underscore work fine for me.

    Does
    $ pman in_array
    work for you?

    Does the file "man3/in_array.3.gz" have any content?

    ReplyDelete
  23. Any chance of getting a new build? April 2010 was a long time ago ... thanks!

    ReplyDelete
  24. Errr... Very good point Sebastian.
    We were looking into how to automatically package and publish pear packages... a year ago...
    I don't know what happened to that idea, but we should at the very least publish new unix manpage builds, even if they are created manually, ASAP

    -Hannes

    ReplyDelete
  25. Committed a freshly generated function reference (generated by Phd) to a public Git repository for those interested: https://github.com/rbakels/PHP-Documentation

    Nothing fancy, except for a recent build of the PHP documentation :).

    ReplyDelete
  26. The doc.php.net channel doesn't work with pear 1.8.1 on Centos 5.5. Perhaps it is something to do with the HTTP Redirect?

    I upgraded to 1.9.2 and it worked fine.

    ReplyDelete
  27. @Sam: IIRC the doc.php.net wasn't "installed by default" until PEAR 1.9, so you had to "channel-dicover" it first. The channel itself should work fine with PEAR 1.8 after that (if not, please do file a bug report).

    @Robin: Thanks for the push :)
    After your kick-in-the-balls we have now published an up2date unix man pages. It is now available on the doc.php.net channel.

    ReplyDelete
  28. This may be an old post.. but still very relevant, thanks a lot for sharing ( and good-bye php.net/manual/ ^^ ) !

    ReplyDelete