cvs: peardoc /en/guide/users installation.xml /en/guide/users/installation checking.xml getting.xml introduction.xml shared.xml
[email protected] ("Christian Weiske")
| Newsgroups | php.pear.doc |
|---|---|
| Message-ID | <cvscweiske1235511567@cvsserver> |
cweiske Tue Feb 24 21:39:27 2009 UTC
Modified files:
/peardoc/en/guide/users installation.xml
/peardoc/en/guide/users/installation checking.xml getting.xml
introduction.xml shared.xml
Log:
Update installation docs after the IRC talk with Trixer today
cweiske-20090224213927.txt
(text/plain, 20.7 KB)
http://cvs.php.net/viewvc.cgi/peardoc/en/guide/users/installation.xml?r1=1.7&r2=1.8&diff_format=u
Index: peardoc/en/guide/users/installation.xml
diff -u peardoc/en/guide/users/installation.xml:1.7 peardoc/en/guide/users/installation.xml:1.8
--- peardoc/en/guide/users/installation.xml:1.7 Wed Nov 12 22:07:09 2008
+++ peardoc/en/guide/users/installation.xml Tue Feb 24 21:39:27 2009
@@ -1,6 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="installation">
- <info><title>Installation</title>
+ <info>
+ <title>Installation</title>
<author><personname><firstname>Martin</firstname><surname>Jansen</surname></personname></author>
<date>2006-11-25</date>
</info>
http://cvs.php.net/viewvc.cgi/peardoc/en/guide/users/installation/checking.xml?r1=1.6&r2=1.7&diff_format=u
Index: peardoc/en/guide/users/installation/checking.xml
diff -u peardoc/en/guide/users/installation/checking.xml:1.6 peardoc/en/guide/users/installation/checking.xml:1.7
--- peardoc/en/guide/users/installation/checking.xml:1.6 Thu Oct 9 15:16:18 2008
+++ peardoc/en/guide/users/installation/checking.xml Tue Feb 24 21:39:27 2009
@@ -1,15 +1,21 @@
<?xml version="1.0" encoding="utf-8"?>
-<section xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="installation.checking"><info><title>Checking if PEAR works</title></info>
-
+<section xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="installation.checking">
+ <info>
+ <title>Checking if PEAR works</title>
+ </info>
+
+
+ <section xml:id="installation.checking.cli">
+ <info>
+ <title>Verifying command line tool</title>
+ </info>
- <section xml:id="installation.checking.cli"><info><title>Verifying command line tool</title></info>
-
<para>
Both <command>pear</command> and <command>pecl</command> tools
should be available everywhere on command line.
- For that to work, pear's binary directory should be in your
- <literal>PATH</literal> variable.
+ For that to work, pear's binary (<literal>bin</literal>) directory
+ should be in your <literal>PATH</literal> variable.
</para>
<para>
@@ -17,81 +23,82 @@
A list of commands should be shown:
</para>
- <screen><![CDATA[
-$ pear
+ <screen><![CDATA[$ pear
Commands:
build Build an Extension From C Source
bundle Unpacks a Pecl Package
channel-add Add a Channel
-...
- ]]></screen>
+...]]></screen>
<para>
You should further test that PEAR is up to date:
</para>
- <screen><![CDATA[
-$ pear version
+ <screen><![CDATA[$ pear version
PEAR Version: 1.7.2
PHP Version: 5.2.6RC4-pl0-gentoo
Zend Engine Version: 2.2.0
-Running on: Linux ...
- ]]></screen>
+Running on: Linux ...]]></screen>
+
+ </section>
- </section>
+ <section xml:id="installation.checking.includepath">
+ <info>
+ <title>Verifying the include path</title>
+ </info>
- <section xml:id="installation.checking.includepath"><info><title>Verify the include path</title></info>
-
<para>
To use PEAR and PEAR compatible packages in your applications,
you normally include them into your PHP scripts using
- <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.php.manual.auto;require_once"><function>require_once</function></link>.
+ <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.php.manual.auto;require_once">
+ <function>require_once</function>
+ </link>.
For this to work, PEAR's <literal>php_dir</literal> must be a
part of PHP's include path.
</para>
<orderedlist>
- <listitem>
+ <listitem xml:id="installation.checking.cli.phpdir">
<para>
First, check where PEAR installs <filename>.php</filename> files:
</para>
- <screen><![CDATA[
-$ pear config-get php_dir
-/usr/share/lib/php/
- ]]></screen>
+ <screen><![CDATA[$ pear config-get php_dir
+/usr/share/lib/php/]]></screen>
+
+ <para>
+ This directory will contain <filename>System.php</filename>.
+ </para>
</listitem>
- <listitem>
+ <listitem xml:id="installation.checking.cli.inilocation">
<para>
Now it's time to find which configuration file is used by
your PHP installation. On command line, execute:
</para>
- <screen><![CDATA[
-$ php --ini
+ <screen><![CDATA[$ php --ini
Configuration File (php.ini) Path: /etc/php/cli-php5
Loaded Configuration File: /etc/php/cli-php5/php.ini
Scan for additional .ini files in: /etc/php/cli-php5/ext-active
Additional .ini files parsed: /etc/php/cli-php5/ext-active/php_gtk2.ini,
-/etc/php/cli-php5/ext-active/xdebug.ini
- ]]></screen>
+/etc/php/cli-php5/ext-active/xdebug.ini]]></screen>
<para>
To see which <filename>php.ini</filename> is used by PHP on your
web server, create a file with only <literal><?php phpinfo(); ?></literal>
- as the contents, and save it in your local web root as
+ as the contents, and save it in your local web root as
<filename>check_php.php</filename>. Open the file in your browser as
- <literal>http://localhost/check_php.php</literal>, to find the path to
+ <literal>http://localhost/check_php.php</literal>, to find the path to
the <filename>php.ini</filename> file your web server is using.
</para>
</listitem>
- <listitem>
+ <listitem xml:id="installation.checking.cli.checkincludepath">
<para>
Now check PHP's
@@ -99,13 +106,11 @@
setting on command line:
</para>
- <screen><![CDATA[
-php -c /path/to/php.ini -r 'echo get_include_path()."\n";'
- ]]></screen>
+ <screen><![CDATA[$ php -c /path/to/php.ini -r 'echo get_include_path()."\n";']]></screen>
<para>
- To check PHP's include_path in your web server, create a file with
- only <literal><?php phpinfo(); ?></literal> as the contents, and
+ To check PHP's include_path in your web server, create a file with
+ only <literal><?php phpinfo(); ?></literal> as the contents, and
save it in your local web root as <filename>check_php.php</filename>.
Open the file in your browser as <literal>http://localhost/check_php.php</literal>,
to verify the include_path your web server is using.
@@ -121,12 +126,13 @@
<para>
Now that this is done, try including a file. Create a new
- <literal>.php</literal> file with the following contents:
+ <literal>check_pear.php</literal> file with the following contents:
</para>
<programlisting role="php"><![CDATA[
<?php
require_once 'System.php';
+var_dump(class_exists('System'));
?>
]]></programlisting>
@@ -134,18 +140,42 @@
<filename>System.php</filename> is shipped with every PEAR installation
and thus should be on your computer, too.
Open the file with the browser from your web server, and also try
- it on command line. There should be no output.
- A message like:
+ it on command line. The only output should be
</para>
+ <screen><![CDATA[bool(true)]]></screen>
+ <para>
+ A message like:
+ </para>
<screen><![CDATA[
Warning: require_once(System.php): failed to open stream:
- No such file or directory in /path/to/test.php on line 2
+ No such file or directory in /path/to/check_pear.php on line 2
]]></screen>
<para>
means that your include path is not correct.
+ (So go and <link linkend="installation.checking.cli.modifyingphpini">fix it</link>!)
+ </para>
+
+ <para>
+ A completely white page in your browser hints two things:
</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ Your server is configured to not display any errors to the
+ user/browser (<varname>display_errors</varname> Off)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ There was an error including <filename>System.php</filename>, and
+ you should check you server's error log.
+ </para>
+ </listitem>
+ </itemizedlist>
+
</listitem>
</orderedlist>
@@ -155,8 +185,10 @@
</para>
- <section><info><title>Things that could be in your way</title></info>
-
+ <section xml:id="installation.checking.cli.inyourway">
+ <info>
+ <title>Things that could be in your way</title>
+ </info>
<itemizedlist>
<listitem>
@@ -164,6 +196,11 @@
After changing <filename>php.ini</filename>, you need to restart
your web server.
</para>
+ <para>
+ Few people also reported they had to restart the whole machine
+ physically, probably due to PATH changes not propagating correctly.
+ Before wasting hours and after you tried everything else, just try that.
+ </para>
</listitem>
<listitem>
@@ -201,6 +238,53 @@
</itemizedlist>
</section>
- </section>
+ <section xml:id="installation.checking.cli.modifyingphpini">
+ <info>
+ <title>Modifying <filename>php.ini</filename></title>
+ </info>
+
+ <para>
+ To get PEAR working properly, you need to adjust PHP's include_path.
+ After you found <link linkend="installation.checking.cli.inilocation">php.ini</link>,
+ open it in an editor.
+ </para>
+ <para>
+ Search for the line <literal>include_path</literal>.
+ </para>
+ <para>
+ Now that you found it, you probably will see a semicolon
+ <literal>;</literal> at the beginning. This means the line is a comment.
+ Add a new line below it.
+ </para>
+ <para>
+ In this line, write:
+ </para>
+ <screen><![CDATA[include_path="."]]></screen>
+ <para>
+ Depending on your operating system, add a
+ <literal>:</literal> (Unix/Linux/FreeBSD/Mac OS X)
+ or a <literal>;</literal> (Windows) after the dot.
+ Add <link linkend="installation.checking.cli.phpdir">PEAR's <literal>php_dir</literal></link>
+ after it.
+ (The directory <filename>System.php</filename> is located in!)
+ </para>
+
+ <para>
+ The result should look like that:
+ </para>
+ <programlisting role="ini"><![CDATA[
+; Unix
+include_path=".:/usr/local/php/pear/"
+]]></programlisting>
+ <para>
+ or
+ </para>
+ <programlisting role="ini"><![CDATA[
+; Windows
+include_path=".;C:\php\pear\"
+]]></programlisting>
+ </section>
</section>
+
+</section>
http://cvs.php.net/viewvc.cgi/peardoc/en/guide/users/installation/getting.xml?r1=1.9&r2=1.10&diff_format=u
Index: peardoc/en/guide/users/installation/getting.xml
diff -u peardoc/en/guide/users/installation/getting.xml:1.9 peardoc/en/guide/users/installation/getting.xml:1.10
--- peardoc/en/guide/users/installation/getting.xml:1.9 Thu Oct 9 15:16:18 2008
+++ peardoc/en/guide/users/installation/getting.xml Tue Feb 24 21:39:27 2009
@@ -1,10 +1,13 @@
<?xml version="1.0" encoding="utf-8"?>
-<section xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="installation.getting"><info><title>Getting the manager</title></info>
-
-
-
- <section><info><title>Windows</title></info>
-
+<section xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="installation.getting">
+ <info>
+ <title>Getting and installing the PEAR package manager</title>
+ </info>
+
+ <section xml:id="installation.getting.windows">
+ <info>
+ <title>Windows</title>
+ </info>
<para>
After you have downloaded and installed PHP, you have to manually
@@ -12,14 +15,22 @@
<filename>c:\php\go-pear.bat</filename>. The setup will ask you
some questions and afterwards the PEAR Package Manager will be
installed in the path, which you have specified during installation.
+ </para>
+
+ <para>
Finally you have to add that installation path to your
<literal>PATH</literal> environment. Either do this manually (Start >
Control Panel > System > Environment) or run (double-click) the
newly generated <filename>PEAR_ENV.reg</filename> that's now found in the
- PHP source directory. After that you can access the PEAR Package Manager
+ PHP source directory.
+ </para>
+
+ <para>
+ After that you can access the PEAR Package Manager
by running the command <literal>pear</literal> in a Windows Command
Prompt.
</para>
+
<para>
To update your PEAR installation, request
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pear.go;">&url.pear.go;</link>
@@ -35,19 +46,25 @@
<note>
<para>
- After changing <filename>php.ini</filename>, you need to restart
- your web server.
+ After
+ <link linkend="installation.checking.cli.modifyingphpini">
+ changing <filename>php.ini</filename>
+ </link>,
+ you need to restart your web server.
</para>
</note>
<para>
Now <link linkend="installation.checking">check that PEAR works</link>.
</para>
- </section>
+ </section>
- <section><info><title>Unix/Linux/BSD</title></info>
-
+ <section xml:id="installation.getting.unix">
+ <info>
+ <title>Unix/Linux/BSD</title>
+ </info>
+
<para>
When using PHP >= 4.3.0, the PEAR Package Manager is already
installed unless one has used the <filename>./configure</filename>
@@ -91,11 +108,14 @@
<para>
Now <link linkend="installation.checking">check that PEAR works</link>.
</para>
- </section>
+ </section>
- <section><info><title>Mac OS X</title></info>
-
+ <section xml:id="installation.getting.osx">
+ <info>
+ <title>Mac OS X</title>
+ </info>
+
<para>
On Mac OS 10.4 and earlier, the PEAR Package Manager is already
installed in <filename>/usr/bin/pear</filename>.
@@ -124,16 +144,20 @@
<para>
Now <link linkend="installation.checking">check that PEAR works</link>.
</para>
- </section>
+ </section>
- <section><info><title>PEAR in hosting environments</title></info>
-
+ <section xml:id="installation.getting.hosted">
+ <info>
+ <title>PEAR in hosting environments</title>
+ </info>
+
<para>
If you are running your site at a web hosting provider with no
direct access to the server (via local logins, Telnet or SSH), you
- can use the PEAR Installer using the Web Frontend.
+ can use the PEAR Installer using the Web Frontend or
+ <link linkend="installation.shared">(S)FTP</link>.
</para>
<para>
Go to <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.pear.go;">&url.pear.go;</link> and save as
@@ -142,16 +166,17 @@
your server and open the corresponding URL in your browser, for
example <filename>http://example.com/pear/go-pear.php</filename>.
</para>
- <warning xml:id="installation.web.prerequesite"><info><title>Prerequisites</title></info>
-
+ <warning xml:id="installation.web.protect">
<para>
Do not forget to protect the pear directory if you did not do
- already before the installation.
+ already before the installation: Make it unreadable and not executable
+ from external (i.e. put it outside <literal>public_html</literal>).
</para>
</warning>
<para>
Now <link linkend="installation.checking">check that PEAR works</link>.
</para>
- </section>
</section>
+
+</section>
http://cvs.php.net/viewvc.cgi/peardoc/en/guide/users/installation/introduction.xml?r1=1.5&r2=1.6&diff_format=u
Index: peardoc/en/guide/users/installation/introduction.xml
diff -u peardoc/en/guide/users/installation/introduction.xml:1.5 peardoc/en/guide/users/installation/introduction.xml:1.6
--- peardoc/en/guide/users/installation/introduction.xml:1.5 Thu Oct 9 15:16:18 2008
+++ peardoc/en/guide/users/installation/introduction.xml Tue Feb 24 21:39:27 2009
@@ -1,24 +1,24 @@
<?xml version="1.0" encoding="utf-8"?>
<section xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="installation.introduction"><info><title>Introduction</title></info>
-
+
<para>
Before you install PEAR, we recommend you understand
<link linkend="about.pear">what PEAR is</link> and why you
should install it.
</para>
<para>
- The base installation that comes with the PHP distribution,
- contains all the stuff
- that is needed to run the PEAR installation tools etc. If you have
- a recent installation of PHP, you can relax: The PEAR base
- installation is already there, unless you have compiled your PHP
+ The base installation that comes with the PHP distribution
+ contains all the stuff that is needed to run the PEAR installation tools etc.
+ If you have a recent installation of PHP, you can relax: The PEAR base
+ installation is already there - unless you have compiled your PHP
with the <filename>./configure</filename> flag
<literal>--without-pear</literal>.
</para>
<para>
The packages that do not come with PHP can be installed with the PEAR
package manager. The manager handles installation similar to Debian's
- <quote><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.debian.apt;">apt-get</link></quote> package management
+ <quote><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="&url.debian.apt;">apt-get</link></quote>
+ package management
utility, as well as others such as <quote>yum</quote>. Again:
If you are running a recent version of PHP (> 4.3.0) you can skip
the next section. But if you are running PHP 4.2.* or earlier, you
http://cvs.php.net/viewvc.cgi/peardoc/en/guide/users/installation/shared.xml?r1=1.6&r2=1.7&diff_format=u
Index: peardoc/en/guide/users/installation/shared.xml
diff -u peardoc/en/guide/users/installation/shared.xml:1.6 peardoc/en/guide/users/installation/shared.xml:1.7
--- peardoc/en/guide/users/installation/shared.xml:1.6 Thu Oct 9 15:16:18 2008
+++ peardoc/en/guide/users/installation/shared.xml Tue Feb 24 21:39:27 2009
@@ -1,15 +1,22 @@
<?xml version="1.0" encoding="utf-8"?>
-<section xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="installation.shared"><info><title>Installation of a local PEAR copy on a shared host</title></info>
-
+<section xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="installation.shared">
+ <info>
+ <title>Installation of a local PEAR copy on a shared host</title>
+ </info>
- <para>
+
+ <para>
Many users have a shared provider that grants access to a system-wide PEAR installation.
However, in many cases, it is advantageous to have a local copy of PEAR that can be used
for packages that are not installed by the host provider. There are ways of installing
PEAR both for users with a telnet/ssh shell access and users who only have ftp access.
- </para>
- <section xml:id="installation.shared.shell"><info><title>Installing a local copy of PEAR through SSH</title></info>
-
+ </para>
+
+ <section xml:id="installation.shared.shell">
+ <info>
+ <title>Installing a local copy of PEAR through SSH</title>
+ </info>
+
<para>
To install PEAR through SSH, you can use this command sequence to set up a local copy of PEAR:
</para>
@@ -57,16 +64,18 @@
<para>
Or, in an .htaccess file for apache using php_value.
</para>
- </section>
- <section xml:id="installation.shared.ftp"><info><title>Installing a local copy of PEAR through ftp/ftps/sftp</title></info>
-
+ </section>
+
+
+ <section xml:id="installation.shared.ftp"><info><title>Installing a local copy of PEAR through ftp/ftps/sftp</title></info>
+
<para>
There are two ways to install a local copy of PEAR through ftp: the old, difficult way,
and the new, easy way. The new, easy way requires an upgrade to version 1.4.3 or newer
of PEAR.
</para>
<section><info><title>New improved method using PEAR 1.4.3+ and PEAR_RemoteInstaller</title></info>
-
+
<para>
Installing a local copy of PEAR through ftp has become a piece of cake in PEAR 1.4.3+.
</para>
@@ -206,7 +215,7 @@
Windows first:
</para>
<para>
- Pick a location to store your local copy of the remote code. For example,
+ Pick a location to store your local copy of the remote code. For example,
<filename>C:\remote\pear</filename>. From a Command prompt (click Start here =>
Programs and search for the Command Prompt), type:
</para>
@@ -353,7 +362,7 @@
</section>
<section><info><title>The traditional way of installing a local copy of PEAR through ftp</title></info>
-
+
<para>
In order to install a local copy of PEAR through ftp, you must have an ftp client that can set permissions
on upload. First, create a directory that is NOT in your publicly accessible web space, and name it