[DOCUMENTATION] English:

- manual fixes (only line length)

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@15845 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/en/module_specs/Zend_Auth.xml

@@ -5,25 +5,28 @@
     <title>Introduction</title>
 
     <para>
-        <classname>Zend_Auth</classname> provides an API for authentication and includes concrete authentication adapters for
-        common use case scenarios.
+        <classname>Zend_Auth</classname> provides an API for authentication and includes concrete
+        authentication adapters for common use case scenarios.
     </para>
 
     <para>
-        <classname>Zend_Auth</classname> is concerned only with <emphasis>authentication</emphasis> and not with
-        <emphasis>authorization</emphasis>. Authentication is loosely defined as determining
-        whether an entity actually is what it purports to be (i.e., identification), based on some set of
-        credentials. Authorization, the process of deciding whether to allow an entity access to, or to
-        perform operations upon, other entities is outside the scope of <classname>Zend_Auth</classname>. For more information about
-        authorization and access control with Zend Framework, please see
-        <link linkend="zend.acl"><classname>Zend_Acl</classname></link>.
+        <classname>Zend_Auth</classname> is concerned only with <emphasis>authentication</emphasis>
+        and not with <emphasis>authorization</emphasis>. Authentication is loosely defined as
+        determining whether an entity actually is what it purports to be (i.e., identification),
+        based on some set of credentials. Authorization, the process of deciding whether to allow
+        an entity access to, or to perform operations upon, other entities is outside the scope of
+        <classname>Zend_Auth</classname>. For more information about authorization and access
+        control with Zend Framework, please see <link
+            linkend="zend.acl"><classname>Zend_Acl</classname></link>.
     </para>
 
     <note>
         <para>
-            The <classname>Zend_Auth</classname> class implements the Singleton pattern - only one instance of the class is
-            available - through its static <methodname>getInstance()</methodname> method. This means that using the <emphasis>new</emphasis>
-            operator and the <emphasis>clone</emphasis> keyword will not work with the <classname>Zend_Auth</classname> class; use
+            The <classname>Zend_Auth</classname> class implements the Singleton pattern - only one
+            instance of the class is available - through its static
+            <methodname>getInstance()</methodname> method. This means that using the
+            <emphasis>new</emphasis> operator and the <emphasis>clone</emphasis> keyword will not
+            work with the <classname>Zend_Auth</classname> class; use
             <methodname>Zend_Auth::getInstance()</methodname> instead.
         </para>
     </note>
@@ -33,25 +36,30 @@
         <title>Adapters</title>
 
         <para>
-            A <classname>Zend_Auth</classname> adapter is used to authenticate against a particular type of authentication service,
-            such as LDAP, RDBMS, or file-based storage. Different adapters are likely to have vastly different
-            options and behaviors, but some basic things are common among authentication adapters. For example,
-            accepting authentication credentials (including a purported identity), performing queries against the
-            authentication service, and returning results are common to <classname>Zend_Auth</classname> adapters.
+            A <classname>Zend_Auth</classname> adapter is used to authenticate against a particular
+            type of authentication service, such as LDAP, RDBMS, or file-based storage. Different
+            adapters are likely to have vastly different options and behaviors, but some basic
+            things are common among authentication adapters. For example, accepting authentication
+            credentials (including a purported identity), performing queries against the
+            authentication service, and returning results are common to
+            <classname>Zend_Auth</classname> adapters.
         </para>
 
         <para>
-            Each <classname>Zend_Auth</classname> adapter class implements <classname>Zend_Auth_Adapter_Interface</classname>. This interface defines one
-            method, <methodname>authenticate()</methodname>, that an adapter class must implement for performing an authentication
-            query. Each adapter class must be prepared prior to calling <methodname>authenticate()</methodname>. Such adapter
-            preparation includes setting up credentials (e.g., username and password) and defining values for adapter-
-            specific configuration options, such as database connection settings for a database table adapter.
+            Each <classname>Zend_Auth</classname> adapter class implements
+            <classname>Zend_Auth_Adapter_Interface</classname>. This interface defines one method,
+            <methodname>authenticate()</methodname>, that an adapter class must implement for
+            performing an authentication query. Each adapter class must be prepared prior to
+            calling <methodname>authenticate()</methodname>. Such adapter preparation includes
+            setting up credentials (e.g., username and password) and defining values for
+            adapter-specific configuration options, such as database connection settings for a
+            database table adapter.
         </para>
 
         <para>
