Cherrycake
ExamplesGithub
version 2.x alpha
version 2.x alpha
  • Introduction
  • Status
  • Changelog
  • Migration
  • Architecture
    • Basics
    • Modules
    • Classes
    • Lifecycle
      • Deep lifecycle
    • Performance
    • Security
    • Patterns
      • Files structure
    • Items
    • Server requirements
  • Guide
    • Getting started
      • Skeleton start
      • Docker start
    • Modules guide
    • Classes guide
    • Actions guide
      • Complex actions
      • Variable path components
      • Accept GET or POST parameters
      • Getting the URL of an action
      • Cached actions
      • Brute force attacks
    • Patterns guide
      • Passing variables to a pattern
      • Nested patterns
      • Cached patterns
    • Cache guide
      • Time To Live
      • Using cache
      • Lists
      • Queues
      • Pools
    • Database guide
      • Basic queries
      • Prepared queries
      • Cached queries
      • Cache key naming
      • Removing queries from cache
    • Items guide
      • Item cache
      • Item lists
      • Items custom filters
      • Items custom ordering
      • Mixing filters and ordering
      • Items with relationships
      • Items cache
    • HtmlDocument guide
    • Css and Javascript guide
      • Modules injecting CSS and JavaScript
    • Session guide
    • Login guide
      • Creating a complete login workflow
    • Locale guide
      • Multilingual texts
      • Domain based site localization
    • Log guide
      • Loading Log events from the database
    • Stats guide
      • Stats events with additional dimensions
      • Loading Stats events from the database
    • Janitor guide
      • Janitor tasks configuration files
    • Command line interface
    • Debugging
  • Reference
    • Core modules
      • Actions
        • Actions methods
      • Browser
      • Cache
        • Cache methods
      • Css
        • Css methods
      • Database
      • Email
      • Errors
      • HtmlDocument
        • HtmlDocument methods
      • ItemAdmin
      • Janitor
        • Janitor methods
      • Javascript
        • Javascript methods
      • Locale
        • Locale methods
      • Log
        • Log methods
      • Login
        • Login methods
      • Output
        • Output methods
      • Patterns
        • Patterns methods
      • Security
        • Security methods
      • Session
        • Session methods
      • Stats
        • Stats methods
      • SystemLog
      • TableAdmin
      • Translation
      • Validate
    • Core classes
      • Action
        • Action methods
        • Action properties
      • AjaxResponseJson
      • BasicObject
        • BasicObject methods
      • CacheProvider
        • CacheProvider methods
      • Color
      • DatabaseProvider
        • DatabaseProvider methods
      • DatabaseResult
        • DatabaseResult methods
        • DatabaseResult properties
      • DatabaseRow
      • Engine
        • Engine methods
        • Engine properties
      • Gradient
      • Item
        • Item methods
        • Item properties
      • Items
        • Items methods
        • Items properties
      • Image
      • JanitorTask
        • JanitorTask methods
        • JanitorTask properties
      • LogEvent
        • LogEvent methods
        • LogEvent Properties
      • LogEvents
        • LogEvents methods
      • Module
        • Module methods
        • Module properties
      • Response
      • Request
        • Request methods
      • RequestParameter
        • RequestParameter methods
      • RequestPathComponent
        • RequestPathComponent methods
      • Result
      • StatsEvent
        • StatsEvent properties
      • StatsEvents
        • StatsEvents methods
      • SystemLogEvent
        • SystemLogEvent methods
        • SystemLogEvent properties
      • SystemLogEvents
        • SystemLogEvents methods
  • Code conventions
  • License
  • Extras
Powered by GitBook
On this page
  • Installing the Cherrycake engine
  • Setting up autoload
  • The public directory
  • Setting up the web server
  • Setting up the skeleton database
  • Creating the index.php
  • The "Hello world" module

Was this helpful?

  1. Guide

Getting started

A simple guide to build a simple "Hello world" application with Cherrycake.

PreviousServer requirementsNextSkeleton start

Last updated 3 years ago

Was this helpful?

In this guide we'll be creating a simple web application with Cherrycake that shows the well known "Hello world" message in the browser. We won't be using any boilerplates or assisting tools, we'll write all the code you need line by line so you'll learn the very basics of how Cherrycake works.

First of all, check that your web server meets the and create a folder for your project.

Installing the Cherrycake engine

