CakeDC Blog

TIPS, INSIGHTS AND THE LATEST FROM THE EXPERTS BEHIND CAKEPHP

Lighty Story

I will tell you a story. Once upon a time... Seriously though, it was not too long ago in the past - but it happened and it is possible you can benefit from it.

What?

This tutorial will show how to make lighttpd 1.4.20 serve virtual hosts with CakePHP applications. Our scenario is quite simple:

  1. For admin purposes, lighttpd will listen on localhost, it will serve several CakePHP applications on several external ip addresses, without SSL.
  2. Virtual hosts will be organized in groups and every group will use one CakePHP core checkout for its virtual hosts.
  3. Every virtual host will have it own access log (this server will not run hundreds of virtual hosts, so we can afford to waste one file descriptor for each) and its own directory for caching of compressed static files.
  4. Management of virtual hosts, their default and custom settings should be as easy as possible, so we can delegate the management of some ip addresses or just groups of virthosts to someone else and sleep well, because nobody will have to touch our precious configuration files.

However, our scenario has some special requirements which we need to solve. By the way, I will be showing you how to do things the hard way from the start. In hopes to spare you a lot of headaches in future. Lighttpd is sweet piece of software, and is under active development. Unfortunately, there are things that are not easy to set up. For example - when using any of provided virtual host modules, it is impossible to set up different access logs and cache directories for compressed content etc. dynamically in a pure lighty config file without external scripts. Everything (except for per virtual host errorlog) is possible by writing necessary configuration by hand. But we willing to work more now, so we can be lazy later!

There are several approaches for bash, Ruby etc. However, nothing usable in PHP as far as I know. I will show you how easy it could be. Take this as a working example, I am sharing ideas here, not bullet-proof all-mighty solutions. Lets go for it - and utilize PHP and the include_shell command in our lighttpd configuration file. The motto of this article is: it is easier read generated configuration, then write it by hand.

How? Lighty!

Don't think this is not a good answer. Lets set up a decent lighttpd installation. We'll assume you have it compiled and installed. Lets also assume that you have PHP prepared for lighttpd's ModFastCGI and are just waiting for configuration and the first test run. Also, for shell commands which need to be executed under root account, I'll use sudo in following examples.

    sudo mkdir /usr/local/etc/lighttpd

First of all, we need a directory for our custom configuration. When in doubt, a fast look into its contents will tell you everything one should know about virtual hosts configuration.

    sudo mkdir -p /usr/local/www/data/default/webroot
    echo "<html><head><title>It works<body>It works" > /usr/local/www/data/default/webroot/index.html

Next we created a directory for our default webroot. It will be used on localhost only, with index.html.

    sudo touch /var/log/lighttpd.error.log /var/log/lighttpd.access.log
    sudo chown www:www /var/log/lighttpd.error.log /var/log/lighttpd.access.log

Now we need to create error and access log files. The first one will be common for whole server, the second will be used for localhost only.

    sudo mkdir -p /var/cache/lighttpd/compress/default
    sudo chown -R www:www /var/cache/lighttpd

The last thing we had to prepare was the default directory for caching of compressed static files.

In /usr/local/etc/lighttpd.conf we will setup a simple config file containing the common configuration we will utilize later:

    server.modules = (
        "mod_simple_vhost",
        "mod_magnet",
        "mod_redirect",
        "mod_access",
        "mod_auth",
        "mod_expire",
        "mod_compress",
        "mod_fastcgi",
        "mod_accesslog"
    )
    
    server.document-root = "/usr/local/www/data/default/webroot/"
    server.errorlog = "/var/log/lighttpd.error.log"
    accesslog.filename = "/var/log/lighttpd.access.log"
    server.port = 80
    server.bind = "127.0.0.1"
    server.username = "www"
    server.groupname = "www"
    server.pid-file = "/var/run/lighttpd.pid"
    index-file.names = ( "index.php", "index.html", "index.htm", "default.htm" )
    
    # shortened !!!
    mimetype.assign = (
        ...
    )
    
    url.access-deny = ( "~", ".inc" )
    
    static-file.exclude-extensions = ( ".php", ".pl", ".fcgi" )
    
    dir-listing.activate = "disable"
    
    etag.use-mtime = "enable"
    static-file.etags = "enable"
    
    $HTTP["url"] =~ "^(/css/|/files/|/img/|/js/|/images/|/themed/|/favicon.ico)" {
        expire.url = ( "" => "access 7 days" )
    }
    
    compress.cache-dir = "/var/cache/lighttpd/compress/default/"
    compress.filetype = ( "text/plain", "text/html", "text/xml", "text/javascript", "text/css" )
    
    fastcgi.server = (
        ".php" => ((
            "bin-path" => "/usr/local/bin/php-cgi -c /usr/local/etc/php.ini",
            "socket" => "/tmp/lighttpd_php5.socket",
            "min-procs" => 1,
            "max-procs" => 1,
            "bin-environment" => (
                "FCGI_WEB_SERVER_ADDRS" => "127.0.0.1",
                "PHP_FCGI_CHILDREN" => "4",
                "PHP_FCGI_MAX_REQUESTS" => "1000"
            ),
            "bin-copy-environment" => ( "PATH", "SHELL", "USER"),
            "broken-scriptfilename" => "enable"
        ))
    )
    
    simple-vhost.server-root = "/usr/local/www/data/"
    simple-vhost.document-root = "webroot"
    simple-vhost.default-host = "default"
    
    $HTTP["host"] =~ "^www\.(.*)" {
        url.redirect = ( "^/(.*)" => "http://%1/$1" )
    }

How far along are we? So far we have a configured webserver with few preloaded modules and simple common configuration.

Our sever is currently:

  1. Listening on localhost:80.
  2. Refusing directory listing or sending some filetypes as plain text.
  3. Using etags and sending expiration headers for a set of static resources to 7 days by default. This allows us to schedule an upgrade of any virtual host just a week before it will happen.
  4. Using compression and caching of compressed static files for several mimetypes.
  5. Starting PHP as FastCGI, with only one parent process (we are going to use opcode cache). We are allowing only few child processes for this example tutorial and killing fcgi child processes after every 1000 requests
  6. Using mod_simple_vhost for name-based virtual hosting (preconfigured for fallback to default webroot).
  7. Redirecting all domains using www subdomain to the shorter version.

You will probably want to tweak some other settings. I am not going to describe all the server.max* configuration options, or talk about other pretty obvious things like mod_evasive, mod_status, mod_rrdtool etc, don't worry. Two things you should consider if some of your visitors will use one of the major browsers.

    $HTTP["url"] =~ "\.pdf$" {
        server.range-requests = "disable"
    }

You do not want to cut off IE users from your pdf documents, right?

    compress.filetype = ( "text/plain", "text/html", "text/xml" )
    $HTTP["useragent"] =~ "Firefox" {
        compress.filetype  += ("text/javascript", "text/css" )
    }

