====== Introduction ====== Bedrock is a new kind of web framework, designed with the bigger picture in mind. Rather than building a framework for the sake of building a framework, Bedrock is just the first step. It is part of a platform that intends to transform the way web applications are managed and built. ===== What Is Bedrock? ===== Bedrock is a web framework written in PHP and represents a collection of code designed to simplify the building of PHP-based web applications. Think of it as a code toolbox, containing all the tools you need to build your application quickly and on solid ground. Bedrock is being built around three primary principles: * **Unity** describes the goal of unifying disparate systems. Bedrock is being designed to support a plethora of web technologies currently available. This includes database systems (i.e. MySQL, PostgreSQL, MS SQL Server), public APIs (i.e. Google Maps, Facebook, Twitter, etc.), data formats (i.e. XML, YAML, CSV, etc.), and web-based communication (i.e. SOAP, AJAX, JSON, REST). By removing the barriers between these technologies, the hope is that developers will be able to focus on implementing their ideas rather than subtle logistics. * **Transparency** refers to the goal of making applications as easy to understand as possible, at all levels. Whether you are looking at the codebase of a Bedrock application, reading the logs it generates, or watching for errors or potential problems, we want to make examining your application as transparent as possible. * **Scalability** is the most difficult yet most important goal. We want every Bedrock application to scale with ease and require little to no refactoring. We consider every application a living, growing thing that rarely stays in one place or the same size. Because of this, we want Bedrock applications to be easily modified and as portable as possible. ===== Getting Started ===== Before building your first Bedrock application, ensure the environment on which you will be running your application meets the following requirements: * Web Server (Apache recommended, with sessions and mod_rewrite enabled) * PHP 5.2 or newer (legacy support is planned, but not available yet) * Database System (optional, MySQL 4.0+ is currently supported) You are welcome to try Bedrock with other untested configurations. If you do so, we encourage you to send feedback about the environment and any problems you encounter. We are constantly working to broaden the range of hardware and software on which Bedrock can run. Keep in mind that there are plans to simplify the following process in future releases. Be sure to check this section for updates as newer versions of Bedrock are released. ==== Step 1: Download ==== Refer to the [[http://www.bedrockframework.com/download/|download page]] to obtain the latest version available. We recommend downloading the full release (instead of the core) in order to fully explore all the functionality available. ==== Step 2: Directory Structure ==== Below is the recommended directory structure for a Bedrock application. For your first application, it is recommended that you follow this structure (either by downloading and building on the sample application, or recreating it using this guide). You may also use your own directory structure, however some components may require additional configuration if you do so. Note that in a production environment, the document root should point to the //pub// directory, so that all other files are not directly accessible from the web. === cfg === This directory contains all configuration data. This includes application and install configurations, as well as other user-editable files. Initially, this directory should contain at least one configuration file (often named "application.xml") containing all configuration options for your application. //**Note:** Permissions on this directory must be set to writeable for the account under which PHP is running.// === lib === All external libraries, frameworks, and classes are contained here. Most applications will start with only the Bedrock class hierarchy stored here. === log === All log files are stored here, and by default are divided into daily files (named "YYYY-MM-DD.log"). Log files for other components or applications may also be placed here. //**Note:** Permissions on this directory must be set to writeable for the account under which PHP is running.// === pub === This directory represents the publicly accessible area of the web application. For optimal security, it is recommended that this directory be set as the document root so that peer directories are not accessible directly via the web. Depending on whether or not Bedrock's template system is used, this directory will either contain the template system's public directory structure, or a more basic structure that can be organized at the developer's discretion. At a minimum this directory should contain an index file ("index.php") that will act as the point of entry for browsers accessing the application. Additionally, it is recommended that an Apache .htaccess file is also defined in order to utilize Bedrock's support for "friendly" URLs. === tmp === This directory is intended for general purpose temporary storage. Any component that require temporary storage of files (i.e. image manipulation, caching, etc.) should use this directory to store relevant files. //**Note:** Permissions on this directory must be set to writeable for the account under which PHP is running.// ==== Step 3: Configuration ==== Every Bedrock application utilizes a central XML configuration file to define any needed settings. For a basic application, this file (named "application.xml" in the [[sample application]]) typically contains the following XML:
Sample Bedrock Application 1.0.0 Application unix / /absolute/path/to/application /absolute/path/to/application/cfg /absolute/path/to/application/lib /absolute/path/to/application/log /absolute/path/to/application/pub
==== Step 4: Initial Scripts ==== Before your application is ready to run, you must set up two initial scripts. First you will need to set up your main controller class, which will contain all the user-written code for your application. Once that is set up, you will need to set up your //index.php// script, which will be used to initialize your application. === Main Controller === **File:** //lib/Application/Control/Index.php// The application's main controller is the container for all of the application's business logic. It is here that the framework steps aside and allows the developer to step in. The sample application includes an initial controller to allow you to get started right away. If you choose not to use the sample application, consider this example: === Index Script === **File:** //pub/index.php// The application index script will be used to initialize the application environment and will load up the controller you just created. This file should be named //index.php// and should be located within the //pub// directory within your application root. If you are using the sample application, this script has already been created for you and you will only have to make a single modification (specifying the absolute path to your configuration file). Otherwise, consider using the below example as a reference for creating your own: delegate(); Bedrock_Common_Logger::logExit(); } catch(Bedrock_Common_Exception $ex) { Bedrock_Common_Logger::exception($ex); Bedrock_Common_Logger::logExit(); } ?> === Apache URL Rewrite === **File:** //pub/.htaccess// If you are hosting your application with Apache, you may optionally include an //.htaccess// file in your //pub// directory in order to utilize friendly URLs. Without this file, pages are accessed using URLs like this: http://www.yourdomain.com/index.php?route=path/to/controller/and_method With this file, they can look like this: http://www.yourdomain.com/path/to/controller/and_method The sample application includes this file, which contains the following: RewriteEngine on RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule ^(.*)$ index.php?route=$1 [L,QSA] As you can see from the above snippet, the URL is rewritten to the friendly format only if the specified URL does not point to an existing file and/or directory. ==== Step 5: The Tutorials ==== At this point you should have everything set up and working. To verify this, point your browser to the //index.php// file located in the application's //pub// directory. You should see a blank page absent of any PHP or web server errors (and will display any output you specified in the [[#main_controller|above mentioned controller]]). If everything isn't working as expected, visit the [[http://forums.bedrockframework.com/|forums]] to get help from Bedrock's developers as well as fellow community members. Otherwise, it is recommended that you work through the introductory [[Docs:Tutorials|tutorials]] to familiarize yourself with the core components of the framework (including more advanced concepts such as //controller nesting//).