Develop professional web applications with Kohana

Kohana 3.0

Beginner's Guide

Develop professional web applications with Kohana

Jason D. Straughan

Beginner's Guide

Copyright © 2011 Packt Publishing

All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews.

Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author, nor Packt Publishing, and its dealers and distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book.

Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.

First published: August 2011

Production Reference: 1180811

Published by Packt Publishing Ltd. Livery Place

35 Livery Street Birmingham B3 2PB, UK

ISBN 978-1-849512-40-4

www.packtpub.com

Credits

Author

Jason D. Straughan

Reviewers

Geert De Deckere

Paul Liversidge

Acquisition Editor Tarun Singh

Development Editor Chris Rodrigues

Technical Editor Ajay Shanker

Indexer

Hemangini Bari

Project Coordinator Michelle Quadros

Proofreader Clyde Jenkins

Graphics

Nilesh Mohite

Production Coordinator Adline Swetha Jesuthas

Cover Work

About the Author

Jason D. Straughan

lives in the beautiful Texas Hill Country, where he builds web

applications, writes, and spends time with his family. He began programming in grade school, developing professionally in the early 1990s, and has spent his career working in project management and software development. His passion for open source technologies and the Web experience has been a driving force in his appreciation for PHP and the Kohana framework.

Jason spends his days as a software engineer at Live Oak 360, a custom application development company focused on complex solutions and unique social platforms. During his time at Live Oak 360 and its sister company, 44Doors, Jason has assisted with the development of two software-as-a-service products, BudURL and BearHug, in addition to several custom application platforms. He also provides consultation and training to a select number of private clients, and is a founding partner in Straughan Photography (SanAntonioWeddingPhotography.com) with his wife and managing partner, Chrystina.

You can follow Jason's blog, and read more about Kohana and web-related topics at

www.JDStraughan.com.

Most of all, I would like to think my wife, Chrystina, and my son, Michael, for all their love and support. This book would never have become a reality had it not been for their patience and understanding during many evenings and weekends of writing.

enhancements, and suggestions that are reflected in the final draft. This group of reviewers had a significant impact on the final text, and I genuinely thank each and every one who contributed. Specifically, I would like to thank Geert De Deckere for his level of dedication to the project, and for being a great resource throughout the revision process.

About the Reviewers

Geert De Deckere

is a web designer and developer living in Belgium. Mostly in the earlier

years of Kohana, he was involved in the development of the framework. Also, he is the creator of http://kohanajobs.com/. When he is not building websites or playing around

with regular expressions, he enjoys cycling. His personal website can be found at http:// geertdedeckere.be/.

Paul Liversidge

is a freelance ICT management consultant by day, and a web developer

by night. As a consultant, his role is to turnaround ailing ICT departments through the innovative use of technology, adopting best practice processes, and addressing the most critical assets—the people. With a technical background in network and server design, project management expertise and business acumen gained from multiple business sectors, he brings a formidable breadth of experience to bear on any ICT issue.

As a web developer, he's excited by all things shiny, such as jQuery, Kohana, and pushing PHP, MySQL, CSS, and HTML forward. A frequent contributor to open source products that struggles to balance the responsibilities of a wife, two kids, and a dog, with a mania for writing code.

Paul is originally from Yorkshire in the UK, but now calls Vancouver, BC, Canada home.

www.PacktPub.com

Support files, eBooks, discount offers and more

You might want to visit www.PacktPub.com for support files and downloads related to your

book.

Did you know that Packt offers eBook versions of every book published, with PDF and ePub files available? You can upgrade to the eBook version at www.PacktPub.com and as a print

book customer, you are entitled to a discount on the eBook copy. Get in touch with us at

service@packtpub.com for more details.

At www.PacktPub.com, you can also read a collection of free technical articles, sign up for a

range of free newsletters and receive exclusive discounts and offers on Packt books and eBooks.

http://PacktLib.PacktPub.com

Do you need instant solutions to your IT questions? PacktLib is Packt's online digital book library. Here, you can access, read and search across Packt's entire library of books.

Why Subscribe?

‹ Fully searchable across every book published by Packt

‹ Copy & paste, print and bookmark content

‹ On demand and accessible via web browser

Free Access for Packt account holders

If you have an account with Packt at www.PacktPub.com, you can use this to access

Table of Contents

Preface 1

Chapter 1: Getting Started

11

System requirements 12

Case Study 12

Downloading and installing from the Web 13

Time for action – Downloading from web 13

Installing Kohana from GitHub 14

Time for action – downloading using Git 14

Advanced installation with Git 17

Taking inventory 18

Preparing the Filesystem 19

Testing the environment 20

Configuring Kohana for Development Environment 22

Time for action – Setting your Timezone 22

Configuring URL settings 23

Time for action – setting base URL 23

Setting up the Application Environment 24

Time for action – Setting Kohana::$environment 24

Enabling modules 25

Time for action – Enabling the User Guide 25

Creating a default config file 26

Server configuration 27

Configuring Apache 27

Configuring nginx 28

Testing your configuration 28

Chapter 2: Using Views and Controllers

33

What are controllers and views? 34

Anatomy of a view 34

Anatomy of a controller 35

Updating our Welcome Controller 37

Time for action – Getting our controller action to use a view file 37

Passing data to the view 38

Using the factory( ) method 39

Time for action – Passing data via the factory method 39

Using view variables 40

Time for action – Passing data as view variables 40

Using the set( ) method 41

Time for action – Passing data using the set() method 41

Using the bind( ) method 42

Time for action – Passing data using the bind( ) method 42

Putting it all together 44

Time for action – Passing data using multiple methods 44

Using the Template Controller 46

Time for action – Extending Kohana's Template Controller 46

Examining the Template controller 48

Setting global view variables 50

Time for action – Setting global view variables 50

Binding global view variables 52

Time for action – Binding global view variables 53

Beyond the Welcome Controller 53

Creating new controllers 54

Time for action – Creating our first controller 54

Time for action – Expanding on our first controller 55

Creating a base controller 58

Time for action – Creating an abstract controller 58

Putting it all together 60

Time for action – Adding stylesheets to template 61

Adding structure to view files 65

