Getting started - raymondjavaxx/roxphp GitHub Wiki

Getting started with RoxPHP

RoxPHP borrows heavily from CakePHP: it follows a similar Model-View-Controller (MVC) architecture and has a similar file structure. If you are already familiar with Cake, you should have little trouble adapting to Rox.

Main differences from Cake:

  • The model layer returns objects, not arrays. In Cake, models are singletons that provide access to the underlying database table. In Rox, you work with the model layer by instantiating model objects and performing operations on them.

  • Rox requires at least PHP 5.3

A few words about the file structure:

  • app/controllers - this is where your site’s controllers live

  • app/models - this is where your site’s models live

  • app/views - this is where you put your site’s views / html templates and reusable elements

  • app/helpers - this is where you put reusable logic used in views

  • app/lib - this is where you put reusable code that is not strictly depent on Rox.

  • app/config - Rox configuration directory. The configuration directory contains:

    • init.php - site/project settings

    • database.php - database access credentials

    • routes.php - routing configuration

5-minute blog tutorial

Grab Rox from github:

git clone https://github.com/raymondjavaxx/roxphp.git rox_app

Create the database and tables:

CREATE DATABASE rox_app;
USE rox_app;
CREATE table posts (
    id INT(11) NOT NULL AUTO_INCREMENT PRIMARY KEY,
    title VARCHAR(255),
    body TEXT,
    created_at DATETIME,
    updated_at DATETIME
);

Open app/config/database.php file inside the rox_app directory in your favorite text editor and make sure that the database settings match your MySQL setup. I will be using these settings:

ConnectionManager::setConfig('default', array(
    'host'     => 'localhost',
    'username' => 'root',
    'password' => '',
    'database' => 'rox_app'
));

Generate a model, controller and standard views for posts by opening up a terminal, navigating to libraries/rox/console and executing the rox script (rox.bat on Windows):

./rox gen model posts
./rox gen controller posts
./rox gen views posts

If the last command is throwing an error saying that Rox cannot establish a database connection, you need to go back to app/config/database.php and double-check your database connection credentials. Note that on some systems localhost vs. 127.0.0.1 values for the host key are not synonymous.

Assuming that you placed the rox_app directory under your web server’s public_html directory, you should now be able to see the newly generated pages in your browser. To do so, go to the post index page at http://localhost/rox_app/posts. You should see an empty HTML table. The reason it’s empty is because we’ve yet to add any content. Let’s do so now.

The rox gen commands above generated all the pieces necessary for simple create, read, update, delete (CRUD) logic. You should now be able to use the links on the post index page to add, edit and delete posts.

Now that you’ve seen Rox in action, let’s examine how it works.

Routing

Routing is the process of mapping URLs to controller actions. The routing rules that Rox uses are specified in app/config/routes.php file. It comes with a set of default rules that you can substitute or modify depending on your needs, but these rules are sufficient to write a simple application. Let’s take a look at the rule responsible for mapping the /posts url to a controller:

Router::connect('/:controller', array(
    'action' => 'index',
), array('via' => 'GET'));

This rule states that any GET request to the URL starting with a slash and a single word will be mapped to the corresponding controller’s index action. For /posts, the controller will reside in a file called PostsController.php and have a function called indexAction.

Controllers

Controllers serve as a mediator between views and models, reside in the app/controllers directory and follow the naming convention of {uppercase table name} + Controller.php, so that controller for posts becomes app/controllers/PostsController.php. Action names contain one or more words describing the action and an Action suffix, e.g. indexAction or viewAction.

The generated index action contains only a few lines of code that pull a single page of posts and render the page using a view.

class PostsController extends ApplicationController {
    public function indexAction() {
        $posts = Post::paginate(array(
            'page' => $this->request->getQuery('page', 1)
        ));
        $this->set(compact('posts'));
    }
    // ...
}

The Post::paginate() method is used to paginate through the posts table or, in other words, to retrieve posts 10 items at a time. The set method accepts an associative array of variable names to values that are passed on to the view.

Views

Views are used to separate presentation from business logic and contain HTML markup with a minimum of PHP to render the contents accepted from the calling controller. A filename convention is used to locate a view corresponding to a controller. The conventional path is app/views/{controller name}/{action name}.html.tpl. For the indexAction of the posts controller, the corresponding view would be located in app/views/posts/index.html.tpl. The complete source for the index.html.tpl view is as follows:

<h1>Posts</h1>
<table>
    <tr>
        <th>Id</th>
        <th>Title</th>
        <th>Body</th>
        <th>Created At</th>
        <th>Modified At</th>
        <th>Actions</th>
    </tr>
    <?php foreach ($posts as $i => $post): ?>
        <tr>
            <td><?php echo $post->id ?></td>
            <td><?php echo htmlspecialchars($post->title) ?></td>
            <td><?php echo htmlspecialchars($post->body) ?></td>
            <td><?php echo $post->created_at ?></td>
            <td><?php echo $post->modified_at ?></td>
            <td>
                <?php echo $html->deleteLink('Delete', $post) ?> |
                <?php echo $html->editLink('Edit', $post) ?> |
                <?php echo $html->viewLink('View', $post) ?>
            </td>
        </tr>
    <?php endforeach; ?>
</table>
<p><?php echo $html->link('New Post', '/posts/new') ?></p>
<?php echo $pagination->links($posts) ?>

The view iterates over the array of Post objects returned by the Post::paginate()call in the indexAction() above and displays object properties in an HTML table, together with links for CRUD logic and pagination links.

Models

Model objects provide ActiveRecord-style access to the underlying database, as well as validation.

Associations

Associations in Rox are defined in a static property on the model class:

class User extends \rox\ActiveRecord {
    protected static $_hasMany = array('posts');
    // ...
}

Related records can then be accessed from a model instance:

$user = User::find($id);
foreach ($user->posts as $post) {
    echo $post->title;
}
⚠️ **GitHub.com Fallback** ⚠️