Learning Phalcon PHP

The request component is probably one of the most used components in any framework. It handles any HTTP request (such as GET, POST, or DELETE, among others) and also provides a few shortcuts for the $_SERVER variable. Most of the time, we will use the request component in the controllers. The Phalcon documentation (http://docs.phalconphp.com/en/latest/reference/mvc.html) states the following:

In Phalcon, all controllers should extend the \Phalcon\Mvc\Controller component, and the name of the public methods that we want to access via HTTP GET should have the suffix Action. For example:

<?php

class ArticleController extends \Phalcon\Mvc\Controller
{
  // Method for rendering the form to create an article
  public function createAction()
  {
  }

  // Method for searching articles
  public function searchAction()
  {
  }

  // This method will not be accessible via http GET
  public function search()
  {
  }
}

Okay. So, how do we use the request component? Easy! Do you remember that we talked about built-in components in the DI section? The request component is one of them. All we need to do is get the DI. Here is an example of how to get and use the request component:

<?php

class ArticleController extends \Phalcon\Mvc\Controller
{
  public function searchAction()
  {
    $request = $this->getDI()->get('request');
    // You can also use $request = $this->request; but I don't
    // recommend it because $this->request can be easily overwritten
    // by mistake and you will spend time to debug ... nothing.

    $request->getMethod(); // Check the request method
    $request->isAjax(); // Checks if the request is an ajax request
    $request->get(); // Gets everything, from the request (GET, POST, DELETE, PUT)
    $request->getPost(); // Gets all the data submitted via POST method
    $request->getClientAddress(); // Return the client IP
  }
}

These are just a few common methods that are built into the request component. Let's continue with the next important component—Response.

So, what can this component do? Well, pretty much everything that is response or output related. Using it, we can set headers, do redirects, send cookies, set content, and much more. Here is a list of common methods from this component:

<?php

public function testRedirectAction()
{
  $response = $this->getDI()->get('response');
   // or you can use $this->response directly
  
  // Redirect the user to another url
  $this->view->disable();
  return $response->redirect('http://www.google.com/', true);
}

The redirect method accepts three parameters: a location (string), if it is an external redirect (this is a Boolean type which is by default false), and a status code (http status code range). The following lines of code is the redirect method:

  <?php

  /**
  * Redirect by HTTP to another action or URL
  *
  * @param string $location
  * @param boolean $externalRedirect
  * @param int $statusCode
  * @return \Phalcon\Http\ResponseInterface
  */
  public function redirect($location, $externalRedirect, $statusCode);

Another useful method is the setHeader method:

<?php

public function testSetHeaderAction()
{
  $this->response->setHeader('APIKEY', 'AWQ23XX258561');
}

The preceding example sets a header named APIKEY with the value as AWQ23XX258561. Sending headers is a common approach when you develop APIs. You can send any type of headers and overwrite current headers using this method.

Content related methods: setContent() and setJsonContent(). Let's take for example the following code:

<?php

public function testContentAction()
{
  // First, we disable the view if there is any
  $this->view->disable();
  
  // Set a plain/text or html content
  $this->response->setContent('I love PhalconPHP');

  // OR

  // Set a json content (this will return a json object)
  $this->response->setJsonContent(array(
    'framework' => 'PhalconPHP'
    'versions' => array(
      '1.3.2',
      '1.3.3',
      '2.0.0'
    )
  ));

  // We send the output to the client
  return $this->response->send();
}

When you need to send any JSON content, you should set the header as application/json using the built-in method in the response object:

<?php

$this->response->setContentType('application/json', 'UTF-8');

Now that we know the basics about response/request components, we might find ourselves in a situation where we may need to log different things, such as errors. For this, we need to check the logger component.

In a production environment, we cannot afford to throw errors or blank pages at the client. We will avoid this and log the errors in a log file. You will read more about this in the next chapters. To sum it up, we will implement a custom logger to our DI, catch exceptions, and then log them. For example, perform the following set of steps:

In the preceding example, we try to execute a nonexistent method, and our code will throw an exception that we catch. It will log it and then redirect the user to a friendly error page, error/500.html. You will notice that our logger component calls a method named error. There are other methods that are implemented, such as, debug, info, notice, warning, and so on.

The logger component can be transactional. (Phalcon stores the logs temporarily in memory, and later on, it writes the data to the relevant adapter.) For example, consider the following code snippet:

<?php

$this->logger->begin();

$this->logger->error('Ooops ! Error !');
$this->logger->warning('A warning message');

$this->logger->commit();

Crypt is a very useful component if someone needs to encrypt data and decrypt it on your side. One situation where you might want to use the crypt component is to send data over the HTTP get method or save sensitive information in your database.

This component has many built-in methods such as encrypt, decrypt, getAvailableChipers, setKey, getKey, and so on. Here is an example of using the crypt component in the HTTP get method.

First, we overwrite the DI, and then we pass a key to it in order to avoid setting it every time:

<?php

$di['crypt'] = function () {
  $crypt = new \Phalcon\Crypt();
  $crypt->setKey('0urSup3rS3cr3tK3y!?');

  return $crypt;  
};

public function sendActivationAction()
{
  $activation_code = $this->crypt->encryptBase64('1234');
  $this->view->setVar('activation_code', $activation_code);
}

public function getActivationAction($code)
{
  if ('1234' == $this->crypt->decryptBase64($code)) {
    $this->flash->success('The code is valid ');
  } else {
    $this->flash->error('The code is invalid');
  }
}

Of course, you are probably never going to use it this way. The preceding example just demonstrates the power of this component. You might have noticed that there is a new DI method called flash. We are going to talk about it next.

This component is used to send notifications to the client and inform him or her about the status of the component's actions. For example, we can send a successful message after a user has completed the registration on our website or submitted a contact form.

There are two kinds of flash messages—direct and session—and both are available in DI. The direct method outputs the message directly and cannot be loaded on a future request. On the contrary, the session method, stores the messages in a session, and they are automatically cleared after they are printed.

Here is a common usage of flash direct and flash session, assuming that you have a page called register, and you post the data on the same page:

public function registerAction()
{
  // … code
  if ($errors) {  
    $this->flash->warning('Please fix the following errors: ');
    foreach($errors as $error) {
      $this->flash->error($error);
    }
  } else {
    $this->flash->success('You have successfully registered on our website');
  }
}  

In our view, we will render the messages using the getContent() method or content() in the template engine Volt (we'll cover this later in the chapter).

If we need to redirect our user to another page (let's call it registerSuccess), then we need to use the flash session method; otherwise, the message will not appear.

<?php

public function registerAction()
{
  // render our template
}

The register template will contain a form with method post and action pointing to the create method. The create method will look something like this:

<?php

public function createAction()
{
  if ($errors) {  
    $this->flashSession->warning('Please fix the following errors: ');
    foreach($errors as $error) {
      $this->flashSession->error($error);
    }
  } else {
    $this->flashSession->success('You have successfully registered on our website');
  }

  return $this->response->redirect('/register');
}

In the preceding example, we set the messages in the session using the flashSession method, and we redirect the user back to the register page. In order to render the messages in our view, we need to call the method flashSession()->output();.

The router component helps us to map friendly URLs to our controllers and actions.

By default, if the rewrite module is enabled in your web server, you will be able to access a controller named Post and the read action like this: http://www.learning-phalcon.localhost/post/read. Our code can look like this:

<?php

class PostController extends \Phalcon\Mvc\Controller
{
  public function readAction()
  {
    // get the post
  }
}

However, sometimes, this code is not apt if you need to translate the URLs into multiple languages, or if you need to name the URLs in a different way to how they are defined in the code. Here is a usage example for the router component:

<?php

$router = new \Phalcon\Mvc\Router();
// Clear the default routes
$router->clear();

$st_categories = array(
  'entertainment',
  'travel',
  'video'
);

$s_categories = implode('|', $st_categories);

$router->add('#^/('.$s_categories.')[/]{0,1}$#', array(
    'module' => 'frontend',
    'controller' => 'post',
    'action' => 'findByCategorySlug',
    'slug' => 0
));

In the preceding example, we map all the categories to the controller post and action findByCategorySlug. The router component allows us to use regular expressions for our URLs. With preg_match, this can be represented as follows

$url = 'http://www.learning-phalcon.localhost/video';
preg_match('#^/(entertainment|travel|video)[/]{0,1}$#', $url);

By accessing http://www.learning-phalcon.localhost/video, the request will be forwarded to the findByCategorySlug action from the post controller:

<?php

class PostController extends \Phalcon\Mvc\Controller
{
  public function findByCategorySlug()
  {
    $slug = $this->dispatcher->getParam('slug', array('string', 'striptags'), null);

    // We access our model (entity) to get all the posts from this category
    $posts = Posts::findByCategorySlug($slug);

    if ($posts->count() > 0) {
      $this->view->setVar('posts', $posts);
    } else {
      throw new \Exception('There are no posts', 404);
    }
  }
}

The getParam() method has three parameters. The first one is the name that we are searching for, the second parameter is an array of filters that can be applied automatically, and the third parameter is the default value in case the requested name does not exist or is not set.

We will discuss models in the next chapter. This was just a simple example of how you can use the router.

The router also supports a precheck of the request method. You may be used to check whether the method is POST, DELETE, PUT, or GET, like this:

<?php

if ($_SERVER['REQUEST_METHOD'] == 'post') {
  // process the information
}

While this is perfectly correct, it is not very friendly for our code. Phalcon's router has this capability by which you can add the right type of request that you are expecting, without the need to check this in your code:

<?php

// Add a get route for register method within the user controller
$router->addGet('register', 'User::register');

// Add a post route for create method, from the user controller
$router->addPost('create', 'User::create');

This is the basic usage of the router. As always, please read the documentation in order to learn everything about this component.

This component can handle configuration files of various formats by using adapters. Phalcon has two built-in adapters for it, which are INI and Array. Using INI files is probably never a good idea. Therefore, I recommend you to make use of native arrays.

What kind of data can or needs to be stored in these files? Well, pretty much everything that will be needed globally in our application, such as database connection parameters. In the old days, we used $_GLOBALS (a big security issue), or we used the define() method, and then gradually we started using it globally.

Here is an example of a config file, and how we can use it:

<?php

$st_settings = array(
  'database' => array(
    'adapter'  => 'Mysql',
    'host'     => 'localhost',
    'username' => 'john',
    'password' => 'johndoe',
    'dbname'     => 'test_database',
  ),
  'app' => array(
    'name' => 'Learning Phalcon'
  )
);

$config = new \Phalcon\Config($st_settings);

// Get our application name:
echo $config->app->name; // Will output Learning Phalcon

The config object can be converted back to an array by using toArray() method:

<?php

$st_config = $config->toArray();
echo $config['app']['name']; // Will output Learning Phalcon

Another useful method for this object is the merge method. If we have multiple configuration files, we can easily merge them into one object:

<?php

$config = array(
  'database' => array(
    'adapter'  => 'Mysql',
    'host'     => 'localhost',
    'dbname'     => 'test_database',
  ),
  'app' => array(
    'name' => 'Learning Phalcon'
  )
);

$config2 = array(
  'database' => array(
    'username' => 'john',
    'password' => 'johndoe',
  )

Now, the $config object will have the same content as it did before.

This component is used to render our templates. By default, the templates have the .phtml extension, and they contain HTML and PHP code. Here are some examples on how to use the view:

Simple, isn't it? This component also supports hierarchical rendering. You can have a base layout, a general template for posts, and a template for a single post. Let's take, for example, the following directory structure:

app/views/
- index.phtml
- post/detail.phtml

Phalcon will first render app/views/index.phtml. Then, when we request for detailAction() from the post controller, it will render app/views/post/details.phtml. The main layout can contain something similar to this code:

<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Learning Phalcon</title>
</head>
<body>
<?php echo $this->getContent(); ?>
</body>
</html>

And, the details.phtml template will have the following content:

<?php foreach($posts as $post) { ?>
  <p><?php echo $post->getPostTitle(); ?></p>
  <p><?php echo $post->getPostContent(); ?></p>
<?php } ?>

This component also allows you to pick different templates to set a render level, disable or enable the view, and much more.

Phalcon has a built-in template engine named Volt. If you are familiar with PHP template engines such as Smarty or Twig, you will want to use them for sure. Volt is almost identical to Twig, and you will find it very useful—it is inspired by Jinja (http://jinja.pocoo.org/). You can even use your own template engine, or any other template engine that you can find there.

In order to enable the Volt template engine, we need to make a small modification to our view service, and we need to create a Volt service; here is how to do this:

<?php

$di['voltService'] = function($view, $di) use ($config) {

    $volt = new \Phalcon\Mvc\View\Engine\Volt($view, $di);

    if (!is_dir($config->view->cache->dir)) {
        mkdir($config->view->cache->dir);
    }

    $volt->setOptions(array(
        "compiledPath" => $config->view->cache->dir,
        "compiledExtension" => ".compiled",
        "compileAlways" => false
    ));

    $compiler = $volt->getCompiler();

    return $volt;
};

// First, we setup the view in the DI
$di['view'] = function () use ($config) {
  $view = \Phacon\Mvc\View();
  $view->setViewsDir($config->view->dir);
  $view->registerEngines(array(
    '.volt' => 'voltService'
  ));

  return $view;
};

By adding this modification and voltService, we can now use this template engine. From the inheritance point of view, Volt acts a little bit differently. We first need to define a main layout with named blocks. Then, the rest of the templates should extend the main layout, and we need to put our content in the same blocks as the main layout. Before we look at some examples, I will tell you a little bit about Volt's syntax, the details are as follows.

The list is long. Additionally, you can use expressions, comparison operators, logic operators, filters, and so on. Let's write a simple template to see how it works:

<!-- app/views/index.volt -->
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>{% block pageTitle %}Learning Phalcon{% endblock%}</title>
</head>
<body>
  <div class='header'>{% block header %}Main layout header{% endblock%}</div>
  <div class='content'>{% block content %}This is the main layout content{% endblock %}</div>
</body>
</html>
 
<!-- app/views/post/detail.volt 
{% extends 'index.volt' %}

{% block pageTitle  %}
  {{ post.getPostTitle() }}
{% endblock %}

{% block header %}
  Post layout
{% endblock %}

{% block content %}
  <p>{{ post.getPostContent() }}</p>
{% endblock%}

This component provides object-oriented wrappers to access session data. To start the session, we need to add the service into the DI container:

<?php

$di['session'] = function () {
  $session = new Phalcon\Session\Adapter\Files();
  $session->start();
  return $session;  
};

The following is a code example for working with session:

<?php

public function testSessionAction()
{
  // Set a session variable
  $this->session->set('username', 'john');

  // Check if a session variable is defined
  if ($this->session->has('username')) {
    $this->view->setVar('username', $this->session->get('username'));
  }

  // Remove a session variable
  $this->session->remove('username');
  
  // Destroy the session
  $this->session->destroy();
}

If you check Phalcon's incubator, there are many available adapters, such as Redis, Database, Memcache, and Mongo. You can also implement your own adapter.

To improve the performance of some applications, you will need to cache data. For example, we can cache the query results for a post. Why? Imagine 1 million views or posts. Normally, you will query the database for it, but this will mean 1 million queries (you can multiply this by at least 3, if you are using it, and for ORM—this means 3 million queries at least). Why? When you query, the ORM will act like this:

To solve this problem, we will save the post object into our caching system.

Personally, I use Redis and Igbinary. Redis is probably the most powerful tool, since it stores the data in memory and, saves the data on disk for redundancy. This means that every time you request the data from cache, you will get it from memory. Igbinary (https://pecl.php.net/package/igbinary) is a replacement for the standard php serializer. Here is an example cache service:

<?php

$di['redis'] = function () {
    $redis = new \Redis();
    $redis->connect(
        '127.0.0.1',
        6379
    );

    return $redis;
};

$di['cache'] = function () use ($di, $config) {
    $frontend = new \Phalcon\Cache\Frontend\Igbinary(array(
        'lifetime' => 86400
    ));
    $cache = new \Phalcon\Cache\Backend\Redis($frontend, array(
        'redis' => $di['redis'],
        'prefix' => 'learning_phalcon'
    ));

    return $cache;
};

The cache component has the following methods that are commonly used:

<?php

// Save data in cache
$this-cache->save('post', array(
  'title' => 'Learning Phalcon',
  'slug' => 'learning-phalcon',
  'content' => 'Article content'
));

// Get data from cache
$post = $this->cache->get('post');

// Delete data from cache
$this->cache->delete('post');