Time for action – Adding header and footer view files 65

Summary 68

Chapter 3: Routing and Request Handling

69

Hierarchy is King in Kohana 70

Cascading filesystem 70

Request flow in Kohana 72

Creating a profile page to render messages 76

Time for action – Creating a profile page with messages 77

Calling a new request inside a request 79

Time for action – Creating a request within a request 79

Routing in Kohana 83

Time for action – Making profiles dynamic using ID 84

Creating friendly URLs using custom routes 86

Time for action – Creating a Custom Route 86

Making routes explicit 88

Time for action – Adding regex to a route 88

Allowing additional data in a URI 89

Time for action – Allowing additional segments in a route 89

Using subdirectories with routes 90

Time for action – Using Subdirectories and Routes 91

Summary 93

Chapter 4: Working with Helpers and Classes

95

Autoloading classes 96

The Arr (Array) Class 104

The Arr::get() method 105

The Encrypt (Encryption) Class 112

The Feed Class 115

The Form Class 118

Time for action – Creating a login form using the Form helper class 119

Time for action – Creating a signup form for new users 122

Extending Helpers 127

Transparent Class Extension 127

Time for action – Extending the HTML helper method 127

Creating your own helpers 130

Summary 130

Chapter 5: Installing and Configuring Modules

131

Anatomy of a Module 131

Loading and configuring modules 132

Bundled modules 133

User guide module 134

Image module 135

oAuth module 138

Database and ORM modules 138

Time for action – Configuring your application to use a database 139

Time for action – Creating a database table and using the query builder 141

Pagination module 145

Time for action – Adding pagination to database results 146

Auth module 151

Code Bench module 152

Cache and Unit Test modules 153

Installing modules 153

Installing modules from source files 153

Time for action – Installing a module from an archive 154

Installing modules via Git 156

Time for action – Installing a module using git 156

Creating your own modules 159

Summary 160

Chapter 6: Interacting with the Database

161

Anatomy of a model 161

Creating models 162

Using the Database module 163

Configuring the Database module 163

Creating and running queries 165

Using the Query Builder 169

Select statements 169

Time for action – Refactoring Model_Message to allow dynamic search 179

Insert statements 185

Time for action – Adding the ability to insert messages in case study site 185

Updating statements 192

Time for action – Add ability to edit messages in case study site 193

Delete statements 201

Time for action – Add ability to delete messages from the case study site 202

Other functions and expressions 209

Using the Database Module with sessions 211

Configuring database sessions 211

Time for action – Adding session handling with the database adapter 211

Using Database Sessions 212

Summary 213

Chapter 7: Using the ORM and Auth Modules

215

Using the ORM module 215

Setting up the ORM module 216

Convention over configuration 216

ORM API Overview 217

Time for action – Updating Message Model to use ORM 224

ORM, Forms, and Validation 230

The Validation class 230

Time for action – Adding validation to Message Model 234

ORM and Relational Data 238

Using the Auth module 241

Configuring the Auth module 241

Time for action – Adding users and Auth to case study site 241

Implementing the Auth module 243

Time for action – Adding the Auth functionality to the case study site 244

Securing controllers and actions 258

Time for action – Adding secure actions to the case study site 258

Summary 262

Chapter 8: Troubleshooting and Error Handling

263

Debugging code with Kohana 263

Debugging with the Kohana class 264

Error and exception handling 268

Time for action – Adding error messages to signup form 269

Disabling the error handler 272

Viewing the error logs 273

Handling 404 redirects 273

Time for action – Adding a custom 404 page 274

Time for action – Adding profiling to the case study project 278

Summary 281

Chapter 9: Securing and Deploying Kohana 3

283

Securing our applications 283

XSS attacks 284

Time for action – Securing against XSS risks 285

SQL injection 288

Cookies and sessions 289

Securing cookies 289

Securing sessions 291

Configuring the application environment 292

Preparing for production 294

Removing unnecessary files 295

Directory structure considerations 295

Multiple Application Configuration 297

Updating the Configuration settings 298

Summary 299

Appendix: Upgrading from CodeIgniter and Kohana 2

301

What makes Kohana different from CodeIgniter? 302

Moving from CodeIgniter to Kohana 304

Autoloading classes 304

Strict PHP 5 codebase 304

Included ORM 304

Modules 305

Moving from Kohana 2.x 305

GET and POST methods 306

Directory structure 306

Naming conventions 307

Views 308

Updated ORM 308

Routing and requests 310

Upgrading from Kohana 3.0 to 3.1 312

Request and response classes 312

Security enhancements 313

Bootstrapping and the front controller 313

Validation library 314

Other changes 314

Preface

The Kohana framework for PHP 5 is a robust library for rapidly creating applications. No previous experience with Kohana, CodeIgniter, or MVC frameworks is assumed or needed to understand and use this book, and any previous experience will only assist you as we learn the Kohana framework from the ground up.

Brief history of Kohana

Before Kohana, there was CodeIgniter. Developed by EllisLab, and the driving force behind Expression Engine, CodeIgniter, gained huge popularity in the PHP community, especially among developers seeking MVC solutions for their growing needs.

Eventually, CodeIgniter was forked to bring it up to speed with PHP 5, and Kohana was born. Kohana 2 relied on the open source community for its development, and quickly grew into a production-ready framework, used by developers all over the world.

Kohana 3 is a completely rebuilt framework, utilizing a HMVC design pattern, and leveraging the power of PHP 5 like never before. Although Kohana 2 is still being supported, all new applications written with Kohana are recommended to use the Kohana 3 release to allow for a longer support cycle. Kohana 3 is not backwards compatible with Kohana 2 or CodeIgniter, and migration can be difficult.

If you have experience with Kohana 2, and would like to see the differences in more details, and understand the process of moving from Kohana 2 to Kohana 3, please take at look at the

Appendix: Upgrading from CodeIgniter and Kohana 2. This is also a good resource if you have

Kohana's user guide and API reference

Kohana ships with a complete user guide and API reference. In Chapter 1, we will install the framework with the user guide module, allowing us to browse the guide from within our application. The official guide is available on the Kohana website at http:// kohanaframework.org/guide/about.kohana