If your visitors are using an old (and/or above mentioned undesirable) internet browser, you can control compression settings per useragent in this way. Instead of the above example, compressing all 5 crucial mimetypes.

Ready to go? Ok, start lighttpd and make sure you see what you expect at http://localhost/

    echo "<?php phpinfo(); ?>" > /usr/local/www/data/default/webroot/phpinfo.php

Just to be sure that fcgi works as expected, try to see info about your current PHP setup at http://localhost/phpinfo.php and watch /var/log/lighttpd.error.log.

Url rewriting

It is possible to use lighttpd's mod_rewrite and create pattern for our static files if we are sure they exist. This approach has downsides though. We want to setup this part of webserver up and forget it exists. This is not possible with mod_rewrite, because for example, we are not going to force our developers to forget about /js/something.js as url for some of application controllers. Instead, we will use mod_magnet and custom Lua script. Visit this thread at CakePHP Google Group. Save the provided script to /usr/local/etc/lighttpd/cleanurl-v6.lua and add the following line to bottom of /usr/local/etc/lighttpd.conf:

    magnet.attract-physical-path-to = ( "/usr/local/etc/lighttpd/cleanurl-v6.lua" )

After restarting lighttpd, we are ready to remove all the .htaccess files from our filesystem and forget they exist. All requests for non-existing static files will be rewritten to /index.php?url=xxx like CakePHP requires.

Virtual hosts

Now we want to set up a directory structure and custom configuration for our virtual hosts and their groups. We will design a directory structure that can be used for dynamic configuration later, with no need to repeat anything obvious in configuration files. In this case, only logs folder matters (make sure it is writable by webserver). We will symlink everything else. Lets use the following directory structure with CakePHP core and our applications checkouts like our standard:

    # example.com (with redirect from www.example.com)
    /home/company/
                  logs/
                  www/
                      cake/
                      mainsite/
                               ...
                               webroot/
                      vendors/
    # dev-main.example.com and dev-product.example.com
    /home/development/
                  logs/
                  www/
                      cake/
                      mainsite/
                               ...
                               webroot/
                      product/
                               ...
                               webroot/
                      vendors/
    # stage-main.example.com and stage-product.example.com
    /home/staging/
                  logs/
                  www/
                      cake/
                      mainsite/
                               ...
                               webroot/
                      product/
                               ...
                               webroot/
                      vendors/
    # api.example.com, book.example.com, product.com ( with redirect from www.product.com)
    /home/product/
                  logs/
                  www/
                      api/
                          ...
                          index.html
                      book/
                               ...
                               webroot/
                      cake/
                      product/
                               ...
                               webroot/
                      vendors/

If you think the above directory tree is overcomplicated, or it seems too long for simple tutorial example, stop reading please, and feel free to come back any time later. It was nice to meet you :-) Things are only getting worse from here on in. For those brave enough to read on, you should have an idea of which domains will use which applications, and which applications will share one CakePHP core and folder for logs (not necessarily, read more).

Now we are getting somewhere - we need tell our webserver on which external ip addresses it has to listen for incoming connections, and which virtual hosts map to each ip address. Our www subdomains (redirected) should listen on a different ip address then their short versions. This allows us to use different SSL certificates for them later, if there is a need for secure connections. To show what is possible with our config parser, api.example.com will not use a /webroot/ folder, it contains just static html files. To make things even more tricky, api.example.com and book.example.com will not listen on same ip like their neighbour application product.com.

    cd /usr/local/etc/lighttpd

From now on, we will continue our work in this directory.

Lets say that we want to use ip 1.2.3.4 for domains example.com, api.example.com and book.example.com.

    sudo mkdir -p ./1.2.3.4:80/company
    sudo ln -s /home/company/www/cake ./1.2.3.4:80/company/cake
    sudo ln -s /home/company/www/vendors ./1.2.3.4:80/company/vendors
    
    sudo ln -s /home/company/www/mainsite ./1.2.3.4:80/company/example.com
    
    sudo mkdir ./1.2.3.4:80/product
    sudo ln -s /home/product/www/cake ./1.2.3.4:80/product/cake
    sudo ln -s /home/product/www/vendors ./1.2.3.4:80/product/vendors
    
    sudo ln -s /home/product/www/api ./1.2.3.4:80/product/api.example.com
    sudo ln -s /home/product/www/book ./1.2.3.4:80/product/book.example.com

What exactly did we just do? We created a folder named 1.2.3.4:80, containing 2 subfolders company and product. These will be used as groups of virtual hosts - their names should be the same as the name of their home directory (by default, path for logs can be adjusted). We will use them for setting paths to log files later. Both company and product have a symlinked cake and vendors folders and symlinks named as real domains and pointing to our app folders.

Lets continue - ip 2.3.4:5:80 will be used for rest of the group product.

    sudo mkdir -p ./2.3.4.5:80/product
    sudo ln -s /home/product/www/cake ./2.3.4.5:80/product/cake
    sudo ln -s /home/product/www/vendors ./2.3.4.5:80/product/vendors
    
    sudo ln -s /home/product/www/product ./2.3.4.5:80/product/product.com

That means only one virtual host for now.

Ok, ip 3.4.5.6 is going to be used for the www subdomains. No symlinks to existing applications are necessary here, because lighttpd will redirect requests coming to www.example.com to example.com automatically.

    sudo mkdir -p ./3.4.5.6:80/company/www.example.com ./3.4.5.6:80/product/www.product.com

We just had to create ip:port directory for the socket, group(s) of www virtualhosts and some domain-based directories just to have something to point default virtual host of this group at.

Staging and development checkouts will all share one ip 4.5.6.7.

    sudo mkdir -p ./4.5.6.7:80/development
    sudo ln -s /home/development/www/cake ./4.5.6.7:80/development/cake
    sudo ln -s /home/development/www/vendors ./4.5.6.7:80/development/vendors
    
    sudo ln -s /home/development/www/mainsite ./4.5.6.7:80/development/dev-main.example.com
    sudo ln -s /home/development/www/product ./4.5.6.7:80/development/dev-product.example.com
    
    sudo mkdir ./4.5.6.7:80/staging
    sudo ln -s /home/staging/www/cake ./4.5.6.7:80/staging/cake
    sudo ln -s /home/staging/www/vendors ./4.5.6.7:80/staging/vendors
    
    sudo ln -s /home/staging/www/mainsite ./4.5.6.7:80/staging/stage-main.example.com
    sudo ln -s /home/staging/www/product ./4.5.6.7:80/staging/stage-product.example.com

Four virtual hosts on one ip from different home folders (therefore placed in different groups).

The hard part is complete. Lets go through the bothering part of this custom setup. Did I said already that everything is a file? Don't be scared from amount of necessary steps, it will all be worth it in the future.