-            The following is an example authentication adapter that requires a username and password to be set
-            for authentication. Other details, such as how the authentication service is queried, have been
-            omitted for brevity:
+            The following is an example authentication adapter that requires a username and
+            password to be set for authentication. Other details, such as how the authentication
+            service is queried, have been omitted for brevity:
 
             <programlisting language="php"><![CDATA[
 class MyAuthAdapter implements Zend_Auth_Adapter_Interface
@@ -80,10 +88,12 @@ class MyAuthAdapter implements Zend_Auth_Adapter_Interface
 }
 ]]></programlisting>
 
-            As indicated in its docblock, <methodname>authenticate()</methodname> must return an instance of
-            <classname>Zend_Auth_Result</classname> (or of a class derived from <classname>Zend_Auth_Result</classname>). If for some
-            reason performing an authentication query is impossible, <methodname>authenticate()</methodname> should throw
-            an exception that derives from <classname>Zend_Auth_Adapter_Exception</classname>.
+            As indicated in its docblock, <methodname>authenticate()</methodname> must return an
+            instance of <classname>Zend_Auth_Result</classname> (or of a class derived from
+            <classname>Zend_Auth_Result</classname>). If for some reason performing an
+            authentication query is impossible, <methodname>authenticate()</methodname> should
+            throw an exception that derives from
+            <classname>Zend_Auth_Adapter_Exception</classname>.
         </para>
 
     </sect2>
@@ -93,49 +103,54 @@ class MyAuthAdapter implements Zend_Auth_Adapter_Interface
         <title>Results</title>
 
         <para>
-            <classname>Zend_Auth</classname> adapters return an instance of <classname>Zend_Auth_Result</classname> with
-            <methodname>authenticate()</methodname> in order to represent the results of an authentication attempt. Adapters
-            populate the <classname>Zend_Auth_Result</classname> object upon construction, so that the following four methods
-            provide a basic set of user-facing operations that are common to the results of <classname>Zend_Auth</classname> adapters:
+            <classname>Zend_Auth</classname> adapters return an instance of
+            <classname>Zend_Auth_Result</classname> with <methodname>authenticate()</methodname> in
+            order to represent the results of an authentication attempt. Adapters populate the
+            <classname>Zend_Auth_Result</classname> object upon construction, so that the following
+            four methods provide a basic set of user-facing operations that are common to the
+            results of <classname>Zend_Auth</classname> adapters:
             <itemizedlist>
                 <listitem>
                     <para>
-                        <methodname>isValid()</methodname> - returns true if and only if the result represents a
-                        successful authentication attempt
+                        <methodname>isValid()</methodname> - returns true if and only if the result
+                        represents a successful authentication attempt
                     </para>
                 </listitem>
                 <listitem>
                     <para>
-                        <methodname>getCode()</methodname> - returns a <classname>Zend_Auth_Result</classname> constant identifier for
-                        determining the type of authentication failure or whether success has occurred. This may be
-                        used in situations where the developer wishes to distinguish among several authentication
-                        result types. This allows developers to maintain detailed authentication result statistics,
-                        for example. Another use of this feature is to provide specific, customized messages to
-                        users for usability reasons, though developers are encouraged to consider the risks of
-                        providing such detailed reasons to users, instead of a general authentication failure
-                        message. For more information, see the notes below.
+                        <methodname>getCode()</methodname> - returns a
+                        <classname>Zend_Auth_Result</classname> constant identifier for determining
+                        the type of authentication failure or whether success has occurred. This
+                        may be used in situations where the developer wishes to distinguish among
+                        several authentication result types. This allows developers to maintain
+                        detailed authentication result statistics, for example. Another use of this
+                        feature is to provide specific, customized messages to users for usability
+                        reasons, though developers are encouraged to consider the risks of
+                        providing such detailed reasons to users, instead of a general
+                        authentication failure message. For more information, see the notes below.
                     </para>
                 </listitem>
                 <listitem>
                     <para>
-                        <methodname>getIdentity()</methodname> - returns the identity of the authentication attempt
+                        <methodname>getIdentity()</methodname> - returns the identity of the
+                        authentication attempt
                     </para>
                 </listitem>
                 <listitem>
                     <para>
-                        <methodname>getMessages()</methodname> - returns an array of messages regarding a failed
-                        authentication attempt
+                        <methodname>getMessages()</methodname> - returns an array of messages
+                        regarding a failed authentication attempt
                     </para>
                 </listitem>
             </itemizedlist>
         </para>
 
         <para>