The guide contains basic information about Kohana, installation, configuration, and tutorials. Most importantly, it includes the API reference, which allows easily us to explore and view the methods and properties of every class in the library see.

As we build our applications, the guide expands to include our code, documentation, and help files. This can be quite a resource for developing large projects with multiple developers, revisiting old projects for which you need to refresh your memory, and making it generally easier to find your way around.

It is a good idea to familiarize yourself with the documentation online, and spend some time looking over the pages and API Reference.

Structure and patterns

In order for Kohana to work properly, some basic patterns and coding conventions must be followed. You are encouraged to follow the Allman/BSD style that is consistent throughout the framework; however, not following exactly will not break your application.

That being said, not following certain coding conventions will prevent Kohana from autoloading your files, and thereby breaking your application. Because Kohana embraces Convention over Configuration, the naming of your directories, files, and classes determine how (and if) they are automatically loaded into the framework. This is a great feature as we do not have to write a lot of include() or require() statements, and it eliminates the

need for trying to find files before we can use them.

Another advantage of using this convention is we can utilize Kohana's cascading filesystem, which allows us to easily extend and override lower-level classes. Essentially, this means we can put a class in a module, and use it directly. All we need to do to extend it in our application is to drop a file with the same name into our application directory structure, and we can begin extending and overloading the class. We will get into this in more detail in Chapter 3.

To begin working with Kohana, there are a few very important rules you must know, and we will cover the rest of the nuances as we progress through the book. The main thing to know now is: all class names must adhere to the following conventions:

‹ All classes live in the /classes/ directory, usually located in the application

‹ Underscores ( _ ) represent directories, example: Controller_Foo would be

located in classes/controller/foo.

‹ All class filenames and directory names must be lowercase.

To get a more detailed look at the conventions and patterns used in Kohana, please visit:

http://kohanaframework.org/guide/about.conventions. For more information

and examples of Allman/BSD syntax, please visit http://en.wikipedia.org/wiki/ Indent_style#Allman_style_.28bsd_in_Emacs.29

HMVC in a nutshell

Most modern PHP frameworks use, or at least offer, a Model View Controller (MVC) pattern for constructing and organizing your project. The advantages of using Object-Oriented Programming (OOP) were recognized with the release of PHP 5, and the development community quickly began finding ways to create more reusable, lightweight, and expandable code. The MVC pattern fits perfectly for web application development, allowing developers to create code once, and use it across multiple projects.

The MVC design pattern allows presentation, data, and logic layers to all be coded separately and used together. Traditionally, MVCs use a front-controller to handle all requests, route and load a controller, and the render the output from a view.

Hierarchical MVC (HMVC) takes this approach one step further. Much like AJAX allows web browsers to interact with the server without reloading the page, HMVC allows your server-side application to handle multiple requests without having to display a page every time.

Where MVCs allow for one controller to be loaded and executed, the HMVC pattern loads a primary controller, and then allows requests to be created repeating the loop of routing and loading controllers, and allowing for even more requests.

Although this can be confusing at first, it is actually quite powerful. Having full control over routing and requests gives developers a lot of flexibility and power when writing code. We will take a much deeper look at the HMVC structure in Kohana when we explore routing and request handling in Chapter 3.

Models, Views, and Controllers

Finding the right place for our code is important, especially as our application grows. Anyone who has ever worked on a project consisting of more than a few pages quickly realizes that code can become convoluted in no time, and good organization pays off.

‹ CONTROLLERS – These are the driving force behind our applications. Our controllers

are loaded immediately after the request, and will delegate data modeling to our models, and presentation duties to our views. Controllers are where we utilize our models and prepare our data for output.

‹ MODELS – Any external data that needs to be used by our application will live in a

model. More often than not, models are used to interact with a database or other data store. We will store any methods necessary for creating, updating, reading, and deleting data from any data stores with which we interact.

‹ VIEWS – Perhaps the easiest way to think of views is just to imagine HTML. These

are the files where all of our markup will go, with minimal logic. View files should contain the least amount of PHP code of the three types, and should utilize PHP's alternative syntax for control structures when it is necessary to use server-side scripting.

The above definitions are made with broad strokes, and I do not suggest they completely outline where and how to use each. In Chapter 2, we will take an in-depth look at Controllers and Views, and in Chapter 6 we use Models to interact with our database. For now, knowing the basic use for each of the MVC layers will give you an idea of how it all fits together.

Alternative syntax

It is not uncommon for HTML and PHP to be intermixed within the same document. In fact, many of us began web development by making very long files with PHP and HTML so mixed together, it was sometimes hard to tell them apart.

Kohana allows us to keep our business logic in our controllers and models, and our markup in views. Although view files are used for presentation, and mainly consist of HTML code, we will need do have some PHP for dynamic content.

Instead of using curly braces everywhere, making our code confusing to read, we will be using PHP's alternative syntax. You can read more about alternative syntax here: http:// php.net/manual/en/control-structures.alternative-syntax.php

Routing and request overview

As explained earlier, Kohana utilizes the HMVC design pattern, and allows us to create requests essentially anywhere within our applications. The request flow is the order in which files are loaded, starting with index.php and moving throughout the framework, loading

What this book covers

Chapter 1, Getting Started, covers Kohana 3 installation—displaying the default welcome

content and user guide for the framework.

Chapter 2, Using Views and Controllers, will jump into using Kohana's controllers and views,

and make something more robust than a simple "hello, world" script.

Chapter 3, Routing and Request Handling, will talk about the way Kohana routes our

requests, and how to use request handling and routing to make our applications more robust. We will also learn more about Kohana's cascading filesystem, the Heirarchy aspect of HMVC, and how Kohana works at runtime.

Chapter 4, Working with Helpers and Classes, will look at some of the helper and

service-oriented classes provided in Kohana, and take a look at extending their functionality, and creating a few of our own.

Chapter 5, Installing and Configuring Modules, will cover how to extend Kohana's core

functionality by implementing modules. We will be exploring the modules that ship with the framework, learn how to use third-party modules, and how to create modules of our own.

Chapter 6, Interacting with the Database, will take a more detailed look at the Database and