Lets look what we have done in directory /usr/local/etc/lighttpd/:

    1.2.3.4:80/
               company/
                        cake/        <-- /home/company/www/cake
                        example.com/ <-- /home/company/www/mainsite
                        vendors/     <-- /home/company/www/vendors
               product/
                        api.example.com/  <-- /home/product/www/api
                        book.example.com/ <-- /home/product/www/book
                        cake/             <-- /home/product/www/cake
                        vendors/          <-- /home/product/www/vendors
    2.3.4.5:80/
               product/
                        cake/        <-- /home/product/www/cake
                        product.com/ <-- /home/product/www/product
                        vendors/     <-- /home/product/www/vendors
    3.4.5.6:80/
               company/www.example.com/ <-- empty directory (redirected), necessary for default virtual host 
               product/www.product.com/ <-- empty directory (redirected), necessary for default virtual host
    4.5.6:7:80/
               development/
                        cake/                    <-- /home/development/www/cake
                        dev-main.example.com/    <-- /home/development/www/mainsite
                        dev-product.example.com/ <-- /home/development/www/product
                        vendors/                 <-- /home/development/www/vendors
               staging/
                        cake/                      <-- /home/staging/www/cake
                        stage-main.example.com/    <-- /home/staging/www/mainsite
                        stage-product.example.com/ <-- /home/staging/www/product
                        vendors/                   <-- /home/staging/www/vendors

Some new folders with symlinks.

Are you still with me? For those who know mod_simple_vhost, you should be already be pretty clear where we are going. Besides the accesslog path and compress folder path, we will also switch simple-vhost.server-root and simple-vhost.default-host in dependency of used socket and some hostname condition for virthost group. Actually, there is a bit more as well that I will show you.

The above directory structure shows that we have 7 groups of virtual hosts in 4 sockets, so lets create 7 simple configuration files for our groups of virtual hosts. Configuration file for group is not required in very special case - no regex pattern for this group, only one virtual host inside and - either only group in socket, or (alphabetically) last one.

<?php # /usr/local/etc/lighttpd/1.2.3.4:80/company/config.php
    $config['group'] = array(
        'host' => '^example\.com',
        'default' => 'example.com'
    );
?>
<?php # /usr/local/etc/lighttpd/1.2.3.4:80/product/config.php
    $config['group'] = array(
        'host' => '^(.*)\.example\.com',
        'default' => 'book.example.com'
    );
?>
<?php # /usr/local/etc/lighttpd/2.3.4.5:80/product/config.php
    $config['group'] = array(
        'host' => '^product\.com',
        'default' => 'product.com'
    );
?>
<?php # /usr/local/etc/lighttpd/3.4.5.6:80/company/config.php
    $config['group'] = array(
        'host' => '^(.*)\.example\.com',
        'default' => 'www.example.com'
    );
?>
<?php # /usr/local/etc/lighttpd/3.4.5.6:80/product/config.php
    $config['group'] = array(
        'host' => '^(.*)\.product\.com',
        'default' => 'www.product.com'
    );
?>
<?php # /usr/local/etc/lighttpd/4.5.6:7:80/development/config.php
    $config['group'] = array(
        'host' => '^dev-(.*)\.example\.com',
        'default' => 'dev-main.example.com'
    );
?>
<?php # /usr/local/etc/lighttpd/4.5.6:7:80/staging/config.php
    $config['group'] = array(
        'host' => '^stage-(.*)\.example\.com',
        'default' => 'stage-main.example.com'
    );
?>

And that's it. Every group (subfolder of ip.ad.dr.es:80 socket folder) has the required minimal configuration, and everything is properly set up. So lets see what we can take off from it.

Dynamic configuration

Extract this file in folder /usr/local/etc/lighttpd.

    sudo chmod a+x ./simple_config.php

Make simple_config.php executable for everyone.

Now run it as a non-privileged user.

    ./simple_config.php | more

You should see a basic generated configuration for your sockets, virthosts and virthosts groups.

