DEVELOP.md 10.9 KB
Newer Older
1 2 3 4 5 6 7 8
# Application description and Development guide

## Requirements

- `php`: >=5.5
- `slim/slim`: ^3.0
- `kanellov/config-merge`: dev-master
- `kanellov/php-events`: ^2.0
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

## Install dependencies via composer

In the project folder run

    $ ./composer.phar install

to install dependencies.

If you add any dependencies in `composer.json` file, run 
    
    $ ./composer.phar update

to install new dependencies.

## Directory structure

26 27 28 29 30 31 32 33 34 35 36
- `config`: Application main configuration
    - `settings`: Configuration files for Slim Settings (_`*.local.php` are deployment specific files and ignored by git_)
- `data`: Directory for storing related application files
    - `cache`: Directory for cache files
        - `config`: Directory to cache merged configuration
        - `templates`: Twig's autogenerated cache files
    - `db`: 'Database schema and other database related files`
    - `log`: Log files
    - `tmp`: Temporary directory
    - `uploads`: Directory for uploaded files
- `module`: Directory for application modules
37 38 39 40 41
- `public`: Webserver Document root
- `vendor`: Composer dependencies

## Special files

42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195
- `config/app.config.php`: Main application configuration. Sets modules and config cache path
- `config/dev.config.php.dist`: Application configuration for development. Create a `dev.config.php` to include development related modules and to disable config caching.
- `config/settings/{,*.}{global,local}.php`: Configuration files for Slim settings; `*.global.php` are loaded first and then can be overridden by `*.local.php`
- `public/index.php`: Application entry point

## Application configuration and settings

### Application config

Modules to include are defined in `config/app.config.php` file. 

The order of module definition matters if a module depends from another. For example, if ModuleA depends on ModuleB, ModuleB must be defined before ModuleA.