-            A developer may wish to branch based on the type of authentication result in order to perform more
-            specific operations. Some operations developers might find useful are locking accounts after too many
-            unsuccessful password attempts, flagging an IP address after too many nonexistent identities are
-            attempted, and providing specific, customized authentication result messages to the user. The following
-            result codes are available:
+            A developer may wish to branch based on the type of authentication result in order to
+            perform more specific operations. Some operations developers might find useful are
+            locking accounts after too many unsuccessful password attempts, flagging an IP address
+            after too many nonexistent identities are attempted, and providing specific, customized
+            authentication result messages to the user. The following result codes are available:
 
             <programlisting language="php"><![CDATA[
 Zend_Auth_Result::SUCCESS
@@ -184,15 +199,15 @@ switch ($result->getCode()) {
         <title>Identity Persistence</title>
 
         <para>
-            Authenticating a request that includes authentication credentials is useful per se, but it is also
-            important to support maintaining the authenticated identity without having to present the
-            authentication credentials with each request.
+            Authenticating a request that includes authentication credentials is useful per se, but
+            it is also important to support maintaining the authenticated identity without having
+            to present the authentication credentials with each request.
         </para>
 
         <para>
-            HTTP is a stateless protocol, however, and techniques such as cookies and sessions have been
-            developed in order to facilitate maintaining state across multiple requests in server-side web
-            applications.
+            HTTP is a stateless protocol, however, and techniques such as cookies and sessions have
+            been developed in order to facilitate maintaining state across multiple requests in
+            server-side web applications.
         </para>
 
         <sect3 id="zend.auth.introduction.persistence.default">
@@ -200,20 +215,24 @@ switch ($result->getCode()) {
             <title>Default Persistence in the PHP Session</title>
 
             <para>
-                 By default, <classname>Zend_Auth</classname> provides persistent storage of the identity from a successful
-                 authentication attempt using the PHP session. Upon a successful authentication attempt,
-                 <classname>Zend_Auth::authenticate()</classname> stores the identity from the authentication result into
-                 persistent storage. Unless configured otherwise, <classname>Zend_Auth</classname> uses a storage class named
+                 By default, <classname>Zend_Auth</classname> provides persistent storage of the
+                 identity from a successful authentication attempt using the PHP session. Upon a
+                 successful authentication attempt,
+                 <classname>Zend_Auth::authenticate()</classname> stores the identity from the
+                 authentication result into persistent storage. Unless configured otherwise,
+                 <classname>Zend_Auth</classname> uses a storage class named
                  <classname>Zend_Auth_Storage_Session</classname>, which, in turn, uses
-                 <link linkend="zend.session"><classname>Zend_Session</classname></link>. A custom class may instead be used by providing an
-                 object that implements <classname>Zend_Auth_Storage_Interface</classname> to
+                 <link linkend="zend.session"><classname>Zend_Session</classname></link>. A custom
+                 class may instead be used by providing an object that implements
+                 <classname>Zend_Auth_Storage_Interface</classname> to
                  <classname>Zend_Auth::setStorage()</classname>.
             </para>
 
             <note>
                 <para>
-                    If automatic persistent storage of the identity is not appropriate for a particular use case, then
-                    developers may forgo using the <classname>Zend_Auth</classname> class altogether, instead using an adapter
+                    If automatic persistent storage of the identity is not appropriate for a
+                    particular use case, then developers may forgo using the
+                    <classname>Zend_Auth</classname> class altogether, instead using an adapter
                     class directly.
                 </para>
             </note>
@@ -223,11 +242,14 @@ switch ($result->getCode()) {
                 <title>Modifying the Session Namespace</title>
 
                 <para>
-                    <classname>Zend_Auth_Storage_Session</classname> uses a session namespace of 'Zend_Auth'. This
-                    namespace may be overridden by passing a different value to the constructor of
-                    <classname>Zend_Auth_Storage_Session</classname>, and this value is internally passed along to the constructor
-                    of <classname>Zend_Session_Namespace</classname>. This should occur before authentication is attempted, since
-                    <classname>Zend_Auth::authenticate()</classname> performs the automatic storage of the identity.
+                    <classname>Zend_Auth_Storage_Session</classname> uses a session namespace of
+                    'Zend_Auth'. This namespace may be overridden by passing a different value to
+                    the constructor of <classname>Zend_Auth_Storage_Session</classname>, and this
+                    value is internally passed along to the constructor of
+                    <classname>Zend_Session_Namespace</classname>. This should occur before
+                    authentication is attempted, since
+                    <classname>Zend_Auth::authenticate()</classname> performs the automatic storage
+                    of the identity.
 
                     <programlisting language="php"><![CDATA[
 // Save a reference to the Singleton instance of Zend_Auth
@@ -256,9 +278,10 @@ $result = $auth->authenticate($authAdapter);
             <title>Implementing Customized Storage</title>
 
             <para>
-                Sometimes developers may need to use a different identity storage mechanism than that provided by
-                <classname>Zend_Auth_Storage_Session</classname>. For such cases developers may simply implement
-                <classname>Zend_Auth_Storage_Interface</classname> and supply an instance of the class to
+                Sometimes developers may need to use a different identity storage mechanism than
+                that provided by <classname>Zend_Auth_Storage_Session</classname>. For such cases
+                developers may simply implement <classname>Zend_Auth_Storage_Interface</classname>
+                and supply an instance of the class to
                 <classname>Zend_Auth::setStorage()</classname>.
             </para>
 
@@ -339,7 +362,8 @@ class MyStorage implements Zend_Auth_Storage_Interface
                 </para>
 
                 <para>
-                    In order to use this custom storage class, <classname>Zend_Auth::setStorage()</classname> is invoked before an
+                    In order to use this custom storage class,
+                    <classname>Zend_Auth::setStorage()</classname> is invoked before an
                     authentication query is attempted:
 
                     <programlisting language="php"><![CDATA[
@@ -384,8 +408,8 @@ $result = Zend_Auth::getInstance()->authenticate($authAdapter);
         </para>
 
         <para>
-            The following example illustrates how to use a <classname>Zend_Auth</classname> adapter indirectly, through the use of
-            the <classname>Zend_Auth</classname> class:
+            The following example illustrates how to use a <classname>Zend_Auth</classname> adapter
+            indirectly, through the use of the <classname>Zend_Auth</classname> class:
 
             <programlisting language="php"><![CDATA[
 // Get a reference to the singleton instance of Zend_Auth
@@ -412,8 +436,8 @@ if (!$result->isValid()) {
         </para>
 
         <para>
-            Once authentication has been attempted in a request, as in the above example, it is a simple
-            matter to check whether a successfully authenticated identity exists:
+            Once authentication has been attempted in a request, as in the above example, it is a
+            simple matter to check whether a successfully authenticated identity exists:
             <programlisting language="php"><![CDATA[
 $auth = Zend_Auth::getInstance();
 if ($auth->hasIdentity()) {
@@ -424,19 +448,21 @@ if ($auth->hasIdentity()) {
         </para>
 
         <para>
-            To remove an identity from persistent storage, simply use the <methodname>clearIdentity()</methodname> method.
-            This typically would be used for implementing an application "logout" operation:
+            To remove an identity from persistent storage, simply use the
+            <methodname>clearIdentity()</methodname> method. This typically would be used for
+            implementing an application "logout" operation:
             <programlisting language="php"><![CDATA[
 Zend_Auth::getInstance()->clearIdentity();
 ]]></programlisting>
         </para>
 
         <para>
-            When the automatic use of persistent storage is inappropriate for a particular use case, a
-            developer may simply bypass the use of the <classname>Zend_Auth</classname> class, using an adapter class
-            directly. Direct use of an adapter class involves configuring and preparing an adapter object and
-            then calling its <methodname>authenticate()</methodname> method. Adapter-specific details are discussed in the
-            documentation for each adapter. The following example directly utilizes
+            When the automatic use of persistent storage is inappropriate for a particular use
+            case, a developer may simply bypass the use of the <classname>Zend_Auth</classname>
+            class, using an adapter class directly. Direct use of an adapter class involves
+            configuring and preparing an adapter object and then calling its
+            <methodname>authenticate()</methodname> method. Adapter-specific details are discussed
+            in the documentation for each adapter. The following example directly utilizes
             <emphasis>MyAuthAdapter</emphasis>:
 
             <programlisting language="php"><![CDATA[

documentation/manual/en/module_specs/Zend_Auth_Adapter_DbTable.xml

@@ -221,10 +221,9 @@ if ($result->isValid()) {
              authorization problem within the authentication adapter.
         </para>
         <para>
-            With that disclaimer out of the way,
-            <classname>Zend_Auth_Adapter_DbTable</classname> has some built in mechanisms that can be
-            leveraged for additional checks at authentication time to solve
-            some common user problems.
+            With that disclaimer out of the way, <classname>Zend_Auth_Adapter_DbTable</classname>
+            has some built in mechanisms that can be leveraged for additional checks at
+            authentication time to solve some common user problems.
         </para>
         <programlisting language="php"><![CDATA[
 // The status field value of an account is not equal to "compromised"

documentation/manual/en/module_specs/Zend_Auth_Adapter_OpenId.xml

@@ -8,8 +8,8 @@
 
         <title>Introduction</title>
         <para>
-            The <classname>Zend_Auth_Adapter_OpenId</classname> adapter can be used to authenticate users using
-            remote OpenID servers. This authentication method assumes that the user
+            The <classname>Zend_Auth_Adapter_OpenId</classname> adapter can be used to authenticate
+            users using remote OpenID servers. This authentication method assumes that the user
             submits only their OpenID identity to the web application. They are
             then redirected to their OpenID provider to prove identity ownership
             using a password or some other method. This password is never provided to
@@ -30,8 +30,9 @@
 
         <note>
             <para>
-                <classname>Zend_OpenId</classname> takes advantage of the <ulink url="http://php.net/gmp">GMP extension</ulink>,
-                where available. Consider enabling the GMP extension for better performance when using
+                <classname>Zend_OpenId</classname> takes advantage of the <ulink
+                    url="http://php.net/gmp">GMP extension</ulink>, where available. Consider
+                enabling the GMP extension for better performance when using
                 <classname>Zend_Auth_Adapter_OpenId</classname>.
             </para>
         </note>
@@ -40,31 +41,34 @@
     <sect2 id="zend.auth.adapter.openid.specifics">
         <title>Specifics</title>
         <para>
-            As is the case for all <classname>Zend_Auth</classname> adapters, the <classname>Zend_Auth_Adapter_OpenId</classname>
-            class implements <classname>Zend_Auth_Adapter_Interface</classname>, which
-            defines one method: <methodname>authenticate()</methodname>. This method performs
-            the authentication itself, but the object must be prepared prior to
-            calling it. Such adapter preparation includes setting up the OpenID
-            identity and some other <classname>Zend_OpenId</classname> specific options.
+            As is the case for all <classname>Zend_Auth</classname> adapters, the
+            <classname>Zend_Auth_Adapter_OpenId</classname> class implements
+            <classname>Zend_Auth_Adapter_Interface</classname>, which defines one method:
+            <methodname>authenticate()</methodname>. This method performs the authentication itself,
+            but the object must be prepared prior to calling it. Such adapter preparation includes
+            setting up the OpenID identity and some other <classname>Zend_OpenId</classname>
+            specific options.
         </para>
 
         <para>
-            However, as opposed to other <classname>Zend_Auth</classname> adapters, <classname>Zend_Auth_Adapter_OpenId</classname>
-            performs authentication on an external server in two
-            separate HTTP requests. So the <classname>Zend_Auth_Adapter_OpenId::authenticate()</classname> method
-            must be called twice. On the first invocation the method won't return, but will
-            redirect the user to their OpenID server. Then after the user is authenticated on the remote
-            server, they will be redirected back and the script for this second
-            request must call <classname>Zend_Auth_Adapter_OpenId::authenticate()</classname>
-            again to verify the signature which comes with the redirected request from the
-            server to complete the authentication process. On this second invocation, the
-            method will return the <classname>Zend_Auth_Result</classname> object as expected.
+            However, as opposed to other <classname>Zend_Auth</classname> adapters,
+            <classname>Zend_Auth_Adapter_OpenId</classname> performs authentication on an external
+            server in two separate HTTP requests. So the
+            <classname>Zend_Auth_Adapter_OpenId::authenticate()</classname> method must be called
+            twice. On the first invocation the method won't return, but will redirect the user to
+            their OpenID server. Then after the user is authenticated on the remote server, they
+            will be redirected back and the script for this second request must call
+            <classname>Zend_Auth_Adapter_OpenId::authenticate()</classname> again to verify the
+            signature which comes with the redirected request from the server to complete the
+            authentication process. On this second invocation, the method will return the
+            <classname>Zend_Auth_Result</classname> object as expected.
         </para>
 
         <para>
-            The following example shows the usage of <classname>Zend_Auth_Adapter_OpenId</classname>.
-            As previously mentioned, the <classname>Zend_Auth_Adapter_OpenId::authenticate()</classname>
-            must be called two times. The first time is after the user submits the HTML form with the
+            The following example shows the usage of
+            <classname>Zend_Auth_Adapter_OpenId</classname>. As previously mentioned, the
+            <classname>Zend_Auth_Adapter_OpenId::authenticate()</classname> must be called two
+            times. The first time is after the user submits the HTML form with the
             <varname>$_POST['openid_action']</varname> set to <emphasis>"login"</emphasis>,
             and the second time is after the HTTP redirection from OpenID server with
             <varname>$_GET['openid_mode']</varname> or <varname>$_POST['openid_mode']</varname>