Now we are already looking at a snippet of the generated configuration.

    #
    # Simple configuration parser output
    #
    # ERROR logfile /home/company/logs/example-access_log can not be created, SKIPPING
    # ERROR compress cache /var/cache/lighttpd/compress/example.com/ can not be created, SKIPPING
    # ERROR logfile /home/product/logs/api-access_log can not be created, SKIPPING
    # ERROR compress cache /var/cache/lighttpd/compress/api.example.com/ can not be created, SKIPPING
    # ERROR logfile /home/product/logs/book-access_log can not be created, SKIPPING
    # ERROR compress cache /var/cache/lighttpd/compress/book.example.com/ can not be created, SKIPPING
    # ERROR logfile /home/product/logs/product-access_log can not be created, SKIPPING
    # ERROR compress cache /var/cache/lighttpd/compress/product.com/ can not be created, SKIPPING
    # ERROR logfile /home/company/logs/www-access_log can not be created, SKIPPING
    # ERROR compress cache /var/cache/lighttpd/compress/www.example.com/ can not be created, SKIPPING
    # ERROR logfile /home/product/logs/www-access_log can not be created, SKIPPING
    # ERROR compress cache /var/cache/lighttpd/compress/www.product.com/ can not be created, SKIPPING
    # ERROR logfile /home/development/logs/dev-main-access_log can not be created, SKIPPING
    # ERROR compress cache /var/cache/lighttpd/compress/dev-main.example.com/ can not be created, SKIPPING
    # ERROR logfile /home/development/logs/dev-product-access_log can not be created, SKIPPING
    # ERROR compress cache /var/cache/lighttpd/compress/dev-product.example.com/ can not be created, SKIPPING
    # ERROR logfile /home/staging/logs/stage-main-access_log can not be created, SKIPPING
    # ERROR compress cache /var/cache/lighttpd/compress/stage-main.example.com/ can not be created, SKIPPING
    # ERROR logfile /home/staging/logs/stage-product-access_log can not be created, SKIPPING
    # ERROR compress cache /var/cache/lighttpd/compress/stage-product.example.com/ can not be created, SKIPPING
    #
    
    $SERVER["socket"] == "1.2.3.4:80" {
            $HTTP["host"] =~ "^example\.com" {
                    simple-vhost.server-root = "/usr/local/etc/lighttpd/1.2.3.4:80/company/"
                    simple-vhost.default-host = "example.com"
                    $HTTP["host"] == "example.com" {
                    ....

You can see which files this script is trying to create. It will create all of them when you will run it as root once. But there are two things we would like to fix first: access logs /home/company/logs/www-access_log and /home/product/logs/www-access_log are generated for our redirected domains.

Lets redirect these logs to those used by domains example.com and product.com:

<?php # /usr/local/etc/lighttpd/3.4.5.6:80/company/config.php
    $config['group'] = array(
        'host' => '^(.*)\.example\.com',
        'default' => 'www.example.com'
    );
    $config['virthosts'] = array(
        'www.example.com' => array(
            'log' => 'example'
        )
    );
?>
<?php # /usr/local/etc/lighttpd/3.4.5.6:80/product/config.php
    $config['group'] = array(
        'host' => '^(.*)\.product\.com',
        'default' => 'www.product.com'
    );
    $config['virthosts'] = array(
        'www.product.com' => array(
            'log' => 'product'
        )
    );
?>

Running ./simple_config.php as unprivileged user again shows this script is no longer trying to create any www-access_log files. We will not care about directories for compressed content, they can be used later, but we will never serve different content on example.com and www.example.com, so it is logical that they share one log file. Every decent logfile parser can handle several domains in one log file.

Now, you can run this script as root:

    sudo ./simple_config.php

and result will look much better now:

#
# Simple configuration parser output
#
# NOTICE created logfile /home/company/logs/example-access_log
# NOTICE created compress cache /var/cache/lighttpd/compress/example.com/
# NOTICE created logfile /home/product/logs/api-access_log
# NOTICE created compress cache /var/cache/lighttpd/compress/api.example.com/
# NOTICE created logfile /home/product/logs/book-access_log
# NOTICE created compress cache /var/cache/lighttpd/compress/book.example.com/
# NOTICE created logfile /home/product/logs/product-access_log
# NOTICE created compress cache /var/cache/lighttpd/compress/product.com/
# NOTICE created compress cache /var/cache/lighttpd/compress/www.example.com/
# NOTICE created compress cache /var/cache/lighttpd/compress/www.product.com/
# NOTICE created logfile /home/development/logs/dev-main-access_log
# NOTICE created compress cache /var/cache/lighttpd/compress/dev-main.example.com/
# NOTICE created logfile /home/development/logs/dev-product-access_log
# NOTICE created compress cache /var/cache/lighttpd/compress/dev-product.example.com/
# NOTICE created logfile /home/staging/logs/stage-main-access_log
# NOTICE created compress cache /var/cache/lighttpd/compress/stage-main.example.com/
# NOTICE created logfile /home/staging/logs/stage-product-access_log
# NOTICE created compress cache /var/cache/lighttpd/compress/stage-product.example.com/
#

    $SERVER["socket"] == "1.2.3.4:80" {
            $HTTP["host"] =~ "^example\.com" {
                    simple-vhost.server-root = "/usr/local/etc/lighttpd/1.2.3.4:80/company/"
                    simple-vhost.default-host = "example.com"
                    $HTTP["host"] == "example.com" {
                            accesslog.filename = "/home/company/logs/example-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/example.com/"
                    }
            }
            else $HTTP["host"] =~ "^(.*)\.example\.com" {
                    simple-vhost.server-root = "/usr/local/etc/lighttpd/1.2.3.4:80/product/"
                    simple-vhost.default-host = "book.example.com"
                    $HTTP["host"] == "api.example.com" {
                            accesslog.filename = "/home/product/logs/api-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/api.example.com/"
                    }
                    else $HTTP["host"] == "book.example.com" {
                            accesslog.filename = "/home/product/logs/book-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/book.example.com/"
                    }
            }
    }
    $SERVER["socket"] == "2.3.4.5:80" {
            $HTTP["host"] =~ "^product\.com" {
                    simple-vhost.server-root = "/usr/local/etc/lighttpd/2.3.4.5:80/product/"
                    simple-vhost.default-host = "product.com"
                    $HTTP["host"] == "product.com" {
                            accesslog.filename = "/home/product/logs/product-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/product.com/"
                    }
            }
    }
    $SERVER["socket"] == "3.4.5.6:80" {
            $HTTP["host"] =~ "^(.*)\.example\.com" {
                    simple-vhost.server-root = "/usr/local/etc/lighttpd/3.4.5.6:80/company/"
                    simple-vhost.default-host = "www.example.com"
                    $HTTP["host"] == "www.example.com" {
                            accesslog.filename = "/home/company/logs/example-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/www.example.com/"
                    }
            }
            else $HTTP["host"] =~ "^(.*)\.product\.com" {
                    simple-vhost.server-root = "/usr/local/etc/lighttpd/3.4.5.6:80/product/"
                    simple-vhost.default-host = "www.product.com"
                    $HTTP["host"] == "www.product.com" {
                            accesslog.filename = "/home/product/logs/product-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/www.product.com/"
                    }
            }
    }
    $SERVER["socket"] == "4.5.6.7:80" {
            $HTTP["host"] =~ "^dev-(.*)\.example\.com" {
                    simple-vhost.server-root = "/usr/local/etc/lighttpd/4.5.6.7:80/development/"
                    simple-vhost.default-host = "dev-main.example.com"
                    $HTTP["host"] == "dev-main.example.com" {
                            accesslog.filename = "/home/development/logs/dev-main-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/dev-main.example.com/"
                    }
                    else $HTTP["host"] == "dev-product.example.com" {
                            accesslog.filename = "/home/development/logs/dev-product-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/dev-product.example.com/"
                    }
            }
            else $HTTP["host"] =~ "^stage-(.*)\.example\.com" {
                    simple-vhost.server-root = "/usr/local/etc/lighttpd/4.5.6.7:80/staging/"
                    simple-vhost.default-host = "stage-main.example.com"
                    $HTTP["host"] == "stage-main.example.com" {
                            accesslog.filename = "/home/staging/logs/stage-main-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/stage-main.example.com/"
                    }
                    else $HTTP["host"] == "stage-product.example.com" {
                            accesslog.filename = "/home/staging/logs/stage-product-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/stage-product.example.com/"
                    }
            }
    }

Getting close to what we need from this setup.

I will process several steps now, and then I will paste here final output of config parser for you to compare with above one.

We have another domain manual.example.com (with no virthost set) and we want to redirect it to api.example.com with configuration only, it will be using its own manual-access_log. Furthermore, we want book.example.com condition happen sooner then the condition on api.example.com, because book is gaining more traffic, and attach domain aliases bibliotheca.example.com and bookstore.example.com to book.example.com. Also, expire headers for book should be set for 2 years and as previously mentioned api.example.com is not using /webroot/ folder.

<?php # /usr/local/etc/lighttpd/1.2.3.4:80/product/config.php
    $config['group'] = array(
        'host' => '^(.*)\.example\.com',
        'default' => 'book.example.com'
    );
    $config['virthosts'] = array(
        'book.example.com' => array(
            'expire' => array(
                '^(/css/|/files/|/img/|/js/|/images/|/themed/|/favicon.ico)' => 'access 2 years'
            ),
            'aliases' => array(
                'bibliotheca.example.com',
                'bookstore.example.com'
            )
        ),
        'api.example.com' => array(
            'webroot' => '/'
        ),
        'manual.example.com' => array(
             'redirect' => 'http://api.example.org/'
        )
    );
?>

All of it is fixed now. We even do not need folder/symlink for manual.example.com in this case.

Important note: we do not have to create folders for domains bibliotheca.example.com and bookstore.example.com, because they are aliases for book.example.com and it is used as default virtual host for this group! If you will set alias for non-default virtual host, you have to symlink aliased application several times to group folder - every time with a different domain name.

We want all staging sites to store logs in /home/development/logs. Also all staging and development sites should use expire headers for 5 minutes only and have to use http auth (one common file for now).

<?php # /usr/local/etc/lighttpd/4.5.6:7:80/development/config.php 
    $config['group'] = array(
        'host' => '^dev-(.*)\.example\.com', 
        'default' => 'dev-main.example.com', 
        'expire' => array(
             '^(/css/|/files/|/img/|/js/|/images/|/themed/|/favicon.ico)' => 'access 5 minutes' 
        ), 
        'auth' => array( 
            'backend' => 'htpasswd', 
            'file' => '/var/projects/company/.trac.htpasswd', 
            'protect' => array( 
                '/' => array( 
                    'realm' => 'Development Access', 
                    'require' => 'valid-user' 
                ) 
            )
        ) 
    );
?>
<?php # /usr/local/etc/lighttpd/4.5.6:7:80/staging/config.php 
    $config['group'] = array(
        'host' => '^stage-(.*)\.example\.com', 
        'default' => 'stage-main.example.com', 
        'expire' => array( 
            '^(/css/|/files/|/img/|/js/|/images/|/themed/|/favicon.ico)' => 'access 5 minutes' 
        ),
        'logs' => '/home/development/logs', 
        'auth' => array( 
            'backend' => 'htpasswd', 
            'file' => '/var/projects/company/.trac.htpasswd', 
            'protect' => array( 
                '/' => array( 
                    'realm' => 'Staging Access', 
                    'require' => 'valid-user' 
                ) 
            )
        ) 
    ); 
?>

This has all been fixed now.

Now our simple_config.php returns this:

    #
    # Simple configuration parser output
    #
    
    $SERVER["socket"] == "1.2.3.4:80" {
            $HTTP["host"] =~ "^example\.com" {
                    simple-vhost.server-root = "/usr/local/etc/lighttpd/1.2.3.4:80/company/"
                    simple-vhost.default-host = "example.com"
                    $HTTP["host"] == "example.com" {
                            accesslog.filename = "/home/company/logs/example-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/example.com/"
                    }
            }
            else $HTTP["host"] =~ "^(.*)\.example\.com" {
                    simple-vhost.server-root = "/usr/local/etc/lighttpd/1.2.3.4:80/product/"
                    simple-vhost.default-host = "book.example.com"
                    $HTTP["host"] =~ "^(book\.example\.com|bibliotheca\.example\.com|bookstore\.example\.com)" {
                            accesslog.filename = "/home/product/logs/book-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/book.example.com/"
                            $HTTP["url"] =~ "^(/css/|/files/|/img/|/js/|/images/|/themed/|/favicon.ico)" {
                                    expire.url = ("" => "access 2 years")
                            }
                    }
                    else $HTTP["host"] == "api.example.com" {
                            accesslog.filename = "/home/product/logs/api-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/api.example.com/"
                            simple-vhost.document-root = "/"
                    }
                    else $HTTP["host"] == "manual.example.com" {
                            accesslog.filename = "/home/product/logs/manual-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/manual.example.com/"
                            url.redirect = (
                                    ".*" => "http://api.example.org/"
                            )
                    }
            }
    }
    $SERVER["socket"] == "2.3.4.5:80" {
            $HTTP["host"] =~ "^product\.com" {
                    simple-vhost.server-root = "/usr/local/etc/lighttpd/2.3.4.5:80/product/"
                    simple-vhost.default-host = "product.com"
                    $HTTP["host"] == "product.com" {
                            accesslog.filename = "/home/product/logs/product-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/product.com/"
                    }
            }
    }
    $SERVER["socket"] == "3.4.5.6:80" {
            $HTTP["host"] =~ "^(.*)\.example\.com" {
                    simple-vhost.server-root = "/usr/local/etc/lighttpd/3.4.5.6:80/company/"
                    simple-vhost.default-host = "www.example.com"
                    $HTTP["host"] == "www.example.com" {
                            accesslog.filename = "/home/company/logs/example-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/www.example.com/"
                    }
            }
            else $HTTP["host"] =~ "^(.*)\.product\.com" {
                    simple-vhost.server-root = "/usr/local/etc/lighttpd/3.4.5.6:80/product/"
                    simple-vhost.default-host = "www.product.com"
                    $HTTP["host"] == "www.product.com" {
                            accesslog.filename = "/home/product/logs/product-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/www.product.com/"
                    }
            }
    }
    $SERVER["socket"] == "4.5.6.7:80" {
            $HTTP["host"] =~ "^dev-(.*)\.example\.com" {
                    simple-vhost.server-root = "/usr/local/etc/lighttpd/4.5.6.7:80/development/"
                    simple-vhost.default-host = "dev-main.example.com"
                    $HTTP["url"] =~ "^(/css/|/files/|/img/|/js/|/images/|/themed/|/favicon.ico)" {
                            expire.url = ("" => "access 5 minutes")
                    }
                    auth.backend = "htpasswd"
                    auth.backend.htpasswd.userfile = "/var/projects/company/.trac.htpasswd"
                    auth.require = (
                            "/" => (
                                    "method" => "basic",
                                    "realm" => "Development Access",
                                    "require" => "valid-user"
                            )
                    )
                    $HTTP["host"] == "dev-main.example.com" {
                            accesslog.filename = "/home/development/logs/dev-main-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/dev-main.example.com/"
                    }
                    else $HTTP["host"] == "dev-product.example.com" {
                            accesslog.filename = "/home/development/logs/dev-product-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/dev-product.example.com/"
                    }
            }
            else $HTTP["host"] =~ "^stage-(.*)\.example\.com" {
                    simple-vhost.server-root = "/usr/local/etc/lighttpd/4.5.6.7:80/staging/"
                    simple-vhost.default-host = "stage-main.example.com"
                    $HTTP["url"] =~ "^(/css/|/files/|/img/|/js/|/images/|/themed/|/favicon.ico)" {
                            expire.url = ("" => "access 5 minutes")
                    }
                    auth.backend = "htpasswd"
                    auth.backend.htpasswd.userfile = "/var/projects/company/.trac.htpasswd"
                    auth.require = (
                            "/" => (
                                    "method" => "basic",
                                    "realm" => "Staging Access",
                                    "require" => "valid-user"
                            )
                    )
                    $HTTP["host"] == "stage-main.example.com" {
                            accesslog.filename = "/home/development/logs/stage-main-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/stage-main.example.com/"
                    }
                    else $HTTP["host"] == "stage-product.example.com" {
                            accesslog.filename = "/home/development/logs/stage-product-access_log"
                            compress.cache-dir = "/var/cache/lighttpd/compress/stage-product.example.com/"
                    }
            }
    }

Now it looks like we are set with everything we needed.

One last line for /usr/local/etc/lighttpd.conf is:

    include_shell "/usr/local/etc/lighttpd/simple_config.php"

And that's all.

Before you will start or restart lighttpd, try and see if it can parse the new configuration (with our include) without errors, or inspect how it sees configuration after parsing:

    lighttpd -t -f /usr/local/etc/lighttpd.conf
    lighttpd -p -f /usr/local/etc/lighttpd.conf

It is better to run the above commands as root, off course.

Now what?

Think twice about patterns for groups - don't be surprised if you get 'It works' page or default virthost of another group, if you are too lazy to read the generated configuration! Groups are processed in alphabetical order - just so you know which patterns are going to be checked first. Well, it is possible to change order of groups - change name of some company group folder to xxx_company and:

    $config['group'] = array(
        'name' => 'company',

Now you should be fine - this group in folder named xxx_company instead of company, and everything will still work.

Everything that is necessary should be up and running now. Lighttpd should serve all virtual hosts from groups in sockets from now on. Read how to clear cache for mod_compress too. Smart brain should ask now, why we are using mod_simple_vhost, if our parser generates configuration for every virtual host it founds in our configuration files and directory structure. We don't do it, but you can - read code. Note for these who do not want or can not follow our default logs location, home directories, cache directories, user account lighttpd will use, or want to store directory structure with sockets/groups/virthosts somewhere else - read code too ;-) Reason why we set mod_simple_vhost for this example as default is simple - to get some domain serving some application, we need only one simple thing: symlink to app directory with domain name, placed in some virtual group in proper socket. This virtual host will be accessible immediately - although, restart of webserver is still necessary to have configuration for access logfile and compress directory for this virtual host (otherwise default accesslog and compress dir will be used), but not required.

A few questions remain, what and how needs to be done in obvious use cases - adding new ip addresses, groups, virthosts, or moving whole groups over sockets, moving virthosts over sockets, etc... I assume this part will be sweet piece of cake for you. Definitely - feel free to call simple_config.php as often as you want to. It is highly reccommended to save functional configuration to a backup file by redirecting the output. Sure, one can use include "/some/path/generated_output.conf" exclusively, instead of include_shell - it is up to you.

Backup, backup, backup. This is nothing more then a functional example, but the entire code lives in one class, so feel free to change or extend it for your needs. It is released under MIT license and is provided as it is, so you can do anything you want with it (except for removing license and copyright note). Keep in mind it was not tested in all possible situations and some of things I did not mention in this tutorial (but they are implemented in code) were not intensively tested yet.

If you feel that some of the subdomains used in this tutorial sound familiar to you, you are probably right. I didn't said it was going to be a fairy tale. I said, I will tell you a story. To be continued...

Latest articles

How To: CakePHP, CakeDC Users and Amazon Cognito

Long time ago, in 2010, CakeDC Users plugin for CakePHP was released for CakePHP 1.3. Almost nine years has passed and the initial code has changed dramatically, offering new and exciting features. In 2011 the team released the first version to be compatible with the new CakePHP 2.0. At this moment we focused in keeping the same features and only adding support for the new version of the framework. When CakePHP 3.0 arrived in 2015 we decided to refactor Users plugin completely, making it easier to use but also adding terrific features out of the box like:

  • Social login with most popular providers
  • RBAC permissions
  • Superuser
  • And much more..
It continued evolving and today we will show how to use the latest provider we have added to the social login feature in the plugin, Amazon Cognito. Let’s talk first about it. We'll use Amazon Cognito basically as an Oauth 2.0 Server. It'll let you manage your user groups and users. It provides a simple interface to sign up, sign-in and also use many social providers like Facebook, Google and Amazon. It also allows using SAML 2.0 providers and they promise it may scale to millions of users. You can also fully customize form and buttons. Best of all, it is free for the first 50,000 logins. Let's start configuring Amazon Cognito in AWS Panel. We must first create a user pool. You could have different user pools and each of them having an exclusive set of features.     Now we need to customize our new pool adding a pool name, etc. We can use default settings for testing purposes. If you want to customize fields you should then go through steps.     Once we check everything is okay we can click on Create Pool.     Now, it's time to setup App Clients. If you are familiar with OAuth and another services it is like creating a Facebook or Twitter App.     And then click on Add an app client.  Just add a name and save.   Remember to write down your client ID and client secret because they will be needed later to configure Users plugin. The next step is to setup app client settings. We need to configure:
  • Callback url: set it to /auth/cognito if you want to use plugin defaults.
  • The flow to Authorization code grant and the scopes you must select at least email and openid. You can select profile in case you want to get all the user information from cognito.
      Finally we need to configure a domain name for the user pool. Use a custom domain or a subdomain from Cognito.     Now that we are ready with Cognito setup, let’s easily create a new CakePHP app, to connect with Amazon Cognito. First, we need a new CakePHP app: composer create-project --prefer-dist cakephp/app users-app Remember to create a new empty database. Now we can go to users-app folder and run: composer require cakedc/users After CakeDC Users plugin is installed, we need to install Oauth 2 Cognito provider package: composer require cakedc/oauth2-cognito CakeDC Users plugin configuration is pretty easy: $this->addPlugin('CakeDC/Users'); public function pluginBootstrap() { parent::pluginBootstrap(); Configure::load('users'); } return [ 'Users.Social.login' =--> true, 'OAuth.providers.cognito.options.clientId' => 'CLIENT_ID', 'OAuth.providers.cognito.options.clientSecret' => 'CLIENT_SECRET', 'OAuth.providers.cognito.options.cognitoDomain' => 'DOMAIN', 'OAuth.providers.cognito.options.region' => 'REGION', ];
  • Load the Users Plugin bin/cake plugin load CakeDC/Users
  • If you prefer to do this manually, add this line at the end of your src/Application.php bootstrap() method
  • Add the following line into AppController::initialize() method $this->loadComponent('CakeDC/Users.UsersAuth');
  • Add the following code to your src/Application.php pluginBootstrap() method to ensure we override the plugin defaults
  • Add the file config/users.php with your specific configuration, including
In case you used a custom domain for you user pool, you can replace cognitoDomain option by using hostedDomain option (including protocol): 'OAuth.providers.cognito.options.hostedDomain' => 'YOUR DOMAIN', Scope option defaults to email openid . If you selected another scopes, you may want to add them as well: 'OAuth.providers.cognito.options.scope' => 'email openid profile', Finally we just need to go to /login.     and click on Sign in with Cognito. If everything is setup correctly you should see the following screen:   You can previously create a user in AWS panel or just click signup on that screen. After login you will be redirected to homepage in CakePHP App. As you can see, the setup for both Cognito and App are simple if you use default settings. However after testing defaults, you can start customizing forms, fields, adding third party apps. You have no limits.  

Last words

We create and maintain many open source plugins as well as contribute to the CakePHP Community as part of our open source work in CakeDC. While developing this provider, we've also published a generic Oauth2 Amazon Cognito repository. Reference  

Boost CakePHP using RoadRunner Plugin

https://github.com/CakeDC/cakephp-roadrunner was just released! Some time ago we developed a bridge for the PHP Process Manager, and now we've integrated with another alternative, a fast, go based, PHP application server (see https://github.com/spiral/roadrunner) Using this approach, and configuring nginx + roadrunner + cakephp, we're getting ~1500 requests per second for a typical index operation (including database access), and over 2200 (!) requests per second using a cached resultset. Here's what you need to do:

  • composer require cakedc/cakephp-roadrunner
  • Download roadrunner binary and place the file in your filesystem, for example under /usr/local/bin/rr
  • Create a RoadRunner worker file, or use the example worker provided
cp vendor/cakedc/cakephp-roadrunner/worker/cakephp-worker.php . cp vendor/cakedc/cakephp-roadrunner/worker/.rr.json . Note the configuration is stored in .rr.json file, check all possible keys here https://github.com/spiral/roadrunner/wiki/Configuration
  • Start the server, either using your own configuration or the sample configuration provided in the plugin
/usr/local/bin/rr serve   Check plugin details here > https://github.com/CakeDC/cakephp-roadrunner

Last words

Please let us know if you use it, we are always improving our plugins - And happy to get issues and pull requests for our open source plugins. As part of our open source work in CakeDC, we maintain many open source plugins as well as contribute to the CakePHP Community.

Integrating Users and ACL plugins in CakePHP

In previous posts, we saw how CakeDC Users plugin can help you to build an application that manages everything related to users: registration, social login, permissions, etc. Recently it has been noted by the team that there are some use cases where a deeper control of permissions is needed - more than is offered in RBAC. Today we’ll go into this using the ACL approach. ACL or Access Control List, refers to the application using a detailed list of objects to decide who can access what. It can be as detailed as particular users and rows through to specifying which action can be performed (i.e user XX has permissions to edit articles but does not have permissions to delete articles). One of the big features of ACL is that both the accessed objects; and objects who ask for access, can be organized in trees. There’s a good explanation of how ACL works in the CakePHP 2.x version of the Book. ACL does not form part of CakePHP core V 3.0 and can be accessed through the use of the cakephp/acl plugin. Let’s just refresh the key concepts of ACL:

  • ACL: Access Control List (the whole paradigm)
  • ACO: Access Control Object (a thing that is wanted), e.g. an action in a controller: creating an article
  • ARO: Access Request Object (a thing that wants to use stuff), e.g. a user or a group of users
  • Permission: relation between an ACO and an ARO
For the purpose of this article - we shall use this use case: You are using CakeDC/users plugin and now want to implement ACL in your application.

Installation

Starting with a brand new CakePHP app: composer selfupdate && composer create-project --prefer-dist cakephp/app acl_app_demo && cd acl_app_demo We are going to use CakeDC/users and cakephp/acl plugins. In a single step we can install them with composer: composer require cakedc/users cakephp/acl Create a DB and set its name and credentials in the config/app.php file of the just created app (in the Datasources/default section). This command can help you out if you are using MySQL: mysql -u root -p -e "create user acl_demo; create database acl_demo; grant all privileges on acl_demo.* to acl_demo;" Plugins will be loaded always with the app. Let’s set them on the bootstrap file: bin/cake plugin load -br CakeDC/Users
bin/cake plugin load -b Acl Now let’s insert a line in bootstrap.php before Users plugin loading, so cakedc/users will read the configuration from the config/users.php file of our app. Configure::write('Users.config', ['users']); This file does not exist yet. The plugin provides a default file which is very good to start with. Just copy it to your app running: cp -i vendor/cakedc/users/config/users.php config/ Also, let’s copy the permissions file the same way to avoid warnings in our log files: cp -i vendor/cakedc/users/config/permissions.php config/ We need to change cakedc/users config: remove RBAC, add ACL. In cakephp/acl there’s ActionsAuthorize & CrudAuthorize. We’ll start just using ActionsAuthorize. We will tell ActionsAuthorize that actions will be under the 'controllers/' node and that the users entity will be MyUsers (an override of the Users entity from the plugin). Edit the Auth/authorize section of config/users.php so that it sets: 'authorize' => [ 'CakeDC/Auth.Superuser', 'Acl.Actions' => [ 'actionPath' => 'controllers/', 'userModel' => 'MyUsers', ], ], Add calls to load components both from Acl & Users plugin in the initialize() method in AppController: class AppController extends Controller { public function initialize() { parent::initialize(); // (...) $this->loadComponent('Acl', [ 'className' => 'Acl.Acl' ]); $this->loadComponent('CakeDC/Users.UsersAuth'); // (...) } // (...) }

Database tables

Some tables are required in the database to let the plugins work. Those are created automatically just by running their own migrations: bin/cake migrations migrate -p CakeDC/Users
bin/cake migrations migrate -p Acl One table from the Acl plugin needs to be fixed because Users migration creates users.id as UUID (CHAR(36)) and Acl migrations creates AROs foreing keys as int(11). Types must match. Let’s fix it adapting the aros table field: ALTER TABLE aros CHANGE foreign_key foreign_key CHAR(36) NULL DEFAULT NULL; Now, it’s time to set our own tables as needed for our app. Let’s suppose we are developing a CMS app as specified in the CMS Tutorial from the CakePHP book. Based on the tutorial, we can create a simplified articles table: CREATE TABLE articles ( id INT AUTO_INCREMENT PRIMARY KEY, user_id CHAR(36) CHARACTER SET latin1 COLLATE latin1_swedish_ci NOT NULL, title VARCHAR(255) NOT NULL, body TEXT, published BOOLEAN DEFAULT FALSE, created DATETIME, modified DATETIME, FOREIGN KEY user_key (user_id) REFERENCES users(id) ); Note: Specify CHARACTER SET and COLLATE for user_id only if the table CHARACTER SET and COLLATE of the table differ from users.id (than may happen running migrations). They must match. Roles will be dynamic: admin will be allowed to manage them. That means that they has to be stored in a table. CREATE TABLE roles ( id CHAR(36) NOT NULL PRIMARY KEY, name VARCHAR(100) NOT NULL, created DATETIME, modified DATETIME ); Association between users and roles bill be belongsTo, so we’ll need a foreign key in the users table instead of a role varchar field: ALTER TABLE users ADD role_id CHAR(36) CHARACTER SET latin1 COLLATE latin1_swedish_ci NULL DEFAULT NULL AFTER role, ADD INDEX role_id (role_id), ADD FOREIGN KEY (role_id) REFERENCES roles(id); ALTER TABLE users DROP role;

Baking

Time to think about what will be ACOs and AROs. In most cases, Users will be the only AROs. To do that, we need to link the Users entity and table to the ACL plugin. In this case that we are using CakeDC/users plugin, we first need to extend the plugin as it is explained in the docs. We will also add the behavior and parentNode() as shown in the cakephp/acl readme file, so at the end we’ll need to create those files: src/Model/Entity/MyUser.php: <?php namespace App\Model\Entity; use CakeDC\Users\Model\Entity\User; /** * Application specific User Entity with non plugin conform field(s) */ class MyUser extends User { public function parentNode() { return ['Roles' => ['id' => $this->role_id]]; } } src/Model/Table/MyUsersTable.php: <?php namespace App\Model\Table; use CakeDC\Users\Model\Table\UsersTable; class MyUsersTable extends UsersTable { public function initialize(array $config) { parent::initialize($config); $this->addBehavior('Acl.Acl', ['requester']); $this->belongsTo('Roles'); $this->hasMany('Articles'); } } Run bin/cake bake controller MyUsers (beware of case) Then, edit the top of src/Controller/MyUsersController.php as: <?php namespace App\Controller; use App\Controller\AppController; use CakeDC\Users\Controller\Traits\LinkSocialTrait; use CakeDC\Users\Controller\Traits\LoginTrait; use CakeDC\Users\Controller\Traits\ProfileTrait; use CakeDC\Users\Controller\Traits\ReCaptchaTrait; use CakeDC\Users\Controller\Traits\RegisterTrait; use CakeDC\Users\Controller\Traits\SimpleCrudTrait; use CakeDC\Users\Controller\Traits\SocialTrait; class MyUsersController extends AppController { use LinkSocialTrait; use LoginTrait; use ProfileTrait; use ReCaptchaTrait; use RegisterTrait; use SimpleCrudTrait; use SocialTrait; // CRUD methods ... To generate the template files for MyUsers we can run: bin/cake bake template MyUsers Next, just let Cake bake all objects for articles and roles: bin/cake bake all Articles
bin/cake bake all Roles Add behavior to their tables. ArticlesTable will act as controlled because it will represent ACOs: class ArticlesTable extends Table { public function initialize(array $config) { parent::initialize($config); // (...) $this->addBehavior('Acl.Acl', ['controlled']); // (...) The case of RolesTable will be similar but it will act as requester, as it will represent AROs: class RolesTable extends Table { public function initialize(array $config) { parent::initialize($config); // (...) $this->addBehavior('Acl.Acl', ['requester']); // (...) Create the parentNode() method in both entities: Article and Role. public function parentNode() { return null; }

Testing

Ok, time to test the whole system! At this point, the app should be ready to use. At least, for an administrator. Let’s quickly create one: it is as easy as running bin/cake users add_superuser. New credentials will appear on screen. When accessing our app in the URL that we installed it, a login form will appear. Log as the just created admin. First, let’s create some roles. Go to /roles in your app’s URL. Then, click on "New Role". Create the roles:
  • Author
  • Editor
  • Reader
Then, we can create two users an author and a reader. Head to /my-users and add them. Remember to select the Active checkbox and the proper role in the dropdown menu. Because MyUsers has the AclBehavior, AROs has been automatically created while creating users, along with the created roles. Check it out with bin/cake acl view aro Aro tree: --------------------------------------------------------------- [1] Roles.24c5646d-133d-496d-846b-af951ddc60f3 [4] MyUsers.7c1ba036-f04b-4f7b-bc91-b468aa0b7c55 [2] Roles.5b221256-0ca8-4021-b262-c6d279f192ad [3] Roles.25908824-15e7-4693-b340-238973f77b59 [5] MyUsers.f512fcbe-af31-49ab-a5f6-94d25189dc78 --------------------------------------------------------------- Imagine that we decided that authors will be able to write new articles and readers will be able to view them. First, let’s create the root node for all controllers: bin/cake acl create aco root controllers Then, let’s inform ACL that there are such things as articles: bin/cake acl create aco controllers Articles Now, we will tell that there are 5 actions related to Articles: bin/cake acl create aco Articles index bin/cake acl create aco Articles view bin/cake acl create aco Articles add bin/cake acl create aco Articles edit bin/cake acl create aco Articles delete We can see the first branch of the ACOs tree here: bin/cake acl view aco Aco tree: --------------------------------------------------------------- [1] controllers [2] Articles [3] index [4] view [5] add [6] edit [7] delete --------------------------------------------------------------- ACL knows that articles can be added, so let’s tell who can do that. We can check which aro.id belongs to role Author with: mysql> select id from roles where name like 'Author'; +--------------------------------------+ | id | +--------------------------------------+ | 24c5646d-133d-496d-846b-af951ddc60f3 | +--------------------------------------+ 1 row in set (0.00 sec) And the same with the Reader role:: mysql> select id from roles where name like 'Reader'; +--------------------------------------+ | id | +--------------------------------------+ | 25908824-15e7-4693-b340-238973f77b59 | +--------------------------------------+ 1 row in set (0.00 sec) So, if we look up this id in the bin/cake acl view aro output, it turns out that aro.id 1 is Author and that aro.id 3 is Reader. If we want to let authors (ARO 1) add articles (ACO 5), we must grant permission to Articles/add to editors by running: bin/cake acl grant 1 5 And we'll grant readers (ARO 3) view articles (ACO 4) with: bin/cake acl grant 3 4 Don't forget to grant access to Articles/index for all roles, or nobody would access /articles: bin/cake acl grant 1 3 bin/cake acl grant 2 3 bin/cake acl grant 3 3 Note: Obviously, it would be easier to set a "super role" which includes the 3 roles and grant access to index to it, but we don't want to add too many steps in this tutorial. You can try it for yourself. Then, aros_acos table becomes: mysql> select * from aros_acos; +----+--------+--------+---------+-------+---------+---------+ | id | aro_id | aco_id | _create | _read | _update | _delete | +----+--------+--------+---------+-------+---------+---------+ | 1 | 1 | 5 | 1 | 1 | 1 | 1 | | 2 | 3 | 4 | 1 | 1 | 1 | 1 | | 3 | 1 | 3 | 1 | 1 | 1 | 1 | | 4 | 2 | 3 | 1 | 1 | 1 | 1 | | 5 | 3 | 3 | 1 | 1 | 1 | 1 | +----+--------+--------+---------+-------+---------+---------+ 5 rows in set (0.00 sec) Let’s create a new article as the first user. To do that:
  • Log out (we are still logged in as superadmin) going to /logout
  • Log in as the first created user
  • Go to /articles
  • Create an article
Right now, author can add an article but not view it, since we only set the add permission. Check it out clicking in View next to the article. Log in as a reader to check how the reader can really view the article. Obviously, more than a couple of permissions have to be grant in a big app. This tutorial served just as an example to start.

Last words

That's all for now related to the use of ACL in a webapp made with CakePHP. A lot more can be done with ACL. Next step would be to use CrudAuthorize to specify which CRUD permissions are granted for any ARO to any ACO. Keep visiting the blog for new articles! This tutorial has been tested with:
  • CakePHP 3.5.10
  • CakeDC/users 6.0.0
  • cakephp/acl 0.2.6
An example app with the steps followed in this tutorial is available in this GitHub repo. Please let us know if you use it, we are always improving on them - And happy to get issues and pull requests for our open source plugins. As part of our open source work in CakeDC, we maintain many open source plugins as well as contribute to the CakePHP Community. Reference

We Bake with CakePHP