[prev in list] [next in list] [prev in thread] [next in thread] 

List:       pear-doc
Subject:    [PEAR-DOC] cvs: peardoc /en/package system.xml  /en/package/system folders.xml  /en/package/system/f
From:       "Christian Weiske" <cweiske () php ! net>
Date:       2006-03-18 11:22:44
Message-ID: cvscweiske1142680964 () cvsserver
[Download RAW message or body]

cweiske		Sat Mar 18 11:22:44 2006 UTC

  Added files:                 
    /peardoc/en/package/system	folders.xml 
    /peardoc/en/package/system/folders	example.xml intro.xml 

  Modified files:              
    /peardoc/en/package	system.xml 
  Log:
  System_Folders documentation
  
  
["cweiske-20060318112244.txt" (text/plain)]

http://cvs.php.net/viewcvs.cgi/peardoc/en/package/system.xml?r1=1.8&r2=1.9&diff_format=u
Index: peardoc/en/package/system.xml
diff -u peardoc/en/package/system.xml:1.8 peardoc/en/package/system.xml:1.9
--- peardoc/en/package/system.xml:1.8	Sat Feb 18 16:55:37 2006
+++ peardoc/en/package/system.xml	Sat Mar 18 11:22:44 2006
@@ -1,5 +1,4 @@
-
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
 
 <chapter id="package.System">
   <title>System</title>
@@ -9,6 +8,7 @@
 
   &blankpagehack;
 
+  &package.system.folders;
   &package.system.system-procwatch;
   &package.system.windrives;
 </chapter>

http://cvs.php.net/viewcvs.cgi/peardoc/en/package/system/folders.xml?view=markup&rev=1.1
Index: peardoc/en/package/system/folders.xml
+++ peardoc/en/package/system/folders.xml
<?xml version="1.0" encoding="iso-8859-1" ?>
<!-- $Revision: 1.1 $ -->

<sect1 id="package.system.folders">
 <title>System_Folders</title>

 <para>
  Returns locations of system folders like
  home, desktop, documents and others.
 </para>

 &package.system.folders.intro;
 &package.system.folders.example;
</sect1>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

http://cvs.php.net/viewcvs.cgi/peardoc/en/package/system/folders/example.xml?view=markup&rev=1.1
Index: peardoc/en/package/system/folders/example.xml
+++ peardoc/en/package/system/folders/example.xml
<?xml version="1.0" encoding="iso-8859-1" ?>
<!-- $Revision: 1.1 $ -->

<refentry id="package.system.folders.example">
 <refnamediv>
  <refname>Example</refname>
  <refpurpose>
   How to use System_Folders
  </refpurpose>
 </refnamediv>

 <refsect1>
  <title>Using System_Folders</title>
  <example>
   <title>General usage</title>
   <programlisting role="php">
    <![CDATA[
<?php
require_once 'System/Folders.php';

$sf = new System_Folders();

$arData = array(
'Username'         => $sf->getUserName(),
'Home'             => $sf->getHome(),
'Documents'        => $sf->getDocuments(),
'Shared documents' => $sf->getSharedDocuments(),
'Temp'             => $sf->getTemp(),
'Desktop'          => $sf->getDesktop(),
'AppData'          => $sf->getAppData(),
'Programs'         => $sf->getPrograms(),
'Windows'          => $sf->getWindows()
);

echo 'System: ' . $sf->getSys() . "\r\n";
var_dump($arData);
?>
]]></programlisting>
  </example>
  <para>
   At first, you need to instantitiate a new
   <classname>System_Folders</classname> object. The operating
   system is determined there, which is needed for all the
   other methods.
  </para>
  <para>
   Then just use the <literal>getXXX()</literal> methods to retrieve
   the folder locations. Remember that they return <literal>NULL</literal>
   if the location can't be determined.
  </para>

 </refsect1>


 <refsect1>
  <title>Using System_Folders>Cached</title>
  <example>
   <title>General usage</title>
   <programlisting role="php">
    <![CDATA[
<?php
require_once 'System/Folders/Cached.php';
$sf = new System_Folders_Cached();

//show the path of the config file
echo 'Config file: ' . $sf->getDefaultConfigFile() . "\r\n";

//load the stored settings from last time
$err = $sf->loadFromFile();

echo 'Home:      ' . $sf->getHome() . "\r\n";
echo 'Documents: ' . $sf->getDocuments() . "\r\n";

echo "\r\n";

$doc = $sf->getDocuments();
if (file_exists($doc)) {
    echo "Setting new Documents directory\r\n";
    //Set an own documents directory
    // and save the settings for next time
    $sf->setDocuments('/strange/path/to/MyDocuments/');
    $sf->saveToFile();
    echo 'New Documents directory: ' . $sf->getDocuments() . "\r\n";
    echo "Run this program again to reset the path to default\r\n";
} else {
    //unset the path
    echo "Unsetting the documents directory\r\n";
    $sf->setDocuments(null);
    $sf->saveToFile();
    echo 'New Documents directory: ' . $sf->getDocuments() . "\r\n";
}
?>
]]></programlisting>
  </example>
  <para>
   This example displays the location of the config file (in which
   the folder settings are stored), shows some folder locations and
   sets the documents directory to a (probably non-existing) directory
   and saves the folder locations.
  </para>
  <para>
   In the next program call, the documents directory is reset to the
   normal one and saved again.
  </para>

 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

