====== WACT File Organization ====== WACT is designed to operate with two different file organizations, development and production. The development environment is based around the SubVersion source code control system. The production environment is organized differently based on security and performance requirements. WACT is ''include_path'' oriented. ===== Development Configuration ===== The WACT development file organization is designed largely to be compatible with SVN. A WACT application is divided up into multiple projects. Each project is a directory containing ''.wactproj'' file, along with all of its subdirectories. Each project directory is designed to be a root directory added to the ''include_path''. Additionally, a project may be divided up into multiple PEAR style packages. The definition of such a package is as of yet, undefined. ==== Installing a WACT project for Development ==== A WACT project is designed to be installed for development purposes by using ''svn export'' or ''svn checkout''. WACT projects may be checked out into the document root of a development test server. Some additional configuration may be necessary to run a WACT application in the development configuration. //put /bin in your shell path.// //setting up the proper include_path.// ===== Production Configuration ===== The file organization is designed to be compatible with PEAR. The production organization of a WACT application is based on several directory locations. ==== Installing a WACT project in Production ==== Before installing into production, you will generally want to tag a project in svn, create a package from that project, then use the PEAR installer to install that package on your production server. //Staging and rollback issues.// ===== File Roles ===== Each file in a WACT project is associated with a specific role. The role of any given file in a development configuration can be determined by either its file extension, or its path, relative to nearest enclosing project (as defined by ''.wactproj''). The file role names correspond to the PEAR file roles, except for ''public'' and ''static'', which have no official PEAR equivalent. ^ File extension based roles ^^^ ^ Role ^ Extention ^ Description ^ | php | .php | A standalone PHP file. Designed to be CLI utility or front controller in document root. | | php | .inc.php | An includable php file. Intended to be included or required into another program. | | php | .face.php | A php file that declares nothing but interfaces. | | php | .xcpt.php | A php file that declares nothing but exception classes. | | test | .test.php | A file that declares test cases. The WACT test runner will scan for these files when building a list of test cases that can be run. | | test | .test.inc.php | A file that is used by more than one test case, but is not a test case itself. | | test | .test.pre.php | Defines a test prerequisite for the test runner. | ^ Path based roles ^^^ ^ Role ^ Extention ^ Description ^ | script | /bin/ | All files in this directory are considered to be command line utilities | | data | /data/ | Data files | | public | /public/ | All files in this directory should be placed in the web server's document root | | static | /static/ | Static resources. | | doc | /doc/ | Documentation files | ===== Locating Files ===== Because the production and development configurations for a WACT project can be so different, it can be a challenge to produce code that can locate a file of any given role in both environments. //Using a bootstrap file to establish initial configuration. Production bootstrap vs. development bootstrap. // ==== Front End Directories ==== The front end directories are those accessible my the web server. === Document Root === The document root is the directory that the web server associates with a given website. WACT application should strive to minimize the number of files placed into the Document Root. For security reasons, only front controllers or stubs should be placed into the document root. These front controllers should then access files from back end locations. //Explain file permissions and ownership in DocumentRoot.// === Static resources === It can be advantageous in high performance production environments to serve dynamic content from one domain or with one web server and to serve static content from another domain or a different web server. WACT supports these configurations. The directory for static resources need not be different from the Document Root directory. === Uploads === Sometimes it is necessary to allow a web application to dynamically place files in a location accessible to the web browsers. For example, a user may be allowed to upload an avatar image to be served from the file system. Best practice to disable scripting and dynamic content from this directory. ==== Back End Directories ==== The back end directories hold information that should not be publicly accessible to the web browser. There are multiple back end directories based on the roles of the contents and necessary permissions. === include_path === The ''include_path'' is the primary location of php files in a WACT application. Corresponds to the PEAR ''php_dir'' variable. Files with the role ''php'' are placed here by the PEAR installer. === Temporary === Holds temporary files. Temporary files may be periodically deleted without consequence. The PEAR installer does not install files into this directory. === Cache === Holds cached information. May be deleted without consequence. The system should automatically regenerate any files that are missing. The PEAR installer does not install files into this directory. === Static Data === Holds read only data required by the application. Corresponds to the PEAR ''data_dir'' variable. Files with the role ''data'' are placed here by the PEAR installer. === Data === Holds data required by the application. Must be writable. May not be deleted. //How and why is this different than Static Data.// === Documentation === Corresponds to the PEAR ''doc_dir'' variable. Files with the role ''doc'' are placed here by the PEAR installer. === Tests === Corresponds to the PEAR ''test_dir'' variable. Files with the role ''test'' are placed here by the PEAR installer. === Bin === Corresponds to the PEAR ''bin_dir'' variable. Files with the role ''script'' are placed here by the PEAR installer.