ORM modules, their use, and a more in depth look at some of the official modules that use and rely on these very important modules. Working with databases has never been more fun and easy, and in this chapter, we will expand our case study website to make it work with dynamic data, user authentication, and related data.

Chapter 7, Using the ORM and Auth Modules, will take an in-depth look at two modules that

rely on the Database module to function: the ORM and the Auth modules. By implementing these modules in your projects, you can make working with data even easier and authorizing users a breeze.

Chapter 8, Troubleshooting and Error Handling, will be covering troubleshooting and error

handling, and we will be able to see how to detect and debug errors in our applications while adding the final touches to the case study site.

Chapter 9, Securing and Deploying Kohana, will discuss methods to secure our applications,

and keep our code safe from attacks.

Appendix, Upgrading from CodeIgniter and Kohana 2, will look at migrating from an earlier

Who this book is for

If you are a developer who understands PHP, has some experience with Object-Oriented Programming (OOP), and has a desire to harness the power of a Hierarchical Model-View-Controller (HMVC) framework, then this book is for you.

Conventions

In this book, you will find several headings appearing frequently.

To give clear instructions of how to complete a procedure or task, we use:

Time for action – heading

1.

_{Action 1}

2.

_{Action 2}

3.

_{Action 3}

Instructions often need some extra explanation so that they make sense, so they are followed with:

What just happened?

This heading explains the working of tasks or instructions that you have just completed.

You will also find some other learning aids in the book, including:

Pop quiz – heading

These are short multiple-choice questions intended to help you test your own understanding.

Have a go hero – heading

These set practical challenges and give you ideas for experimenting with what you have learned.

You will also find a number of styles of text that distinguish between different kinds of information. Here are some examples of these styles, and an explanation of their meaning.

A block of code is set as follows:

foreach (ORM::factory('post', 1)->where('active', '=', 1)->author- >find_all() as $author)

{

echo $author->name . '<br />'; }

When we wish to draw your attention to a particular part of a code block, the relevant lines or items are set in bold:

<div class="field">

<?php $body = isset($value) ? $value : ''; ?> <?php echo Form::textarea('content', $body); ?>

</div>

Any command-line input or output is written as follows:

$ git clone https://github.com/kohana/kohana.git -b 3.0/master egotist

New terms and important words are shown in bold. Words that you see on the screen,

in menus or dialog boxes, for example, appear in the text like this: " By clicking the Edit Message link, you can now edit the message:".

Warnings or important notes appear in a box like this.

Tips and tricks appear like this.

Reader feedback

Feedback from our readers is always welcome. Let us know what you think about this book— what you liked or may have disliked. Reader feedback is important for us to develop titles out of which you really get the most.

To send us general feedback, simply send an e-mail to feedback@packtpub.com, and

If there is a book that you need and would like to see us publish, please send us a note in the

SUGGEST A TITLE form on www.packtpub.com, or e-mail suggest@packtpub.com.

If there is a in which that you have expertise, and you are interested in either writing or contributing to a book, see our author guide on www.packtpub.com/authors.

Customer support

Now that you are the proud owner of a Packt book, we have a number of things to help you to get the most from your purchase.

Downloading the example code for this book

You can download the example code files for all Packt books you have purchased from your account at http://www.PacktPub.com. If you purchased this

book elsewhere, you can visit http://www.PacktPub.com/support and

register to have the files e-mailed directly to you.

Errata

Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you find a mistake in one of our books—maybe a mistake in the text or the code— we would be grateful if you would report this to us. By doing so, you can save other readers from frustration and help us improve subsequent versions of this book. If you find any errata, please report them by visiting http://www.packtpub.com/support, selecting

your book, clicking on the erratasubmissionform link, and entering the details of your

errata. Once your errata are verified, your submission will be accepted, and the errata will be uploaded on our website, or added to any list of existing errata, under the Errata section of that title. Any existing errata can be viewed by selecting your title from http://www. packtpub.com/support.

Piracy

Piracy of copyright material on the Internet is an ongoing problem across all media. At Packt, we take the protection of our copyright and licenses very seriously. If you come across any illegal copies of our works, in any form, on the Internet, please provide us with the location address or website name immediately so that we can pursue a remedy.

Please contact us at copyright@packtpub.com with a link to the suspected pirated

material.

Questions

You can contact us at questions@packtpub.com if you are having a problem with any

1

Getting Started

To start using Kohana 3, you must first learn how to install and configure the framework. Here, you will learn how to install Kohana from the website and via the official Git repository, configure Kohana for development, and display the default welcome page.

This chapter includes:

‹ System requirements

‹ Installation from Kohana's website

‹ Installing from Kohana's Git repository

‹ Overview of Kohana's filesystem

‹ Configuring the framework for a development environment

‹ Displaying your welcome page

No previous experience or exposure to Kohana is required to follow the instructions and examples in this book. You will start off by setting up the framework from scratch, examine the necessary steps to configure Kohana, and apply your knowledge by building a real application.

By the end of this chapter, you will have a full Kohana 3 installation displaying the default welcome content and user guide for the framework.

System requirements

The exact system requirements for Kohana are somewhat fluid, with newer versions of the framework requiring newer versions of PHP. The basic requirements are essentially the same: a newer version of PHP5, some common extensions, and a few optional extensions that allow Kohana to do more. My experience has been that most hosting providers, and out-of-the-box development servers (WAMP, MAMP, XAMPP, etc), come pretty well suited for Kohana right out of the box.

At the time of writing, Kohana requires the following:

‹ PHP 5.2.3 or newer ‹ PCRE with UTF-8 Support ‹ PHP SPL Enabled

‹ PHP Reflection Enabled ‹ Filters Extension ‹ Iconv Extension

‹ Native MBString (not overloaded by extension) ‹ Character Type (CTYPE) Extension

The following extensions are not required, however, they are recommended for full functionality. Through the course of this book, you will assume these extensions will be present: cURL, mcrypt, GD, and PDO.

Again, most providers and development packages should work fine. Also, during installation, Kohana will check for all the required and optional extensions and let us know if anything is out of order. For more information, visit the Kohana website at http://kohanaframework.org