http://cvs.php.net/viewcvs.cgi/peardoc/en/package/system/folders/intro.xml?view=markup&rev=1.1
Index: peardoc/en/package/system/folders/intro.xml
+++ peardoc/en/package/system/folders/intro.xml
<?xml version="1.0" encoding="iso-8859-1" ?>
<!-- $Revision: 1.1 $ -->

<refentry id="package.system.folders.intro">
 <refnamediv>
  <refname>Introduction</refname>
  <refpurpose>
   Get system folder locations.
  </refpurpose>
 </refnamediv>

 <refsect1 id="package.system.folders.intro.contrib">
  <title>Contributors</title>
  <para>
   <itemizedlist>
    <listitem><simpara>Christian Weiske</simpara></listitem>
   </itemizedlist>
  </para>
 </refsect1>

 <refsect1 id="package.system.folders.intro.desc">
  <title>Description</title>
  <para>
   <classname>System_Folders</classname> provides methods to get the locations
   of various system folders like home directory, desktop folder and
   "My documents". You can use it on nearly every operating system: It works
   on Linux, Windows and Mac OS; allowing you to write OS independent
   programs.
  </para>

  <para>
   The methods return a string of the directory (with trailing slash)
   if the directory can be determined, and <literal>NULL</literal> if
   it fails or isn't available on the system. For example, the
   "Shared Documents" folder exists on Windows only. If you run
   <literal>getSharedDocuments()</literal> on a Mac or Linux, the method
   will return <literal>NULL</literal>.
  </para>

  <para>
   The class does heavy use of environment variables. That means
   it is very likely that the methods fail when running in a php server
   module (e.g. apache) because there is user information available.
   Using them on command line (cli) scripts gives best results, as the
   class is meant to be used for such ones.
  </para>

  <table>
   <title>Available folders and their methods</title>
   <tgroup cols="3">
    <thead>
     <row>
      <entry>Folder</entry>
      <entry>Method to use</entry>
      <entry>Notes</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>All users directory</entry>
      <entry>getAllUsers()</entry>
      <entry>Windows only</entry>
     </row>
     <row>
      <entry>Application data</entry>
      <entry>getAppData()</entry>
      <entry></entry>
     </row>
     <row>
      <entry>Desktop</entry>
      <entry>getDesktop()</entry>
      <entry></entry>
     </row>
     <row>
      <entry>Documents / My Documents</entry>
      <entry>getDocuments()</entry>
      <entry></entry>
     </row>
     <row>
      <entry>Home directory</entry>
      <entry>getHome()</entry>
      <entry></entry>
     </row>
     <row>
      <entry>Programs folder (installed ones)</entry>
      <entry>getPrograms()</entry>
      <entry></entry>
     </row>
     <row>
      <entry>Temporary files</entry>
      <entry>getTemp()</entry>
      <entry></entry>
     </row>
     <row>
      <entry>Shared documents</entry>
      <entry>getSharedDocuments()</entry>
      <entry>Windows only</entry>
     </row>
     <row>
      <entry>Windows directory</entry>
      <entry>getWindows()</entry>
      <entry>Windows only</entry>
     </row>
    </tbody>
   </tgroup>
  </table>

 </refsect1>

 <refsect1 id="package.system.folders.intro.cached">
  <title>System_Folders_Cached</title>

  <para>
   On every getXXX() call, the whole procedure of looping through
   environment variables, checking the existence of the folders and
   trying some common locations is executed. So if you call the same
   method again and again, it will cost you the same amount of cpu cycles
   every time and perhaps be a slowdown in your application.
  </para>

  <para>
   Another problem might be that some methods fail or don't return the correct
   path, e.g. because the user has an unusual installation or unusual
   preferences.
  </para>

  <para>
   Both issues are addressed with <classname>System_Folders_Cached</classname>.
   It provides a cached version of the <literal>getXXX()</literal> methods,
   meaning that the result of the first method calls are stored locally and
   returned on every further call, which speeds up consecutive calls to the
   same method a lot.
  </para>

  <para>
   Further, the class provides methods to set the folder locations and
   save this settings into an ini file. Saving them can be done with
   <literal>saveToFile()</literal> and they can be loaded with
   <literal>loadFromFile()</literal>. This allows customization of the
   folder locations, and persistency across sessions.
  </para>

 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->



-- 
PEAR Documentation List Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

[prev in list] [next in list] [prev in thread] [next in thread]