System_Folders
[ class tree: System_Folders ] [ index: System_Folders ] [ all elements ]

Source for file Folders.php

Documentation is available at Folders.php

  1. <?php
  2. /**
  3. * Provides the locations of several system and user directories
  4. * independent of the operating system used.
  5. *
  6. * Simpe example:
  7. *     require_once 'System/Folders.php';
  8. *     $sf = new System_Folders();
  9. *     echo $sf->getHome();
  10. *
  11. * If you want the folders to be cached (not re-calculated on every
  12. *  read), use System_Folders_Cached.
  13. *
  14. * PHP version 4
  15. *
  16. @category System
  17. @package  System_Folders
  18. @author   Christian Weiske <cweiske@php.net>
  19. @license  http://www.gnu.org/copyleft/lesser.html LGPL
  20. @version  CVS: $Id$
  21. @link     http://pear.php.net/package/System_Folders
  22. */
  23.  
  24. require_once 'OS/Guess.php';
  25.  
  26. if (!defined('SYS_LINUX')) {
  27.     define('SYS_LINUX''linux');
  28.     define('SYS_WINDOWS''windows');
  29.     define('SYS_MAC''darwin');
  30. }
  31.  
  32. /**
  33. * Provides the locations of several system and user directories
  34. * independent of the operating system used.
  35. *
  36. * If a path does not exist or can't be found (error), NULL is returned.
  37. *
  38. * The class uses both $_ENV and $_SERVER to retrieve the environment
  39. *  paths, as this seems to be different between php4 and 5.
  40. *
  41. @category System
  42. @package  System_Folders
  43. @author   Christian Weiske <cweiske@php.net>
  44. @license  http://www.gnu.org/copyleft/lesser.html LGPL
  45. @link     http://pear.php.net/package/System_Folders
  46. */
  47. {
  48.     /**
  49.     * The operating system on which
  50.     * we work here
  51.     * Gotten from OS_Guess::getSysname()
  52.     *
  53.     * Values (are lowercase):
  54.     * - windows
  55.     * - linux
  56.     * - darwin
  57.     *
  58.     * Use the SYS_* constants to check it
  59.     *
  60.     * @var    string 
  61.     * @access protected
  62.     */
  63.     var $sys = 'unknown';
  64.  
  65.     /**
  66.     * Known names for the application directory
  67.     * in windows.
  68.     *
  69.     * @var    array 
  70.     * @access protected
  71.     */
  72.     var $arAppDataNames = array(
  73.         'Application data',       //english
  74.         'Anwendungsdaten',        //german
  75.         'Toepassingsgegevens',    //dutch
  76.         'Datos de programa',      //spanish
  77.         'Dados de aplicativos',   //portugese
  78.         'Data aplikac√≠',          //czech
  79.         'Programdata',            //norwegian
  80.         'Henkilokohtainen',       //finnish
  81.         'Donnees d\'applications',//french
  82.         'Dati applicazioni',      //italian
  83.         'Dane aplikacji',         //polish
  84.     );
  85.  
  86.  
  87.     /**
  88.     * Known names for the my documents directory
  89.     * on windows.
  90.     *
  91.     * @var    array 
  92.     * @access protected
  93.     */
  94.     var $arDocumentsWindows = array(
  95.         'My Documents',   //english
  96.         'Own Files',      //english?
  97.         'Eigene Dateien'//german
  98.         'Documenti',      //italian
  99.     );
  100.  
  101.  
  102.     /**
  103.     * Known names for the my Desktop directory.
  104.     *
  105.     * @var    array 
  106.     * @access protected
  107.     */
  108.     var $arDesktop = array(
  109.         'Desktop' //english, german, italian
  110.     );
  111.  
  112.  
  113.  
  114.     /**
  115.     * Known names for the my documents directory
  116.     * on linux and mac.
  117.     *
  118.     * @var    array 
  119.     * @access protected
  120.     */
  121.     var $arDocumentsLinux = array(
  122.         'Documents',    //english
  123.         'Dokumente',    //german
  124.         'Documenti',    //italian
  125.     );
  126.  
  127.  
  128.     /**
  129.     * Known paths for the documents and settings directory
  130.     * on windows.
  131.     *
  132.     * @var    array 
  133.     * @access protected
  134.     */
  135.     var $arDocsAndSettings = array(
  136.         'C:\\Documents and Settings\\',     //english, italian
  137.         'C:\\Dokumente und Einstellungen\\' //german
  138.     );
  139.  
  140.  
  141.     /**
  142.     * Known paths for the programs directory on windows.
  143.     *
  144.     * @var    array 
  145.     * @access protected
  146.     */
  147.     var $arProgramsWindows = array(
  148.         'C:\\Program Files\\',
  149.         'C:\\Programs\\',
  150.         'C:\\Programme\\',     //german
  151.         'C:\\Programmi\\',     //italian
  152.     );
  153.  
  154.     /**
  155.     * Known names for the shared documents directory
  156.     * on windows.
  157.     * Although the explorer shows "Shared documents"
  158.     * or "Gemeinsame Dokumente", the *real* directory
  159.     * is only one of the ones here.
  160.     *
  161.     * @var    array 
  162.     * @access protected
  163.     */
  164.     var $arSharedDocumentsWindows = array(
  165.         'Documents'//english
  166.         'Dokumente'//german
  167.         'Documenti'//italian
  168.     );
  169.  
  170.     /**
  171.     * Known paths for the windows directory.
  172.     *
  173.     * @var    array 
  174.     * @access protected
  175.     */
  176.     var $arWindowsDirs = array(
  177.         'C:\\WINDOWS\\',
  178.         'C:\\WINNT\\',
  179.         'C:\\WIN98\\',
  180.         'C:\\WIN95\\',
  181.         'C:\\WIN2000\\',
  182.         'C:\\WIN2K\\',
  183.         'C:\\WINXP\\'
  184.     );
  185.  
  186.     /**
  187.     * COM object used in Windows to get
  188.     * special folder locations via SpecialFolders()
  189.     * described in
  190.     * @link http://msdn.microsoft.com/library/default.asp?url=/library/en-us/script56/html/14761fa3-19be-4742-9f91-23b48cd9228f.asp
  191.     *
  192.     *  Available folders:
  193.     *  AllUsersDesktop
  194.     *  AllUsersStartMenu
  195.     *  AllUsersPrograms
  196.     *  AllUsersStartup
  197.     *  Desktop
  198.     *  Favorites
  199.     *  Fonts
  200.     *  MyDocuments
  201.     *  NetHood
  202.     *  PrintHood
  203.     *  Programs
  204.     *  Recent
  205.     *  SendTo
  206.     *  StartMenu
  207.     *  Startup
  208.     *  Templates
  209.     *
  210.     *  If this variable is NULL, it hasn't been created yet.
  211.     *  If it is FALSE, it cannot be created and used (e.g.
  212.     *      because COM is not available)
  213.     *
  214.     * @var    COM 
  215.     * @access protected
  216.     */
  217.     var $objCom = null;
  218.  
  219.  
  220.  
  221.     /**
  222.     * Constructor; initializes the system variable.
  223.     */
  224.     function System_Folders()
  225.     {
  226.         $og = new OS_Guess();
  227.         $this->sys = $og->getSysname();
  228.     }//function System_Folders()
  229.  
  230.  
  231.  
  232.     /**
  233.     * Adds a trailing slash to the given path if there is none.
  234.     * Uses DIRECTORY_SEPARATOR, so it works with windows and *nix.
  235.     *
  236.     * @param string $strPath The path
  237.     *
  238.     * @return string The path with a trailing slash
  239.     *
  240.     * @access protected
  241.     */
  242.     function addTrailingSlash($strPath)
  243.     {
  244.         if ($strPath === null{
  245.             return $strPath;
  246.         }
  247.         if (substr($strPath-1!== DIRECTORY_SEPARATOR{
  248.             $strPath .= DIRECTORY_SEPARATOR;
  249.         }
  250.         return $strPath;
  251.     }//function addTrailingSlash($strPath)
  252.  
  253.  
  254.  
  255.     /**
  256.     * Directories in windows environment variables sometimes
  257.     * have a double backslash, and this needs to be fixed.
  258.     *
  259.     * @param string $strPath The path
  260.     *
  261.     * @return string The fixed path
  262.     *
  263.     * @access protected
  264.     */
  265.     function fixWindowsPath($strPath)
  266.     {
  267.         if ($strPath === null{
  268.             return null;
  269.         }
  270.         return str_replace('\\\\''\\'$strPath);
  271.     }//function fixWindowsPath($strPath)
  272.  
  273.  
  274.  
  275.     /**
  276.     * Loops through a list of given paths and checks
  277.     * which of them are correct.
  278.     *
  279.     * @param array  $arPaths   Array with paths to test
  280.     * @param string $strBase   Base directory that shall be prepended to all paths
  281.     * @param string $strSuffix String appended to the directory path
  282.     *
  283.     * @return string The directory that exists. NULL if none of them matched.
  284.     *
  285.     * @access protected
  286.     * @static
  287.     */
  288.     function tryPaths($arPaths$strBase ''$strSuffix '')
  289.     {
  290.         foreach ($arPaths as $strName{
  291.             $strTmp $strBase $strName $strSuffix;
  292.             if (file_exists($strTmp&& is_dir($strTmp)) {
  293.                 return $strTmp;
  294.             }
  295.         }
  296.  
  297.         return null;
  298.     }//function tryPaths($arPaths, $strBase = '', $strSuffix = '')
  299.  
  300.  
  301.  
  302.     /**
  303.     * Loads the COM object into the $objCom variable.
  304.     *
  305.     * @return boolean True if it could be loaded, false if not
  306.     *
  307.     * @access protected
  308.     */
  309.     function loadCOM()
  310.     {
  311.         //prevent double-loading
  312.         if ($this->objCom !== null{
  313.             return $this->objCom !== false;
  314.         }
  315.  
  316.         if (!class_exists('COM')) {
  317.             $this->objCom = false;
  318.             return false;
  319.         }
  320.         $this->objCom = new COM('WScript.Shell');
  321.         if (!$this->objCom{
  322.             $this->objCom = false;
  323.             return false;
  324.         }
  325.         return true;
  326.     }//function loadCOM()
  327.  
  328.  
  329.  
  330.     /**
  331.     * Loads a windows path via COM using $objCom.
  332.     *
  333.     * @param string $strType See $objCom for allowed values.
  334.     *
  335.     * @return mixed False if no path could be obtained, string otherwise
  336.     *
  337.     * @access protected
  338.     */
  339.     function getCOMPath($strType)
  340.     {
  341.         if (!$this->loadCOM()) {
  342.             return false;
  343.         }
  344.         $strPath $this->objCom->SpecialFolders($strType);
  345.         if (!$strPath || $strPath == ''{
  346.             return false;
  347.         else {
  348.             return $strPath;
  349.         }
  350.     }//function getCOMPath($strType)
  351.  
  352.  
  353.  
  354.     /**
  355.     * Returns the All Users directory.
  356.     * Works on windows only, returns NULL if not found.
  357.     *
  358.     * @return string The all users directory
  359.     *
  360.     * @access public
  361.     */
  362.     function getAllUsers()
  363.     {
  364.         if ($this->sys == SYS_WINDOWS{
  365.             $arEnv $_SERVER $_ENV;
  366.             if (isset($arEnv['ALLUSERSPROFILE'])
  367.                 && is_dir($arEnv['ALLUSERSPROFILE'])
  368.             {
  369.                 return $this->addTrailingSlash($arEnv['ALLUSERSPROFILE']);
  370.             else {
  371.                 $strDocsAndSettings System_Folders::tryPaths(
  372.                     $this->arDocsAndSettings
  373.                 );
  374.                 if ($strDocsAndSettings !== null{
  375.                     $strAll $strDocsAndSettings 'All Users';
  376.                     if (is_dir($strAll)) {
  377.                         return $this->addTrailingSlash($strAll);
  378.                     }
  379.                 }
  380.             }
  381.         }
  382.         return null;
  383.     }//function getAllUsers()
  384.  
  385.  
  386.  
  387.     /**
  388.     * Returns the path to the application data directory.
  389.     * This is the directory in which applications save their
  390.     * settings.
  391.     *
  392.     * On Windows, this is an own directory called "Application data",
  393.     * on *nix, the home directory is used.
  394.     * MacOS X has two application settings directories:
  395.     *  - $HOME/Library/Preferences/<pref_file> for normal settings
  396.     *  - $HOME/Library/Application Support/<app_name>/ for data files that
  397.     *         that the application needs to store
  398.     * This method returns the latter, as it works for both storing just
  399.     *  prefs and files in an application specific subdir. That's not 100%
  400.     *  correct for apple, but it will work.
  401.     *
  402.     * @return string  The application data directory
  403.     *
  404.     * @access public
  405.     */
  406.     function getAppData()
  407.     {
  408.         $strAppData = null;
  409.         if ($this->sys == SYS_WINDOWS{
  410.             /**
  411.             *   win2k/xp: user_dir/names
  412.             *   win98: C:\windows\Anwendungsdaten|appdata
  413.             */
  414.             $strHome $this->getHome();
  415.             $strAppData System_Folders::tryPaths($this->arAppDataNames$strHome);
  416.             if ($strAppData == null{
  417.                 /**
  418.                 *   We didn't find it in the user directory,
  419.                 *   so check the windows dir - win9x had the
  420.                 *   data there
  421.                 */
  422.                 $strWindows $this->getWindows();
  423.                 $strAppData System_Folders::tryPaths(
  424.                     $this->arAppDataNames$strWindows
  425.                 );
  426.             }//appdata still null
  427.         else {
  428.             $strAppData $this->getHome();
  429.         }
  430.  
  431.         return $this->addTrailingSlash($strAppData);
  432.     }//function getAppData()
  433.  
  434.  
  435.  
  436.     /**
  437.     * Returns the path to the user's desktop.
  438.     *
  439.     * @return string The user's desktop
  440.     *
  441.     * @access public
  442.     */
  443.     function getDesktop()
  444.     {
  445.         $strDesktop   = null;
  446.  
  447.         if ($this->sys == SYS_WINDOWS{
  448.             $strDesktop $this->getCOMPath('Desktop');
  449.             if ($strDesktop !== false && file_exists($strDesktop)) {
  450.                 return $this->addTrailingSlash($this->fixWindowsPath($strDesktop));
  451.             }
  452.         }
  453.  
  454.         $strHome      $this->getHome();
  455.         if ($strHome === null{
  456.             return null;
  457.         }
  458.  
  459.         $strDesktop System_Folders::tryPaths($this->arDesktop$strHome);
  460.  
  461.         return $this->addTrailingSlash($strDesktop);
  462.     }//function getDesktop()
  463.  
  464.  
  465.  
  466.     /**
  467.     * Returns the path to the user's documents directory.
  468.     * (normally below the home folder)
  469.     *
  470.     * @return string The "documents" directory
  471.     *
  472.     * @access public
  473.     */
  474.     function getDocuments()
  475.     {
  476.         $strDocuments = null;
  477.  
  478.         if ($this->sys == SYS_WINDOWS{
  479.             $strDocuments $this->getCOMPath('MyDocuments');
  480.             if ($strDocuments !== false && file_exists($strDocuments)) {
  481.                 return $this->addTrailingSlash($this->fixWindowsPath($strDocuments));
  482.             }
  483.             $arKnownNames $this->arDocumentsWindows;
  484.         else {
  485.             $arKnownNames $this->arDocumentsLinux;
  486.         }
  487.  
  488.         $strHome $this->getHome();
  489.         if ($strHome === null{
  490.             return null;
  491.         }
  492.         $strDocuments System_Folders::tryPaths($arKnownNames$strHome);
  493.  
  494.         return $this->addTrailingSlash($strDocuments);
  495.     }//function getDocuments()
  496.  
  497.  
  498.  
  499.     /**
  500.     * Returns the path to the user's home directory.
  501.     *
  502.     * @return string The user's home directory
  503.     *
  504.     * @access public
  505.     */
  506.     function getHome()
  507.     {
  508.         $strHome = null;
  509.         if ($this->sys == SYS_LINUX{
  510.             if (isset($_ENV['HOME'])) {
  511.                 //environment variable set
  512.                 $strHome $_ENV['HOME'];
  513.             else {
  514.                 //env not set, so try the default directory
  515.                 $strUser $this->getUserName();
  516.                 if ($strUser == 'root'{
  517.                     $strHome '/root';
  518.                 else if ($strUser !== null{
  519.                     $strHome '/home/' $strUser;
  520.                 }
  521.             }
  522.         else if ($this->sys == SYS_MAC{
  523.             if (isset($_ENV['HOME'])) {
  524.                 //environment variable set
  525.                 $strHome $_ENV['HOME'];
  526.             else {
  527.                 //env not set, so try the default directory
  528.                 $strUser $this->getUserName();
  529.                 if ($strUser !== null{
  530.                     $strHome '/Users/' $strUser;
  531.                 }
  532.             }
  533.         else if ($this->sys == SYS_WINDOWS{
  534.             $arEnv $_SERVER $_ENV;
  535.             if (isset($arEnv['USERPROFILE'])) {
  536.                 $strHome $arEnv['USERPROFILE'];
  537.             else if (isset($arEnv['HOMEPATH']&& isset($arEnv['HOMEDRIVE'])) {
  538.                 $strHome $arEnv['HOMEDRIVE'$arEnv['HOMEPATH'];
  539.             else {
  540.                 //guess it...
  541.                 $strUser $this->getUserName();
  542.                 if ($strUser !== null{
  543.                     //It seems as if the german version of windows is the only
  544.                     //one that translated "docs and settings". All other languages
  545.                     //use the english name
  546.                     $strHome System_Folders::tryPaths(
  547.                         $this->arDocsAndSettings
  548.                     $strUser;
  549.                 }
  550.             }
  551.             $strHome $this->fixWindowsPath($strHome);
  552.         }//windows
  553.  
  554.         return $this->addTrailingSlash($strHome);
  555.     }//function getHome()
  556.  
  557.  
  558.  
  559.     /**
  560.     * Returns the path to the programs directory.
  561.     * This is the dir where all programs are installed
  562.     * normally.
  563.     *
  564.     * On windows, it's mostly "C:\Programs\", on linux,
  565.     * the /opt/ directory is returned.
  566.     *
  567.     * @return string The programs directory
  568.     *
  569.     * @access public
  570.     */
  571.     function getPrograms()
  572.     {
  573.         $strPrograms = null;
  574.  
  575.         if ($this->sys == SYS_LINUX{
  576.             if (file_exists('/opt/'&& is_dir('/opt/')) {
  577.                 $strPrograms '/opt/';
  578.             }
  579.         else if ($this->sys == SYS_MAC{
  580.             $strPrograms '/Applications/';
  581.         else if ($this->sys == SYS_WINDOWS{
  582.             $strPrograms $this->getCOMPath('Programs');
  583.             if ($strPrograms === false || !file_exists($strPrograms)) {
  584.                 $arEnv $_SERVER $_ENV;
  585.                 if (isset($arEnv['ProgramFiles'])) {
  586.                     $strPrograms $arEnv['ProgramFiles'];
  587.                 else {
  588.                     //guess it
  589.                     $strPrograms System_Folders::tryPaths(
  590.                         $this->arProgramsWindows
  591.                     );
  592.                 }//guess it
  593.             }
  594.             $strPrograms $this->fixWindowsPath($strPrograms);
  595.         }//windows
  596.  
  597.         return $this->addTrailingSlash($strPrograms);
  598.     }//function getPrograms()
  599.  
  600.  
  601.  
  602.     /**
  603.     * Returns the path to the directory for temporary files.
  604.     *
  605.     * @return string The temporary directory
  606.     *
  607.     * @access public
  608.     */
  609.     function getTemp()
  610.     {
  611.         $strTemp = null;
  612.  
  613.         if ($this->sys == SYS_LINUX || $this->sys == SYS_MAC{
  614.             if (file_exists('/tmp/'&& is_dir('/tmp/')) {
  615.                 $strTemp '/tmp/';
  616.             }
  617.         else if ($this->sys == SYS_WINDOWS{
  618.             $arEnv $_SERVER $_ENV;
  619.             if (isset($arEnv['TEMP'])) {
  620.                 $strTemp $arEnv['TEMP'];
  621.             else if (isset($arEnv['TMP'])) {
  622.                 $strTemp $arEnv['TMP'];
  623.             else {
  624.                 //guess it
  625.                 $strTemp System_Folders::tryPaths(
  626.                     $this->arWindowsDirs'''\\Temp'
  627.                 );
  628.             }//no env variable
  629.             $strTemp $this->fixWindowsPath($strTemp);
  630.         }//windows
  631.  
  632.         return $this->addTrailingSlash($strTemp);
  633.     }//function getTemp()
  634.  
  635.  
  636.  
  637.     /**
  638.     * Returns the path to the shared documents directory.
  639.     *
  640.     * Supports windows only (at least for now) as no other
  641.     * operating system seems to have such a folder.
  642.     * Returns NULL on failure (not windows or not found).
  643.     *
  644.     * @return string The shared documents dir
  645.     *
  646.     * @access public
  647.     */
  648.     function getSharedDocuments()
  649.     {
  650.         $strShared = null;
  651.         if ($this->sys == SYS_WINDOWS{
  652.             $strAll $this->getAllUsers();
  653.             if ($strAll !== null{
  654.                 $strShared System_Folders::tryPaths(
  655.                     $this->arSharedDocumentsWindows$strAll
  656.                 );
  657.             }
  658.         }
  659.  
  660.         return $this->addTrailingSlash($strShared);
  661.     }//function getSharedDocuments()
  662.  
  663.  
  664.  
  665.     /**
  666.     * Returns the name of the guesses system.
  667.     * Can be compared with SYS_* constants.
  668.     *
  669.     * @return string The detected system
  670.     *
  671.     * @access public
  672.     */
  673.     function getSys()
  674.     {
  675.         return $this->sys;
  676.     }//function getSys()
  677.  
  678.  
  679.  
  680.     /**
  681.     * Returns the name for the user
  682.     * under which name the program runs.
  683.     *
  684.     * This function returns the *system user name*,
  685.     * not the name with forename and surname
  686.     * On unix, this would be e.g. 'fbar' or so for
  687.     * the user 'Foo Bar'
  688.     *
  689.     * This method is used my most other methods, so
  690.     * recognizing the user name is really important.
  691.     * Be sure to check this method if the others fail.
  692.     *
  693.     * @return string The user name
  694.     *
  695.     * @access public
  696.     */
  697.     function getUserName()
  698.     {
  699.         $strUser = null;
  700.         if ($this->sys == SYS_LINUX
  701.             || $this->sys == SYS_MAC
  702.         {
  703.             if (isset($_ENV['USER'])) {
  704.                 $strUser $_ENV['USER'];
  705.             else {
  706.                 $strUser trim(`whoami`);
  707.             }
  708.         else if ($this->sys == SYS_WINDOWS{
  709.             $arEnv $_SERVER $_ENV;
  710.             if (isset($arEnv['USERNAME'])) {
  711.                 $strUser $arEnv['USERNAME'];
  712.             }
  713.         }
  714.         return $strUser;
  715.     }//function getUserName()
  716.  
  717.  
  718.  
  719.     /**
  720.     * Returns the windows directory (if any).
  721.     * NULL is returned if the system is not Windows.
  722.     *
  723.     * @return string The windows directory, NULL if not on windows
  724.     *
  725.     * @access public
  726.     */
  727.     function getWindows()
  728.     {
  729.         if ($this->sys != SYS_WINDOWS{
  730.             return null;
  731.         }
  732.  
  733.         $strWindows = null;
  734.         $arEnv $_SERVER $_ENV;
  735.         if (isset($arEnv['SystemRoot'])) {
  736.             $strWindows $arEnv['SystemRoot'];
  737.         else if (isset($arEnv['windir'])) {
  738.             $strWindows $arEnv['windir'];
  739.         else {
  740.             $strWindows System_Folders::tryPaths($this->arWindowsDirs);
  741.         }//no env variable
  742.  
  743.         return $this->addTrailingSlash($this->fixWindowsPath($strWindows));
  744.     }//function getWindows()
  745.  
  746. }//class System_Folders
  747. ?>

Documentation generated on Fri, 21 Dec 2012 15:30:03 +0000 by phpDocumentor 1.4.3. PEAR Logo Copyright © PHP Group 2004.