System_Folders 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.
The methods return a string of the directory (with trailing slash) if the directory can be determined, and NULL if it fails or isn't available on the system. For example, the "Shared Documents" folder exists on Windows only. If you run getSharedDocuments() on a Mac or Linux, the method will return NULL.
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.
Table 56-1. Available folders and their methods
| Folder | Method to use | Notes |
|---|---|---|
| All users directory | getAllUsers() | Windows only |
| Application data | getAppData() | |
| Desktop | getDesktop() | |
| Documents / My Documents | getDocuments() | |
| Home directory | getHome() | |
| Programs folder (installed ones) | getPrograms() | |
| Temporary files | getTemp() | |
| Shared documents | getSharedDocuments() | Windows only |
| Windows directory | getWindows() | Windows only |
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.
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.
Both issues are addressed with System_Folders_Cached. It provides a cached version of the getXXX() 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.
Further, the class provides methods to set the folder locations and save this settings into an ini file. Saving them can be done with saveToFile() and they can be loaded with loadFromFile(). This allows customization of the folder locations, and persistency across sessions.