You can simply download the latest version of the engine from , but the recommended installation method is using . To do so, cd into your project directory and require the Cherrycake engine using composer:

composer require tin-cat/cherrycake-engine dev-master

This will create the /vendor directory in your project, and will install there the Cherrycake engine and all its dependencies.

Setting up autoload

To allow your own classes and modules to be loaded automatically, add this to your composer.jsonfile:

"autoload": {
    "psr-4": {
        "CherrycakeApp\\": "src/"
    }
}

If you want to use a namespace other than CherrycakeAppfor your App, modify the snippet above to match it.

The public directory

For security reasons, we'll put all the files that will be served publicly to the Internet in a subdirectory called /public. Create this subdirectory now.

Setting up the web server

Setting up a web server to work with a Cherrycake application it's almost exactly the same as with any other application, except for one detail: We need to tell the web server to redirect all the queries to the index.php file instead of the usual server behavior. This is how it's done:

For NGINX: Add the following to your virtual host configuration file:

root /<path_to_your_app>/public;
index index.php;
location / {
    try_files $uri $uri/ /?$query_string;
}

For Apache: Be sure to point your Virtual Host DocumentRoot directive to /path_to_your_app/public in your virtual host configuration file and create the file /public/.htaccess in your project with the following contents:

RewriteEngine On
RewriteCond %{DOCUMENT_ROOT}/$1 -f [OR]
RewriteCond %{DOCUMENT_ROOT}/$1 -d
RewriteRule (.*) - [L]
RewriteRule (.*) / [L]

Setting up the skeleton database

It's not required, but some of the most interesting Cherrycake features need a database to work, you'll discover them while you dive in the rest of this guides.

Creating the index.php

The /public/index.php file will receive all the requests to your app and will be in charge of starting up the Cherrycake engine. Create it now and let's go step by step:

Cherrycake apps need to be declared in a namespace of your choice, or you can use the default CherrycakeApp namespace. In any case, we declare the namespace first:

<?php

namespace CherrycakeApp;
require "vendor/autoload.php";

Now we can instantiate the engine. We use the $e variable as a convention:

$e = new \Cherrycake\Engine;

Note that the entire Cherrycake engine lives inside the Cherrycake namespace, while your application lives in its own different namespace you declared above. Every time you'll refer to a Cherrycake class, module or constant you'll need to prefix it with the appropriate \Cherrycake\ namespace like we did here, or add a use statement at the top of your code. You'll see examples of that in the guide section and the provided examples.

if ($e->init(__NAMESPACE__, [
    "appName" => "CherrycakeApp",
    "isDevel" => true,
    "baseCoreModules" => [
        "Actions"
    ]
]))
    $e->attendWebRequest();

The second parameter is an optional hash array that lets you configure some important parameters of the Cherrycake engine. The ones we're using here are:

  • appName The name of the application. You can skip this and one will be generated automatically.

  • isDevel When set to true, the application works in development mode, meaning you'll get extended error reports and other tricks to help you develop your app. When not specified, this parameter defaults to false.

It's as if the Actions module asked all other modules: "If you have any actions you would like to map to respond to requests, please let me know now!"

$e->end();

So, our index.php file ends looking like this:

<?php

namespace CherrycakeApp;

require "vendor/autoload.php";

$e = new \Cherrycake\Engine;

if ($e->init(__NAMESPACE__, [
    "isDevel" => true
]))
    $e->attendWebRequest();

$e->end();

Your Cherrycake app setup is ready, but if you run it now by browsing to your web server address, you'll get an error:

No mapped action found for this request

This is quite normal, since we haven't yet configured any actions for Cherrycake to respond to. Let's do it now.

The "Hello world" module

Four our setup to be complete, we'll tell Cherrycake to attend requests to the / route of your web application and respond by showing a simple HTML "Hello world" message.

Create the file /src/HelloWorld/HelloWorld.class.php and edit it so it declares an empty module structure, like this:

<?php

namespace CherrycakeApp\HelloWorld;

class HelloWorld extends \Cherrycake\Module {
}

Remember to use the same namespace you choose for your application in the /public/index.php file.

Also, don't forget that modules have their own directory inside /src, that directory name must match the module name, even with uppercase and lowercase characters.

<?php

namespace CherrycakeApp\HelloWorld;

class HelloWorld extends \Cherrycake\Module {