_More information about modules in [Modular application skeleton](#modular-application-skeleton) section._

Also, in this file is defined the path to store the merged settings, that are loaded from `config/settings`. See [Slim settings files](#slim-settings-files) for more information.

``` php
<?php

return [
    'modules' => [
        // Modules definition. Full path for module file
        'module/application/bootstrap.php',
    ],
    // Full path for file to store merged configuration
    'cache_config' => 'data/cache/config/settings.php',
];

// ?>
```

### Slim settings files

- `acl.global.php`: defines resources, roles and privileges for acl
- `assets_manager.global.php`: defines paths for module assets and public dir for copying 
- `authentication.global.php`: defines route guards for login and logout routes
- `authentication.local.php.dist`: defines password salt and encryption algorithm cost
- `db.local.php.dist`: defines database 
- `debug.global.php`: defines debug log path
- `global.php`: defines basic slim settings
- `inventory.local.php.dist`: defines the api url for inventory.sch.gr
- `ldap.local.php.dist`: defines ldap settings
- `monolog.global.php`: defines logger settings
- `nav.global.php`: defines application navigation
- `sch_mm.local.php.dist`: defines api url and credentials for mm.sch.gr
- `schools.global.php`: defines settings for schools module
- `sso.local.php.dist`: defines phpCAS settings for sso.sch.gr 
- `twig.global.php`: defines twig settings


## Html rendering and Templates

Application uses [Twig](http://twig.sensiolabs.org/) as template engine for rendering html.

## Modular application skeleton

Application is base on [Slim Framework](http://www.slimframework.com/) and is implemented in a modular way. There are some key concepts that should be taken in mind, in order to implement a fully functional module.

### Dependency Container

Application uses the default `Slim\Container` for handling dependencies. See http://www.slimframework.com/docs/concepts/di.html for more information.

### Autoloading

Application uses composer's autoloader `Composer\Autoload\ClassLoader` to handle class autoloading. See https://github.com/composer/composer/blob/master/doc/01-basic-usage.md#autoloading for more information.

### Application events

Application uses `Knlv\events` function to handle events. See [php-events](https://github.com/kanellov/php-events). 

After `Slim\App` initialization the following events are triggered:

1. `app.autoload`: Modules that listen to this event can setup the class autoloading. Event listener should expect the `Composer\Autoload\ClassLoader` instance as argument.
2. `app.services`: Modules that listen to this event can register their services in the `Slim\Container` Dependency Container.
3. `app.bootstrap`: When this event is triggered, autoloading is completed and dependency container should contain all registered services. Modules listening for this event can register routes, or override services in the Dependency Container.

### How to define a module

A module is defined with a file which should return a Closure.

Here is a typical module implementation:

``` php
<?php 
return function (Slim\App $app) {
    // module initialization code
    
    $container = $app->getContainer();
    $events = $container->get('events');

    $events('on', 'app.autoload', function ($autoloader) {
        // register autoloading for module classes
        $autoloader->addPsr4('Module\\', __DIR__ . '/src');
    });

    $events('on', 'app.services', function ($stop, $c) {
        $c[Module\SomeAction::class] = function ($c) {
            return new Module\SomeAction(
                // dependencies
            );
        };

        $c[Module\Middleware::class] = function ($c) {
            return new Module\Middleware(
                //dependencies
            );
        };
    });

    $events('on', 'app.bootstrap', function ($app, $c) {

        // add middleware
        $app->add(Module\Middleware::class);

        // register routes
        $app->get('/some-path', Module\SomeAction::class)
            ->setName('some-route');
    });

    // To add middleware for an existing route provided by some other module, 
    // you must ensure that the route exists. Low listener priority ensures
    // that the app.bootstrap listeners are executed and all routes exist.
    $events('on', 'app.bootstrap', function ($app, $c) {
        $route = $c->get('router')->getNamedRoute('some-other-route');
        $route->add(function ($req, $res, $next) {
                // middleware logic
            });
    }, -100); // low priority
};
// ?>
```

## Existing Modules

### application

Master module that defines the basic services such as:

- `Slim\Views\Twig` for view
- `Monolog` for logger
- `RedBeanPHP` for database
- `Slim\Flash\Messages` for flash message service
- `Slim\Csrf\Guard` for CSRF protection

It also provides the routes for home and about pages.

#### Dependencies

- `gabordemooij/redbean`: ^4.3.1
- `slim/twig-view`: ^2.0
- `slim/csrf`: ^0.6.0
- `slim/flash`: ^0.1.0
- `kanellov/slim-twig-flash`: ^0.1
196
- `kanellov/assets-manager-middleware`: ^1.0,
197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296
- `monolog/monolog`: ^1.13

### application_form

Module that is responsible for application form submission by schools. It renders the form and stores the submitted form in database.

It also overrides schools index view by appending application form information.

#### Dependencies

- application module
- authentication module
- schools module
- `zendframework/zend-inputfilter`: ^2.0

### authentication

Module that provides user authentication against database. The module includes the view for login page.

#### Dependencies

- application module
- `zendframework/zend-authentication`: ^2.0
- `zendframework/zend-crypt`: ^2.0

### authorization

The module that provides the acl service and assigns role to users. See [`acl.global.php` in Slim settings files](#slim-settings-files).

#### Dependencies

- authentication module
- `zendframework/zend-permissions-acl`: ^2.0

### debug

This module should only be enabled during development and in a production deployment. It provides a debug logger and enables extensive information in error messages.

#### Dependencies

- application module

### sch_inventory

It provides the service for retrieving school's rooms and equipment from http://inventory.sch.gr.

#### Dependencies

- `guzzlehttp/guzzle`: ^6.1

### sch_ldap

It initilizes an ldap connection with sch.gr. See [`ldap.local.php.dist` in Slim settings files](#slim-settings-files).

#### Dependencies

- `zendframework/zend-ldap`: ^2.0

### sch_mm

Module for retrieving extensive information about school from http://mm.sch.gr.

#### Dependencies

- `guzzlehttp/guzzle`: ^6.1

### sch_sso

Module that enables SSO with http://sso.sch.gr. Schools use this authentication method.

It overrides login view.

#### Dependencies

- application module
- authentication module
- authorization module
- `jasig/phpcas`: 1.3.4

### sch_sync

Module that gathers information from the other sch services and stores school's information in local database.

#### Dependencies

- application module
- authentication module
- sch_inventory module
- sch_ldap module
- sch_mm module
- schools module

### schools

This module provides the services, views and javascript for schools to submit the staff, rooms, equipment and software.

#### Dependencies

- application module
- `zendframework/zend-inputfilter`: ^2.0
297

298 299 300 301 302
### tpe_survey

This module overrides staff view of schools module. It allows school user to submit 
information about teachers using IT in education.

303 304 305 306 307 308 309
### in_numbers

This module ovverides index page by placing a panel with the total numbers of schools 
registered in application and of submitted application forms.

It also provides the /in_numbers route where total numbers are analyzed by school type.

310 311 312 313
#### Dependencies

 - schools module

314 315 316 317
## ER diagram

![ER diagram](https://github.com/eellak/gredu_labs/blob/develop/data/db/er.png)

318 319 320 321 322
## Run it:

1. `$ cd gredu_labs`
2. `$ php -S 0.0.0.0:8888 -t public public/index.php`
3. Browse to http://localhost:8888
323

324
**Warning:** kanellov/assets-manager-middleware does not work with php-server sapi. Assets from modules will have to be copied in `public` directory by hand.
325 326 327 328 329 330 331

## Links
- [Slim Framework](http://www.slimframework.com/)
- [slimphp/Slim-Csrf](https://github.com/slimphp/Slim-Csrf)
- [slimphp/Slim-Flash](https://github.com/slimphp/Slim-Flash)
- [kanellov/config-merge](https://github.com/kanellov/config-merge)
- [kanellov/php-events](https://github.com/kanellov/php-events)
332
- [kanellov/assets-manager-middleware](https://github.com/kanellov/assets-manager-middleware)
333 334 335 336 337 338 339 340
- [monolog](https://github.com/Seldaek/monolog)
- [zendframework/zend-ldap](https://github.com/zendframework/zend-ldap)
- [zendframework/zend-authentication](https://github.com/zendframework/zend-authentication)
- [zendframework/zend-crypt](https://github.com/zendframework/zend-crypt)
- [zendframework/zend-permissions-acl](https://github.com/zendframework/zend-permissions-acl)
- [zendframework/zend-inputfilter](https://github.com/zendframework/zend-inputfilter)
- [Guzzle, PHP HTTP client](http://docs.guzzlephp.org/en/latest/)
- [Twig](http://twig.sensiolabs.org/)