Don't worry about getting too caught up with the system requirements. Everything that is required, even optionally, is open source and free, installed on most systems, and there is a lot of support out there. Let's move right along and prepare to get Kohana installed and running on your system.

Case Study

Our sample application will be called "Egotist", and will encourage users to befriend each other and share details about their daily activities. They will be able to post comments, and see comments that are posted by their 'friends'. We will implement basic authorization, session handling, a database for your posts, users, and friendships, and do it all in Kohana.

Downloading and installing from the Web

Kohana's website http://kohanaframework.org/ hosts an archive of the latest releases

in its download section. Here, you will also find user forums, documentation, and other releases of the framework.

The website makes it very easy to obtain and install the most current stable release of Kohana, browse the documentation, and interact with the Kohana community.

Time for action – Downloading from web

Let's take a look at installing Kohana from their website:

1.

_{Open http://kohanaframework.org/ in your web browser.}

2.

_{Navigate to the download page and select the newest 3.0.x version marked Stable.}

3.

_{Clicking the download link will retrieve a file named Kohana-3.X.X.zip (where X could}

be any number, representing the version of the framework).

4.

_{Create a web directory called egotist.}

5.

_{Unzip the downloaded file into your egotist site folder on your development}

environment.

What just happened?

As you can see, you have unarchived Kohana into your webroot directory. Take note of the mark-down (.md) files, especially those labelled DEVELOPERS, TESTING, and README. It is

recommended that you give these files a read. Also, notice the framework comes complete with index.php, a system folder, application folder, and modules folder.

Although installing Kohana via the download archive is a quick and easy way of obtaining the framework, the code repository is hosted and maintained on GitHub (http://github. com), and can be accessed and updated via this resource. If you would like to install Kohana

via GitHub, the next section is for you.

Installing Kohana from GitHub

In a nutshell, Git is a Distributed Version Control System (DVCS) or Source Code Management (SCM) tool written by Linus Torvalds originally designed for the Linux kernel developers. Its popularity, especially amongst open source developers, has grown considerably in recent years, for many reasons. Git provides developers with many features that make working with your code more convenient. Using Git, you can easily create and merge different branches, create forks of existing repositories, and issue pull requests for patches or upgrades made to forked projects. The distributed nature of Git allows every team member to keep the entire repository duplicated in their environment. GitHub is a storage solution for Git repositories, with free hosting for open source projects. Kohana uses GitHub for hosting, and you can get Kohana directly from GitHub.

Installing Kohana via GitHub makes it easier to keep your application up to date with the most recent releases of both the Kohana 3 system files, but also any submodules that you may be using that are also hosted on GitHub. When you want to use one of hundreds of actively developed modules for Kohana, installing them using Git will be painless.

To access repositories on GitHub, you must first have Git installed on your system. For more information on installing and using Git, please visit http://git-scm.com/. Git is free and

open-source, and is available for all popular operating systems. Most providers that offer secure shell access also offer Git.

Time for action – downloading using Git

The Kohana repository can be found at http://github.com/kohana/kohana, where

For your development project, you will simply use the most current stable release in the trunk of the master branch that contains the basic framework with official modules. This is easiest way to keep the current stable version of Kohana for your projects.

1.

_{First, let's create a place to put your application. For the case study in this book,}

you will be creating a social networking application called Egotist. So, in your web directory, let's create a directory named egotist.

2.

_{Now, you can run the following command to retrieve Kohana and place it in your}

egotist directory:

$ git clone https://github.com/kohana/kohana.git -b 3.0/master egotist

Git should retrieve the repository, and make a copy of it into your site directory. Remember to execute the command from within your egotist or site root

3.

_{After the clone has completed, you can list the contents of your site root directory.}

It should contain all the Kohana files with a few files associated with Git and all the submodules in place for your system and modules directories.

Included in the repo are some submodules, the 'official' modules sanctioned by the Kohana 3 development team to be included in the basic installation of the framework. The master Kohana repository keeps these submodule locations up to date. Right now these submodules have not downloaded any files to your system.

1.

_{Download each of these repositories directly into your project, you will want to}

update these submodules by running the following:

2.

_{Now that you have let Git know about the submodules you want to install, you need}

to do an initial update to clone all the submodules into your install.

$ gitsubmodule update

The update may take a little while. Git will go through each submodule and download its newest stable release.

What just happened?

The Git clone available at https://github.com/kohana/kohana.git tells Git to clone,

or to make an exact copy of, the repository located at https://github.com/kohana/ kohana.git, the second argument, –b 3.0/master tells GitHub which branch you want

to clone, and the final argument tells Git where to place the cloned repository, in this case the egotist directory.

In the future, updating the codebase will be as simple as returning to the site root and running:

$ git pull

$ gitsubmodule update

The first command will pull, or download, the newest content from GitHub in the master branch. The second command updates, or downloads, all the submodules you have installed for your project.

Currently, you are only updating submodules that are included with the Kohana install. Later, in Chapter 5, you will be adding modules to your project, and some of these will be installed using Git. Once installed, they can be updated in a similar fashion.

Advanced installation with Git

By cloning the kohana.git repository, you got a copy of the entire repository that is meant

to build the compressed files for download, and it is not really designed to be cloned into projects for use. The method described above is used by many beginners, but has some drawbacks. First, the repo is now pointed to Kohana/Kohana.git, not the repository you

Creating your project's directory structure and using existing repositories on GitHub as submodules will make your application more flexible, and easier to maintain. Although there are a few more steps involved here, the savings in the long run are enormous.

If you are running a UNIX-compatible operating system, like Linux or Mac OS X, you can use an install a script written by Kohana's Benevolent Dictator for Life, Woody Gilk, aka shadowhand, which handles this process quite elegantly. The script, and instructions for use, can be found here: https://github.com/shadowhand/kohana-installer.

If you prefer to set up your application environment by hand, you can create your directory structure, add the Kohana core repository (https://github.com/kohana/core) to

your system directory, add all the modules you need to your modules path, create your

application structure, bootstrap, and front controller. This provides you with the most flexibility and is the preferred method for most professional developers. For a full tutorial on installing Kohana in this manner, please visit: http://kohanaframework.org/3.0/ guide/kohana/tutorials/git

Although you can use Git to manage the code for your project, we will leave Git behind here, and move forward with your Kohana project. For more information on Git, please visit http://git-scm.com.

Now, your development directory has the Kohana 3 framework with the official submodules in place, ready for configuration. Before you dive into installation, let's make sure your environment is properly set up to handle Kohana 3.

Taking inventory

A quick look at the files you have downloaded reveals some files you are familiar with, and others that you may not be. You can see there is the standard index.php file, some

mark-down files, a readme file, and 3 sub-directories: application, modules, and system. One of the nice things about Kohana is that it comes with the file structure and core files necessary to get your project up and running very quickly.

We will explore Kohana's routing a bit more later on, but it is important to know that

index.php will be the first file loaded by the framework. The index file will create the

The application directory is where the majority of your code will live. This is where you will create your application's controllers, models, config files, and views. You will also keep your logs and various other items here, well-organized, and easy to access and update. Unlike previous versions of Kohana and CodeIgniter, all of the classes for your app (Controllers, Helpers, Models, etc) will live in the application/classes directory, in their respective

sub-directories (application/classes/model, application/classes/controller,

etc). You may remember that helper classes in previous versions of the framework had their own designated place to live, and now simply reside in application/classes, and are

not designated has 'helpers'.

The system folder houses the core files for Kohana, and although you are free to override any file in the library, you are discouraged from changing the contents of any files in the system directory. If you need to make changes to the Kohana system, you can do so by extending and overriding classes in the framework. We will cover this in more detail when you explore routing and requests in Chapter 3.

Any modules you install or create will be stored in the modules folder. Kohana comes with some modules bundled with the distribution, like the user-guide, database, oAuth, and others. There are hundreds of modules available from other developers online, and we will learn how to create your own modules in Chapter 5. Although these modules ship with the framework, they are not enabled by default. We will cover how these modules are activated and used later in the book.

Preparing the Filesystem

In order for Kohana to work properly, it must have the ability to write cache and log files to the filesystem. By default, the framework uses application/cache for caching, and application/logs for its log files. You can change these locations in the index.php or

application/bootstrap.php files, however, the default location is just fine for your needs.

To make these directories writeable, you will need to change their permissions. Using a Linux system, you can accomplish this using the chmod command. On a Windows system, you

need to make sure the folder is writeable by your web server.

Make sure you are in your site directory, in your

case /egotist/.

While changing the permissions for your cache and logs on your development environment to full access to all users, on your production servers you will want to enforce a bit of security, and your web server should be the owner or a member of the group with write access to this directory. For development purposes, it is usually okay to leave these directories writable for all users.

Next, you might want to create a public folder where you will place your front-facing files. Our application will have CSS and images, and may grow to have publicly accessible media. Let's create a directory named public where you can organize these files as you are

building your application.

$ mkdir public

Inside this public folder you can create three directories to house your JavaScript, CSS files, and images:

$ cd public $ mkdirjs $ mkdircss $ mkdir images

Now, you have a place to organize your supporting files for your project, and once you begin development, adding stylesheets, images, and JavaScript files will be a breeze.

It is worth noting that when you prepare your app for production, you will move your framework outside of the web root folder for your site, and only expose the files necessary to run your application. Alternate directory structures not only allow you to minimize the available public directories and files, it can also allow you to share the framework and modules across several projects and applications. Many developers set up their development, staging, and production environments all using a shared directory structure. For more information on site structure and filesystem concerns in a production environment, please see Chapter 9.

Testing the environment

Kohana ships with a nice install script that will let you know if your web server and PHP installation are properly configured to handle the framework. Most hosting providers that I have used have no problems meeting the system requirements for Kohana 3, and local development environments typically work out of the box.

To test the installation on your system we will browse to your local installation, located at http://localhost/egotist (your URL may vary depending on your web server

A successful installation will result in the following page being displayed:

Configuring Kohana for Development Environment

Kohana needs some setup before you can begin using it. The front controller, bootstrap, and basic config files all need to be set up. You need a place to put your configuration options, and a place to put your public files like stylesheets and JavaScript. We will want to enable modules, set your default timezone, application environment, and prepare your project for use.

This may sound a bit daunting, but thankfully, Kohana has done most of the heavy lifting for you. You just need to change a few files.

First, let's remove the install.php file in your site root directory. Now that you

have tested your system environment, you will not be needing this file any longer. If you plan on re-testing in the future, or testing on other systems, you can simply rename it

install_old.php for future use.

Now that the install.php is out of our way, Kohana's front controller index.php

will continue to load the bootstrap, located in the application directory, and named bootstrap.php.

Time for action – Setting your Timezone

We need to tell Kohana a little bit about your system and the desired setup. Let's do this by making a few changes to your bootstrap.php file in the /application directory.

Let's begin by opening the application/bootstrap.php file.

The first setting in the bootstrap.php file contains your timezone information:

date_default_timezone_set('America/Chicago');

You can set your default timezone to any identifier recognized by PHP's Date/Time library. For a complete list of supported timezones, please visit: http://www.php.net/manual/ en/timezones.php.

Next, you are able to set your default locale:

setlocale(LC_ALL, 'en_US.utf-8');

What just happened?

For most installations, the locale settings will be fine. Both the default timezone and locale can be reset later in your code if you need to do internationalization or have users set their local timezones for example.

Although having the right time is nice, it is much more important to have working URLs. Without them, your users will never get to view or use your application. Next, you will let Kohana know about your URL scheme.

After these settings, you will see some setting for autoloading, SPL, and application environment. For your development setup, you will leave these at their default values. We will delve into the production ready setup in Chapter 9.

Configuring URL settings

Below the environment setting block, you see the Kohana::init() method call, initializing

Kohana and allowing us to pass an array of default options to the framework in the form of name/value pairs. For now, you are only concerned with your base_url and index_file

settings.

We will use the URL http://localhost/egotist/ for your base URL. You will want to

use the URL that points to your Kohana installation. For local installations, it is common to use the http://localhost/ domain; if you are developing on a live server, you might

want to use that URL. Either way, it is recommended to use the full path to your site here, as it will be used later for accessing files, creating links, and all sorts of goodness.

Time for action – setting base URL

1.

_{In your bootstrap.php file, find the following block of code:}

Kohana::init(array( 'base_url' => '/› ));

2.

_{Now update the array being passed to Kohana::init() with the following values,}

using your base URL for the base_url value:

Kohana::init(array(

'base_url' => '/egotist/›, ‹index_file› => ‹›

What just happened?

Here you set the base URL for your application, and have the opportunity to define your index file that will act as your front controller. For the case study site, we will hide the index file, so this can be left blank.

Hiding the index file is an optional step, however, all the example URLs for your local site will reflect this change, and will not include the index.php file in your URLs. This is a very

common practice that creates clean, readable URLs for your applications. You will need to configure your web server to reroute all requests to your index.php file, so it will not be

necessary for users to include it in the URL. If you do not set it to blank here, Kohana will include it when it creates URLs for us when you use the built in helper methods.

Setting up the Application Environment

When developing your application, you may need some features to be accessible only in your development environment, and others only when in production. This may include profiling, additional information, features not ready for prime time, error stacks, and other code that is only meant for certain environments. You could even have configuration options based on environment settings.

Time for action – Setting Kohana::$environment

1.

_{For the time being, let's define your KOHANA_ENV constant right after the}

"Configuration and Initialization" comment in your bootstrap.php file by

adding this line:

Kohana::$environment = Kohana::DEVELOPMENT;

2.

_{The next block of code in the bootstrap.php reads as follows:}

if (isset($_SERVER['KOHANA_ENV'])) {

Kohana::$environment = $_SERVER[‹KOHANA_ENV›]; }

What just happened?

With your constant defined, the static property Kohana::$environment will be set

For your case study, you will be using two environment settings: Kohana::DEVELOPMENT

and Kohana::PRODUCTION. When you prepare your application for deployment on your

production server, you will want to change the value of KOHANA_ENV to production.

Enabling modules

Lastly you will want to look at the Kohana::modules method, and the array of options

that are commented out. As you build your application, you will be utilizing several of these modules, adding other modules, and creating your own.

Time for action – Enabling the User Guide

Let's remove the comments for the 'userguide' module so your code block looks like this:

Kohana::modules(array(

// 'auth' => MODPATH.'auth', // Basic authentication

// 'cache' =>MODPATH.'cache', // Caching with multiple backends

// 'codebench' => MODPATH.'codebench', // Benchmarking tool // 'database' =>MODPATH.'database', // Database access // 'image' =>MODPATH.'image', // Image manipulation // 'orm' => MODPATH.'orm', // Object Relationship Mapping

// 'oauth' => MODPATH.'oauth', // OAuth authentication

// 'pagination' =>MODPATH.'pagination', // Paging of results // 'unittest' => MODPATH.'unittest', // Unit testing 'userguide' => MODPATH.'userguide', // User guide and API documentation

));

What just happened?

The Kohana::modules() method accepts an array of key/value pairs representing a

module and its path. The default modules that ship with Kohana are listed for us, and commented out to prevent them from loading without being activated and configured.

When you create or add modules to your project, you will want to add them here. To use any of the modules that ship with Kohana you simply uncomment the line. You should know that most modules require some configuration. We will be getting into modules for Kohana more in Chapter 5.

Save your bootstrap.php file and see what it takes to get a basic configuration file in place

Creating a default config file

As you create parts of your application, you are going to want to access config files. When you set up your database, use sessions or cookies, install or create modules, or have information that may change, you will want to organize these options in one place.

In your application directory, there is a sub-directory placed there for us called config. In this folder, you can create configuration files, and access them via a static method. For now, you will load some basic data into a config file for Egotist.

In application/config, create a file called site.php and insert the following code:

<?php defined('SYSPATH') or die('No direct script access.'); return array(

'name' => 'Egotist',

'tag_line' => "Let's talk about me!" );

Now, whenever you want to access your site name and tag line, you can do so using the following code:

$site_config = Kohana::config('site');

This will find your file named site.php in the application/config folder, and load

the array into $site_config. You could then access your config options like so:

$site_name = $site_config['name']; $tag_line = $site_config['tag_line'];

We do not need to load the entire array if you only need a single config option. If, for example, you needed the app_name variable only, you could get it using this:

$site_name = Kohana::config('site.name');

Kohana will return the value of the array for any keys using the above dot syntax. This allows us to retrieve the value without having to get the entire array. Kohana also allows us to nest arrays within your config files. You can change your application/config/site.php file

to read as follows:

return array(

'name' => 'Egotist', 'details' => array(

'tag_line' => "Let's talk about me!", 'alt_tag_line' => "Today's subject: ME!"; );

We can still access the array directly:

// Load site config array

$site_config = Kohana::config('site'); // Echo site name and details

echo $site_config['name']; // Egotist

echo $site_config['details']['tag_line'] // Lets talk about me! echo $site_config['details']['alt_tag_line'] // Today's subject: ME!

Alternatively, you can access nested options using the dot syntax method described above:

echo Kohana::config('site.name'); // Egotist

echo Kohana::config('site.details.tag_line'); // Lets talk about me! echo Kohana::config('site.details.alt_tag_line') // Today's subject: ME!

As you build your application, your config folder will contain files for your database,

sessions, modules, and other files and components. This will allow us to keep your code DRY (an acronym for Don't Repeat Yourself) and easy to maintain.

Let's save your site.php config file and take a look at configuring your web server to

properly handle URL rewriting for your project.

Server configuration

For Kohana to function properly, it needs to rewrite all incoming URLs to route through your

index.php file. Kohana ships with a file named example.htaccess, which provides a very

good outline for what is needed to accomplish this task on an Apache web server.

Configuring Apache

Let's begin by opening and examining example.htaccess:

# Turn on URL rewriting RewriteEngine On

# Installation directory RewriteBase /site_name/

# Protect hidden files from being viewed <Files .*>

Order Deny,Allow Deny From All </Files>

# Protect application and system files from being viewed

RewriteRule ^(?:application|modules|system)\b.* index.php/$0 [L] # Allow any files or directories that exist to be displayed directly RewriteCond %{REQUEST_FILENAME} !-f

RewriteCond %{REQUEST_FILENAME} !-d

You will want to alter the RewriteBase to contain the location that you put in bootstrap. php for base_url. For your example site, it would read:

RewriteBase /egotist/

This lets Apache know where to find your site, and to rewrite all requests to /egotist/ index.php/and allow Kohana to do its magic.

You will need to save the file as .htaccess, or save and rename it without the example

prepended. Most web hosting providers allow .htaccess files in their web root folder to

make alterations to Apache's default configuration.

Configuring nginx

Of course, you are not required to use Apache as your web server. There are other web servers that are gaining popularity, one of the most notable being nginx. The official Kohana documentation shows this configuration for nginx:

location /egotist/ {

index index.php index.html index.htm; try_files $uriindex.php;

}

location = index.php {

include fastcgi.conf; fastcgi_pass 127.0.0.1:9000; fastcgi_indexindex.php; }

For more information on configuring Kohana for clean URLs with Apache or nginx, please visit: http://kohanaframework.org/3.0/guide/kohana/tutorials/clean-urls.

Testing your configuration

Kohana has a very simple default welcome page, showing us the ever popular "hello, world!" text. Later, we will be replacing this with a more robust page, but for now, this is much better than an error page.

Although this lets us know you are viewing your basic welcome controller properly, you will also want to make sure the URL rewriting is working properly, and your userguide module

has loaded. To do this, you can browse to http://localhost/egotist/guide, where

Looks like you are all set! This is a local copy of the Official Kohana User Guide, and it is included with every installation. You know your setup is working correctly by viewing this page for three reasons:

‹ Our modules are configured correctly, or you cannot see the User Guide

‹ Our .htaccess are set up right, or you would need index.php in the URL ‹ bootstrap.php is also properly configured

If you are unable to view the User Guide from your local installation, be sure to check the settings in your .htaccess and bootstrap.php files.

The API Browser will show all the classes used by Kohana, including classes you create or modify. By exploring different classes, you will find the ability to drill down into methods and properties, making it easy to learn more about Kohana's functionality.

While you build your application, you will be paying close attention to proper documentation techniques, and will be expanding the API Browser as you code, simplifying the

documentation process, and making your lives much easier when you need to go back and see how something works.

In Chapter 8, we will delve further into using and expanding the User Guide. For now, it is important to know it is here, and take the time to explore and familiarize yourself with its content and layout.

Pop quiz – Installation and Configuration

Throughout the course of the book, you will be testing your knowledge while reviewing what you have recently learned. You are encouraged to test yourself when these sections appear to ensure you have a good understanding of the topics you are covering.

1. For the framework to run properly, it must have write access for logging and caching. Which directories must be modified to allow for these actions?

‰ application/system and application/logs/ ‰ application/cache/ and application/logs/

‰ kohana/cache/ and kohana/logs/

2. When you configure Kohana for your server environment, you must set the base_ url and index_file. Which method is used to set these options?

‰ Kohana::$environment ‰ Kohana::init()

‰ Kohana::config()

‰ Kohana::base_url()

3. Config options can be accessed as either a complete array of all options for a particular configuration file, or directly using dot notation. Which of the following examples would return the background color from a config file named test.php?

‰ Kohana::config('background-color', 'test') ‰ $backgroundColor = Kohana::config('test') ‰ Kohana::config('test.background-color')

‰ Kohana::config['test']['background-color']

Summary

So far you have accomplished a lot. You reviewed the system requirements necessary for your environment. Then you learned how to install Kohana from both the official website and GitHub repositories. Next, you prepared the filesystem and tested your installation using the Kohana Environment Test run via install.php. After passing your install test,

you configured your application for development—preparing yourselves to build on a stable foundation. Our Egotist application has its environment variable set, you have created places for your config files, stylesheets, JavaScript, and images. Lastly, you were greeted with the sign of a working Kohana installation, "hello, world".

We also discussed using the install test script, preparing for production, and how to keep your Kohana installation up to date using Git. Now that we've learned how to install and configure Kohana for development, let's go develop something!

2

Using Views and Controllers

One of the best features of the MVC pattern is the clear separation of logic and presentation. Kohana's structure makes it even easier by providing the basic file structure and files needed to quickly get our app going.

In the last chapter, we configured Kohana and displayed the default controller. In this chapter, we will:

‹ Learn the anatomy of a view file

‹ Learn the anatomy of a controller

‹ Create and extend controllers

‹ Create and use controller actions

‹ Create view files

‹ Implement templates

‹ Create an application controller

By the end of this chapter, we will have created controllers and views, utilized Kohana's template system, leveraged some of the power of the HMVC pattern, and used it all together to bring our first bit of interactivity to the case study site.

What are controllers and views?

Simply put, controllers handle the request and pass data between models and views, while views display the output for the user. Controllers are classes that contain specialmethods named action methods or controller actions that can be called via a request. The action methods can then send data to models, compute data, render views, call requests, or all of the above. Most of the controllers we will create will be defining actions that render views as web pages.

Controllers in Kohana are organized in the classes sub-directory of either an application, directory, or a module. For this chapter, we will be working in the application directory of our site root, and we will work with modules later in Chapter 5.

In a typical web-based application, views will contain primarily HTML, either hard-coded or as generated output. The controller can pass data to the views, and can render multiple views on to one page. Views can therefore be nested, used as templates, or called as needed for different actions.

Anatomy of a view

A view can be any markup that we plan on presenting to the user in our applications. As web developers, we use views to create the final HTML that is displayed to our users. As we create applications, we will be creating many view files: some for our headers, footers, navigation menus, and so on. When we put them all together, then pass some data to them to make them data-driven, the final product will be a fully rendered web page.

View files will contain a mixture of HTML and PHP using alternative syntax. It is considered a best practice to only use scripting in the views to render output, and not to perform business logic: that is what models do. By following the practice of building skinny controllers and fat models, our views will only have to display the rendered material.

In Kohana, by default, view files are stored in the application/views/ directory when

used in the application, and in modules/<module name>/views/ when used in a module.

For now, let's just focus on the application/views/ directory.