Differences

This shows you the differences between the selected revision and the current version of the page.


docs:introduction 2009/03/09 15:22 docs:introduction 2009/03/20 14:37 current
Line 5: Line 5:
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: 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. +  * **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. 
-**//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.
- +
-**//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 ===== ===== Getting Started =====
Before building your first Bedrock application, ensure the environment on which you will be running your application meets the following requirements: 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)   * Web Server (Apache recommended, with sessions and mod_rewrite enabled)
  * PHP 5.2 or newer (legacy support is planned, but not available yet)   * PHP 5.2 or newer (legacy support is planned, but not available yet)
Line 18: Line 17:
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. 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 ==== ==== Step 1: Download ====
-Refer to the 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 currently offered.+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 ==== ==== Step 2: Directory Structure ====
-Below is the recommended directory structure for a Bedrock application, and a description of what goes in each directory. You may also use your own directory structure, however some components may require additional configuration if you do so.+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.
<html> <html>
- <ul class="treeviewlist filetree"> +    <ul class="treeviewlist filetree"> 
- <span class="folder">application_root</span> +       <span class="folder">application_root</span> 
- <li><span class="folder">cfg</span> +       <li><span class="folder">cfg</span> 
- <ul> +           <ul> 
- <li><span class="file">application.xml</span></li> +               <li><span class="file">application.xml</span></li> 
- <li><span class="file">database.xml</span></li> +               <li><span class="file">install.xml</span></li> 
- <li><span class="file">install.xml</span></li> +           </ul> 
- </ul> +        </li> 
- </li> +        <li><span class="folder">lib</span> 
- <li><span class="folder">lib</span> +            <ul> 
- <ul> +                <li class="closed"><span class="folder">Application</span> 
- <li><span class="folder">Bedrock</span></li> +                    <ul> 
- <li><span class="file">Bedrock.php</span></li> +                        <li>&nbsp;...</li> 
- </ul> +                   </ul> 
- </li> +               </li> 
- <li><span class="folder">log</span></li> +               <li class="closed"><span class="folder">Bedrock</span> 
- <li><span class="folder">pub</span> +                   <ul> 
- <ul> +                       <li>&nbsp;...</li> 
- <li><span class="file">index.php</span></li> +                    </ul> 
- </ul> +                </li> 
- </li> +                <li><span class="file">Application.php</span></li> 
- <li><span class="folder">tmp</span></li> +               <li><span class="file">Bedrock.php</span></li> 
- </ul>+           </ul> 
 +       </li> 
 +       <li><span class="folder">log</span></li> 
 +       <li><span class="folder">pub</span> 
 +           <ul> 
 +               <li><span class="folder">css</span></li> 
 +                <li><span class="folder">images</span></li> 
 +                <li><span class="folder">js</span></li> 
 +                <li><span class="file">.htaccess</span></li> 
 +                <li><span class="file">index.php</span></li> 
 +           </ul> 
 +       </li> 
 +       <li><span class="folder">tmp</span></li> 
 +   </ul>
</html> </html>
 +
 +=== 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 ==== ==== Step 3: Configuration ====
-While a Bedrock application can work without any configuration, most will require at least some basic configuration (the most common being database connection details).+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: 
 + 
 +<code html> 
 +<?xml version="1.0"?> 
 +<config> 
 +    <main> 
 +        <meta> 
 +            <title>Sample Bedrock Application</title> 
 +            <version>1.0.0</version> 
 +            <namespace>Application</namespace> 
 +        </meta> 
 +        <env> 
 +            <os>unix</os> 
 +        </env> 
 +        <root> 
 +            <web>/</web> 
 +            <system>/absolute/path/to/application</system> 
 +            <cfg>/absolute/path/to/application/cfg</cfg> 
 +            <lib>/absolute/path/to/application/lib</lib> 
 +            <log>/absolute/path/to/application/log</log> 
 +            <pub>/absolute/path/to/application/pub</pub> 
 +        </root> 
 +    </main> 
 +</config> 
 +</code> 
 + 
 +==== 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: 
 + 
 +<code php> 
 +<?php 
 +/** 
 + * Main Application Controller 
 + * 
 + * Represents the main controller for the application. For simple 
 + * applications, rall user code will likely only appear here. 
 + */ 
 +class Application_Control_Index extends Bedrock_Control { 
 +    /** 
 +    * Main index for the application. 
 +    *  
 +    * @param array $args additional agruments passed via the URL 
 +    */ 
 +    public function index($args) { 
 +        Bedrock_Common_Logger::logEntry(); 
 + 
 +        try { 
 +             
 +            // Your application code goes here.... 
 +             
 +             
 +             
 + 
 +            Bedrock_Common_Logger::logexit(); 
 +        } 
 +        catch(Bedrock_Common_Exception $ex) { 
 +            Bedrock_Common_Logger::exception($ex); 
 +            Bedrock_Common_Logger::logexit(); 
 +        } 
 +    } 
 +} 
 +?> 
 +</code> 
 + 
 +=== 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: 
 + 
 +<code php> 
 +<?php 
 +/** 
 + * Main Index Page 
 + * 
 + * Initializes the application environment, setting up an autoload 
 + * function, include paths, and loads any needed configuration files. 
 + */ 
 + 
 +// Imports 
 +require_once '../lib/Bedrock.php'; 
 +require_once '../lib/Bedrock/Common.php'; 
 + 
 +try { 
 +    // Initialize Environment 
 +    Bedrock_Common::init('/absolute/path/to/configuration.xml'); 
 +    Bedrock_Common_Logger::logEntry(); 
 + 
 +    // Start Router 
 +    Bedrock_Common_Registry::get('router')->delegate(); 
 + 
 +    Bedrock_Common_Logger::logExit(); 
 +} 
 +catch(Bedrock_Common_Exception $ex) { 
 +    Bedrock_Common_Logger::exception($ex); 
 +    Bedrock_Common_Logger::logExit(); 
 +} 
 +?> 
 +</code> 
 + 
 +=== 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: 
 + 
 +<code>RewriteEngine on 
 + 
 +RewriteCond %{REQUEST_FILENAME} !-f 
 +RewriteCond %{REQUEST_FILENAME} !-d 
 + 
 +RewriteRule ^(.*)$ index.php?route=$1 [L,QSA] 
 +</code>
-   +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.
-===== Tutorials =====+
 +==== 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//).