    public static function mapActions() {
        global $e;
        $e->Actions->mapAction(
            "home",
            new \Cherrycake\Actions\ActionHtml([
                "moduleType" => ACTION_MODULE_TYPE_APP,
                "moduleName" => "HelloWorld",
                "methodName" => "show",
                "request" => new \Cherrycake\Actions\Request([
                    "pathComponents" => false,
                    "parameters" => false
                ])
            ])
        );
    }
    
}

If we run our app now, we'll get this error:

Mapped method HelloWorld::show not found

<?php

namespace CherrycakeApp\HelloWorld;

class HelloWorld extends \Cherrycake\Module {

    public static function mapActions() {
        global $e;
        $e->Actions->mapAction(
            "home",
            new \Cherrycake\Actions\ActionHtml([
                "moduleType" => ACTION_MODULE_TYPE_APP,
                "moduleName" => "HelloWorld",
                "methodName" => "show",
                "request" => new \Cherrycake\Actions\Request([
                    "pathComponents" => false,
                    "parameters" => false
                ])
            ])
        );
    }
    
    function show() {
        global $e;
        $e->Output->setResponse(new \Cherrycake\Actions\ResponseTextHtml([
            "code" => RESPONSE_OK,
            "payload" => "<html><body>Hello world</body></html>"
        ]));
    }
    
}

And that's it! If you now run your app you should see a boring yet quite welcoming "Hello world" message in your browser.

This seems to be a somewhat overkill way of doing what could've been done with a simple echo "Hello world" line, isn't it?

Bear with me with the rest of the guides and you'll find this architecture to really come in handy when what you want to accomplish with your app is much more complex than a "Hello World"!

If you're going to use this features, you'll need to install the skeleton database by importing some SQL scripts into your MySQL or MariaDB database server. You'll find this scripts in the official , in the /install/database directory.

Now we load the engine, along with any other additional packages. Since Cherrycake works with , this is done just by including the autoload.php file, like this:

Now we call the method to start it up:

accepts two parameters. The first must be the namespace of your app. Since we just declared it above, we can pass here the PHP constant __NAMESPACE__

baseCoreModules Is an array of the module names that should be loaded upon initialization of the engine. If not specified, only the module will be loaded.

Check the documentation for more configuration parameters when initializing the engine.

Let's take a pause here to see why we've added the module on the baseCoreModules list: We need our app to attend requests (it would be pretty useless otherwise), and is the module in charge of doing exactly that.

By including in baseCoreModules, it will be loaded immediately and, as part of the loading process, it will be initialized by calling the method. What this method does in the module, among other things, is to go through all available modules in both the Cherrycake engine and your app, check if they have a method called mapActions and run it.

This causes all modules that have some action to map to do so (by using the method), thus leaving ready to attend requests.

Note that there's actually no need to specify a baseCoreModules setup key when initializing the engine. If you skip this parameter, the module will be loaded by default, which is the most common scenario when developing regular apps.

Now, if goes well, we run the method. What this method does is quite simple: By calling the method, it asks the module to go through all mapped actions and run the one that matches the current request.

Lastly, we need to finalize execution by calling the method, which in turn calls the end methods of all the loaded modules, so they can perform any cleaning tasks like disconnecting from external sources:

Note that because we're ok with the default configuration parameters for the call, we've simplified it and only the isDevel configuration key remains.

To do this, we'll create a module called HelloWorld that will map an action into the module.

To map an action for the HelloWorld module so it will respond to requests, declare the static method mapActions, and call the method, like this:

This will map an action that will respond to requests to the / path (that's why pathComponents has been set to false), and will call the show method on the HelloWorld module (the same module we're working on). Take a look at the to learn about how to map more advanced actions.

Which is quite understandable, because we haven't yet created the show method we told the to run. Let's add it now:

To send our "Hello World" HTML code to the client, we send a object using the method.

See this example working in the site.

minimum requirements
GitHub
composer
Cherrycake skeleton repository
composer
Actions
Actions
Actions
Actions
Actions
Actions guide
Action
Cherrycake documentation examples
Actions
Actions
Actions
Actions
ResponseTextHtml
Actions::init
Actions::mapAction
Actions::mapAction
Output::setResponse
Actions::run
Engine::init
Engine::init
Engine::init
Engine::init
Engine::attendWebRequest
Engine::end
Engine::init